About C++ Extensions
C++ extensions are packages of code written in C++ that can interface with LDPL code and be added to your LDPL projects.
Because LDPL programs compile down to C++, there is no need for a translation layer or bridge: extensions can be included directly into LDPL programs and manipulate, share, and access subprocedures and variables natively. All that's needed is a few naming conventions on the C++ side and the use of the
external syntax for variables and subprocedures on the LDPL side. External variable and sub-procedure naming conventions are explained in detail in the Naming Schemes section of this documentation.
Extensions contain sub-procedures and variables that are considered to be external.
This means that they are not part of an LDPL source code and thus must be accessed and called in a different way to what you might be used to. External sub-procedures should be called using the
call external statement. While it is explained in greater detail in the Control Flow Statements section of this documentation, the statement works just like the normal
call statement with the exception that it doesn't accept parameters.
1 2 3 4
External variables (declared in a C++ file) should be re-declared again in your LDPL data section with the same type they have in the C++ file, appending to their type the
extenal keyword. This allows programmers to extend LDPL with new features or to wrap 3rd party libraries and re-use their functionality.
1 2 3
This will be explained in greater detail in the following sections.
Writing C++ Extensions
If LDPL lacks some feature that C++ might offer, for example graphics or networking, you might find yourself in the need of writing a C++ extension (provided an extension for what you are looking for has not been already written, of course).
Extensions can create variables and functions that are accessible from LDPL through the
call external and
external data type keyword, as explained in the previous section. Typically, all you need is a single
.cpp file that you include from your LDPL source using the
extension keyword (explained in the Code Structure section of this documentation), but you may also include
.a files, or any combination of them all.
To create a function in C++ that can be called from an LDPL program, you must follow four rules:
- The function type must be
- The function name must conform to LDPL's external identifier naming conventions explained in the Naming Schemes section of this documentation.
- The function must not take any parameters.
- The function must not return any values.
Because LDPL does not know the name of any variables or functions declared in non-LDPL files, it allows the programmer to call any function or variable, existing or not, by using the
external syntax. If the variable or function you are trying to access does not exist, the C++ linker will throw a nasty error. Also, all C++ variable and function names must contain only
0-9, and the
_ character. Every character on the LDPL side will be converted to upper case, and non alpha-numeric characters will be converted to an underscore (
_) when referencing the C++ side (again, as stated in the Naming Schemes section of this documentation).
For example, this function in a file called add.cpp
1 2 3 4 5 6 7 8 9
can be accessed from LDPL in the following way
1 2 3 4
To create a variable in a C++ extension that can be accessed from LDPL code, you must follow two rules:
- The variable's name must conform to the LDPL external identifier naming convention stated in the Naming Schemes section of this documentation.
- The C++ type of the variable must match the type used by LDPL for the data type represented by that variable.
The first rule should be familiar from the previous section: all C++ variable and function names must contain only
0-9, and the
_ character. Everything else on the LDPL side will get converted to an underscore (
For the second rule, the LDPL compiler provides the data types
ldpl_map<T>. These will be explained in greater detail in the next section.
Declaring variables is easy on the C++ side:
1 2 3
These will be available to an LDPL program when declared as external in its
1 2 3 4
The LDPL Data Types
The LDPL compiler provides the data types
ldpl_map<T>. To use
them, just use them as if they were declared and the LDPL compiler will add the declarations and definitions for you
once the extension is compiled.
ldpl_numberdata type is just a rename for
ldpl_textdata type is a special UTF-8 string class used just like the regular C++
std::stringclass, with the exception that if you want to get an
ldpl_textyou can call the
ldpl_text::str_rep()to get the
std::stringrepresentation of an
ldpl_text. Just like you would use
std::string::c_str()to get the C
char*representation of an
ldpl_list<T>data type represents an
std::vectorwith a special
ldpl_map<T>data type represents an
You can read the definition of these data types on the ldpl_lib.cpp file of the LDPL source repository.
Accessing Variables in C++ Functions
Since LDPL and C++ are using the same variable when you use the
external keyword (say, for example,
MY_VAR in C++ and external
my-var in LDPL), any changes you make to the content of said variables are shared. Use them just like you would use any regular variable, both in C++ and LDPL.
1 2 3 4 5
1 2 3 4 5 6 7 8 9 10
Building and running this program will print
Building C++ Extensions
Extensions are easy to build: when compiling your LDPL program, use the
extension keyword (explained in detail in the Code Structure section of this documentation) to add
.o files, or
.a files to your LDPL project. They will be included in your program and become available using the
If your C++ extension files require extra flags to be passed to the C++ compiler in order to compile (for example,
-lSDL when working with SDL) you can use the
flag statement (explained in detail in the Code Structure section of this documentation) to pass flags to the C++ compiler.
1 2 3 4 5 6 7
"Hello World" C++ Example
1 2 3 4
1 2 3 4
1 2 3 4 5 6
Sometimes when writing C++ Extensions you'll find yourself in the need of declaring a function in C++ but coding it in LDPL. This is the opposite of writing C++ functions and calling them from LDPL, it's writing LDPL sub-procedures and calling them from C++.
These C++ callable sub-procedures are called external sub-procedures, as they can be called from an external medium.
In order to declare an external sub-procedure, you must first forward-declare it in your C++ source code. Say, for example, that you want to declare a sub-procedure called
helloWorld. In your C++ you should write the following line:
Note that external sub-procedures cannot receive any kind of parameters and must be declared as
void. You may then call the external sub-procedure from C++ code like this:
1 2 3 4
Once that's taken care of, you can declare your external sub-procedure as any other sub-procedure in LDPL by prepending the identifier
external to the sub-procedure declaration:
1 2 3
1 2 3
These sub-procedures can be called from LDPL like you would call any other sub-procedure, but their names must follow the external identifier naming scheme detailed in the Naming Schemes section of this documentation as any other C++ interfacing identifier.
Variables defined in extensions can be accessed by prefacing their data type declaration with the
external keyword. This must occur in the data section of your LDPL code. Once an external variable is declared, it can be used just like any other LDPL variable.
1 2 3