Some of the options are still experimental. Momentarily an effort is made to rationalize the options, so this may change at some point in the near future.

Since Ampersand-v3.5.3, it is possible to use a configuration file, reducing the need to rewrite the same options every time you use ampersand.exe. A configuration file can be used using the --config option.

This text may deviate slightly from the Ampersand version you are running, especially as new options are introduced. The command ampersand --help will give you the actual list.

-h, -?, --help

Print a usage message briefly summarizing the most common command-line options and the bug-reporting address, then exit. When used in combination with --verbose, it shows all command-line options. Use this to get the actual list of options of your Ampersand compiler.

-V, --version

Print the version number of Ampersand to the standard output stream. Please mention this information in every bug report you submit (see below).

Other options

--ECA

generate documentation with ECA rules.

--add-semantic-metamodel

The metamodel in Formal-ampersand is loaded together with your own model. Use this feature in conjunction with --meta-tables to get a metamodel populated with your own script into the database.

--altGraphics

generate graphics in an alternate way. (you may experiment with this option to see the differences for yourself)

--atlas-without-terms

Temporary option to create an Atlas without terms. This feature is used in RAP3 for performance reasons.

--blackWhite

do not use colors in generated graphics. Use this feature if you must print in black and white, to obtain better results than printing a colored source on a black-and-white printer.

--config=config.yaml

By default, the Ampersand compiler looks in the working directory for a config file (.yaml) with the same filename as the Ampersand script. Use this feature to redirect to another file. Use --sampleConfigFile to get a template.

--crowfoot

generate crowfoot notation in conceptual models. This is used to better match the preferences of some database engineers in the generated documentation.

--crud-defaults=CRUD

Set the default CRUD function for services. This function is explained in interface terms. This feature is used temporarily to gain experience with CRUD and learn about its semantics.

--customizations=DIRECTORY [, DIRECTORY]*

copy one or more directories into the generated prototype. This overrules the default directory, which is called customizations.

--dbName=NAME (-d)

database name. Use this for choosing the name of the SQL database. This overrules the environment variable CCdbName. It defaults to the filename of your Ampersand script.

--dev, --ignore-invariant-violations

Allow building a prototype, even if there are invariants that are being violated. (See issue 728 on Github)

--diagnosis

diagnose your Ampersand script. Use this if you wish to generate a document containing only the diagnosis chapter.

--do-not-trim-cellvalues

Do not ignore leading and trailing spaces in .xlsx files that are INCLUDED in the script. Normally, Ampersand removes spaces around cell values in .xlsx files when transforming the cell value to atoms. Use this to enforce that spaces around cell values are meaningful.

--export[=file] (-e)

export as plain Ampersand script.

--force-reinstall-framework

re-install the prototype framework. This discards any previously installed version. Use this to eradicate any doubt about a fresh reinstall.

--fpa

Generate Function Point Analysis chapter. Use this to include a measure of the functional complexity (size) of the generated application into your functional specification document. This feature is currently out of order.

--fpa-excel

generate an Excel workbook (FPA_<filename>.xml). Use this to obtain the base data used in the function point analysis. This feature is currently out of order.

--fspec=FORMAT (-f)

generate a functional design document in specified output format (FORMAT=[Asciidoc, Context, Docbook, Docx, Html, Latex, Man, Markdown, Mediawiki, Opendocument, Org, Pandoc, Pdf, Plain, Rst, Rtf, Texinfo, Textile]). Use this to obtain documentation in the format of your own choice.

--gen-as-rap-model

generate populations for use in RAP3.

--haskell

generate internal data structure, written in Haskell. Use this for debugging.

--help (-h, -?)

get (this) usage information.

--services (-x)

generate services. This feature does not work properly at the moment.

--language=LANG

Pick 'NL' for Dutch or 'EN' for English, as the language to be used in your output. Without this option, the output is written in the language of your context. Text snippets in other languages than the one specified are ignored. Use this to get a functional specification in the language of your choice.

--meta-file

