Store API¶
Function
|
Description
|
---|---|
to_string | Produce short one-line description of store element.
|
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>
structstore_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 theenvironment
option
: A long option name for commands (without dashes)mnemonic
: A single character for short option (without dash, cannot ben
orv
)name
: A singular name that is used in help textsname_plural
: A plural name that is used in help texts
Note
Make sure to specialize
store_info
inside thealice
namespace. You can use theALICE_ADD_STORE
macro instead of the partial specialization. AlsoALICE_MAIN
will automatically pick up all stores that were defined usingALICE_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* 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::stringalice
::
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>
voidalice
::
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 streamelement
: Store element
-
template <typename StoreType>
voidalice
::
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 streamelement
: Store element
-
template <typename StoreType>
nlohmann::jsonalice
::
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>
boolalice
::
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 withalice::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>
StoreTypealice
::
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. Seecan_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 astd::string
is thrown, this string is used to output an error message to the error stream.- Parameters
filename
: Filename to read fromcmd
: Reference to command, e.g., to check whether custom options are set
-
template <typename StoreType, typename Tag>
boolalice
::
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. Seecan_read
for an example which can easily be adapted forcan_write
andwrite
.- Parameters
cmd
: Mutable reference to command, e.g., to add custom options
-
template <typename StoreType, typename Tag>
voidalice
::
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 writefilename
: Filename to write tocmd
: Reference to command, e.g., to check whether custom options are set
-
template <typename StoreType, typename Tag>
voidalice
::
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 writeos
: Output stream to write tocmd
: Reference to command, e.g., to check whether custom options are set
-
template <typename SourceStoreType, typename DestStoreType>
boolalice
::
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 withconvert
.
-
template <typename SourceStoreType, typename DestStoreType>
DestStoreTypealice
::
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 withcan_convert
.- Return
- Converted store element
- Parameters
element
: Store element to convert
-
template <typename StoreType>
boolalice
::
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 commandshow
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>
voidalice
::
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 streamout
to a file that is shown using a program by theshow
command.- Parameters
out
: Output streamelement
: Store element to showcmd
: Reference to command, e.g., to check whether custom options are set
-
template <typename StoreType>
boolalice
::
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 ofhtml_repr
is used to create HTML output for a store element.Works only in Python mode.
-
template <typename StoreType>
std::stringalice
::
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