Struct kserd::fmt::Formatter

pub struct Formatter<'a, 'k> { /* fields omitted */ }

A structure to format individual Kserd nodes.

The formatter implements Deref to Navigator so movement around the structure is possible. A formatter can provide finer formatting control over a Kserd than using a FormattingConfig. There are four main methods, id(), inline(), concise(), verbose() which control the representations. A line representation has constraints based on its parent representation, along with the type of Value it contains.

1. Representations are ordered: Inline < Concise < Verbose
2. A child cannot be formatted with a line representation greater than its parent. That is if the parent is formatted as Inline, the child cannot be formatted as Verbose or Concise.
3. Tuples cannot be formatted as Verbose
4. Primitives can only be formatted as Inline
5. A sequence or map which is at the root cannot be formatted as Verbose

If a request is made that fails one of these conditions, an error result is returned.

When a request is made, subsequent formatting of descendant nodes is also carried out to ensure the above conditions are met. So if a sequence is formatted as concise, all descendants will be formatted a min(fmt, Concise) where fmt is the current format. An important detail to note is that inverse operation will not result in the same Kserd formatting. To extend the sequence example, if it is request to format as inline, all descendants will be formatted as inline as well (as inline is the minimum representation). If a request is then made to format as concise, all the descendants will remain formatted as inline.

It is best practice to format from maximum representations to minimums.

Example

use kserd::fmt::*;

// indices can be found in various ways, the Navigator stores the Kserd
// as a flattened vector in depth-first order

let kserd = Kserd::new_cntr(vec![ // root, idx 0
    ("a", Kserd::new_num(0)), // idx 1
    ("b", Kserd::new(Value::Seq(vec![ // seq idx 2
        Kserd::new(Value::Tuple(vec![ // tuple idx 3
            Kserd::new_num(1), // idx 4
            Kserd::new_num(3.14) // idx 5
        ]))
    ])))
]).unwrap();

let mut fmtr = Formatter::new(&kserd);

// the Formatter default is at each node's maximum line representation, and the
// id's are all display (all true). Basically the maximal verbosity.

// check that the sequence is verbose
assert_eq!(fmtr.fmts()[2], Fmt { id: true, line: Repr::Verbose });

fmtr.concise(0).unwrap(); // make the root concise, this makes the seq concise as well

assert_eq!(fmtr.fmts()[0], Fmt { id: true, line: Repr::Concise });
assert_eq!(fmtr.fmts()[2], Fmt { id: true, line: Repr::Concise });

fmtr.verbose(0).unwrap(); // we can set the root back to verbose
                          // but sequence will still be concise

assert_eq!(fmtr.fmts()[0], Fmt { id: true, line: Repr::Verbose });
assert_eq!(fmtr.fmts()[2], Fmt { id: true, line: Repr::Concise });

fmtr.inline(3).unwrap(); // make the tuple inline

let formatted = fmtr.write_string(String::new());

// check the formatted string

