Package file format reference

From sygnm
Jump to: navigation, search

A sygnm package descriptor file is a text file with .sygnmpkg extension. It consists of key-value pairs, code snippets and documentation. Lists are separated by commas. Boolean values are always written as true or false, not as numbers. It is recommended to read some of the .sygnmpkg files which describe the packages that come with the sygnm system for real world examples of the file format.

Key-value pairs in package descriptor files

Key

Value

Context

Required

Description

package

[a-z_][a-z_0-9]*

package

Yes

Name (identifier) of the package.

version

[0-9]+\.[0-9]+\.[0-9]+([-a-zA-Z_0-9]+)?

package

Yes

Version of the package. A version string (like 1.2.3 or 1.0.0alpha1), preferably following the semantic versioning standard.

debug

String

package

No

Print a debug message when the code generator processes the package.

author

Author Name author@example.com

package

Yes

Name and e-mail address of package author.

depends on

List of package names

package

No

List of packages which must be loaded before this package is loaded.

conflicts with

List of package names

package

No

List of packages which can't be used together with this package.

needs libraries

List of libraries (see Package file format reference#Package dependencies)

package

No

List of external libraries this package depends on.

abbrev

String -> String

package

No

Defines a package-level ID abbreviation which can be used in parameter lists. ID abbreviations only appear in the generated documentation, they are replaced with their full form by the code generator when reading the package descriptor file (unlike aliases which are handled by the sygnm system and can be used at runtime). Note that only IDs and typeclass names can be abbreviated, so it is not possible to abbreviate (type) parameter lists, like example.example<:type_param1> to example_tp1 (however it is possible to write ex<:tp1> by using two abbreviations).

configuration

key_namespace.key_name = value

package

No

A configuration key to be written into the package's configuration file.

typeclass

Typeclass name

package

No

Typeclass declaration.

extends

List of typeclass names

typeclass

No

List of typeclasses extended by the current typeclass.

tree transformation

TODO

package

No

Declares a tree transformation.

priority

Integer

package

No

Priority of the tree transformation (higher priority will be executed sooner).

transformation stages

TODO

tree transformation

No

TODO

disabled by default

Boolean

package

No

If true, this package is built only if it is explicitly enabled when configuring the build.

test

sygnm expression

package

No

A test case is a sygnm expression which is evaluated when tests are run. By default, if it evaluates to true, the test passes otherwise it fails.

test properties

NOT IMPLEMENTED YET

package

No

NOT IMPLEMENTED YET

example

sygnm expression

package

No

A test case which can also be used as an example in the documentation. Works the same as test.

result

sygnm expression

test

No

The expected result of a test. If it is not specified, the expected result is 'true'.

context hashing

TODO

TODO

No

TODO

context hash keys

TODO

TODO

No

TODO

implementation

A complete function ID (all three parts)

function

No

This key specifies that the implementation of the current function is the same as the function with the given ID.

reversed implementation

A complete function ID (all three parts)

function

No

This key specifies that the implementation of the current function is the same as the function with the given ID except that the order of arguments is reversed.

hash memoization

Boolean

function

No

Enables hash-based memoization.

full memoization

Boolean

function

No

Enables full memoization (a copy of the input arguments is stored in a lookup table).

function

A function name

package

No

Declares a function.

copyright

String

package

Yes

Single line copyright notice of the package (e.g. Copyright (C) 2015-2017 Author Name <author@example.com>)

data type

A data type name

package

No

Declares a data type.

parser

A parser name

package

No

Declares a parser.

renderer

A renderer name

package

No

Declares a renderer.

I/O interface

An I/O interface name

package

No

Declares an I/O interface.

typeclass implementation

A typeclass name

package

No

Declares a typeclass implementation.

parameters

Parameter list (see Package file format reference#Parameter list format)

function, typeclass, typeclass implementation

No

Parameter list.

type parameters

Parameter list (see Package file format reference#Parameter list format)

data type

No

Type parameter list.

returns

Parameter list of length 1 (see Package file format reference#Parameter list format)

function

No

Return value of the function.

base

Parameter list of length 1 (see Package file format reference#Parameter list format)

typeclass, data type, function

No

Base typeclass set of a function or data type.

aliases

List of names

function

No

List of alternative names for the function.

difficulty score

An integer or "custom"

function

No

Difficulty score for this function. If the value is an integer, then that integer will be the difficulty score. If the value is "custom", then the difficulty score function is implemented by the package creator (can be non-constant).

flag type

Data type name.

package

No

Declares a special data type (a flag type), whose values are subsets of pre-defined set of named flags. (Similar to C/C++ enums but the values are string and an object of this type can store multiple values.)

values

List of strings

flag type

Yes

List of possible values for the current flag type.

alias

Function name -> Function name

package

No

Defines an alias for all functions in the package with the given name.

documentation page

Filename of documentation page, relative to package directory or a MediaWiki URL in the http://example.com/index.php?title=Page_title format.

package

No

Declares a documentation page. The page contents will be read, processed and included in the package documentation.

additional files

List of filenames, relative to package directory

package

No

Additional files which should not be compiled but should still appear in the CMake project for the package. This is mostly for IDEs which process CMake files.

additional implementation files

List of filenames, relative to package directory

package

No

Additional files which belong to the package implementation and should be compiled with it.

Package dependencies

Package dependency descriptors are simple JSON files which describe an external dependency. In sygnm package descriptor files, the needs libraries key lists the names of the dependency descriptor files (without the .json extension) which are needed to build and use the package.

Key

Value

cpp_headers

A list of headers to be included in the generated code.

link_library

Name of the CMake variable containing the link libraries for this dependency.

find_package

Name of the CMake find module of this dependency.

include_dir

Name of the CMake variable containing the include dirs for this dependency.

Example

The following is a package dependency file for the arb library. This makes it possible to use the arb library from any package which lists arb in its external dependencies.

{
    "cpp_headers": ["arb.h", "arb_poly.h", "acb.h", "arb_mat.h", "fmpz_extras.h"],
    "link_library": "Arb_LIBRARIES",
    "find_package": "Arb",
    "include_dir": "Arb_INCLUDE_DIRS"
}

Parameter list format

A parameter list consists of multiple parameters (typeclass sets), separated by commas.

A parameter begins with a name ([a-z_][a-z0-9_]* or can be empty), which is optionally followed by a list of attributes. The name can optionally begin with a * character, which is not part of the name itself. The * marks the typeclass set as starred (can match any number of actual parameters). Only the last typeclass set can be marked as starred in a parameter list. The attribute list begins with [ and ends with ]. An attribute can either be an integer, a single name or a key-value pair.

The parameter name (and optional attributes) are followed by a :. After the :, a set of typeclass names or the "any" keyword follows. The typeclass name set can also contain a single object ID. A set is started by a { and ended with a }. If the set has only one element, the braces are optional. Inside the set, elements are separated by commas. The set can contain any number of typeclass names (starting with a capital letter) and at most one object ID. The object ID can be incomplete. These typeclasses and object ID determine what objects are acceptable as actual parameters (see Objects, type and function overloading to learn about signatures and typeclass set matching). If instead of a set, the special "any" keyword is used then all objects are accepted.

If there is a type parameter list for this parameter, then it follows the ending }. It starts with a < and is finished by a >. Type parameter lists are themselves parameter lists and therefore use the same format. Type parameters can be nested to an arbitrary level.

The following is a table of parameter attributes. An attribute can only appear at most once in an attribute list.

Attribute

Description

A non-negative integer

The tag (label) of this typeclass set. Typeclass sets with the same tag must match the exact same types.

pnum=0|([1-9][0-9]*) or $0|([1-9][0-9]*)

Only applicable in typeclass interfaces. This is the number of the typeclass parameter that the current typeclass set represents.

always_inherited=List, Of, Typeclass, Names

Typeclasses that are always inherited from this typeclass set.

can_inherit=List, Of, Typeclass, Names

Typeclasses that this typeclass set can inherit.

do_not_add_to_base

If this appears in a typeclass set of a typeclass implementation parameter list, then the typeclass whose interface is implemented will not be added to the base of the parameter with this attribute.

do_not_match_dynamic

This typeclass set does not match dynamic nodes.

only_match_dynamic

This typeclass set can only match dynamic nodes.

never_inherit

This typeclass set never inherits typeclasses from type parameters.

multiparam_tcs=TypeclassA/0, TypeclassB/2#1, ...

A list of multiparametric typeclass descriptors. This is used when the typeclass set contains multiparametric typeclasses. Each entry in the list is a typeclass name (the name of the multiparametric typeclass), followed by a / character, then the index of this typeclass set (starting from 0) in the typeclass parameter list. Each entry may end in a # character followed by a numeric ID to differentiate between different uses of the same multiparametric typeclass.

Examples

function: add.integer
parameters: a: numbers.integer, b: numbers.integer

function: div.complex
parameters: a: numbers.complex<:Rational>, b: numbers.complex<:Rational>

function: id
parameters: a: any

/*
 * Array constructor function, accepts any number of arguments.
 */
function: array_
parameters: *data: any

Short form declarations

In data type, function, typeclass and typeclass implementation declarations it is possible to write the (type) parameter list and (for functions) the return value directly in the same line the object is declared instead of using separate parameters, type parameters and returns keys.

The parameter list follows the ID of the declared object in parentheses. Optionally, this is followed by -> and then the return value.

Examples

function: add.integer(a: numbers.integer, b: numbers.integer) -> :numbers.integer

function: div.complex(a: numbers.complex<:Rational>, b: numbers.complex<:Rational>) -> :numbers.complex<:Rational>

function: id(a: any)

/*
 * Array constructor function, accepts any number of arguments.
 */
function: array_(*data: any)

Code snippets

Code snippets are sections of raw code found in the sygnm package descriptor files which will be directly copied into the generated code. A code snippet begins with an opening tag which must stand alone in a line. The code generator will process the following lines as raw code until a corresponding end tag is reached.

Begin/end tag

Contexts

Description

begin-cpp-top/end-cpp-top

package

Raw C++ code that will be inserted into the top of the generated package header file (but still in the package namespace), directly after the forward declarations.

begin-cpp-global/end-cpp-global

package

Raw C++ code that will be inserted into the top of the generated package header file, outside the package namespace.

begin-cpp/end-cpp

package, data type, renderer, parser, I/O interface

Raw C++ code that will be inserted into the generated package header file.

begin-swig/end-swig

package

Raw SWIG declarations that will be inserted into the generated SWIG interface file.

Documentation

Documentations snippets are written directly into the package descriptor files, preceding the declarations they document. All declarations can be documented. The documentation uses C-style comment syntax. The documentation should use LaTeX notation for math. The documentation of any sygnm object can be divided into multiple sections, which are separated by lines which only contain a @ mark followed by the name of the section to be opened (see example). The default section is 'main'. A section ends when another section is opened or the end of the comment is reached. Standalone documentation pages which do not belong to any object can also be included in a package.

The following sections are recognized (not all sections are applicable for all object types):

Section name

Description

main

The main text of the documentation. This is the default section.

title

Title of the documentation page.

id

ID of the documentation page.

summary

Summary.

categories

List of categories this objects belongs to (one in a line, see example).

tags

Comma-separated list of tags.

related-funcs

IDs of related functions.

related-types

IDs of related data types.

related-types

IDs of related data types.

related-pages

IDs of related documentation pages.

related-typeclasses

Names of related typeclasses.

todo

TODO list (for developers).

limitations

Technical limitations.

impl-details

Implementation details.

examples

Examples.

new-in

The version where the documented object was first introduced.

references

List of external references.

ignore

Special section, its contents won't appear in the documentation. Useful for (non-documentation) comments in package descriptor files.

Macros

There are cases where the same few lines will appear in the same form in the documentation of lots of objects. Instead of copy and pasting the repeating lines, a macro can be used. Macros are searched for in the docmacros subdirectory of the directory which holds the package descriptor files. A macro is a text file with txt extension. The name of the macro is the name of the file (without the extension). Macros can have parameters, which will be inserted into the text using the synatx of the Python format function. In the documentation, a macro line starts with @@, followed by the name of the macro, then the parameters (if any), separated by @@ sequences (see the example below). Macro lines are replaced in the generated documentation with the contents of the macro.

Example

In the following example, a package declaration is documented. Some sections (main, categories, tags, references) are used while the others are left empty.

/*
 * @ignore
 * This line won't appear in the documentation.
 * This will not either.
 * @main
 * This will.
 */

/*
 * Boolean data type and basic operations.
 * @@example_macro_name@@param1@@param2
 * @categories
 * Logic
 * @tags
 * logic, boolean
 * @references
 * Boolean algebra (https://en.wikipedia.org/wiki/Boolean_algebra)
 */
package: boolean

Package size limits

There is no hard limit on how many functions (or data types and other objects) can a package contain, however in practice it is not recommended to have more than 1000 in a single package to avoid extremely large generated code size and excessive resource usage during compilation. Large packages can always be broken up into multiple smaller ones.