Fandango Command Reference#
All Commands#
Here is a list of all fandango commands:
usage: fandango [-h] [--version] [--verbose | --quiet]
[--parser {python,cpp,legacy,auto}]
{fuzz,parse,talk,convert,clear-cache,shell,help,copyright,version} ...
The access point to the Fandango framework
options:
-h, --help show this help message and exit
--version Show version number.
--verbose, -v Increase verbosity. Can be given multiple times (-vv).
--quiet, -q Decrease verbosity. Can be given multiple times (-qq).
--parser {python,cpp,legacy,auto}
Parser implementation to use (default: 'auto': use C++
parser code if available, otherwise Python).
commands:
{fuzz,parse,talk,convert,clear-cache,shell,help,copyright,version}
The command to execute.
fuzz Produce outputs from .fan files and test programs.
parse Parse input file(s) according to .fan spec.
talk Interact with programs, clients, and servers.
convert Convert given external spec to .fan format.
clear-cache Clear the Fandango parsing cache.
shell Run an interactive shell (default).
help Show this help and exit.
copyright Show copyright.
version Show version.
Use `fandango help` to get a list of commands.
Use `fandango help COMMAND` to learn more about COMMAND.
See https://fandango-fuzzer.github.io/ for more information.
Fuzzing#
To produce outputs with fandango, use fandango fuzz:
usage: fandango fuzz [-h] [-f FAN_FILE] [-c CONSTRAINT] [-S START_SYMBOL]
[--max MAXCONSTRAINT] [--min MINCONSTRAINTS] [-I DIR]
[--file-mode {text,binary,auto}] [--no-cache]
[--no-stdlib] [-s SEPARATOR] [-d DIRECTORY]
[-x FILENAME_EXTENSION]
[--format {string,bits,tree,grammar,value,repr,none}]
[--validate] [-N MAX_GENERATIONS] [--infinite]
[--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 DESIRED_SOLUTIONS] [--best-effort]
[-i INITIAL_POPULATION] [--warnings-are-errors]
[--party PARTY] [-o OUTPUT]
[--input-method {stdin,filename,libfuzzer}]
[command] ...
options:
-h, --help show this help message and exit
-o, --output OUTPUT Write output to OUTPUT (default: stdout).
Fandango file settings:
-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.
-S, --start-symbol START_SYMBOL
The grammar start symbol (default: '<start>').
--max, --maximize MAXCONSTRAINT
Define an additional constraint MAXCONSTRAINT to be
maximized. Can be given multiple times.
--min, --minimize MINCONSTRAINTS
Define an additional constraint MINCONSTRAINT to be
minimized. Can be given multiple times.
-I, --include-dir DIR
Specify a directory DIR to search for included
Fandango files.
--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).
--no-cache Do not cache parsed Fandango files.
--no-stdlib Do not include the standard Fandango library.
Output settings:
-s, --separator SEPARATOR
Output SEPARATOR between individual inputs. (default:
newline).
-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.
--validate Run internal consistency checks for debugging.
Generation settings:
-N, --max-generations MAX_GENERATIONS
Maximum number of generations to run the algorithm
(ignored if --infinite is set).
--infinite Run the algorithm indefinitely.
--population-size POPULATION_SIZE
Size of the population.
--elitism-rate ELITISM_RATE
Rate of individuals preserved in the next generation.
--crossover-rate CROSSOVER_RATE
Rate of individuals that will undergo crossover.
--mutation-rate MUTATION_RATE
Rate of individuals that will undergo mutation.
--random-seed RANDOM_SEED
Random seed to use for the algorithm.
--destruction-rate DESTRUCTION_RATE
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, --desired-solutions, --num-outputs DESIRED_SOLUTIONS
Number of outputs to produce.
--best-effort Produce a 'best effort' population (may not satisfy
all constraints).
-i, --initial-population INITIAL_POPULATION
Directory or ZIP archive with initial population.
General settings:
--warnings-are-errors
Treat warnings as errors.
Party settings:
--party PARTY Only consider the PARTY part of the interaction in the
.fan file.
command invocation settings:
--input-method {stdin,filename,libfuzzer}
When invoking COMMAND, choose whether Fandango input
will be passed as standard input (`stdin`), as last
argument on the command line (`filename`) (default),
or to a libFuzzer style harness compiled to a shared
.so/.dylib object (`libfuzzer`).
command Command to be invoked with a Fandango input.
args The arguments of the command.
Parsing#
To parse inputs with fandango, use fandango parse:
usage: fandango parse [-h] [-f FAN_FILE] [-c CONSTRAINT] [-S START_SYMBOL]
[--max MAXCONSTRAINT] [--min MINCONSTRAINTS] [-I DIR]
[--file-mode {text,binary,auto}] [--no-cache]
[--no-stdlib] [-s SEPARATOR] [-d DIRECTORY]
[-x FILENAME_EXTENSION]
[--format {string,bits,tree,grammar,value,repr,none}]
[--validate] [--warnings-are-errors] [--party PARTY]
[--prefix] [-o OUTPUT]
[files ...]
positional arguments:
files Files to be parsed. Use '-' for stdin.
options:
-h, --help show this help message and exit
--prefix Parse a prefix only.
-o, --output OUTPUT Write output to OUTPUT (default: none). Use '-' for
stdout.
Fandango file settings:
-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.
-S, --start-symbol START_SYMBOL
The grammar start symbol (default: '<start>').
--max, --maximize MAXCONSTRAINT
Define an additional constraint MAXCONSTRAINT to be
maximized. Can be given multiple times.
--min, --minimize MINCONSTRAINTS
Define an additional constraint MINCONSTRAINT to be
minimized. Can be given multiple times.
-I, --include-dir DIR
Specify a directory DIR to search for included
Fandango files.
--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).
--no-cache Do not cache parsed Fandango files.
--no-stdlib Do not include the standard Fandango library.
Output settings:
-s, --separator SEPARATOR
Output SEPARATOR between individual inputs. (default:
newline).
-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.
--validate Run internal consistency checks for debugging.
General settings:
--warnings-are-errors
Treat warnings as errors.
Party settings:
--party PARTY Only consider the PARTY part of the interaction in the
.fan file.
Converting#
To convert existing language specs with fandango, use fandango convert:
usage: fandango convert [-h] [--party PARTY]
[--from {antlr,g4,dtd,010,bt,fan,auto}]
[--endianness {little,big}]
[--bitfield-order {left-to-right,right-to-left}]
[-o OUTPUT]
FILENAME [FILENAME ...]
positional arguments:
FILENAME External spec file to be converted. Use '-' for stdin.
options:
-h, --help show this help message and exit
--from {antlr,g4,dtd,010,bt,fan,auto}
Format of the external spec file: 'antlr'/'g4'
(ANTLR), 'dtd' (XML DTD), '010'/'bt' (010 Editor
Binary Template), 'fan' (Fandango spec), or 'auto'
(default: try to guess from file extension).
--endianness {little,big}
Set endianness for .bt files.
--bitfield-order {left-to-right,right-to-left}
Set bitfield order for .bt files.
-o, --output OUTPUT Write output to OUTPUT (default: stdout).
Party settings:
--party PARTY Only consider the PARTY part of the interaction in the
.fan file.
Interacting#
To have Fandango interact with programs and other parties, use fandango talk:
usage: fandango talk [-h] [-f FAN_FILE] [-c CONSTRAINT] [-S START_SYMBOL]
[--max MAXCONSTRAINT] [--min MINCONSTRAINTS] [-I DIR]
[--file-mode {text,binary,auto}] [--no-cache]
[--no-stdlib] [-s SEPARATOR] [-d DIRECTORY]
[-x FILENAME_EXTENSION]
[--format {string,bits,tree,grammar,value,repr,none}]
[--validate] [-N MAX_GENERATIONS] [--infinite]
[--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 DESIRED_SOLUTIONS] [--best-effort]
[-i INITIAL_POPULATION] [--warnings-are-errors]
[--client [NAME=][PROTOCOL:][HOST:]PORT]
[--server [NAME=][PROTOCOL:][HOST:]PORT]
[command] ...
positional arguments:
command Optional command to be interacted with.
args The arguments of the command.
options:
-h, --help show this help message and exit
--client [NAME=][PROTOCOL:][HOST:]PORT
Act as a client NAME (default: 'Client') connecting to
PORT on HOST (default: 127.0.0.1; use '[...]' for IPv6
addresses) using PROTOCOL ('tcp' (default)/'udp').
--server [NAME=][PROTOCOL:][HOST:]PORT
Act as a server NAME (default: 'Server') running at
PORT on HOST (default: 127.0.0.1; use '[...]' for IPv6
addresses) using PROTOCOL ('tcp' (default)/'udp').
Fandango file settings:
-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.
-S, --start-symbol START_SYMBOL
The grammar start symbol (default: '<start>').
--max, --maximize MAXCONSTRAINT
Define an additional constraint MAXCONSTRAINT to be
maximized. Can be given multiple times.
--min, --minimize MINCONSTRAINTS
Define an additional constraint MINCONSTRAINT to be
minimized. Can be given multiple times.
-I, --include-dir DIR
Specify a directory DIR to search for included
Fandango files.
--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).
--no-cache Do not cache parsed Fandango files.
--no-stdlib Do not include the standard Fandango library.
Output settings:
-s, --separator SEPARATOR
Output SEPARATOR between individual inputs. (default:
newline).
-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.
--validate Run internal consistency checks for debugging.
Generation settings:
-N, --max-generations MAX_GENERATIONS
Maximum number of generations to run the algorithm
(ignored if --infinite is set).
--infinite Run the algorithm indefinitely.
--population-size POPULATION_SIZE
Size of the population.
--elitism-rate ELITISM_RATE
Rate of individuals preserved in the next generation.
--crossover-rate CROSSOVER_RATE
Rate of individuals that will undergo crossover.
--mutation-rate MUTATION_RATE
Rate of individuals that will undergo mutation.
--random-seed RANDOM_SEED
Random seed to use for the algorithm.
--destruction-rate DESTRUCTION_RATE
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, --desired-solutions, --num-outputs DESIRED_SOLUTIONS
Number of outputs to produce.
--best-effort Produce a 'best effort' population (may not satisfy
all constraints).
-i, --initial-population INITIAL_POPULATION
Directory or ZIP archive with initial population.
General settings:
--warnings-are-errors
Treat warnings as errors.
Shell#
To enter commands in fandango, use fandango shell or just fandango:
usage: fandango shell [-h]
options:
-h, --help show this help message and exit
Clearing#
To have Fandango clear its parser cache, use fandango clear-cache:
usage: fandango clear-cache [-h] [-n]
options:
-h, --help show this help message and exit
-n, --dry-run Just output the action to be performed; do not actually clear
the cache.