G programming language. For random text generation.

View project on GitHub


G programming language. For random text generation.

Getting Set Up

You will need python 2.7 installed to run Geval. You can check in the terminal.

$ python --version

Using the Geval REPL

Let’s take a look at the geval program:

$ ./geval.py -h
usage: geval.py [-h] [-f FILE] [--ast] [--tokens] [--context]

G language Read-Eval-Print-Loop (REPL)

optional arguments:
  -h, --help            show this help message and exit
  -f FILE, --file FILE  read a gn file instead of opening the repl
  --ast                 print the abstract syntax tree (AST) before evaluation
  --tokens              print tokens before evaluation
  --context             print context after evaluation

Of primary use is -f, the file command. Use this to load a file:

$ ./geval.py -f ./examples/planets.gn
Hello jupiter!

The repl will print a line of text for each non-code, non-empty line in the source file.

Otherwise, Geval launches into the REPL, which is a good place to test the functionality out.

Writing G

So, how do you write new generators?


Start geval:

$ ./geval.py

Enter some text and hit enter. Geval supports bare words.

>>> hi there!
hi there!

That’s not all though, G supports bare words throughout:

>>> @print(hi there!)
hi there!

You can declare and reference variables:

>>> @a: my variable
>>> @a
my variable

@ tells us that this is actual code, not text. If you’ve seen other programming languages, functions are basically the same. If you haven’t, don’t worry- they aren’t especially important for writing generators.

In G, functions use | to separate arguments:

>>> @add(1|2)

One important function is @table. Tables make up the bulk of a random generator, so you’ll be using this one a lot.

>>> @planets: @table(
...    mercury
...    | venus
...    | earth
...    | mars
...    | jupiter
...    | saturn
...    | neptune
...    | uranus
...    )
>>> @select(@planets)

You can also use the selector, otherwise known as a back-tick:

>>> `planets

The selector works for strings too:

>>> @a: hi there!
>>> `a
hi there!

You can even embed it in other strings:

>>> I hope I get to go to `planets one day!
I hope I get to go to mars one day!

Built-In Functions

Here’s a list of the commonly used functions:

  • @add: Add two numbers together
  • @all: TRUE if all arguments are TRUE
  • @any: TRUE if any argument is TRUE
  • @dice: Rolls a dice, eg 1d6, 2d8
  • @divide: Divide a number by another number
  • @equals: TRUE if both arguments are equivalent
  • @exit: Exits the program
  • @fn: Creates a new function
  • @if: If the first argument is TRUE, evaluate the second argument. Otherwise, evaluate the third argument.
  • @import: Loads context from another generator
  • @multiply: Multiply two numbers
  • @not: TRUE if argument is FALSE, TRUE otherwise
  • @print: Output the argument
  • @subtract: Subtract a number from another number

See the following pages for more information:

Advanced Usage


Tables are lazily evaluated, so their references can be reassigned later:

>>> @a: hi
>>> @b: @table(@a)
>>> @a: bye
>>> `b

They can also be recursively defined:

>>> @a: @table(A|B`a)
>>> `a

Development Plan

  • v0.1- Initial Release
  • v0.2- Tables update
    • Table subtypes (weighted, labeled)
    • Table operations (indexing, slicing, splicing)
    • Table syntax for easier table creation
  • v0.3- Functions update
    • @map, @reduce, @filter implementations
    • Better handling of function scope
  • v0.4- Math update
    • @abs, @sum, @product implementation
    • Floating point numbers
  • v0.5- Packaging update
    • Better handling of outside references
    • Improved @import behavior


I wrote G language to make my life simpler, and because I enjoy the art of random generation. However, I welcome others to provide suggestions, pull requests, etc.

I am mainly looking for:

  • example generators
  • core functionality suggestions
  • standard function library work
  • common generator libraries (colors, dice, etc)
  • bug reports
  • unit tests
  • test files and execution tests