[][src]Crate abscissa_core

Abscissa

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 built on top of the gumdrop crate.
  • configuration: TOML configuration file parsing on application-defined configuration 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 crate to provide application-level logging.
  • 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)
  • terminal interactions: support for colored terminal output (with color support autodetection). Useful for Cargo-like status messages with easy-to-use macros.

Creating a new Abscissa application

The following commands will generate an Abscissa application skeleton:

$ cargo install abscissa
$ abscissa new my_cool_app

The resulting app is a Cargo project. The following files are particularly noteworthy:

  • src/application.rs: Abscissa application type for your app
  • src/commands*: application entrypoint and subcommands. Make sure to check out the hello.rs example of how to make a subcommand.
  • src/config.rs: application configuration
  • src/error.rs: error types

Abscissa applications are implemented as Rust libraries, but have a src/bin subdirectory where the binary entrypoint lives. This means you can run the following within your newly generated application:

$ cargo run -- hello world

This will invoke the hello subcommand of your application (you'll probably want to rename that in a real app) which will print the following:

Hello, world!

You can also run the following to print basic help information:

$ cargo run -- --help

Option Parser

Command-line options are parsed using the gumdrop crate.

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 log;
pub use gumdrop::Options;
pub use crate::config::Config;
pub use crate::config::Config;
pub use crate::error::Error;
pub use crate::error::Fail;
pub use crate::application::boot;
pub use crate::application::Application;
pub use crate::component::Component;
pub use crate::command::Command;
pub use crate::path::StandardPaths;
pub use chrono as time;
pub use secrecy as secret;

Modules

application

Trait for representing an Abscissa application and it's lifecycle

command

Application (sub)command(s), i.e. app entry points

component

Application components.

config

Support for managing global configuration, as well as loading it from TOML

error

Error types used by this crate

logging

Logging subsystem

path

Paths for resources used by the application.

terminal

Terminal handling (TTY interactions, colors, etc)

testing

Acceptance testing for Abscissa applications.

thread

Thread wrapper types.

Macros

ensure

Ensure a condition holds, returning an error if it doesn't (ala assert)

err

Create a new error (of a given kind) with a formatted message

fail

Create and return an error with a formatted message

fatal

Terminate the application with a fatal error, running Abscissa's shutdown hooks.

fatal_error

Terminate the application with a fatal error, running Abscissa's shutdown hooks.

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_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)

Structs

EntryPoint

Toplevel entrypoint command.

Help

Help command which prints usage information.

Secret

Wrapper type for values that contains secrets, which attempts to limit accidental exposure and ensure secrets are wiped from memory when dropped. (e.g. passwords, cryptographic keys, access tokens or other credentials)

Version

Represents a version number conforming to the semantic versioning scheme.

Enums

FrameworkErrorKind

Types of errors which occur internally within the framework

Shutdown

Types of shutdown recognized by Abscissa

Constants

VERSION

Abscissa version

Traits

Configurable

Command type with which a configuration file is associated

Fail

The Fail trait.

Options

Implements a set of options parsed from command line arguments.

Runnable

Runnable is a common trait for things which can be run without any arguments.

Type Definitions

FrameworkError

Abscissa-internal framework errors