Generate a .adl file that contains the relations of formal-ampersand, populated with the meta-population of your own .adl model.

--meta-tables

Populate the metamodel of Ampersand with the contents of your own script. Use this feature in conjunction with --add-semantic-metamodel to get a metamodel populated with your own script into the database. This is used for higher-order purposes, specifically in RAP3.

--namespace=NAMESPACE

prefix database identifiers with this namespace, in order to isolate namespaces within the same database. This feature was used in RAP2 to isolate students' work in separate tables.

--newNormalizer

Use the new optimizer at your own risk. Used for research purposes.

--noDiagnosis

omit the diagnosis chapter from the functional design document.

--noGraphics

omit the generation of graphics during the generation of the functional design document.

--oldNormalizer

use the old optimizer at your own risk. Used for research purposes.

--outputDir=DIR (-o)

output directory. Use this if you want the Ampersand compiler to redirect the output to a location of your choice. This overrules the environment variable CCdirOutput.

--pop-xlsx

Generate a .xmlx file containing the populations of your script. Meant to be used as an Excel-file in which you can add bulk data and reuse that for loading the data into your application.

--proofs

generate derivations in HTML-format. Use this to see how Ampersand derives computer instructions from your rules.

--proto[=DIRECTORY] (-p)

generate an information system. Use this to verify your analysis or to obtain a working prototype from your Ampersand script. In some cases, the result will be good enough for production. This option overrules the environment variable CCdirPrototype.

--prototype-framework-version=VERSION

tag, branch or SHA of the prototype framework on Github. Use this to select a specific version when generating an information system.

--reference-table

generate a table of references in the Natural Language chapter, for instance for legal traceability.

--sampleConfigFile

write a sample configuration file (sampleconfig.yaml). Use this to save yourself the trouble of looking up an example configuration file.

--sql-bin-tables

generate binary tables only in the SQL database. Use this to verify that the generated system works with binary tables as well as with wide tables.

--sqlHost=HOSTNAME

set SQL hostname (Defaults to `localhost`). Use this to let the generated system know which database to connect to.

--sqlLogin=USER

set SQL user name (Defaults to `ampersand`). Use this to let the generated system log into the database.

--sqlPwd=PASSWORD

set SQL password (Defaults to `ampersand`). Use this to let the generated system log into the database.

--sqldump

generate a dump of SQL queries. Use this for debugging purposes.

--test

Used for test purposes only.

--testRule=RULE

Show contents and violations of specified rules. Use this for diagnostic purposes.

--uml

Use this to generate conceptual models as a UML 2.0 data model.

--validate

Compare results of rule evaluation in Haskell and SQL. Use this to debug the SQL code generator to validate the meaning of all rules, which are evaluated both in the compiler and in the database. This option requires command-line PHP with MySQL support.

--verbose (-V)

run the compiler in verbose mode. Use this for diagnostic purposes.

--version (-v)

show version and exit. Please use this when reporting bugs on Github.

You configure the precise actions of the compiler by specifying on the command line. If you use the same configuration frequently, consider using a configuration file, so you don't have to remember all these options each time you call the compiler. The configuration file sits in the same directory as your model.

Commands without a script

1. ampersand --version to find out which version of Ampersand you are using.

2. ampersand --help to summarize all level one commands

Commands with a script

In practice, run ampersand --help instead of consulting the following list, just to be sure that the commands match the version you are using. The following list has been taken from version 4.0.0.

The general structure of commands is ampersand [options]* COMMAND. The following commands are available:

1. ampersand [options]* check <filename>

   Check your model for syntax errors and type errors.

2. ampersand [options]* daemon <filename>

   Check your model continuously while editing it.

3. ampersand [options]* data-analysis <filename>

   Export a data model as a plain Ampersand script, for analyzing Excel data.

4. ampersand [options]* dev-output <filename>

   Generate some diagnostic files, intended for developers of Ampersand.

5. ampersand [options]* documentation <filename>

   Generate a functional design document, to kick-start your functional specification.

