Argile Bindings Documentation

[extracted from: arc (Argile Compiler) version 2.1.0]

std/anything

The anything type.

binding(s) from std.argl:

bind :any: to std / anything;
bind :anything: to std / anything;

std/autocast

Add a global automatic implicit type caster; takes a from and a to type parameters. When the reciprocal option is specified at binding, an additionnal caster is added (to and from types inverted). An optional code block can also be specified (except with reciprocal option) to call custom code at casts, then the from type parameter is defined in the block with the same syntax as the type itself.
Syntax requirements:
```
:<type from> <type to>:
:<type from> <type to> <code>:
```
binding(s) from std.argl:
```
- :autocast <type from> - > <type to> (<code>): - std / autocast;
- :autocast <type to> \< - <type from> (<code>): - std / autocast;
- :autocast <type> \< - > <type>: - std / autocast + reciprocal;
```

std/bind

Bind a syntax to a built-in function (called binding) as a new definition; needs a syntax parameter, a parameter named module (word or text) and a parameter named bind (word or text); a list of options (word parameter named option) can be specified to apply to the new definition. If the built-in does not exist, it will warn and bind to std/nil instead.

Syntax requirements:

:<syntax> <word module> <word bind>:
:<syntax> <text module> <text bind>:
:<syntax> {<text module>|<word module>} {<text bind>|<word bind>} [<word option>...]:

binding(s) from std.argl:

bind :bind <syntax> to {<word module> | <text module>} / {<word bind> | <text bind>} [+ <word option> ...]: to std / bind;
bind :- <syntax> - {<word module> | <text module>} / {<word bind> | <text bind>} [+ <word option> ...]: to std / bind;

std/callcode

Call an anonymous function, or dump a constant code block literal. If the code parameter is a constant code literal and some additional parameters are specified, it will be rejected.
Syntax requirements:
```
:<code>:
:<code>[<any>...]:
```
binding(s) from std.argl:
```
- :call <code> (with [<any> ... 1,]): - std / callcode;
```
std/cdata

Generate a data block, with its content separated by commas (',') instead of semicolons (';') used for code blocks. It takes a code literal, and optionally a return type: if it is a class type, the raw type will be returned; otherwise, an array of the type will be assumed, but the return type will match anything (laxist).
Syntax requirements:
```
:<code>:
:<type> <code>:
```
binding(s) from std.argl:
```
- :Cdata (<type>) <code>: - std / cdata;
```
std/class

Define a class type; takes a word or syntax parameter for the name, and a code block that must contain only calls to :<type> <word field> (/<nat>): (the natural option specifies the number of bits for the field). If a field has a raw value class type, then the sub class is included in the current (field by content instead of field by pointer). An optional type parameter can be used to specify a parent class, that makes an implicit field named _parent_ (so it can't be used for other fields). If the bind option union is specified, it will make an union instead of a class (in this case, the parent type will be ignored). If the bind option extern is set, the type will not be defined in C. If the bind option struct is set, no C typedef will be generated.
Syntax requirements:
```
:<word> <code>:
:<syntax> <code>:
:{<word>|<syntax>} (<type>) <code>:
```
binding(s) from std.argl:
```
- :class {<word> | <syntax>} (\< - <type>) <code>: - std / class;
- :extern class {<word> | <syntax>} (\< - <type>) <code>: - std / class + extern;
- :struct {<word> | <syntax>} (\< - <type>) <code>: - std / class + struct;
- :extern struct {<word> | <syntax>} (\< - <type>) <code>: - std / class + extern + struct;
- :union {<word> | <syntax>} <code>: - std / class + union;
- :extern union {<word> | <syntax>} <code>: - std / class + union + extern;
```
std/code

The code type.
binding(s) from std.argl:
```
bind :code: to std / code;
```
std/ctype

Define a new C type, by specifying C syntax; takes a word or syntax parameter for the name of the type, a text parameter for the C prefix, and an optional second text parameter for the C suffix. If the prefix is omitted, it will be guessed from syntax (or word). With bind option def a C-typedef will be generated at top level.
Syntax requirements:
```
:<word>:
:<word> <text>:
:<syntax> <text>:
:{<word>|<syntax>} <text> (<text>):
```
binding(s) from std.argl:
```
- :Ctype (<text>) {<word> | <syntax>} (<text>): - std / ctype;
- :Ctypedef (<text>) {<word> | <syntax>} (<text>): - std / ctype + def;
```
std/dig

Dig call path informations according to the syntax of the function or macro inside which this must be called (eg. Is third option set ? Which case of second enumeration is used ? ...); exactly one bind option must be specified amongst option, enum and list. It takes a natural(> 0) parameter and optionally, inside macros, other parameters depending on which bind option is set: With option, if a parameter of type anything is present, its code is generated when the call option is set, otherwise the code of the second parameter of type anything (if present) is generated; without these additional parameters, a 0 or 1 (int) is returned. With enum, the number (int) of the case is returned, except when a list of parameters of type anything is present, in which case the code of the parameter corresponding to the case is generated. With list, the length of list is returned, except when a list of parameters of type anything are used, in which case for each occurence in call path, generate code of each parameters specified, eventually separating them with a sep parameter.
Syntax requirements:
```
:<nat>:			  with option, enum or list
:<nat> <any> (<any>):		  with option
:<nat> [<any>...2,]:		  with enum
:<nat> [<any>...1,](<any sep>): with list
```
binding(s) from std.argl:
```
- :call option (<nat id = 1>): - std / dig + option;
- :call enum (<nat id = 1>): - std / dig + enum;
- :call list (<nat id = 1>): - std / dig + list;
- :? <nat>: - std / dig + option;
- :# <nat>: - std / dig + enum;
- :@ <nat>: - std / dig + list;
- :? ? <nat> <any> (<any>): - std / dig + option;
- :# # <nat> [<any> ... 2,]: - std / dig + enum;
- :@ @ <nat> [<any> ... 1,] (- sep <any sep>): - std / dig + list;
```
std/dump

Dump the known value of the first parameter (helps debugging macros).
Syntax requirements:
```
:<any>:
```
binding(s) from std.argl:
```
- :dump <any>: - std / dump;
```
std/enum

Define an enum type with a word (called name) or syntax, and a list of word called member, with an optional integer parameter value for each member. Instead of the list of word, a code block can be provided, in which calls will have to match :<word> (= <int>):.
Syntax requirements:
```
:{<syntax>|<word name>} <code>:
:{<syntax>|<word name>} [<word member>(=<int>)...]:
```
binding(s) from std.argl:
```
- :enum {<word name> | <syntax>} is [<word member> (= <int>) {, | .} ... 1,]: - std / enum;
- :enum {<word name> | <syntax>} <code>: - std / enum;
```
std/extdef

Make an external definition with a C identifier (word), a syntax and optionnally a type. If the binding option func is specified, an external function is defined, if not, an exnternal variable is defined. If the binding option Cmacro is specified, an external C macro is defined instead of a function or variable. This is used by modules interfaces (*.argl).
Syntax requirements:
```
:<word> <syntax> (<type>):
```
binding(s) from std.argl:
```
- :def var <word> <syntax> (- > <type>): - std / extdef;
- :def func <word> <syntax> (- > <type>): - std / extdef + func;
```
std/extern

Make an external definition with a C identifier (word), a syntax and optionnally a type. If a syntax is specified, a function is defined, if not, a variable is defined with the identifier as syntax. If no identifier is specified, the syntax must begin by a word which will be used as identifier. If the binding option nodecl is specified, no declaration will be generated.
Syntax requirements:
```
:<word> <syntax> (<type>):
:{<word>|<syntax>} (<type>):
```
binding(s) from std.argl:
```
- :extern {<word> | <syntax>} (- > <type>): - std / extern;
- :# extern {<word> | <syntax>} (- > <type>): - std / extern + nodecl;
```
std/field

Call a field of a class or union. It needs a word parameter (field name) and a parameter of type anything (the union or class instance).
Syntax requirements:
```
:<any> <word>:
```
binding(s) from std.argl:
```
- :<any> . <word>: - std / field;
- :[. <word> ... 1,] = <any>: - std / fieldset;
```
std/fieldset

Generate a field value set statment to be used inside a data block. Needs a word for field name and an anything parameter for its value. Also, it refuses to be called inside a subcall. The word parameter may be in a list to generate subfields
Syntax requirements:
```
:<word> <any>:
:[<word>...] <any>:
```
binding(s) from std.argl:
```
- :[. <word> ... 1,] = <any>: - std / fieldset;
```
std/fsym

Get the body code of a function; it needs a call to the function as parameter, but this does not actually call the function.
Syntax requirements:
```
:<any>:
```
binding(s) from std.argl:
```
- :code of <any>: - std / fsym;
```
std/funcdef

Define a function, a macro or an anonymous function. Needs a syntax, or a word (parameter-less function or macro). When the binding option macro is specified, it defines a macro instead of a function. When no word or syntax parameter is specified, an anonymous function is returned. If the binding option private is set, the definition is private to the module (not exported; equivalent to static in C). If the binding option Cmacro is set, it defines a C-macro (with #define) instead of a C function. May also return the function body code, when it's not a macro or C-macro.
Syntax requirements:
```
:( {<syntax>|<word>} ) (<type>) <code>:
```
binding(s) from std.argl:
```
- :. <syntax> . (- > <type>) <code>: - std / funcdef;
- :. . <syntax> . (- > <type>) <code>: - std / funcdef + private;
- :sub (<word>) (- > <type>) <code>: - std / funcdef;
- :our sub <word> (- > <type>) <code>: - std / funcdef + private;
- := <syntax> = (- > <type>) <code>: - std / funcdef + macro;
- := = <syntax> = (- > <type>) <code>: - std / funcdef + private + macro;
```
std/gencode

Generate code for all its arguments (in a list of any parameter), without separating them. If the binding option ref is set, and the first parameter is a text constant literal beginning by any number of `*' and `&' then they will be understood as address of/dereferencing C operators, and they will be compressed for a clearer C output. If the binding option no_semicolon is set, the next output line ending semicolon will be inhibited.
Syntax requirements:
```
:[<any>...]:
```
binding(s) from std.argl:
```
- :Cgen [<any> ... 1,]: - std / gencode;
```
std/genlist

Generate the list of values of each macro parameter contained in the first syntax list of any parameter named param. Options can be specified in a second list enumerating named parameters: sep for separator between values; nomatch when a parameter is missing, instead of nothing.
Syntax requirements:
```
:[<any param>...] [ {<any sep>|<any nomatch>} ...]:
```
binding(s) from std.argl:
```
- :[@ <any param> ... 1,] [{- sep <any sep> | - nomatch <any nomatch>} ...]: - std / genlist;
```
std/globally

Generate the content of a code block at the beginning of output
Syntax requirements:
```
:<code>:
```
binding(s) from std.argl:
```
- :globally <code>: - std / globally;
```
std/hinclude

Include a C source file (a C header). It takes a word or text parameter; if it's a word and the binding option dot_h is specified, a `.h' will be added to the end of the file name. The include takes place at the beginning of the output code. With the binding option system the #include will have <> instead of "".
Syntax requirements:
```
:{<word>|<text>}:
```
binding(s) from std.argl:
```
- :# include <text>: - std / hinclude;
- :# include \< {<word> | <text>} >: - std / hinclude + system;
- :# include \< <word> . h >: - std / hinclude + system + dot_h;
```
std/integer

The relative integer type.
binding(s) from std.argl:
```
bind :int: to std / integer;
```
std/natural

The natural integer type.
binding(s) from std.argl:
```
bind :nat: to std / natural;
```
std/nil

Return the null element of the expected context type.
binding(s) from std.argl:
```
- :nil: - std / nil;
- :: - std / nil;
```
std/nothing

The nothing type.
binding(s) from std.argl:
```
bind :nothing: to std / nothing;
```
std/print

Print its arguments without spaces between them using printf() and supports formatting for the basic types (int, nat, real, word, text, syntax); for other types, it prints a pointer address (%p format). It can also print spaces between arguments, if the bind option spaced is specified. If the bind option error is set, it will print on standard error rather than the default standard output. Only the first syntax parameter is considered, but it can be in a list.
Syntax requirements:
```
:<any>:
:[<any>...]:
```
binding(s) from std.argl:
```
- :print [<any> ...]: - std / print;
- :prints [<any> ...]: - std / print + spaced;
- :eprint [<any> ...]: - std / print + error;
- :eprints [<any> ...]: - std / print + error + spaced;
```
std/real

The real type.
binding(s) from std.argl:
```
bind :real: to std / real;
```
std/return

Return from current function, with an optional return value. If it is called from an anonymous function, it will also produce a call to va_end().
Syntax requirements:
```
:(<any>):
: <any&>:
```
binding(s) from std.argl:
```
- :return <(any) &>: - std / return;
- :return (<any>): - std / return;
```
std/set

Affect a value to a variable (or reference). It takes a parameter of type anything (for the value) and a parameter of type reference to anything (for the variable). This is deprecated and should be replaced by a macro.
Syntax requirements:
```
:<any&> <any>:
```
binding(s) from std.argl:
```
- :<(any) &> = <any>: - std / set;
- :set <(any) &> to <any>: - std / set;
```
std/shiftlist

Shift values of parameters, options, enumerations and lists contained in the syntax list identified by the parameter named id (which must be an integer > 0); an other parameter named by may be specified to shift values by more than one. This must be called inside a function or macro.
Syntax requirements:
```
:<nat id> (<nat by>):
```
binding(s) from std.argl:
```
- :shift call list (<nat id = 1>) (by <nat by = 1>): - std / shiftlist;
- :@ <nat id> \< \< <nat by>: - std / shiftlist;
```
std/stresc

Generate an escaped text string suitable for inclusion within a double quoted C string. Moreover, if the parameter evaluates to a word, it changes non-ascii characters into hexadecimal sequence.
Syntax requirements:
```
:<any>:
```
binding(s) from std.argl:
```
- :\\ <any>: - std / stresc;
```
std/strunquote

Generate the content of a constant text character string without quotes.
Syntax requirements:
```
:<any>:
```
binding(s) from std.argl:
```
- :unquote <text>: - std / strunquote;
```
std/super

Select a definition that is not local nor a recursive function call.
Syntax requirements:
```
:<any>:
:<any&>:
```
binding(s) from std.argl:
```
- :super <any>: - std / super;
- :super <(any) &>: - std / super;
```

std/syntax

The syntax type.

binding(s) from std.argl:

bind :syntax: to std / syntax;
- :syntax of <any>: - std / syntaxof;

std/syntaxof

Generate a quoted text string litteral containing the syntax of a given definition, delimiteed with two colons (`:').
Syntax requirements:
```
:<any>:
```
binding(s) from std.argl:
```
- :syntax of <any>: - std / syntaxof;
```
std/text

The text type.
binding(s) from std.argl:
```
bind :text: to std / text;
```

std/type

The type type.

binding(s) from std.argl:

bind :type: to std / type;
- :<type> &: - std / typeref;
- :<type> @: - std / typeraw;
- :type of <any>: - std / typeof;
- :<any> the <type>: - std / typeselect;
- :<(any) &> the <type>: - std / typeselect;
- :<any> as <type>: - std / typeconv;
- :<(any) &> as <type>: - std / typeconv;
- :<any> forced as <type>: - std / typeconv + explicit;
- :<(any) &> forced as <type>: - std / typeconv + explicit;
- :<any> . {<word> | <type>}: - std / typeparam;
- :<type> . prefix: - std / typefix + prefix;
- :<type> . suffix: - std / typefix + suffix;
- :<any> . <type>: - std / typeselect + union;
- :<(any) &> . <type>: - std / typeselect + union;

std/typeconv

Cast explicitly anything to a particular type. It needs a type parameter and a parameter of type anything, or a reference to anything. If the element to cast is a word, it will be quoted as a text string litteral; if it is a type, its number will be printed unless it is casted to text, in which case it will be quoted. If the binding option explicit is set, the type context will not be changed; so if syntax parameter type is anything, no implicit autocast will be called.
Syntax requirements:
```
:<any>  <type>:
:<any&> <type>:
```
binding(s) from std.argl:
```
- :<any> as <type>: - std / typeconv;
- :<(any) &> as <type>: - std / typeconv;
- :<any> forced as <type>: - std / typeconv + explicit;
- :<(any) &> forced as <type>: - std / typeconv + explicit;
```
std/typefix

Generate the prefix or the suffix of a type. If the binding option prefix is sepcified, the prefix of the type will be generated. If the binding option suffix is specified, the suffix of the type will be generated. If none or both of these options are specified, both the prefix and the suffix (in this order) will be generated.
Syntax requirements:
```
:<type>:
```
binding(s) from std.argl:
```
- :<type> . prefix: - std / typefix + prefix;
- :<type> . suffix: - std / typefix + suffix;
```
std/typeof

Return the type of the parameter.
Syntax requirements:
```
:<any>:
```
binding(s) from std.argl:
```
- :type of <any>: - std / typeof;
```
std/typeparam

Get a parameter that generated the C-type of the parameter of type anything, by name or by type; it corresponds to a parameter in the syntax of the type generating macro.
Syntax requirements:
```
:<any> { <word> | <type> }:
```
binding(s) from std.argl:
```
- :<any> . {<word> | <type>}: - std / typeparam;
```
std/typeraw

Return a raw value type from the given class type.
Syntax requirements:
```
:<type>:
```
binding(s) from std.argl:
```
- :<type> @: - std / typeraw;
```
std/typeref

Return a reference type from the given (non-reference) type, or the non-raw (and non-reference) version of a raw type.
Syntax requirements:
```
:<type>:
```
binding(s) from std.argl:
```
- :<type> &: - std / typeref;
```
std/typeselect

Select a definition to match a given type (this can be replaced by a macro). The binding option union can be specified to select a particular type field of an union.
Syntax requirements:
```
:<any> <type>:
:<any&> <type>:
```
binding(s) from std.argl:
```
- :<any> the <type>: - std / typeselect;
- :<(any) &> the <type>: - std / typeselect;
- :<any> . <type>: - std / typeselect + union;
- :<(any) &> . <type>: - std / typeselect + union;
```
std/union

Define a union type with a word or syntax, and a list of types. If the bind option silent is specified, a union will never generate a field name when called (e.g. foobar instead of `(foobar).u_int').
Syntax requirements:
```
:{<syntax>|<word>} [<type>...]:
```
binding(s) from std.argl:
```
- :union {<word> | <syntax>} is [<type> (or) ... 1,]: - std / union;
```
std/use

Use an external argile source file, importing its global definitions. It takes a first list containing either a word or text parameter, followed by a word or text parameter, which are file names (a `.argl' or `.arg' may be implicitely appended to match real file names). An optional second list of parameters of type syntax, followed by another parameter of type syntax, may be specified to tell which local definitions must be defined before including the list of source files. If the binding option include is set, the global definitions exported by the included file will also be exported when current file is used or included.
Syntax requirements:
```
:[ {<word>|<text>} , ...] {<word>|<text>} ([<syntax> , ...] <syntax>):
```
binding(s) from std.argl:
```
- :use [{<word> | <text>} , ...] {<word> | <text>} (exporting [{<syntax> | <any>} , ...] {<syntax> | <any>}): - std / use;
- :include [{<word> | <text>} , ...] {<word> | <text>} (exporting [{<syntax> | <any>} , ...] {<syntax> | <any>}): - std / use + include;
```

std/vardef

Define a variable, giving a name (word) or syntax, an optional type, and an optional initial value. Some of these parameters can also be in a list to define several variables in a single call. It is possible to add a second set of parameters (when the first one is in a list). If the binding option return is set, the last variable is returned. If the binding option private is set, the variables are made private to the file (static in C).

Syntax requirements:

:{<word>|<syntax>} (<type>) (<any>):
:<type> <any> [ {<word>|<syntax>} ... 1, ]:
:<type> [ {<word>|<syntax>} (<any>) ... 1, ]:
:[ (<type>) {<word>|<syntax>} (<any>) ... 1, ]:
:[ (<type>) {<word>|<syntax>} (<any>) ... 1, ] {<word>|<syntax>} (<any>):

binding(s) from std.argl:

- :let ((the) <type>) {<word> | <syntax>} ({= | be} <any>): - std / vardef;
- :our (<type>) {<word> | <syntax>} (= <any>): - std / vardef + private;
- :let {<word> | <syntax>} be ({a | an} <type>) (= <any>): - std / vardef;
- :let (<type>) [{<word> | <syntax>} (= <any>) , ... 1,] {<word> | <syntax>} (= <any>) (.): - std / vardef;
- :val (<type>) {<word> | <syntax>} (= <any>): - std / vardef + return;

std/word

The word type.
binding(s) from std.argl:
```
bind :word: to std / word;
```

Argile bindings documentation

[extracted from: arc (Argile Compiler) version 2.1.0]

std/anything

std/autocast

std/bind

std/callcode

std/cdata

std/class

std/code

std/ctype

std/dig

std/dump

std/enum

std/extdef

std/extern

std/field

std/fieldset

std/fsym

std/funcdef

std/gencode

std/genlist

std/globally

std/hinclude

std/integer

std/natural

std/nil

std/nothing

std/print

std/real

std/return

std/set

std/shiftlist

std/stresc

std/strunquote

std/super

std/syntax

std/syntaxof

std/text

std/type

std/typeconv

std/typefix

std/typeof

std/typeparam

std/typeraw

std/typeref

std/typeselect

std/union

std/use

std/vardef

std/word