Struct SyntaxFormatter 

pub struct SyntaxFormatter<'sr, 's, 'f, 'w, S> { /* private fields */ }

Context passed to formatting implementations, containing the formatter and formatting state.

Implementations

impl<'sr, 's, 'f, 'w, S> SyntaxFormatter<'sr, 's, 'f, 'w, S>

pub fn mode(&self) -> Mode

Returns current mode; Normal, Pretty

pub fn state(&self) -> Ref<'_, S>

Returns a reference to the user-defined state.

Panics

• Panics if state is ().

Example

use syntaxfmt::{SyntaxFmt, SyntaxFormatter, syntax_fmt};

trait SymbolResolver {
    fn resolve(&self, name: &str) -> String;
}

struct MyResolver;
impl SymbolResolver for MyResolver {
    fn resolve(&self, name: &str) -> String {
        format!("resolved_{}", name)
    }
}

fn resolve_name<S: SymbolResolver>(name: &str, f: &mut SyntaxFormatter<S>) -> std::fmt::Result {
    let resolved = f.state().resolve(name);
    write!(f, "{}", resolved)
}

#[derive(SyntaxFmt)]
#[syntax(bound = SymbolResolver)]
struct Identifier<'src> {
    #[syntax(cont_with = resolve_name)]
    name: &'src str,
}

let resolver = MyResolver;
let ident = Identifier { name: "foo" };
assert_eq!(format!("{}", syntax_fmt(&ident).state(&resolver)), "resolved_foo");

Examples found in repository

examples/comprehensive.rs (line 60)

fn format_type_with_state<S: TypeDisplay>(
    ty: &Option<&str>,
    f: &mut SyntaxFormatter<S>
) -> std::fmt::Result {
    if f.state().should_show_types() {
        if let Some(t) = ty {
            write!(f, ": {}", t)
        } else {
            Ok(())
        }
    } else {
        Ok(())
    }
}

pub fn state_mut<'a>(&'a mut self) -> RefMut<'a, S>

Returns a mutable reference to the user-defined state.

Panics

• Panics if state is ().
• Panics if state is immutable.

Example

use syntaxfmt::{SyntaxFmt, SyntaxFormatter, syntax_fmt};

struct IdGenerator {
    next_id: usize,
}

impl IdGenerator {
    fn next(&mut self) -> usize {
        let id = self.next_id;
        self.next_id += 1;
        id
    }
}

struct VarDecl<'src> {
    name: &'src str,
}

impl<'src> SyntaxFmt<IdGenerator> for VarDecl<'src> {
    fn syntax_fmt(&self, f: &mut SyntaxFormatter<IdGenerator>) -> std::fmt::Result {
        let id = f.state_mut().next();
        write!(f, "let {}_{}", self.name, id)
    }
}

let mut id_gen = IdGenerator { next_id: 0 };
let x = VarDecl { name: "x" };
let y = VarDecl { name: "y" };
assert_eq!(format!("{}", syntax_fmt(&x).state_mut(&mut id_gen)), "let x_0");
assert_eq!(format!("{}", syntax_fmt(&y).state_mut(&mut id_gen)), "let y_1");

pub fn map_state<F, R>(&mut self, map: F) -> R

where F: FnOnce(&mut Self, &S) -> R,

Takes a closure that receives this formatter and immutable access to state and returns a value of its choice.

Useful when you need concurrent access to both the formatter and state within a single expression, such as within a write! macro.

Arguments

• map - mapping function with signature FnOnce(&mut Self, &S) -> R

Panics

• Panics if state is ().

Example

use syntaxfmt::{SyntaxFmt, SyntaxFormatter, syntax_fmt};

trait Counter {
    fn count(&self) -> usize;
}

struct IdCounter {
    value: usize,
}

impl Counter for IdCounter {
    fn count(&self) -> usize {
        self.value
    }
}

fn format_with_count<S: Counter>(name: &str, f: &mut SyntaxFormatter<S>) -> std::fmt::Result {
    f.map_state(|f, state| write!(f, "{}#{}", name, state.count()))
}

#[derive(SyntaxFmt)]
#[syntax(bound = Counter)]
struct Item<'src> {
    #[syntax(cont_with = format_with_count)]
    name: &'src str,
}

let counter = IdCounter { value: 42 };
let item = Item { name: "value" };
assert_eq!(format!("{}", syntax_fmt(&item).state(&counter)), "value#42");

pub fn map_state_mut<F, R>(&mut self, map: F) -> R

where F: FnOnce(&mut Self, &mut S) -> R,

Takes a closure that receives this formatter and mutable access to state and returns a value of its choice.

Useful when you need concurrent access to both the formatter and mutable state within a single expression, such as within a write! macro.

Arguments

• map - mapping function with signature FnOnce(&mut Self, &mut S) -> R

Panics

