Macro API

Macro
Description
ALICE_MAIN
Alice main routine.
ALICE_ADD_STORE
Adds a store.
ALICE_DESCRIBE_STORE
Returns a one-line string to show when printing store contents.
ALICE_PRINT_STORE
Prints a store element to the terminal.
ALICE_PRINT_STORE_STATISTICS
Prints statistics about a store element to the terminal.
ALICE_LOG_STORE_STATISTICS
Prints statistics about a store element to the terminal.
ALICE_CONVERT
Converts store element into another store element.
ALICE_SHOW
Shows store element.
ALICE_STORE_HTML
Generates HTML output for a store element.
ALICE_ADD_COMMAND
Add a command.
ALICE_COMMAND
Add and implements a simple command.
ALICE_READ_FILE
Read from a file into a store.
ALICE_WRITE_FILE
Write to a file from a store.
ALICE_ADD_FILE_TYPE
Registers a file type to alice.
ALICE_ADD_FILE_TYPE_READ_ONLY
Registers a read-only file type to alice.
ALICE_ADD_FILE_TYPE_WRITE_ONLY
Registers a write-only file type to alice.
ALICE_MAIN(prefix)

Alice main routine.

The use of this macro is two-fold depending on whether alice is used for a stand-alone application or for creating a Python library:

  • In stand-alone application mode, this starts the interactive shell which accepts commands and replaces the C++ main method. The prefix in the shell will be taken from the first argument.
  • In Python mode, this method will create a Python module with name prefix.

Parameters
  • prefix: Shell prefix or python module name (depending on mode)

Stores

ALICE_ADD_STORE(type, _option, _mnemonic, _name, _name_plural)

Adds a store.

Adds a new store type alice. The first parameter is a type, all other parameters are for program arguments and help strings in the general store-related commands.

Parameters
  • type: A type to define the store
  • _option: Long option name to select store in general store commands
  • _mnemonic: Short option name (single character) to select store in general store commands (cannot be n or v)
  • _name: Singular name used in help texts
  • _name_plural: Plural name used in help texts

ALICE_DESCRIBE_STORE(type, element)

Returns a one-line string to show when printing store contents.

This macro is used to return a string that is shown in the output of store, when each store entry is listed with its index and a short one-line descriptiont text.

The macro must be followed by a code block.

Parameters
  • type: Store type
  • element: Reference to the store element

ALICE_PRINT_STORE(type, os, element)

Prints a store element to the terminal.

This macro is used to generate the code that is executed when calling print for a store.

The macro must be followed by a code block.

Parameters
  • type: Store type
  • os: Output stream (default is std::cout when in standalone mode)
  • element: Reference to the store element

ALICE_PRINT_STORE_STATISTICS(type, os, element)

Prints statistics about a store element to the terminal.

This macro is used to generate the output that is printed when calling ps for a store.

The macro must be followed by a code block.

Parameters
  • type: Store type
  • os: Output stream (default is std::cout when in standalone mode)
  • element: Reference to the store element

ALICE_LOG_STORE_STATISTICS(type, element)

Prints statistics about a store element to the terminal.

This macro is used to generate the JSON object that is logged when calling ps for a store element. The body must return an nlohmann::json object.

The macro must be followed by a code block.

Parameters
  • type: Store type
  • element: Reference to the store element

ALICE_CONVERT(from, element, to)

Converts store element into another store element.

This macro adds an implementation for conversion of a store element of type from to a store element of type to. It causes a new option --<from>_to_<to> for the convert command.

The macro must be followed by a code block.

Return
New store element
Parameters
  • from: Store type that should be converted from
  • element: Reference to the store element that should be converted
  • to: Store type that should be converted to

ALICE_SHOW(type, extension, os, element)

Shows store element.

This macro adds an implementation to show a store element using the command show. It implements the store API functions can_show and show.

The macro must be followed by a code block.

Parameters
  • type: Store type
  • extension: Default extension (for temporary filenames, without dot, e.g. "svg")
  • os: Output stream
  • element: Reference to the store element that should be shown

ALICE_STORE_HTML(type, element)

Generates HTML output for a store element.

This macro is only needed when the shell is used as a Python module inside an environment such as Jupyter notebooks. Then a specialized output can be configured for a store element when calling the print method on it. It implements the store API functions has_html_repr and html_repr.

The macro must be followed by a code block.

Parameters
  • type: Store type
  • element: Reference to the current store element

Commands

ALICE_ADD_COMMAND(name, category)

Add a command.

This macro adds a command to the shell interface. When this macro is called, a class of name <name>_command must have been defined that inherits from alice::command or some of its subclasses.

The command is accessible from the shell interface using name. In Python mode, the module will contain a function name.

Parameters
  • name: Name of the command
  • category: Category of the command (as shown in help)

ALICE_COMMAND(name, category, description)

Add and implements a simple command.

Unline ALICE_ADD_COMMAND, this macro can be used to also implement a simple command. However, it allows only to implement the code of the execute function, and therefore no customization of command arguments, validators, and logging is possible.

The macro must be followed by a code block.

Parameters
  • name: Name of the command
  • category: Category of the command (as shown in help)
  • description: Short description of the command (as shown in help)

ALICE_READ_FILE(type, tag, filename, cmd)

Read from a file into a store.

This macro adds an implementation for reading from a file into a store. Different file types may be supported, which are indexed using the tag.

The macro must be followed by a code block.

Parameters
  • type: Store type
  • tag: File tag
  • filename: Filename
  • cmd: Reference to the command line interface of the command

ALICE_WRITE_FILE(type, tag, element, filename, cmd)

Write to a file from a store.

This macro adds an implementation for writing to a file from a store. Different file types may be supported, which are indexed using the tag.

The macro must be followed by a code block.

Parameters
  • type: Store type
  • tag: File tag
  • element: Reference to the store element
  • filename: Filename
  • cmd: Reference to the command line interface of the command

ALICE_ADD_FILE_TYPE(tag, name)

Registers a file type to alice.

Calling this macro will mainly cause the addition of two commands read_<tag> and write_<tag> to alice to read from files and write to files. The actual implementation is done using ALICE_READ_FILE and ALICE_WRITE_FILE which will also associate store types to file tags.

Parameters
  • tag: File tag
  • name: Name that is used for help strings

ALICE_ADD_FILE_TYPE_READ_ONLY(tag, name)

Registers a read-only file type to alice.

Like ALICE_ADD_FILE_TYPE but only adds read_<tag>.

Parameters
  • tag: File tag
  • name: Name that is used for help strings

ALICE_ADD_FILE_TYPE_WRITE_ONLY(tag, name)

Registers a write-only file type to alice.

Like ALICE_ADD_FILE_TYPE but only adds write_<tag>.

Parameters
  • tag: File tag
  • name: Name that is used for help strings