Struct spirit::app::App

pub struct App<O, C> { /* fields omitted */ }

The running application part.

This is returned by Builder::build and represents the rest of the application runtime except the actual application body. It can be used to run at any later time, after the spirit has been created.

This carries all the around-bodies and before-bodies. If you run the application body directly, not through this, some of the pipelines or extensions might not work as expected.

The Builder::run is just a convenient wrapper around this. Note that that one handles and logs errors from the application startup as well as from its runtime. Here it is up to the caller to handle the startup errors.

Examples

use spirit::{AnyError, Empty, Spirit};
use spirit::prelude::*;

Spirit::<Empty, Empty>::new()
    .build(true)?
    .run_term(|| {
        println!("Hello world");
        Ok(())
    });

Implementations

impl<O, C> App<O, C> where
    O: StructOpt + Send + Sync + 'static,
    C: DeserializeOwned + Send + Sync + 'static, 

pub fn spirit(&self) -> &Arc<Spirit<O, C>>

Access to the built spirit object.

The object can be used to manipulate the runtime of the application, access the current configuration and register further callbacks (and extensions and pipelines).

Depending on your needs, you may pass it to the closure started with run or even placed into some kind of global storage.

pub fn run<B>(self, body: B) -> Result<(), AnyError> where
    B: FnOnce() -> Result<(), AnyError> + Send + 'static, 

Run the application with provided body.

This will run the provided body. However, it’ll wrap it in all the around-bodies and precede it with all the before-bodies. If any of these fail, or if the body fails, the error is propagated (and further bodies are not started).

Furthermore, depending on the autojoin_bg_thread configuration, termination and joining of the background thread may be performed. If the body errors, termination is done unconditionally (which may be needed in some corner cases to not deadlock on error).

In other words, unless you have very special needs, this is how you actually invoke the application itself.

Any errors are simply returned and it is up to the caller to handle them somehow.

pub fn run_term<B>(self, body: B) where
    B: FnOnce() -> Result<(), AnyError> + Send + 'static, 

Similar to run, but with error handling.

This calls the run. However, if there are any errors, they are logged and the application terminates with non-zero exit code.

pub fn run_test<B>(self, body: B) -> TerminateGuard<O, C> where
    B: FnOnce() -> Result<(), AnyError> + Send + 'static, 

Run the application in a background thread for testing purposes.

This’ll run the application and return an RAII guard. That guard can be used to access the Spirit and manipulate it. It also terminates the application and background thread when dropped.

This is for testing purposes (it panics if there are errors). See the [testing guide].

testing guide: crate::guide::testing