Skip to content

Ilazki/gsc

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

12 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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.

About

GreyScript preprocessor

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages