Store API¶

Function	Description
to_string	Produce short one-line description of store element.
print	Routine to print a store element to an output stream.
print_statistics	Routine to print statistics of a store element to an output stream.
log_statistics	Statistics to log when calling
can_read	Controls whether a store entry can read from a specific format.
read	Reads from a format and returns store element.
can_write	Controls whether a store entry can write to a specific format.
write	Writes store element to a file format.
write	Writes store element to log file.
can_convert	Controls whether a store entry can be converted to an entry of a different store type.
convert	Converts a store entry into an entry of a different store type.
can_show	Controls whether a store element can be visualized.
show	Generates the file to visualize a store element.
has_html_repr	Controls whether store element has specialized HTML output.
html_repr	Returns an HTML representation for a store element in Python mode.

Declaring a new store type¶

template<typename StoreType> struct store_info¶

Empty prototype class for store information.

You need to specialize this struct in order declare a new store type for the CLI. In this specialization five static constexpr const char* variables must be defined:

key: A unique key for internal storing in the environment
option: A long option name for commands (without dashes)
mnemonic: A single character for short option (without dash, cannot be n or v)
name: A singular name that is used in help texts
name_plural: A plural name that is used in help texts

Note

Make sure to specialize store_info inside the alice namespace. You can use the ALICE_ADD_STORE macro instead of the partial specialization. Also ALICE_MAIN will automatically pick up all stores that were defined using ALICE_ADD_STORE.

Here is an example code to define a store type for a fictional type graph:

namespace alice {

template<>
struct store_info<graph>
{
  static constexpr const char* key = "graph";
  static constexpr const char* option = "graph";
  static constexpr const char* mnemonic = "g";
  static constexpr const char* name = "graph";
  static constexpr const char* plural_name = "graphs";
};

}

You can then use this data structure as part of the CLI when listing its type in the declaration of cli:

alice::cli<..., graph, ...> cli( "prefix" );

Customizing store functions¶

template<typename StoreType> std::string alice::to_string(StoreType const &element)¶

Produce short one-line description of store element.

You can use ALICE_DESCRIBE_STORE to implement this function.

element Store element

template<typename StoreType> void alice::print(std::ostream &out, StoreType const &element)¶

Routine to print a store element to an output stream.

This routine is called by the print command. You can use ALICE_PRINT_STORE to implement this function.

Parameters

out: Output stream
element: Store element

template<typename StoreType> void alice::print_statistics(std::ostream &out, StoreType const &element)¶

Routine to print statistics of a store element to an output stream.

This routine is called by the ps command.

Parameters

out: Output stream
element: Store element

template<typename StoreType> nlohmann::json alice::log_statistics(StoreType const &element)¶

Statistics to log when calling ps

This routine is called by the ps command, if logging is enabled.

Parameters

element: Store element

template<typename StoreType, typename Tag> bool alice::can_read(command &cmd)¶

Controls whether a store entry can read from a specific format.

If this function is overriden to return true, then also the function read must be impemented for the same store element type and format tag.

You can use ALICE_READ_FILE to implement this function together with alice::read. However, if you need custom command line arguments, the macro cannot be used and one needs to specialize using these functions as described by the following example.

template<>
bool can_read<std::string>( command& cmd )
{
  cmd.add_flag( "--flag", "some flag" );
  cmd.add_option<std::string>( "--option", "an option stored in a string" );
}

template<>
std::string read<std::string>( const std::string& filename, const command& cmd )
{
  auto flag = cmd.is_set( "flag" );
  auto option = cmd.option_value<std::string>( "option" );

  // read the file and return a string...
}

Parameters

cmd: Mutable reference to command, e.g., to add custom options

template<typename StoreType, typename Tag> StoreType alice::read(const std::string &filename, const command &cmd)¶

Reads from a format and returns store element.

This function must be enabled by overriding the can_read function for the same store element type and format tag. See can_read for more details and an example.

The read function may throw an exception. In this case, no new element is added to the store. Anything can be thrown, but if a std::string is thrown, this string is used to output an error message to the error stream.

Parameters

filename: Filename to read from
cmd: Reference to command, e.g., to check whether custom options are set

template<typename StoreType, typename Tag> bool alice::can_write(command &cmd)¶

Controls whether a store entry can write to a specific format.

If this function is overriden to return true, then also the function write must be impemented for the same store element type and format tag. See can_read for an example which can easily be adapted for can_write and write.

Parameters

cmd: Mutable reference to command, e.g., to add custom options

template<typename StoreType, typename Tag> void alice::write(StoreType const &element, const std::string &filename, const command &cmd)

Writes store element to a file format.

This function must be enabled by overriding the can_write function for the same store element type and format tag.

Parameters

element: Store element to write
filename: Filename to write to
cmd: Reference to command, e.g., to check whether custom options are set

template<typename StoreType, typename Tag> void alice::write(StoreType const &element, std::ostream &os, const command &cmd)

Writes store element to log file.

This function should be enabled by overriding the can_write function for the same store element type and format tag.

Parameters

element: Store element to write
os: Output stream to write to
cmd: Reference to command, e.g., to check whether custom options are set

template<typename SourceStoreType, typename DestStoreType> bool alice::can_convert()¶

Controls whether a store entry can be converted to an entry of a different store type.

If this function is overriden to return true, then also the function convert must be implemented for the same store types.

You can use ALICE_CONVERT to implement this function together with convert.

template<typename SourceStoreType, typename DestStoreType> DestStoreType alice::convert(SourceStoreType const &element)¶

Converts a store entry into an entry of a different store type.

This function must be enabled by overriding the can_convert function for the same store element types.

You can use ALICE_CONVERT to implement this function together with can_convert.

Return

Converted store element

Parameters

element: Store element to convert

template<typename StoreType> bool alice::can_show(std::string &extension, command &cmd)¶

Controls whether a store element can be visualized.

If this function is overriden to be true, then also the function show mustbe implement for the same store type. The command show allows to visualize a store element. For this purpose a text file is written containing the visual representation, e.g., in terms of DOT or SVG (but other formats are possible).

When implementing this function, it should return true and assign extension a default file extension for the representation format, which will be used to name temporary files.

Parameters

extension: Default extension, without the dot (e.g., "svg")
cmd: Mutable reference to command, e.g., to add custom options

template<typename StoreType> void alice::show(std::ostream &out, StoreType const &element, const command &cmd)¶

Generates the file to visualize a store element.

This function is function can be enabled by overriding the can_show function to return true. It takes as parameter an output stream out to a file that is shown using a program by the show command.

Parameters

out: Output stream
element: Store element to show
cmd: Reference to command, e.g., to check whether custom options are set

template<typename StoreType> bool alice::has_html_repr()¶

Controls whether store element has specialized HTML output.

This function can be used to customize the output of the print in Python mode, when being used in Jupyter notebooks. If this function returns true, the output of html_repr is used to create HTML output for a store element.

Works only in Python mode.

template<typename StoreType> std::string alice::html_repr(StoreType const &element)¶

Returns an HTML representation for a store element in Python mode.

This method enables to return a specialized HTML output for a store element when calling print as a function in Python mode. This output can be used in environments such as Jupyter notebook.

Works only in Python mode.

Parameters

element: Store element