Enum shadow_rs::core::configuration::NullableOption

pub enum NullableOption<T> {
    Value(T),
    Null,
}

This wrapper type allows cli options to specify “null” to overwrite a config file option with None, and is intended to be used for options where “null” is a valid option value.

Warning: This may result in unexpected behaviour when wrapping string types. For example, if this is used for a file path option, the value “null” will conflict with the valid filename “null”. So if the user specifies “null” for this option, Shadow will assume it means “no value” rather than the filename “null”.

Motivation

For configuration options, there are generally three states:

• set
• not set
• null

For serde, all three states are configurable:

• set: runahead: 5ms
• not set: (no runahead option used in yaml)
• null: runahead: null

For clap, there are only two states:

• set: --runahead 5ms
• not set: (no --runahead option used in command)

There is no way to set a “null” state for cli options with clap.

Configuration in Shadow

Shadow first parses the config file and cli options separately before merging them.

Parsing for serde:

• set: runahead: 5ms => runahead is set to Some(5ms)
• not set: (no runahead option used in yaml) => runahead is set to its default (either Some(..) or None)
• null: runahead: null => runahead is set to None

Parsing for clap:

• set: --runahead 5ms => runahead is set to Some(5ms)
• not set: (no --runahead option used in command) => runahead is set to None

Then the options are merged such that any Some(..) options from the cli options will overwrite any Some or None options from the config file.

The issue is that no clap option can overwrite a config file option of Some with a value of None. For example if the config file specifies runahead: 5ms, then with clap you can only use --runahead 2ms to change the runahead to a Some(2ms) value, or you can not set --runahead at all to leave it as a Some(5ms) value. But there is no cli option to change the runahead to a None value.

This NullableOption type is a wrapper to allow you to specify “null” on the command line to overwrite the config file value with None. From the example above, you could now specify “–runahead null” to overwrite the config file value (for example Some(5ms)) with a None value.

Variants

Value(T)

Null

Implementations

impl<T> NullableOption<T>

pub fn as_ref(&self) -> NullableOption<&T>

pub fn as_mut(&mut self) -> NullableOption<&mut T>

pub fn to_option(self) -> Option<T>

Easier to use than Into<Option<T>> since Option has a lot of blanket From implementations, requiring a lot of type annotations.

Trait Implementations

impl<T: Clone> Clone for NullableOption<T>

fn clone(&self) -> NullableOption<T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug> Debug for NullableOption<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de, T: Deserialize<'de>> Deserialize<'de> for NullableOption<T>

fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>

Deserialize this value from the given Serde deserializer.

impl<T> FromStr for NullableOption<T>

where T: FromStr<Err: Debug + Display>,

type Err = <T as FromStr>::Err

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl<T: JsonSchema> JsonSchema for NullableOption<T>

fn schema_name() -> String

The name of the generated JSON Schema.

fn schema_id() -> Cow<'static, str>

Returns a string that uniquely identifies the schema produced by this type.

fn json_schema(gen: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

fn is_referenceable() -> bool

Whether JSON Schemas generated for this type should be re-used where possible using the $ref keyword.

impl<T: PartialEq> PartialEq for NullableOption<T>

fn eq(&self, other: &NullableOption<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: Serialize> Serialize for NullableOption<T>

fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer.

impl<T: Copy> Copy for NullableOption<T>

impl<T: Eq> Eq for NullableOption<T>

impl<T> StructuralPartialEq for NullableOption<T>