• Panics if state is ().
• Panics if state is immutable.

Example

use syntaxfmt::{SyntaxFmt, SyntaxFormatter, syntax_fmt};

trait Counter {
    fn increment(&mut self) -> usize;
}

struct IdCounter {
    count: usize,
}

impl Counter for IdCounter {
    fn increment(&mut self) -> usize {
        let current = self.count;
        self.count += 1;
        current
    }
}

fn format_with_id<S: Counter>(name: &str, f: &mut SyntaxFormatter<S>) -> std::fmt::Result {
    f.map_state_mut(|f, state| {
        let id = state.increment();
        write!(f, "{}_{}", name, id)
    })
}

#[derive(SyntaxFmt)]
#[syntax(bound = Counter)]
struct Node<'src> {
    #[syntax(cont_with = format_with_id)]
    name: &'src str,
}

let mut counter = IdCounter { count: 0 };
let node = Node { name: "node" };
assert_eq!(format!("{}", syntax_fmt(&node).state_mut(&mut counter)), "node_0");
assert_eq!(format!("{}", syntax_fmt(&node).state_mut(&mut counter)), "node_1");

pub fn write_strs(&mut self, strs: Strs) -> FmtResult

Writes a string set to the formatter based on current mode.

pub fn push_indent(&mut self)

Increases the indentation level by one.

pub fn pop_indent(&mut self)

Decreases the indentation level by one.

pub fn write_newline(&mut self) -> FmtResult

Writes newline and current indentation based on current mode.

pub fn push_delim(&mut self, delim: Strs)

Pushes a new delimiter set onto the delimiter stack.

pub fn pop_delim(&mut self)

Pops the top delimiter set from the delimiter stack.

pub fn write_delim(&mut self) -> FmtResult

Writes the current delimiter to the output based on current mode.

Methods from Deref<Target = Formatter<'w>>

pub fn with_options<'b>( &'b mut self, options: FormattingOptions, ) -> Formatter<'b>

🔬This is a nightly-only experimental API. (formatting_options)

Creates a new formatter based on this one with given FormattingOptions.

pub fn pad_integral( &mut self, is_nonnegative: bool, prefix: &str, buf: &str, ) -> Result<(), Error>

Performs the correct padding for an integer which has already been emitted into a str. The str should not contain the sign for the integer, that will be added by this method.

Arguments

• is_nonnegative - whether the original integer was either positive or zero.
• prefix - if the ‘#’ character (Alternate) is provided, this is the prefix to put in front of the number.
• buf - the byte array that the number has been formatted into

This function will correctly account for the flags provided as well as the minimum width. It will not take precision into account.

Examples

use std::fmt;

struct Foo { nb: i32 }

impl Foo {
    fn new(nb: i32) -> Foo {
        Foo {
            nb,
        }
    }
}

impl fmt::Display for Foo {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        // We need to remove "-" from the number output.
        let tmp = self.nb.abs().to_string();

        formatter.pad_integral(self.nb >= 0, "Foo ", &tmp)
    }
}

assert_eq!(format!("{}", Foo::new(2)), "2");
assert_eq!(format!("{}", Foo::new(-1)), "-1");
assert_eq!(format!("{}", Foo::new(0)), "0");
assert_eq!(format!("{:#}", Foo::new(-1)), "-Foo 1");
assert_eq!(format!("{:0>#8}", Foo::new(-1)), "00-Foo 1");

pub fn pad(&mut self, s: &str) -> Result<(), Error>

Takes a string slice and emits it to the internal buffer after applying the relevant formatting flags specified.

The flags recognized for generic strings are:

• width - the minimum width of what to emit
• fill/align - what to emit and where to emit it if the string provided needs to be padded
• precision - the maximum length to emit, the string is truncated if it is longer than this length

Notably this function ignores the flag parameters.

Examples

use std::fmt;

struct Foo;

impl fmt::Display for Foo {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.pad("Foo")
    }
}

assert_eq!(format!("{Foo:<4}"), "Foo ");
assert_eq!(format!("{Foo:0>4}"), "0Foo");

pub fn write_str(&mut self, data: &str) -> Result<(), Error>

Writes some data to the underlying buffer contained within this formatter.

Examples

use std::fmt;

struct Foo;

impl fmt::Display for Foo {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.write_str("Foo")
        // This is equivalent to:
        // write!(formatter, "Foo")
    }
}

assert_eq!(format!("{Foo}"), "Foo");
assert_eq!(format!("{Foo:0>8}"), "Foo");

pub fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<(), Error>

Glue for usage of the write! macro with implementors of this trait.

This method should generally not be invoked manually, but rather through the write! macro itself.

Writes some formatted information into this instance.

Examples

use std::fmt;

struct Foo(i32);

impl fmt::Display for Foo {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.write_fmt(format_args!("Foo {}", self.0))
    }
}

