nyacc/lang/README

Copyright (C) 2015-2019 Matthew R. Wette

Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved.  This file is offered as-is,
without any warranty.

The intention of this directory is to provide parsers for languages.
The parsers will be built with attributed grammar semantics.  The
parse tree will be in SXML format.

# Manifest

File		| Description
----------------|------------
README		| This file
TMPL		| directory of template files for new parsers
		|
nx-devel.texi	| documentation for "NX" languages
nx-lib.scm	| run-time library for nx-languages
nx-load.scm	|
nx-util.scm	| compile-time utilities for nx-languages
		|
c99		| demo and test routines for the C99 parser
ffi-help	| demo and test routines for the FFI helper
		|
calc		| calc demo parser and interpreter
		|
javascript	| parser and partial interpreter
mlang		| parser and partial interpreter for Octave / Matlab
tcl		| parser and partial interpreter for TCL
		|
ecmascript	| immature replacment parser for Guile's emcascript
julia		| partial parser for the Julia langauge
lua		| partial parser for the Lua language
python		| partial parser for python


# Examples

The examples should compile with 2.0.13 and later.

The typical contents are:
mach.scm	the grammar specification, dev parser and table generator
mach.d		a directory containing files of actions and tables 
		generated from procedures in mach.scm
body.scm	code included in parser.scm and sometimes mach.scm
parser.scm	provides the parser procedure, includes mach.d/* and body.scm
pprint.scm	pretty-printer
Umach.scm	code to rerun table generation and generate parsers

When Umach.scm is run it may generate:
,file.txt	file parser output tables, for debugging
,expr.txt	expression parser output tables, for debugging

The output is typically an AST with SXML syntax.  This has the grammar
@example
sexp => (symbol expr ...)
expr => sexp | string
@end example
@noindent
That is, the tree consists of s-expressions with the first element 
always symbol.  The first symbol in such a list may be referred to as
the @dfn{tag}.  The remaining elements are either lists or text strings.
The parsers will identifty numbers for example, but they will appear as
symbols with the source text string (e.g., @code{(float "2.13e4")}).

Tags may not consist of any of the characters
 @code{!"#$%&'()*+,/;<=>?@@[\]^`@{|@}~,} and may not start with
@code{.} or @code{-}.

The second element of a s-expression can be a list with the special
tag @code{@@}.  This indicates a list of attributes.  For example, if
a parser returned the following s-exp
@example
(add (fixed "12") (float "2.3"))
@end example
@noindent
then a type checker may convert it to the following:
@example
(add (@ (type "float")) (fixed-to-float (fixed "12")) (float "2.3"))
@end example

element conventions:
  (name "." ident)	-> `(sel ,$3 ,$1)	selection
  (expr "+" expr) 	-> `(add ,$1 ,$3)	arithmatic
  (ex ":" ex ":" ex)	-> `(colon ,$1 ,$5 ,$3)
  (id "=" ex) 		-> `(assign ,$1 ,$3)
  (id "+=" ex) 		-> `(add-assign ,$1 ,$3)

