GreyScript Compiler (1.0.5)
Author: Ilazki
---------------------------
GreyScript Compiler (gsc) is an alternative to using the default /bin/build
command to compile sources.
The primary advantage of gsc is its use of pragmas to extend GreyScript with
new, unofficial features. Pragmas are special comments of the form "//#" that
have special meaning to gsc and can be used to modify its behaviour.
Currently, the only supported pragma (and the reason for gsc existing) is
//#open, which can be used to load additional files before compilation.
USAGE
-----
Usage: gsc [switches] <source file> [output path]
-h --help Print this message and exit
-v --version Print version information and exit
-o --output Path of output file. Current directory
used if omitted.
--src Generate source file and exit. Skips the
compilation step.
-I --include Comma-separated list of directories to
search for libs. Example: -I=lib,src
Current directory and 'lib' are searched
even if no include switch provided.
Unlike build, the output path is optional in gsc; if one is not provided,
current_path is used. That means gsc can be used as a drop-in replacement for
build, or as a way to save a few keystokes on builds.
OPEN PRAGMA
-----------
The open pragma is used in a greyscript file like so:
//#open util.src
//#open misc.src
When gsc reads a source file, it checks for any open pragmas at the start of
the file and replaces them with the contents of the files themselves. Opened
files can also contain additional open pragmas; if multiple files open the same
source, it is only included once to avoid bloating the final file with
unnecessary duplication.
For the sake of efficiency, open pragmas currently can only appear at the
beginning of a source file. Once a line without a pragma is encountered, gsc
stops reading the file and moves on to parsing its dependencies.
SEARCH PATH
-----------
By default, gsc checks the current directory and ./lib/ for files referenced by
open pragmas. Additional directories can be added to to the search path by
providing a comma-separated list of paths to the -I or --include switches at
the command line. (An //#include pragma may be added later.)
Subdirectories ARE NOT searched recursively. open pragmas can include
subdirectories in their name ("//#open foo/bar/file.src")
Example usage:
$ gsc file.src --include=src,lib,src/util
GOOD PRACTICES
--------------
Since gsc operates by merging multiple files into a single file and compiling
that, it is impossible to have separate namespaces for files. That means any
globals created in a library will be accessible by anything opening it; it's
also possible to unintentionally replace any of a library's functions and
variables by mistake.
Because of this, it's a good idea to organise scripts intended for re-use by
using maps as pseudo-namespaces. By creating a map with the same name as the
file, preferably with the first character in uppercase (as a convention to
denote a namespace), each library only adds a single name to the globals, with
everything else stored safely inside the map. Example:
String = {}
String.startswith = function (str,pred)
return str.indexOf(pred) == 0
end function
If a function is being called often enough that typing the full "namespace"
(e.g. "String.startswith()") is inconvenient, it can be assigned to a shorter
name in your code:
//#open String.src
s = @String.startswith
s("foobar","foo")
BUILDING
--------
gsc is organised and built using itself. For bootstrapping purposes, a source
file generated by "gsc --src" is provided for use with build:
$ build gsc_generated.gst /bin/
RUN.GSC
-------
Usage: run <src> [src args]
An extra utility that compiles <src> and then passes [src args] through to it,
intended to simplify save-and-run development in-game. If /bin/gsc exists it
will use gsc to build, with the shell.build API used as a fallback.