ggc.1

.TH ggc 1 2015-10-01
.SH SYNOPSIS
.B ggc
[input1.gg ... inputn.gg] > output.py
.SH DESCRIPTION
.B ggc
is a generative grammar compiler. It converts grammars written in a simple domain-specific language to python code for generating strings that could be described by those grammars.
.SH LANGUAGE
The GG language consists of a series of named rules. A named rule is a name associated with zero or more possible expansions.

A named rule is defined using the ':=' operator. For instance:

.RS
namedRule:=foo,bar,baz
.RE

can be expanded as 'foo', 'bar', or 'baz'.

Comments in GG begin with an octothorpe ('#').

Files can be included using '#include':

.RS
#include library.gg
.RE


Expansions can contain anonymous rules -- sets of expansions enclosed in braces ({}) -- as well as other named rules (which are prefixed with the dollar sign ('$')) and cached/static expansions of named rules (prefixed by two dollar signs).

Rule names can contain letters, numbers, and underscores. Because of python's naming rules, rule names must not begin with a number.

.SH EXTENSION
Python files can be imported using '#import':

.RS
#import library.py
.RE

Such a python file will be added into the output prior to all generated rules.

A named rule may be defined using a function using that name, taking no arguments and returning a string. For instance:

.RS
def digit(): return random.choice(["0", "1", "2", "3", "4", "5", "6", "7", "8", "9"])
.RE

is equivalent to the GG code:

.RS
digit:=0,1,2,3,4,5,6,7,8,9
.RE

A static/cached expansion may be defined by defining a string with the name "cached_" followed by the rule name.


.SH COPYING

GGC (c) 2015-2016, John Ohno.
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
    * Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in the
      documentation and/or other materials provided with the distribution.
    * Neither the name of the <organization> nor the
      names of its contributors may be used to endorse or promote products
      derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

.SH SEE ALSO
http://github.com/enkiv2/ggc