assert_eq!(&formatted,
"a = <i32> 0
b = [
        (<i32> 1, <f64> 3.14)
    ]
");

Methods

impl<'a, 'k> Formatter<'a, 'k>

pub fn new(root: &'a Kserd<'k>) -> Self

Construct a new Formatter from a Kserd.

pub fn apply_config(&mut self, config: FormattingConfig) -> &mut Self

Apply a FormattingConfig to the Formatter.

This applies the width limitations and identity display that FormattingConfig captures. It does not reset formatting before applying, which means already defined formats may make application fail. Failures are silently ignored and the application continues to try to alter the formatting based on the width constraints.

pub fn fmts(&self) -> &[Fmt]

The current Fmts of each Kserd node.

The order of formats are the same as the underlying Navigator.

pub fn id(&mut self, node_idx: usize, write: bool) -> Result<(), FmtError>

Change whether to display the identity of a Kserd, if one exists.

Example

use kserd::fmt::*;

let kserd = Kserd::new_num(101);

let mut fmtr = Formatter::new(&kserd);

assert_eq!(fmtr.fmts()[0].id, true);

fmtr.id(0, false).unwrap();

assert_eq!(fmtr.fmts()[0].id, false);

pub fn inline(&mut self, node_idx: usize) -> Result<(), FmtError>

Request that the Kserd is formatted as Inline. Will make descendants Inline as well.

Example

use kserd::fmt::*;

let kserd = Kserd::new(Value::Tuple(vec![
    Kserd::new_num(0)
]));

let mut fmtr = Formatter::new(&kserd);

assert_eq!(fmtr.fmts()[0].line, Repr::Concise);

fmtr.inline(0).unwrap();

assert_eq!(fmtr.fmts()[0].line, Repr::Inline);

pub fn concise(&mut self, node_idx: usize) -> Result<(), FmtError>

Request that the Kserd is formatted as Concise. Will make descendants Concise if they are Verbose.

Example

use kserd::fmt::*;

let kserd = Kserd::new_cntr(vec![
    ("a", Kserd::new(Value::Seq(vec![Kserd::new_num(0)])))
]).unwrap();

let mut fmtr = Formatter::new(&kserd);

assert_eq!(fmtr.fmts()[0].line, Repr::Verbose);
assert_eq!(fmtr.fmts()[1].line, Repr::Verbose); // seq is also verbose

fmtr.concise(0).unwrap();

assert_eq!(fmtr.fmts()[0].line, Repr::Concise);
assert_eq!(fmtr.fmts()[1].line, Repr::Concise); // seq is now concise

pub fn verbose(&mut self, node_idx: usize) -> Result<(), FmtError>

Request that the Kserd is formatted as Verbose.

Example

use kserd::fmt::*;

let kserd = Kserd::new_cntr(vec![
    ("a", Kserd::new(Value::Seq(vec![Kserd::new_num(0)])))
]).unwrap();

let mut fmtr = Formatter::new(&kserd);

assert_eq!(fmtr.fmts()[0].line, Repr::Verbose);
assert_eq!(fmtr.fmts()[1].line, Repr::Verbose); // seq is also verbose

fmtr.concise(0).unwrap();

assert_eq!(fmtr.fmts()[0].line, Repr::Concise);
assert_eq!(fmtr.fmts()[1].line, Repr::Concise); // seq is now concise

fmtr.verbose(0).unwrap();

assert_eq!(fmtr.fmts()[0].line, Repr::Verbose);
assert_eq!(fmtr.fmts()[1].line, Repr::Concise); // seq is still concise

pub fn write_string(&self, buf: String) -> String

Write the Kserd as a string using the current formatting state.

Example

use kserd::fmt::*;

let kserd = Kserd::new_cntr(vec![
    ("a", Kserd::new_num(3.14)),
    ("b", Kserd::new(Value::Seq(vec![
        Kserd::new_num(0),
        Kserd::new_num(100),
    ])))
]).unwrap();

let mut fmtr = Formatter::new(&kserd);

fmtr.concise(0).unwrap();
fmtr.inline(2).unwrap();

for i in 0..fmtr.len() {
    fmtr.id(i, false).unwrap(); // set all ids to false
}

assert_eq!(
fmtr.write_string(String::new()),
"(
    a = 3.14
    b = [0, 100]
)");

Methods from Deref<Target = Navigator<'a, 'k>>

pub fn root<'nav: 'node, 'node>(&'nav self) -> Node<'a, 'k, 'nav, 'node>

The root node, that same as the Kserd which was seeded as the root.

Same as index 0.

Example

use kserd::nav::*;

let kserd = Kserd::new_num(3.14);
let nav = Navigator::new(&kserd);

assert_eq!(nav.root().index(), 0);
assert_eq!(nav.root().kserd(), &kserd);

pub fn get<'nav: 'node, 'node>(
    &'nav self,
    index: usize
) -> Option<Node<'a, 'k, 'nav, 'node>>

Get a node at an index.

The Navigator flattens the tree structure into a vector using a depth-first approach. Use the index to quickly obtain a node.

Example

use kserd::nav::*;

let kserd = Kserd::new_map(vec![
    (Kserd::new_num(1), Kserd::new_num(2)),
    (Kserd::new_num(3), Kserd::new_num(4)),
]);

let nav = Navigator::new(&kserd);

let get = |idx| nav.get(idx).map(|x| x.kserd());

assert_eq!(get(1), Some(&Kserd::new_num(1)));
assert_eq!(get(2), Some(&Kserd::new_num(2)));
assert_eq!(get(3), Some(&Kserd::new_num(3)));
assert_eq!(get(4), Some(&Kserd::new_num(4)));

pub fn len(&self) -> usize

The number of nodes.

pub fn is_empty(&self) -> bool

The navigator has no nodes.

Important traits for NodeIter<'a, 'k, 'nav>

impl<'a, 'k, 'nav> Iterator for NodeIter<'a, 'k, 'nav> type Item = Node<'a, 'k, 'nav, 'nav>;

pub fn nodes<'nav>(&'nav self) -> NodeIter<'a, 'k, 'nav>

Iterate over the nodes in depth-first order.

Example

use kserd::nav::*;

let kserd = Kserd::new_map(vec![
    (Kserd::new_num(1), Kserd::new_num(2)),
    (Kserd::new_num(3), Kserd::new_num(4)),
]);

let nav = Navigator::new(&kserd);

let mut nodes = nav.nodes();

let mut next = || nodes.next().map(|x| x.kserd());

next(); // skip the root (hard to equality check)

assert_eq!(next(), Some(&Kserd::new_num(1)));
assert_eq!(next(), Some(&Kserd::new_num(2)));
assert_eq!(next(), Some(&Kserd::new_num(3)));
assert_eq!(next(), Some(&Kserd::new_num(4)));

Trait Implementations

impl<'a, 'k> AsRef<Navigator<'a, 'k>> for Formatter<'a, 'k>

fn as_ref(&self) -> &Navigator<'a, 'k>

Performs the conversion.

impl<'a, 'k> Deref for Formatter<'a, 'k>

type Target = Navigator<'a, 'k>

The resulting type after dereferencing.

fn deref(&self) -> &Navigator<'a, 'k>

Dereferences the value.