Using CLI Functions

Using CLI Functions

Handling argument

`athena.argument.append_to_arguments`

This function appends the given argumnets to the argument list ($ATHENA_ARGS).

USAGE: athena.argument.append_to_arguments <argument...>

RETURN: --

`athena.argument.arg`

This function is a wraper for the athena.argument.get_argument function.

USAGE: athena.argument.arg <argument position or name>

RETURN: string

`athena.argument.args`

This function is a wrapper for the athena.argument.get_arguments function. It returns the argument list ($ATHENA_ARGS).

USAGE: athena.argument.args

RETURN: string

`athena.argument.argument_exists`

This function checks if an argument exists in the argument list $ATHENA_ARGS.

USAGE: athena.argument.argument_exists <argument name>

RETURN: 0 (true), 1 (false)

`athena.argument.argument_exists_and_remove`

This function checks if an argument exists (see athena.argument.argument_exists) in the argument list $ATHENA_ARGS and removes it if it exists.

USAGE: athena.argument.argument_exists_and_remove <argument name> [<name of variable to save the value>]

RETURN: 0 (true), 1 (false)

`athena.argument.argument_exists_or_fail`

This function checks if an argument exists (see athena.argument.argument_exists) in the argument list $ATHENA_ARGS. If no argument was given or the argument was not found script execution is exited and an error message is thrown.

USAGE: athena.argument.argument_exists_or_fail <argument name>

RETURN: --

`athena.argument.argument_is_not_empty`

This function checks if the given arguments string is not empty.

USAGE: athena.argument.argument_is_not_empty <arguments string>

RETURN: 0 (true), 1 (false)

`athena.argument.argument_is_not_empty_or_fail`

This function checks if the given arguments string is not empty. If it is empty execution is stopped and an error message is thrown. If not empty the error code 0 is returned.

USAGE: athena.argument.argument_is_not_empty_or_fail <argument string> [<name>]

RETURN: 0 (true)

`athena.argument.get_argument`

This function returns the requested argument name or value if found in the argument list $ATHENA_ARGS. The function interpretes an given integer as argument index and a given string as argument name (e.g. for the list "a=3 b=5" "3" is return if "a" is requested and "a=3" is returned if "1" is requested).

USAGE: athena.argument.get_argument <argument position or name>

RETURN: string

`athena.argument.get_argument_and_remove`

This function returns the argument name or value (see athena.argument.get_argument) and removes it from the $ATHENA_ARGS list.

USAGE: athena.argument.get_argument_and_remove <argument position or name> [<name of variable to save the value>]

RETURN: string

`athena.argument.get_arguments`

This function will copy the $ATHENA_ARGS array into a variable provided as argument, unless it is being used in a shubshell, then a string containing all the arguments will be output.

USAGE: athena.argument.get_arguments [array_name]

RETURN: 0 (success) | 1 (failure)

`athena.argument.get_integer_argument`

This function returns the value for the given argument and if it is not an integer it will exit with error.

USAGE: athena.argument.get_integer_argument <argument position or name> [<error string>]

RETURN: int

`athena.argument.get_path_from_argument`

This function extract a argument string or value (see athena.argument.get_argument) from the $ATHENA_ARGS list and checks if it is a valid directory path. If it is valid the path is return, if not script execution is exited and an error message is thrown.

USAGE: athena.argument.get_path_from_argument <argument position or name>

RETURN: string

`athena.argument.get_path_from_argument_and_remove`

This function returns a valid direcory path if the given argument name or value (see athena.argument.get_path_from_argument) could be converted and removes the argument from the $ATHENA_ARGS list.

USAGE: athena.argument.get_path_from_argument_and_remove <argument position or name>

RETURN: string

`athena.argument.is_integer`

This function checks if an argument is an integer.

USAGE: athena.argument.is_integer <argument>

RETURN: 0 (true), 1 (false)

`athena.argument.nr_args_lt`

This function returns the error code 0 if the number of arguments in $ATHENA_ARGS is less than the given number. If not the error code 1 is returned.

USAGE: athena.argument.nr_args_lt <number>

RETURN: 0 (true), 1 (false)

`athena.argument.nr_of_arguments`

This function returns the number of arguments found in the argument list $ATHENA_ARGS.

USAGE: athena.argument.nr_of_arguments

RETURN: int

`athena.argument.pop_arguments`

This function pops a number of arguments from the argument list $ATHENA_ARGS.

USAGE: athena.argument.pop_arguments <number>

RETURN: --

`athena.argument.prepend_to_arguments`

