Invoking Fandango

Invoking Fandango#

Running Fandango on our Example Spec#

To run Fandango on our “digits” example, create or download a file digits.fan with the “digits” grammar in the current folder.

Then, you can run Fandango on it to create inputs. The command we need is called fandango fuzz, and it takes two important parameters:

-f followed by the .fan file – for us, that is digits.fan;
-n followed by the number of inputs we want to have – say, 10.

This is how we invoke Fandango:

$ fandango fuzz -f digits.fan -n 10

And this is what we get:

Success! We have created 10 random sequences of digits.

Danger

Be aware that .fan files can contain Python code that is executed when being loaded. This code can execute arbitrary commands.

Caution

Only load .fan files you trust.

More Commands and Options#

Besides fandango fuzz, Fandango supports more commands, and besides -f and -n, Fandango supports way more options. To find out which commands Fandango supports, try

$ fandango --help

Warning

Fandango commands not detailed in this documentation are experimental – do not rely on them.

To find out which option a particular command supports, invoke the command with --help. For instance, these are all the options supported by fandango fuzz:

$ fandango fuzz --help

usage: fandango fuzz [-h] [-f FAN_FILE] [-c CONSTRAINT] [--no-cache]
                     [--no-stdlib] [-s SEPARATOR] [-I DIR] [-d DIRECTORY]
                     [-x FILENAME_EXTENSION]
                     [--format {string,bits,tree,grammar,value,repr,none}]
                     [--file-mode {text,binary,auto}] [--validate]
                     [-S START_SYMBOL] [--warnings-are-errors]
                     [-N MAX_GENERATIONS] [--population-size POPULATION_SIZE]
                     [--elitism-rate ELITISM_RATE]
                     [--crossover-rate CROSSOVER_RATE]
                     [--mutation-rate MUTATION_RATE]
                     [--random-seed RANDOM_SEED]
                     [--destruction-rate DESTRUCTION_RATE]
                     [--max-repetition-rate MAX_REPETITION_RATE]
                     [--max-repetitions MAX_REPETITIONS]
                     [--max-node-rate MAX_NODE_RATE] [--max-nodes MAX_NODES]
                     [-n NUM_OUTPUTS] [--best-effort] [-i INITIAL_POPULATION]
                     [-o OUTPUT] [--input-method {stdin,filename}]
                     [command] ...

options:
  -h, --help            show this help message and exit
  -f, --fandango-file FAN_FILE
                        Fandango file (.fan, .py) to be processed. Can be
                        given multiple times. Use '-' for stdin
  -c, --constraint CONSTRAINT
                        define an additional constraint CONSTRAINT. Can be
                        given multiple times.
  --no-cache            do not cache parsed Fandango files.
  --no-stdlib           do not use standard library when parsing Fandango
                        files.
  -s, --separator SEPARATOR
                        output SEPARATOR between individual inputs. (default:
                        newline)
  -I, --include-dir DIR
                        specify a directory DIR to search for included
                        Fandango files
  -d, --directory DIRECTORY
                        create individual output files in DIRECTORY
  -x, --filename-extension FILENAME_EXTENSION
                        extension of generated file names (default: '.txt')
  --format {string,bits,tree,grammar,value,repr,none}
                        produce output(s) as string (default), as a bit
                        string, as a derivation tree, as a grammar, as a
                        Python value, in internal representation, or none
  --file-mode {text,binary,auto}
                        mode in which to open and write files (default is
                        'auto': 'binary' if grammar has bits or bytes, 'text'
                        otherwise)
  --validate            run internal consistency checks for debugging
  -o, --output OUTPUT   write output to OUTPUT (default: stdout)

general settings:
  -S, --start-symbol START_SYMBOL
                        the grammar start symbol (default: `<start>`)
  --warnings-are-errors
                        treat warnings as errors

algorithm settings:
  -N, --max-generations MAX_GENERATIONS
                        the maximum number of generations to run the algorithm
  --population-size POPULATION_SIZE
                        the size of the population
  --elitism-rate ELITISM_RATE
                        the rate of individuals preserved in the next
                        generation
  --crossover-rate CROSSOVER_RATE
                        the rate of individuals that will undergo crossover
  --mutation-rate MUTATION_RATE
                        the rate of individuals that will undergo mutation
  --random-seed RANDOM_SEED
                        the random seed to use for the algorithm
  --destruction-rate DESTRUCTION_RATE
                        the rate of individuals that will be randomly
                        destroyed in every generation
  --max-repetition-rate MAX_REPETITION_RATE
                        rate at which the number of maximal repetitions should
                        be increased
  --max-repetitions MAX_REPETITIONS
                        Maximal value, the number of repetitions can be
                        increased to
  --max-node-rate MAX_NODE_RATE
                        rate at which the maximal number of nodes in a tree is
                        increased
  --max-nodes MAX_NODES
                        Maximal value, the number of nodes in a tree can be
                        increased to
  -n, --num-outputs, --desired-solutions NUM_OUTPUTS
                        the number of outputs to produce (default: 100)
  --best-effort         produce a 'best effort' population (may not satisfy
                        all constraints)
  -i, --initial-population INITIAL_POPULATION
                        directory or ZIP archive with initial population

command invocation settings:
  --input-method {stdin,filename}
                        when invoking COMMAND, choose whether Fandango input
                        will be passed as standard input (`stdin`) or as last
                        argument on the command line (`filename`) (default)
  command               command to be invoked with a Fandango input
  args                  the arguments of the command

Some of these options are very useful, such as -o and -d, which redirect the inputs generated towards individual files. You can also specify a command to be executed with the inputs Fandango generated.

We will go through these commands and options in due time. For now, let us get back to our specifications and actually fuzz with Fandango.

Invoking Fandango

Contents

Invoking Fandango#

Running Fandango on our Example Spec#

More Commands and Options#