assert_eq!(format!("{}", Foo(-1)), "Foo -1");
assert_eq!(format!("{:0>8}", Foo(2)), "Foo 2");

pub fn flags(&self) -> u32

👎Deprecated since 1.24.0: use the sign_plus, sign_minus, alternate, or sign_aware_zero_pad methods instead

Returns flags for formatting.

pub fn fill(&self) -> char

Returns the character used as ‘fill’ whenever there is alignment.

Examples

use std::fmt;

struct Foo;

impl fmt::Display for Foo {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        let c = formatter.fill();
        if let Some(width) = formatter.width() {
            for _ in 0..width {
                write!(formatter, "{c}")?;
            }
            Ok(())
        } else {
            write!(formatter, "{c}")
        }
    }
}

// We set alignment to the right with ">".
assert_eq!(format!("{Foo:G>3}"), "GGG");
assert_eq!(format!("{Foo:t>6}"), "tttttt");

pub fn align(&self) -> Option<Alignment>

Returns a flag indicating what form of alignment was requested.

Examples

use std::fmt::{self, Alignment};

struct Foo;

impl fmt::Display for Foo {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        let s = if let Some(s) = formatter.align() {
            match s {
                Alignment::Left    => "left",
                Alignment::Right   => "right",
                Alignment::Center  => "center",
            }
        } else {
            "into the void"
        };
        write!(formatter, "{s}")
    }
}

assert_eq!(format!("{Foo:<}"), "left");
assert_eq!(format!("{Foo:>}"), "right");
assert_eq!(format!("{Foo:^}"), "center");
assert_eq!(format!("{Foo}"), "into the void");

pub fn width(&self) -> Option<usize>

Returns the optionally specified integer width that the output should be.

Examples

use std::fmt;

struct Foo(i32);

impl fmt::Display for Foo {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        if let Some(width) = formatter.width() {
            // If we received a width, we use it
            write!(formatter, "{:width$}", format!("Foo({})", self.0), width = width)
        } else {
            // Otherwise we do nothing special
            write!(formatter, "Foo({})", self.0)
        }
    }
}

assert_eq!(format!("{:10}", Foo(23)), "Foo(23)   ");
assert_eq!(format!("{}", Foo(23)), "Foo(23)");

pub fn precision(&self) -> Option<usize>

Returns the optionally specified precision for numeric types. Alternatively, the maximum width for string types.

Examples

use std::fmt;

struct Foo(f32);

impl fmt::Display for Foo {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        if let Some(precision) = formatter.precision() {
            // If we received a precision, we use it.
            write!(formatter, "Foo({1:.*})", precision, self.0)
        } else {
            // Otherwise we default to 2.
            write!(formatter, "Foo({:.2})", self.0)
        }
    }
}

assert_eq!(format!("{:.4}", Foo(23.2)), "Foo(23.2000)");
assert_eq!(format!("{}", Foo(23.2)), "Foo(23.20)");

pub fn sign_plus(&self) -> bool

Determines if the + flag was specified.

Examples

use std::fmt;

struct Foo(i32);

impl fmt::Display for Foo {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        if formatter.sign_plus() {
            write!(formatter,
                   "Foo({}{})",
                   if self.0 < 0 { '-' } else { '+' },
                   self.0.abs())
        } else {
            write!(formatter, "Foo({})", self.0)
        }
    }
}

assert_eq!(format!("{:+}", Foo(23)), "Foo(+23)");
assert_eq!(format!("{:+}", Foo(-23)), "Foo(-23)");
assert_eq!(format!("{}", Foo(23)), "Foo(23)");

pub fn sign_minus(&self) -> bool

Determines if the - flag was specified.

Examples

use std::fmt;

struct Foo(i32);

impl fmt::Display for Foo {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        if formatter.sign_minus() {
            // You want a minus sign? Have one!
            write!(formatter, "-Foo({})", self.0)
        } else {
            write!(formatter, "Foo({})", self.0)
        }
    }
}

assert_eq!(format!("{:-}", Foo(23)), "-Foo(23)");
assert_eq!(format!("{}", Foo(23)), "Foo(23)");

pub fn alternate(&self) -> bool

Determines if the # flag was specified.

Examples

use std::fmt;

struct Foo(i32);

impl fmt::Display for Foo {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        if formatter.alternate() {
            write!(formatter, "Foo({})", self.0)
        } else {
            write!(formatter, "{}", self.0)
        }
    }
}

assert_eq!(format!("{:#}", Foo(23)), "Foo(23)");
assert_eq!(format!("{}", Foo(23)), "23");

pub fn sign_aware_zero_pad(&self) -> bool

Determines if the 0 flag was specified.

Examples

use std::fmt;

struct Foo(i32);