6. ampersand [options]* population <filename>

   Generate a .xmlx file containing the populations of your script.

7. ampersand [options]* proofs <filename>

   Generate a report containing proofs.

8. ampersand [options]* proto <filename>

   Generate a prototype from your specification.

9. ampersand [options]* export <filename>

   Generate a single .adl-file of your script (prettyprinted)

10. ampersand [options]* uml <filename>

    Generate a data model in UML 2.0 style.

11. ampersand [options]* validate <filename>

    Compare results of rule evaluation in Haskell and SQL, for testing expression semantics. This requires command line PHP with MySQL support.

12. ampersand [options]* test <filename>

    Run test suites in a given directory. This is meant to do regression testing during automatic build (e.g. Travis-ci)

Filename

The filename in a command typically has suffix .adl (which stands for Ampersand Description Language). If you omit the suffix .adl, Ampersand does NOT add it for you. The filename conventions of your operating system apply (whether you have Windows, macOS, or Linux).

Options

You may use one of the first three options to specify how verbose your output will be. The other options can be used at random and mixed freely.

1. --help Show the help text. This is always up to date with the version of the compiler you are running. So consider ampersand --help to be authoritative.

2. --verbosity VERBOSITY

   Verbosity: silent, error, warn, info, debug

3. -V, --verbose

   Enable verbose mode: verbosity level "debug"

4. --silent

   Enable silent mode: verbosity level "silent"

5. --[no-]time-in-log

   Enable/disable inclusion of timings in logs, for the purposes of using diff with logs (default: enabled)

6. --[no-]terminal

   Enable/disable overriding terminal detection in the case of running in a false terminal

7. --terminal-width INT

   Specify the width of the terminal, used for pretty-print messages

8. --outputDir DIR

   Specify the directory where your output will be written to.

Options per command

Every command can have options of its own. Use the command and add --help to see which command specific options there are.

Example:

documentation % ampersand documentation --help
Usage: ampersand documentation [--blackWhite] [--[no-]Intro] [--[no-]SharedLang]
                               [--[no-]Diagnosis] [--[no-]ConceptualAnalysis] 
                               [--[no-]DataAnalysis] [--[no-]graphics] 
                               [--[no-]text] --format FORMAT AMPERSAND_SCRIPT 
                               [--sql-bin-tables] [--interfaces] 
                               [--namespace NAMESPACE] [--crud-defaults CRUD] 
                               [--[no-]trim-cellvalues] [--build-recipe RECIPE] 
                               [--ignore-invariant-violations] 
                               [--language OUTPUTLANGUAGE] [--[no-]legal-refs] 
                               [--verbosity VERBOSITY | (-v|--verbose) | 
                                 --silent] [--[no-]time-in-log] 
                               [--[no-]terminal] [--terminal-width INT] 
                               [--output-dir DIR] [--help]
  Generate a functional design document, to kick-start your functional
  specification.

