Struct spirit::fragment::pipeline::Pipeline

pub struct Pipeline<Fragment, Extractor, Driver, Transformation, SpiritType> { /* fields omitted */ }

The Pipeline itself.

The high-level idea behind the Pipeline is described as part of the fragment module documentation.

Limitations

In a sense, the code here moves close to what is possible to do with the Rust type system. This is needed to make the interface flexible ‒ the Pipeline can describe a lot of different use cases on top of completely different types and Resources.

That, however, brigs certain limitations that you might want to know about:

• All the methods and types here are very rich in terms of type parameters and trait bounds.
• The error messages are quite long and hard to read as a result.
• Sometimes, rustc even gives up on producing the helpful hints as a result of the above. There’s a workaround for that in the form of the check method.
• As of rust stable 1.32, extracting references (through the extract and extract_cfg) doesn’t work. Either use a newer compiler or extract only owned types (eg. clone ‒ it should be generally cheap, because these are parts of configuration the user have written and it needs to be extracted only when reloading the configuration).
• As the pipeline is being constructed through the builder pattern, it is possible the types don’t line up during the construction. If you do not make it align by the end, it will not be possible to use the pipeline inside the Extensible::with.

In general, each Fragment comes with an example containing its canonical pipeline. Copy-pasting and possibly modifying that is probably the easiest way to overcome the above limitations.

Creation order

The pipeline describes a mostly linear process that happens every time a configuration is loaded. Therefore, it helps readability if the builder pattern of the Pipeline is written in the same order as the operations happen. In addition, not all orders of the builder pattern will be accepted, due to how the trait bounds are composed.

While not all steps are needed every time, the ones present should be written in this order:

• new: This is the constructor and sets the name of the pipeline.
• extract or extract_cfg: This sets the closure (or other Extractor) the pipeline will use. This also sets the Fragment tied to the pipeline and presets the Driver and the Installer (though the Installer maybe something useless, since not all Fragments create something directly installable).
• set_driver: This overrides the default Driver provided by the Fragment to something user-provided. It is generally rare to use this.
• transform: This applies (another) transformation. It makes sense to call multiple times to chain multiple transformations together. They are applied in the same order as they are added.
• install: Sets or overrides the Installer the pipeline uses. This is sometimes necessary, but sometimes either the Fragment or one of the Transformations provides one.

Implementations

impl Pipeline<(), (), (), (), ()>

pub fn new(name: &'static str) -> Self

Starts creating a new pipeline.

This initializes a completely useless and empty pipeline. It only sets the name, but other properties (at least the Extractor) need to be set for the Pipeline to be of any practical use.

pub fn extract<O, C, E: for<'e> Extractor<'e, O, C>>(
    self,
    e: E
) -> Pipeline<<E as Extractor<'static, O, C>>::Fragment, E, <<E as Extractor<'static, O, C>>::Fragment as Fragment>::Driver, NopTransformation, (O, C)>

Sets the Extractor.

This ties the Pipeline to an extractor. In addition, it also sets the type of config and command line options structures, the Fragment this pipeline works with and sets the default Driver and Installer as provided by the Fragment.

Depending on the Fragment, this might make the Pipeline usable ‒ or not, as some Fragments can’t provide reasonable (working) Installer.

As of rustc 1.32, it is not possible to return references (or types containing them) into the config or command line structures (it is unable to prove some of the trait bounds). You can either return an owned version of the type (eg. with .clone()) or use a newer version of the compiler.

pub fn extract_cfg<O, C: 'static, R, E>(
    self,
    e: E
) -> Pipeline<R, CfgExtractor<E>, R::Driver, NopTransformation, (O, C)> where
    CfgExtractor<E>: for<'a> Extractor<'a, O, C>,
    E: FnMut(&'static C) -> R,
    R: Fragment, 

Sets the Extractor to a closure taking only the configuration.

This is a convenience wrapper around extract. It acts the same way, only the closure has just one parameter ‒ the configuration. Most of the extracted configuration fragments come from configuration anyway.

impl<F, E, D, T, O, C> Pipeline<F, E, D, T, (O, C)> where
    F: Fragment, 

pub fn set_driver<ND: Driver<F>>(
    self,
    driver: ND
) -> Pipeline<F, E, ND, T, (O, C)> where
    T: Transformation<<ND::SubFragment as Fragment>::Resource, F::Installer, ND::SubFragment>, 

Overwrites the Driver of this pipeline.

Most of the time, the Driver provided by the Fragment set through the extract method is good enough, so it is rare the user would need to call this.

impl<F, E, D, T, O, C> Pipeline<F, E, D, T, (O, C)> where
    F: Fragment,
    D: Driver<F>,
    T: Transformation<<D::SubFragment as Fragment>::Resource, F::Installer, D::SubFragment>, 

pub fn transform<NT>(
    self,
    transform: NT
) -> Pipeline<F, E, D, ChainedTransformation<T, NT>, (O, C)> where
    NT: Transformation<T::OutputResource, T::OutputInstaller, D::SubFragment>, 

Applies a transformation to the Resource.

This puts another transformation to the end of the transformation chain.

Transformations can to quite arbitrary things with the Resource, including changing its type (or changing the Installer ‒ which might actually be needed when changing the type).

pub fn map<M, R>(self, m: M) -> Pipeline<F, E, D, Map<T, M>, (O, C)> where
    M: FnMut(T::OutputResource) -> R, 

Maps the Resource through a closure.

This is somewhat similar to transform in that it can modify or replace the resource while it goes through the pipeline. But it is much simpler ‒ only the Resource is passed to the closure (not any configuration, names, etc). And the closure is not allowed to fail. This is mostly for convenience, so in the simple case one does not have to build the full Transformation.

pub fn and_then<A, R>(self, a: A) -> Pipeline<F, E, D, AndThen<T, A>, (O, C)> where
    A: FnMut(T::OutputResource) -> Result<R, AnyError>, 

Maps the Resource through a fallible closure.

This is somewhat similar to transform in that it can modify or replace the resource while it goes through the pipeline. But it is much simpler ‒ only the Resource is passed to the closure (not any configuration, names, etc). This is mostly for convenience, so in the simple case one does not have to build the full Transformation.

Unlike map, this is allowed to fail.

pub fn install<I>(
    self,
    installer: I
) -> Pipeline<F, E, D, SetInstaller<T, I>, (O, C)> where
    I: Installer<T::OutputResource, O, C>, 

Sets the Installer used by the pipeline.

The pipeline will end with the given Installer and use it to install the created Resources.

pub fn check(self) -> Self where
    D::SubFragment: Fragment,
    T::OutputInstaller: Installer<T::OutputResource, O, C>, 

A workaround for missing trait hints in error messages.

Sometimes, rustc gives up on the complexity of the trait bounds and simply says the Extension trait is not implemented ‒ but one would need a lot of guessing to know why it is not implemented.

The check method doesn’t change the pipeline in any way, but it has a subset of the trait bounds on it. Usually, the missing or broken part is detected by these trait bounds, but they are also significantly simpler than the full set, so rustc is willing to issue the hints.

Trait Implementations

impl<F, B, E, D, T> Extension<B> for Pipeline<F, E, D, T, (B::Opts, B::Config)> where
    B::Config: DeserializeOwned + Send + Sync + 'static,
    B::Opts: StructOpt + Send + Sync + 'static,
    B: Extensible<Ok = B>,
    CompiledPipeline<B::Opts, B::Config, T, T::OutputInstaller, D, E, T::OutputResource, <T::OutputInstaller as Installer<T::OutputResource, B::Opts, B::Config>>::UninstallHandle>: for<'a> BoundedCompiledPipeline<'a, B::Opts, B::Config> + Send + 'static,
    D: Driver<F> + Send + 'static,
    F: Fragment,
    T: Transformation<<D::SubFragment as Fragment>::Resource, <D::SubFragment as Fragment>::Installer, D::SubFragment>,
    T::OutputInstaller: Installer<T::OutputResource, B::Opts, B::Config> + 'static, 

fn apply(self, builder: B) -> Result<B, AnyError>

Perform the transformation on the given extensible.