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)
- In stand-alone application mode, this starts the interactive shell which accepts commands and replaces the C++
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 ben
orv
)_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 typeelement
: 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 typeos
: Output stream (default isstd::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 typeos
: Output stream (default isstd::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 annlohmann::json
object.The macro must be followed by a code block.
- Parameters
type
: Store typeelement
: 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 typeto
. It causes a new option--<from>_to_<to>
for theconvert
command.The macro must be followed by a code block.
- Return
- New store element
- Parameters
from
: Store type that should be converted fromelement
: Reference to the store element that should be convertedto
: 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 functionscan_show
andshow
.The macro must be followed by a code block.
- Parameters
type
: Store typeextension
: Default extension (for temporary filenames, without dot, e.g."svg"
)os
: Output streamelement
: 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 functionshas_html_repr
andhtml_repr
.The macro must be followed by a code block.
- Parameters
type
: Store typeelement
: 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 fromalice::command
or some of its subclasses.The command is accessible from the shell interface using
name
. In Python mode, the module will contain a functionname
.- Parameters
name
: Name of the commandcategory
: Category of the command (as shown inhelp
)
-
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 commandcategory
: Category of the command (as shown inhelp
)description
: Short description of the command (as shown inhelp
)
-
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 typetag
: File tagfilename
: Filenamecmd
: 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 typetag
: File tagelement
: Reference to the store elementfilename
: Filenamecmd
: 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>
andwrite_<tag>
to alice to read from files and write to files. The actual implementation is done usingALICE_READ_FILE
andALICE_WRITE_FILE
which will also associate store types to file tags.- Parameters
tag
: File tagname
: 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 addsread_<tag>
.- Parameters
tag
: File tagname
: 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 addswrite_<tag>
.- Parameters
tag
: File tagname
: Name that is used for help strings