impl fmt::Display for Foo {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        assert!(formatter.sign_aware_zero_pad());
        assert_eq!(formatter.width(), Some(4));
        // We ignore the formatter's options.
        write!(formatter, "{}", self.0)
    }
}

assert_eq!(format!("{:04}", Foo(23)), "23");

pub fn debug_struct<'b>(&'b mut self, name: &str) -> DebugStruct<'b, 'a>

Creates a DebugStruct builder designed to assist with creation of fmt::Debug implementations for structs.

Examples

use std::fmt;
use std::net::Ipv4Addr;

struct Foo {
    bar: i32,
    baz: String,
    addr: Ipv4Addr,
}

impl fmt::Debug for Foo {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt.debug_struct("Foo")
            .field("bar", &self.bar)
            .field("baz", &self.baz)
            .field("addr", &format_args!("{}", self.addr))
            .finish()
    }
}

assert_eq!(
    "Foo { bar: 10, baz: \"Hello World\", addr: 127.0.0.1 }",
    format!("{:?}", Foo {
        bar: 10,
        baz: "Hello World".to_string(),
        addr: Ipv4Addr::new(127, 0, 0, 1),
    })
);

pub fn debug_tuple<'b>(&'b mut self, name: &str) -> DebugTuple<'b, 'a>

Creates a DebugTuple builder designed to assist with creation of fmt::Debug implementations for tuple structs.

Examples

use std::fmt;
use std::marker::PhantomData;

struct Foo<T>(i32, String, PhantomData<T>);

impl<T> fmt::Debug for Foo<T> {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt.debug_tuple("Foo")
            .field(&self.0)
            .field(&self.1)
            .field(&format_args!("_"))
            .finish()
    }
}

assert_eq!(
    "Foo(10, \"Hello\", _)",
    format!("{:?}", Foo(10, "Hello".to_string(), PhantomData::<u8>))
);

pub fn debug_list<'b>(&'b mut self) -> DebugList<'b, 'a>

Creates a DebugList builder designed to assist with creation of fmt::Debug implementations for list-like structures.

Examples

use std::fmt;

struct Foo(Vec<i32>);

impl fmt::Debug for Foo {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt.debug_list().entries(self.0.iter()).finish()
    }
}

assert_eq!(format!("{:?}", Foo(vec![10, 11])), "[10, 11]");

pub fn debug_set<'b>(&'b mut self) -> DebugSet<'b, 'a>

Creates a DebugSet builder designed to assist with creation of fmt::Debug implementations for set-like structures.

Examples

use std::fmt;

struct Foo(Vec<i32>);

impl fmt::Debug for Foo {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt.debug_set().entries(self.0.iter()).finish()
    }
}

assert_eq!(format!("{:?}", Foo(vec![10, 11])), "{10, 11}");

In this more complex example, we use format_args! and .debug_set() to build a list of match arms:

use std::fmt;

struct Arm<'a, L, R>(&'a (L, R));
struct Table<'a, K, V>(&'a [(K, V)], V);

impl<'a, L, R> fmt::Debug for Arm<'a, L, R>
where
    L: 'a + fmt::Debug, R: 'a + fmt::Debug
{
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        L::fmt(&(self.0).0, fmt)?;
        fmt.write_str(" => ")?;
        R::fmt(&(self.0).1, fmt)
    }
}

impl<'a, K, V> fmt::Debug for Table<'a, K, V>
where
    K: 'a + fmt::Debug, V: 'a + fmt::Debug
{
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt.debug_set()
        .entries(self.0.iter().map(Arm))
        .entry(&Arm(&(format_args!("_"), &self.1)))
        .finish()
    }
}

pub fn debug_map<'b>(&'b mut self) -> DebugMap<'b, 'a>

Creates a DebugMap builder designed to assist with creation of fmt::Debug implementations for map-like structures.

Examples

use std::fmt;

struct Foo(Vec<(String, i32)>);

impl fmt::Debug for Foo {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt.debug_map().entries(self.0.iter().map(|&(ref k, ref v)| (k, v))).finish()
    }
}

assert_eq!(
    format!("{:?}",  Foo(vec![("A".to_string(), 10), ("B".to_string(), 11)])),
    r#"{"A": 10, "B": 11}"#
 );

pub fn sign(&self) -> Option<Sign>

🔬This is a nightly-only experimental API. (formatting_options)

Returns the sign of this formatter (+ or -).

pub fn options(&self) -> FormattingOptions

🔬This is a nightly-only experimental API. (formatting_options)

Returns the formatting options this formatter corresponds to.

Trait Implementations

impl<'sr, 's, 'f, 'w, S> Deref for SyntaxFormatter<'sr, 's, 'f, 'w, S>

type Target = Formatter<'w>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'sr, 's, 'f, 'w, S> DerefMut for SyntaxFormatter<'sr, 's, 'f, 'w, S>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.