First: you make a dssl like:

syntax extension { .. }

then you open it like:

open syntax extension;

Look in lib/nugram.flxh to see examples.

'page' and 'explain' are for generating documentation.

'requires' specifies other dssls as dependencies, which have to be opened before this one.

As an example production:

sfactor := sfactor . lsqb sexpr to rsqb =>#

"`(ast_apply ,_sr (copyfrom (,_1 ,_4)))"

;

extends the non-terminal 'sfactor', it defines the syntax for handling code like:

x .[ 20 to ]

Here lsqb is used instead of [ because [ is a special meta symbol. I think you can now write

sfactor . " sexpr to ?"

instead: this was a recent modification. Ok, so the Scheme code

`(ast_apply ,_sr (copyfrom (,_1 ,_4)))

is *executed*. The symbol _sr the source reference and has been put in the environment, similarly _1 _2 ... are the attributes of symbols 1 2 3 ... from the production: same as yacc/ocamlyacc's $1 $2 $3 ...

I can't teach Scheme since I only just learned it myself, but

`s ,s

are a quasi-quote and unquote. In other words

`(x ,y)

means a list of symbol x and then whatever y is bound to in the environment.

So the result is an OCS svalue something like

(ast_apply ("file" 10 1 10 10)

(copyfrom (

(ast_name x ()) (ast_literal (ast_int "int" 20))

))

)

This is converted to a sex-pression, which is then converted in

lpsrc/flx_sex2flx.ipk src/compiler/flxlib/flx_sex2flx.ml

to a Felix AST term documented in

lpsrc/flx_types.ipk src/compiler/flxlib/flx_ast.mli

You must study flx_sex2flx.ml to know the Felix AST terms and how they must be encoded in Ocaml, and thus in sex-pressions and thus in OCS values. For example this code:

| Lst [Id "ast_apply"; sr; Lst [e1; e2]] ->

`AST_apply(xsr sr,(ex e1, ex e2))

tells you that an application

f x

is encoded as a list of the symbol 'ast_apply', the source reference, and then the arguments as a nested list. The arguments to 'apply' here are f and x, so roughly:

`AST_apply (sr, (f, x))

is the Ocaml encoding, reflected in the sex-pression and thus the OCS svalue. In particular it is NOT

`AST_apply (sr, f, x)

with 3 arguments, but 2 arguments, the second of which is a pair of both the function and its argument: this was an arbitrary choice made years ago in the encoding of Felix AST terms.

For most of the types such as

Flx_ast.expr_t

which is the type of expression terms, there is a corresponding codec in Flx_sex2flx named like

xexpr_t

i.e. with an 'x' shoved onto the front of the type name. The codec builds an expr_t from suitable sex-pressions.

Actually the HARD bit is knowing what the Felix AST term semantics are. The other parts aren't separately documented because it would be pointless: the encoding is best explained by the actual Ocaml code, and the Ocaml code IS published by interscript on the web.

Well, the semantics of `AST_apply should be obvious: it's a function application. Most of the AST terms simply reflect the parse tree, the best way to understand their semantics is to find the grammar productions that generate them .. :)