This function prepends the given argumnets to the argument list ($ATHENA_ARGS).

USAGE: athena.argument.prepend_to_arguments <argument...>

RETURN: --

`athena.argument.remove_argument`

This function removes an argument from the argument list $ATHENA_ARGS if it is in the list.

USAGE: athena.argument.remove_argument <argument|index>

RETURN: 0 (successful), 1 (failed)

`athena.argument.set_arguments`

This function sets the argument list ($ATHENA_ARGS) to the given arguments.

USAGE: athena.argument.set_arguments <argument...>

RETURN: --

`athena.argument.string_contains`

This function if a string contains a substring. With --literal, regex is not parsed, and there's a literal comparison.

USAGE: athena.argument.string_contains <string> <sub-string> [--literal]

RETURN: 0 (true), 1 (false)

Handling color

`athena.color.print_color`

This function prints the given string in a given color on STDOUT. Available colors are "green", "red", "blue", "yellow", "cyan", and "normal".

USAGE: athena.color.print_color <color> <string> [<non_colored_string>][<redirect_number>]

RETURN: --

`athena.color.print_debug`

This function prints the given string on STDOUT formatted as debug message if debug mode is set.

USAGE: athena.color.print_debug <string> [<redirect_number>]

RETURN: --

`athena.color.print_error`

This function prints the given string on STDOUT formatted as error message.

USAGE: athena.color.print_error <string> [<redirect_number>]

RETURN: --

`athena.color.print_fatal`

This function prints the given string on STDOUT formatted as fatal message and exit with 1 or the given code.

USAGE: athena.color.print_fatal <string> [<exit_code>] [<redirect_number>]

RETURN: --

`athena.color.print_info`

This function prints the given string on STDOUT formatted as info message.

USAGE: athena.color.print_info <string> [<redirect_number>]

RETURN: --

`athena.color.print_ok`

This function prints the given string on STDOUT formatted as ok message.

USAGE: athena.color.print_ok <string> [<redirect_number>]

RETURN: --

`athena.color.print_warn`

This function prints the given string on STDOUT formatted as warn message.

USAGE: athena.color.print_warn <string> [<redirect_number>]

RETURN: --

Handling fs

`athena.fs.absolutepath`

This function checks if the given argument is a valid absolute path to a directory or file. If not, execution is stopped and an error message is thrown. Otherwise the absolute path is returned.

USAGE: athena.fs.absolutepath <file or directory name>

RETURN: string

`athena.fs.basename`

This function returns the basename of a file. If the file does not exist it will generate an error. It can be a full path or relative to the file.

USAGE: athena.fs.basename <filename>

RETURN: string

`athena.fs.dir_contains_files`

This function checks if the given directory contains files with certain pattern (e.g.: *.sh). Globbing has 'dotglob' and 'extglob' (see BASH(1)) enabled.

USAGE: athena.fs.dir_contains_files <directory> <pattern>

RETURN: 0 (true), 1 (false)

`athena.fs.dir_exists_or_create`

This function checks if the given directory name is valid. If not the directory is been created. If the creation fails execution is stopped and an error message is thrown. 0 is returned if the directory exists or was created.

USAGE: athena.fs.file_exists_or_fail <directory name>

RETURN: 0 (true), 1 (false)

`athena.fs.dir_exists_or_fail`

This function checks if the given directory name is valid. If not execution is stopped and an error message is thrown. The displayed error message can be passed as second argument.

USAGE: athena.fs.dir_exists_or_fail <directory name> <message>

RETURN: --

`athena.fs.file_contains_string`

This function checks if the filename contains the given string.

USAGE: athena.fs.file_contains_string_<filename> <string>

RETURN: 0 (true), 1 (true)

`athena.fs.file_exists_or_fail`

This function checks if the given filename is valid. If not execution is stopped and an error message is thrown. The displayed error message can be passed as second argument.

USAGE: athena.fs.file_exists_or_fail <filename> <message>

RETURN: --

`athena.fs.get_cache_dir`

Returns the name of athena cache directory. If it does not exist, then it will be created and then returned.

USAGE: athena.fs.get_cache_dir

RETURN: string

`athena.fs.get_file_contents`

This function checks if the given filename is valid. If not execution is stopped and an error message is thrown. If the given name is a valid filename the file content returned.

USAGE: athena.fs.get_file_contents <filename>

RETURN: string

`athena.fs.get_full_path`

This function checks if the given argument is a valid directory or file and returns the absolute directory path of the given file or directory (a relative path is converted in an absolute directory path). If the path is not valid execution is stopped and an error message is thrown.