Available options:
  --blackWhite             avoid coloring conventions to facilitate readable
                           pictures in black and white.
  --[no-]Intro             Do or do not include chapter Intro in the generated
                           document.
  --[no-]SharedLang        Do or do not include chapter SharedLang in the
                           generated document.
  --[no-]Diagnosis         Do or do not include chapter Diagnosis in the
                           generated document.
  --[no-]ConceptualAnalysis
                           Do or do not include chapter ConceptualAnalysis in
                           the generated document.
  --[no-]DataAnalysis      Do or do not include chapter DataAnalysis in the
                           generated document.
  --[no-]graphics          Enable/disable generation of graphics before
                           generating the document. (default: enabled)
  --[no-]text              Enable/disable generation the document file.
                           (default: enabled)
  --format FORMAT          The format in which the output is written.
  AMPERSAND_SCRIPT         The root file of your Ampersand model.
  --sql-bin-tables         Generate binary tables instead of broad tables in SQL
                           database, for testing purposes.
  --interfaces             Generate interfaces, which currently does not work.
  --namespace NAMESPACE    Prefix database identifiers with this namespace, to
                           isolate namespaces within the same
                           database. (default: "")
  --crud-defaults CRUD     Temporary switch to learn about the semantics of crud
                           in interface expressions. (default: "CRUD")
  --[no-]trim-cellvalues   Enable/disable ignoring the leading and trailing
                           spaces in .xlsx files that are INCLUDED in the
                           script. (default: enabled)
  --build-recipe RECIPE    Build the internal FSpec with a predefined recipe.
                           Allowd values are:
                           [Standard,Grind,Prototype,RAP] (default: "Standard")
  --ignore-invariant-violations
                           ignore invariant violations. In case of the prototype
                           command, the generated prototype might not behave as
                           you expect. Documentation is not affected. This means
                           that invariant violations are reported anyway. (See
                           https://github.com/AmpersandTarski/Ampersand/issues/728)
  --language OUTPUTLANGUAGE
                           Pick 'NL' for Dutch or 'EN' for English, as the
                           language to be used in your output. Without this
                           option, output is written in the language of your
                           context.
  --[no-]legal-refs        Enable/disable generation of a table of legal
                           references in Natural Language chapter of the output
                           document. (default: disabled)
  --verbosity VERBOSITY    Verbosity: silent, error, warn, info, debug
  -v,--verbose             Enable verbose mode: verbosity level "debug"
  --silent                 Enable silent mode: verbosity level "silent"
  --[no-]time-in-log       Enable/disable inclusion of timings in logs, for the
                           purposes of using diff with logs (default: enabled)
  --[no-]terminal          Enable/disable overriding terminal detection in the
                           case of running in a false terminal
  --terminal-width INT     Specify the width of the terminal, used for
                           pretty-print messages
  --output-dir DIR         Specify the directory where your output will be
                           written to
  --help                   Show this help text

Purpose

In many situations, you can avoid running the Ampersand compiler from the command line. For instance, by using a system such as RAP. However, in situations that you run Ampersand from the command line, this page is the place to be.

Prerequisites

We assume you have docker running on your computer and that you are connected to the internet. In that case you don't have to install anything.

COMMAND

The following is the base command on Linux (works for bash as well as zsh)

docker run -it -v $(pwd):/scripts ampersandtarski/ampersand

On the Windows-10 command-line this looks slightly different (todo: check this!)

docker run -it -v $PWD:/scripts ampersandtarski/ampersand

This runs the Ampersand compiler (from your command prompt). The first time you do this, docker will take some time to download the images it needs.

SYNOPSIS

docker run -it -v "$(pwd)":/scripts ampersandtarski/ampersand COMMAND [OPTIONS] FILE

In the sequel we will use ampersand as an alias for docker run -it -v "$(pwd)":/scripts ampersandtarski/ampersand

DESCRIPTION

The command ampersand takes a file as input. It must contain a valid ampersand script, i.e. a script that complies to the syntax and semantics of ampersand. The compiler will not generate any output unless the script is valid.

Environment variables

The standard behavior of ampersand is affected by the following environment variables.

• CCdbName Sets the name of the database that is to be generated. Can be overruled by --dbName

• CCdirOutput Sets the default output directory for generated assets. Can be overruled by --outputDir

• CCdirPrototype Sets the default directory where functional prototypes are being generated. Can be overruled by --proto

EXAMPLES

ampersand documentation --format docx --verbose Hawaii.adl  # generates a specification document for Hawaii.adl
ampersand check Delivery.adl                                # just check Delivery.adl for errors
ampersand proto --proto-dir "D:\htdocs\CvM\" Contracts.adl  # generate a prototype from Contracts.adl and write the application to the specified directory.
ampersand --help
ampersand --help --verbose
ampersand --version

BUGS

We are happy to receive bug reports at AmpersandTarski . However, please try to help us by first checking that it has not been reported already. You can do so by searching the issues. When in doubt however, don't hesitate to create a new issue.

Exit status

In case the Ampersand compiler is called by software and fails, it is useful to have an exit code to give some information about the nature of the failure. The Ampersand compiler produces the following exit codes: