LDef

LDef is an attempt at providing a simple declaration language that can be parsed and from which API definitions for IDEs, stubs, wrappers, etc., can be generated.

Usage

You write your API declarations in the LDef language (see file ldef.md, and call the parser script in order to process it. The parser reads the file and calls a "formatter" to generate the kind of data you want from it (e.g. API indexes for IDEs, bindings for other languages, etc).

The parser requires only stock Lua; there are no third-party dependencies (note that it was mainly tested under LuaJit, which covers 5.1 and 5.2; 5.3 should also work). The parser script is invoked from the command line. A basic invocation is as follows:

lua parse_ldef.lua -f <formatter> -F opt1 -F opt2=value filename.ldef \
    -o <output_file>

Command Line Arguments

General usage:

parse_ldef.lua [OPTIONS] [FILE...]

Available options:

• -h, --help: Display the program's help text and exit.
• -f, --formatter NAME: Set the formatter to be used for writing the output file. See Formatters for more information.
• -F, --formatter-option STRING: Set options for the formatter. STRING may have the format key, or key=value.
• -o, --output FILE: Set output file.

If no FILE is given, or - is given as FILE, the program reads from standard input. If no -o option is given, the program writes to standard output. Error messages always go to standard error.

Note that required arguments for long options are also required for short options, unless stated otherwise.

Formatters

Formatters are responsible for converting the intermediate representation generated by the parser into the final representation.

The formatters available in the LDef distribution (specified with the -f command line option) are as follows:

• null: A simple formatter that writes nothing. This is mainly intended both as a base implementation/interface, and in order to check an LDef script for correctness without generating any output. This formatter has no options currently.
• table: A simple formatter that writes the raw data as a Lua script. This is mainly intended for debugging. This formatter has no options.
• zbstudio: Writes API definition scripts for the ZeroBrane Studio IDE. This formatter has no options currently.

Defining your own formatters

A formatter is a regular Lua module (either Lua script or native library). The module should export a function named write that takes three arguments: state, file, and options:

• state: This is the intermediate representation generated by the parser.
• file: This is the output file (a file object). The formatter should ultimately write its (main) output here.
• options: This is a table mapping string keys to string values. When the program is invoked with any -F options (see above), if the option has the format key, the key will be key, and the value will be the empty string (""). if the option has the format key=value, the key will be key, and the value will be value (both are always strings).