Module schema 

The single description of a block: its parameters and its ports.

The parameters of a block are declared once, with block_params!: the name and the Rust type of every parameter, its default, its unit, its accepted values, its bounds and its meaning. The macro writes the structure, its parser (Params) and its documentation (ParamInfo), so that what a block accepts, what comnum blocks prints, what the Python classes of comnum.blocks take and the JSON Schema of the links (json_schema) cannot differ. A block of another crate declares its parameters the same way (see register).

use comnum_spec::blocks::Params;
comnum_spec::block_params! {
    struct AwgnSpec {
        snr_db: f64 [required] "dB", "signal-to-noise ratio";
        reference: String ["signal"] one_of ["signal", "unit"], "power reference of the SNR";
        bandwidth_hz: Option<f64> [absent "symbol rate"] "Hz" > 0, "noise bandwidth";
    }
}
let p = AwgnSpec::parse("awgn", serde_json::json!({"snr_db": 10})).unwrap();
assert_eq!((p.snr_db, p.reference.as_str(), p.bandwidth_hz), (10.0, "signal", None));
assert_eq!(AwgnSpec::params()[2].default_text(), "symbol rate");
assert!(AwgnSpec::parse("awgn", serde_json::json!({"snr_db": 10, "bandwidth_hz": 0})).is_err());

A default is required, absent (an Option left to None, with the text that says what the block then does) or a JSON value, read as the value of a specification would be (VALUE => "TEXT" shows it as TEXT). Accepted values (one_of) are compared without case; bounds (>, >=, <=, <) apply to a number and to every number of a list.

A parameter whose value is a mapping of parameters of its own (the fibre of the optical blocks, the pilots of ofdm_tx) is declared with block_params! too, and typed Mapping (or NameOr, a name or such a mapping): its keys reach the documentation, the JSON Schema and the Python classes, and are checked as those of a block when the block parses it.

Ports

A block also declares what it reads from the Frame of a trial and what it may add to it, as Facts: awgn needs samples and gives noise, demap needs samples, symbols, constellation and noise and gives llr. check_link checks a link before it runs, so that a missing block is named at once (demap needs noise: add awgn, awgn_ebn0, noise_estimate… before it), and a graphical editor can tell which blocks may follow which. In debug builds every block also checks what it gives while it runs: a fact that it adds to the frame must be declared in its gives (what it needs is checked once, before the link runs, by check_link).

Structs

Mapping

The value of a parameter that is a mapping of the parameters T (declared with block_params!), kept as given until the block parses it (Mapping::parse; the fibre blocks merge it over the fibre of the specification first): its keys are documented with those of the block.

NameOr

The value of a parameter that is a name or a mapping of the parameters T (a constellation 16-QAM or {kind: qam, m: 16}, the pilots none or {pattern: comb, …}), kept as given until the block reads it (NameOr::get).

ParamInfo

One parameter of a block.

Enums

Fact

What the Frame of a trial holds at some point of a link.

Named

What a NameOr is.

ParamDefault

The default of a parameter.

Traits

ParamType

The JSON Schema of the type of a parameter.

Params

The parameters of a block, declared with block_params!.

Functions

check_link

Check the ports of a link: every block finds the facts it needs among those that the blocks before it give.

choice

The accepted value that s names, compared without ASCII case: the one rule of the accepted values of the blocks, for the check of a parameter and its parsing alike.

json_schema

The JSON Schema of a block of a link: one alternative per block of the registry (a mapping with its type, an optional label and its parameters, or its name alone when it needs no parameter).

mapping

The mapping of the parameters of a block, without unknown names.

object_schema

The JSON Schema of a mapping of parameters: its properties (the schema of every parameter), the required ones, no other key; fixed adds properties first (the type of a block or of a variant) and makes them required.

shown

The text of a default written in block_params!: a string literal without its quotes, anything else as written.

take

Take the value of the parameter name from the mapping, or its default.

variants_schema

The JSON Schema of a mapping with a type among variants, each with its parameters (their types, defaults, units, accepted values and bounds), for ParamType::schema.