USAGE: athena.fs.get_full_path <file or directory name>

RETURN: string

Handling os

`athena.os.call_with_args`

This function will call the command/function passed as argument with all the arguments existing in $ATHENA_ARGS.

USAGE: athena.os.call_with_args <command>

RETURN: <command> result | 1 (false) if no <command> was specified or it doesn' exist

`athena.os.enable_error_mode`

This function enables the error only output mode. To be used in conjunction with athena.os.exec.

USAGE: athena.os.enable_error_mode

RETURN: --

`athena.os.enable_quiet_mode`

This function enables the no output mode. To be used in conjunction with athena.os.exec.

USAGE: athena.os.enable_quiet_mode

RETURN: --

`athena.os.enable_verbose_mode`

This function enables the all output mode. To be used in conjunction with athena.os.exec.

USAGE: athena.os.enable_verbose_mode

RETURN: --

`athena.os.exec`

This function wraps command execution to allow for switching output modes. The output mode is defined by using the athena.os.setoutput* functions.

USAGE: athena.os.exec <function> <args>

RETURN: int

`athena.os.exit`

This function exits Athena if called (if a forced exit is required). Default exit_code is 1.

USAGE: athena.os.exit [<exit_code>]

RETURN: --

`athena.os.exit_with_msg`

This function exits Athena with an error message (see athena.os.exit).

USAGE: athena.os.exit_with_msg <error message> [<exit_code>]

RETURN: --

`athena.os.function_exists`

This functions checks if the function with the given name exists.

USAGE: athena.os.function_exists <name>

RETURN: 0 (true) 1 (false)

`athena.os.function_exists_or_fail`

This functions checks if the function with the given name exists, if not it will abort the current execution.

USAGE: athena.os.function_exists_or_fail <name>

RETURN: 0 (true) 1 (false)

`athena.os.get_base_dir`

This functions returns the base directory of athena.

USAGE: athena.os.get_base_dir

`athena.os.get_base_lib_dir`

This functions returns the base lib directory of athena.

USAGE: athena.os.get_base_lib_dir

`athena.os.get_command`

This function returns the content of the $ATHENA_COMMAND variable. If it is not set execution is stopped and an error message is thrown.

USAGE: athena.os.get_command <command>

RETURN: string

`athena.os.get_executable`

This function returns the executable for athena.

USAGE: athena.os.get_executable

RETURN: string

`athena.os.get_host_ip`

This functions returns the ip of the host of athena.

USAGE: athena.os.get_host_ip

RETURN: string

`athena.os.get_instance`

This function returns the value of the current instance as set in the $ATHENA_INSTANCE variable.

USAGE: athena.os.get_instance

RETURN: string

`athena.os.get_prefix`

This functions returns the prefix that is used to create names for

USAGE: athena.os.get_prefix

RETURN: string

`athena.os.getenv_or_fail`

This functions checks if the env variable with the given name exists, if not it will abort the current execution.

USAGE: athena.os.getenv_or_fail <name>

RETURN: string

`athena.os.handle_exit`

This function handles the signals sent to and by athena.

USAGE: athena.os.handle_exit <signal>

RETURN: --

`athena.os.include_once`

This function checks if a given Bash source file exists and includes it if it wasn't loaded before. If it was loaded nothing is done (avoid multiple sourcing).

USAGE: athena.os.include_once <Bash source file>

RETURN: --

`athena.os.is_command_set`

This functions checks if $ATHENA_COMMAND variable is set.

USAGE: athena.os.is_command_set

RETURN: 0 (true) 1 (false)

`athena.os.is_debug_active`

This function returns the error code 0 if the debug flag ($ATHENA_IS_DEBUG) is set. If not it returns the error code 1.

USAGE: athena.os.is_debug_active

RETURN: 0 (true), 1 (false)

`athena.os.is_git_installed`

This function checks if the 'git' command is available (i.e. if git is installed). If not execution is stopped and an error message is thrown.

USAGE: athena.os.is_git_installed

RETURN: --

`athena.os.is_linux`

This function checks if Athena runs on a Linux machine.

USAGE: athena.os.is_mac

RETURN: 0 (true), 1 (false)

`athena.os.is_mac`

This function checks if Athena runs on a Mac OS X.

USAGE: athena.os.is_mac

RETURN: 0 (true), 1 (false)

`athena.os.is_sudo`

This function checks if the $ATHENA_SUDO variable is set.

USAGE: athena.os.is_sudo

RETURN: 0 (true), 1 (false)

`athena.os.override_exit_handler`

This functions overrides the exit handler with the default signals to catch.

