Crate abscissa

Abscissa: an app microframework

Abscissa is a microframework for building Rust applications (either CLI tools or network services), aiming to provide a large number of features with a minimal number of dependencies, and with a strong focus on security.

Features

• command-line option parsing: simple declarative option parser based on (i.e. forked from) gumdrop. The option parser in Abcissa contains numerous improvements which provide better UX and tighter integration with the other parts of the framework (e.g. overriding configuration settings using command-line options).
• configuration: declarative global configuration support using a RwLock on a lazy_static. Simple parsing of TOML configurations to serde-parsed global structures which can be dynamically updated at runtime.
• error handling: generic Error type based on the failure crate, and a unified error-handling subsystem.
• logging: uses the log and simplelog crates to automatically configure application-level logging, presently to standard output or files.
• secrets management: the (optional) secrets module includes a Secret type which derives serde's Deserialize and can be used to represent secret values parsed from configuration files or elsewhere (e.g. credentials loaded from the environment or network requests)
• shell interactions: support for colored terminal output (with color support autodetection). Useful for Cargo-like status messages with easy-to-use macros.

Option Parser

Please see the documentation for the options module.

Status Macros

// Print a Cargo-like justified status to STDOUT
status_ok!("Loaded", "app loaded successfully");

// Print an error message
status_err!("something bad happened");

// Print an indented attribute to STDOUT
status_attr_ok!("good", "yep");

// Print an error attribute to STDERR
status_attr_err!("error", "yep");

Re-exports

pub extern crate failure;

pub extern crate log;

pub use options::Options;

pub use secrets::Secret;

pub use shell::status;

Modules

config	Support for managing global configuration, as well as loading it from TOML
logging	Logging subsystem
macros	Macros defined by this crate
options	Option parser with custom derive support
secrets	Marker newtype for more carefully handling secret values
shell	Terminal handling code
util	Miscellaneous utilities

Macros

debug	Logs a message at the debug level.
err	Create a new error (of a given kind) with a formatted message
error	Logs a message at the error level.
fail	Create and return an error with a formatted message
impl_command	Implement the from_args and from_env_args methods for a command
impl_error_from	Implement an error conversion for the given type
impl_global_config	Impl the GlobalConfig trait for the given Clone + DeserializeOwned type. TODO: replace with a proc macro and derive(GlobalConfig)
info	Logs a message at the info level.
log	The standard logging macro.
log_enabled	Determines if a message logged at the specified level in that module will be logged.
status	Print a justified status message (in the given color if colors are enabled)
status_attr	Print a tab-delimited status (with the given color if enabled)
status_attr_err	Print a tab-delimited status attribute (in red if colors are enabled)
status_attr_ok	Print a tab-delimited status attribute (in green if colors are enabled)
status_err	Print an error message (in red if colors are enabled)
status_info	Print an informational status message (in cyan if colors are enabled)
status_nojust	Print an unjustified status message (in the given color if colors are enabled)
status_ok	Print a success status message (in green if colors are enabled)
status_warn	Print a warning status message (in yellow if colors are enabled)
trace	Logs a message at the trace level.
warn	Logs a message at the warn level.

Structs

CanonicalPath	A reference type for a canonical filesystem path
CanonicalPathBuf	An owned path on the filesystem which is guaranteed to be canonical.
Components	Collections of components, sorted by dependency ordering
ConfigReader	Wrapper around a RwLockReadGuard for reading global configuration data from global static values defined by the init_config! macro.
Error	Error types used by this library, generic around Kinds
LoggingConfig	Logging configuration
Version	Represents a version number conforming to the semantic versioning scheme.

Enums

ApplicationPath	Various types of paths within an application
ColorConfig	Color configuration
FrameworkErrorKind	Types of errors which occur internally within the framework
Stream	Terminal streams

Traits

Application	Core Abscissa trait used for managing the application lifecycle.
Callable	Something which can be called
Command	Subcommand of an application: derives or otherwise implements the Options trait, but also has a call() method which can be used to invoke the given (sub)command.
Component	Framework subcomponents. Handles framework initialization (but could be used for a lot more).
Fail	The Fail trait.
GlobalConfig	Common functions for loading and reading application configuration from TOML files (providing a global lock which allows many readers, and can be automatically implemented using the impl_global_config! macro.
LoadConfig	Support for loading configuration from a file. Does not modify the global configuration. Only handles parsing and deserializing it from files.

Functions

boot	Boot an application of the given type, parsing command-line options from the environment and running the appropriate Command type.

Type Definitions

FrameworkError

Abscissa-internal framework errors