The BSV editor can run scripts written in user-defined high-level languages by providing and installing HLL language modules. This document describes how to do that.

CAVEAT: The high level language module specification is subject to change. In particular, the current implementation requires the language module to be compiled with MSVC Version 15.9.9 with C++17 support switched on. It is likely that the current C++ interface will be wrapped with a C interface, and the C++ interface deprecated.

High Level Language (HLL) Modules

The BSV editor comes with the API-compliant language module for the Hello language pre-installed. The Hello language module is open-source code. Source is available at Hello GitHub repository.

To make a language available, the language provider must register the language module and supply the language compiler as a DLL as per this document.

Language Registration

Language registration allows the editor to detect the presence of language modules.

To register a language module, the following steps must be taken

• Point the HLL_EXT_DIR environment variable to the directory containing the language module. The environment variable may contain more than one location separated by semi-colons.

  If no environment variable is specified, the editor will look in the pwd only.

• Create a registration file in the module directory. The filename should look like

  	<language-name>.hllreg

  The lines in the file should have the following format:

  1. The file extension used by the language source files (E.g. 'hll' for Hello files).

HLL Compiler

A HLL module makes the compiler available to the BSV editor via the following function:

	debuggable* create_<language_name>_compiler();

The compiler object must be derived from the debuggable interface. (See Internals.h)

	class my_HLL_compiler : public debuggable
	{
		virtual std::pair<bool, std::string> compile(const std::string& filename) override;
		virtual std::pair<bool, std::string> execute(const std::string& script_txt) override;
		virtual std::pair<bool, std::string> go() override;
		virtual std::pair<bool, std::string> step_over() override;
		virtual std::pair<bool, std::string> step_into() override;
		virtual void stop() override;
	}
	                

The compiler should exhibit the following behaviour.

• pair<bool, std::string> compile(const string& filename)
  

  This method instructs the compiler to load the specified script file into memory and compile it.

  It may be that this step is required before other methods work (traditional compiler), or it may be the this step is not required (traditional interpreter). Not all language modules may support this method. If not, the returned error message should be "Not implemented" or "Not supported".

• std::pair<bool, std::string> go()
  

  This method instructs the compiler to start or continue a debugging session.

  It is called in response to Start-debugging command (e.g. F5 pressed). If the debugger is not running, the compiler should start and break at the first statement in the script. If the debugger is already runnning, it should execute the remaining code until a breakpoint is encountered or the execution is complete.

• std::pair<bool, std::string> step_over()

  This method instructs the compiler to execute the next statement.

  It is called in response to the Step-over command (e.g. F10 pressed). Typically this method requires a running debug session.

• std::pair<bool, std::string> step_into()

  The method is called in response to the Step-into command (e.g. F11 pressed). It is up to the HLL module how to interpret this command.

• void stop()

  This method instructs the compiler to stop any running debugging session.

  It should free any resources allocated to the debugging session.

• std::pair<bool, string> execute(const std::string& script_txt)

  This method instructs the compiler to execute the statements contained in the passed text.

  It provides a traditional interpreter interface. Not all language modules may support this method. If not, the returned error message should be "Not implemented" or "Not supported".

• std::pair<bool, string> compile(const std::string& script_txt)

  This method instructs the compiler to 'compile' the statements contained in the specified file.

  It provides a traditional compiler interface. Not all language modules may support this method. If not, the returned error message should be "Not implemented" or "Not supported".

  The Hello module currently compiles the file

  	<script-name>.hll 

  by writing out annotated script to the file

  	<script-name>.hll.script 

  which can be loaded into the script debugger.

The editor displays the values in stack, alt-stack and symbol_table defined in debuggable.

Remarks

1. By convention, API functions return

	std::pair<bool, std::string>(true, "") 

if they complete successfully and return

	std::pair<bool, std::string>(false, error-message)

if they do not.

2. The Hello language module is a Q&D hand-crafted language compiler. It follows the tradition pipeline

	tokeniser → parser → AST → instruction pipeline → optimiser 

Further documentation will be added.

Security

The BSV Editor makes calls into another DLL/shared object, which opens up the possibiliy of malicious code in a HLL module doing harm. It is therefore advised that only trusted language modules, or ones compiled from source code, are installed.

This site will maintain a list of trusted publicly-available language modules (none currently available).

Copyright (c) Ventimore Ltd (UK), 2011, 2012, 2017, 2018, 2019.