USAGE: athena.os.override_exit_handler <function_name>

RETURN: --

`athena.os.print_stacktrace`

This function prints the stacktrace.

USAGE: athena.os.print_stacktrace

RETURN: --

`athena.os.register_exit_handler`

This function register the exit handler that takes the decision of what to do when interpreting the exit codes and signals.

USAGE: athena.os.register_exit_handler <function_name> <list_of_signals_to_trap>

RETURN: --

`athena.os.return`

This function assigns a value to a variable and overcomes the problem of assignment in subshells losing the current environment. It is meant to be used in the getters and expects that the function using it follows the convention athena.get_. NOTE: when used in subshell it will echo the value to be assigned to a variable.

USAGE: athena.os.return <value> [<name_of_variable_to_assign_to>]

RETURN: string

`athena.os.set_command`

This function sets the $ATHENA_COMMAND variable to the given command string if it is not empty. If it is empty execution is stopped and an error message is thrown.

USAGE: athena.os.set_command <command>

RETURN: --

`athena.os.set_debug`

This function sets the debug flag ($ATHENA_IS_DEBUG) to the given value. If no value is provided $ATHENA_IS_DEBUG is set to 0 (disabled).

USAGE: athena.os.set_debug <debug value>

RETURN: --

`athena.os.set_exit_handler`

This functions registers the exit handler with the default signals to catch.

USAGE: athena.os.set_exit_handler

RETURN: --

`athena.os.set_instance`

This functions sets the instance value.

USAGE: athena.os.set_instance <value>

RETURN: --

`athena.os.split_string`

This function splits up a string on the specified field separator and will write the array into the given variable.

USAGE: athena.os.split_string <string_to_split> <separator_character> <variable_name>

RETURN: --

`athena.os.usage`

This function prints the usage and exits with 1 and handles the name of the command automatically and the athena executable.

USAGE: athena.os.usage [<min_args>] [<options>] [<multi-line options>]

RETURN: --

Handling utils

`athena.utils.add_to_array`

This functions adds elements to the given array.

USAGE: athena.utils.add_to_array <array_name> <element...>

RETURN: 0 (true), 1 (false)

`athena.utils.array_pop`

This function pops elements from the given array, if argument 2 is an integer then it will pop as many times as specified.

USAGE: athena.utils.array_pop <array_name> [number_of_times]

RETURN: 0 (true), 1 (false)

`athena.utils.compare_number`

This function compares a number to another with the given operator (>, >=, <, <=)

USAGE: athena.utils.compare_number <number_a> <number_b> <comparator>

`athena.utils.find_index_in_array`

This function returns the index of the element specified.

USAGE: athena.utils.find_index_in_array <array_name> <needle> [strict]

RETURN: 0 (true), 1 (false)

`athena.utils.get_array`

This function returns the elements of the given array in case of subshell assignment or stores them in a new variable if specified in argument 2.

USAGE: athena.utils.get_array <array_name> [other_array_name]

RETURN: 0 (true), 1 (false)

`athena.utils.get_version_components`

This function extracts the values from a Semantic Versioning 2 format into an array. index 0 contains the operation, index 1 the MAJOR version, index 2 MINOR version and index 3 the PATCH version.

USAGE: athena.utils.get_version_components <sem_ver_string> <array_name_to_store>

`athena.utils.in_array`

This function checks if the element exists in the given array.

USAGE: athena.utils.in_array <array_name> <element> [strict]

RETURN: 0 (true), 1 (false)

`athena.utils.is_integer`

This function checks if a value is an integer.

USAGE: athena.utils.is_integer <value>

RETURN: 0 (true), 1 (false)

`athena.utils.prepend_to_array`

This function prepends the given elements to the specified array.

USAGE: athena.utils.prepend_to_array <array_name> <element...>

RETURN: 0 (true), 1 (false)

`athena.utils.remove_from_array`

This function removes the specified element from the array.

USAGE: athena.utils.remove_from_array <array_name> <needle> [strict]

RETURN: 0 (succeeded), 1 (failed)

`athena.utils.set_array`

This function assigns the given elements to the specified array.

USAGE: athena.utils.set_array <array_name> <element...>

RETURN: 0 (true), 1 (false)

`athena.utils.validate_version`

This function validates if the given version meets the expected version criteria.

USAGE: athena.utils.validate_version <version_str> <expected_version|base_version end_version>

`athena.utils.validate_version_format`

This function validates if the given version follows Semantic Versioning 2.0.

USAGE: athena.utils.validate_version_format <version>

RETURN: 0 (true) 1 (false)