rune/modules/
fmt.rs

Help
1//! Formatting text.
2
3use core::fmt;
4
5use crate as rune;
6use crate::alloc::fmt::TryWrite;
7use crate::alloc::prelude::*;
8use crate::compile;
9use crate::macros::{FormatArgs, MacroContext, TokenStream};
10use crate::parse::Parser;
11use crate::runtime::{EnvProtocolCaller, Format, Formatter, VmResult};
12use crate::{ContextError, Module};
13
14/// Formatting text.
15///
16/// This includes types, macros, and functions used to format text.
17///
18/// # Examples
19///
20/// ```rune
21/// let who = "World";
22/// let string = format!("Hello {}", who);
23/// assert_eq!(string, "Hello World");
24/// ```
25#[rune::module(::std::fmt)]
26pub fn module() -> Result<Module, ContextError> {
27    let mut m = Module::from_meta(self::module_meta)?.with_unique("std::fmt");
28
29    m.ty::<Formatter>()?;
30    m.ty::<fmt::Error>()?;
31    m.function_meta(fmt_error_display_fmt)?;
32    m.macro_meta(format)?;
33
34    m.ty::<Format>()?;
35    m.function_meta(format_display_fmt__meta)?;
36    m.function_meta(format_debug_fmt__meta)?;
37    m.function_meta(format_clone__meta)?;
38    m.implement_trait::<Format>(rune::item!(::std::clone::Clone))?;
39
40    Ok(m)
41}
42
43#[rune::function(instance, protocol = DISPLAY_FMT)]
44fn fmt_error_display_fmt(error: &fmt::Error, f: &mut Formatter) -> VmResult<()> {
45    vm_write!(f, "{error}")
46}
47
48/// Format a string using a format specifier.
49///
50/// # Examples
51///
52/// ```rune
53/// let who = "World";
54/// let string = format!("Hello {}", who);
55/// assert_eq!(string, "Hello World");
56/// ```
57#[rune::macro_(path = format)]
58pub(crate) fn format(
59    cx: &mut MacroContext<'_, '_, '_>,
60    stream: &TokenStream,
61) -> compile::Result<TokenStream> {
62    let mut p = Parser::from_token_stream(stream, cx.input_span());
63    let args = p.parse::<FormatArgs>()?;
64    p.eof()?;
65    let expanded = args.expand(cx)?;
66    Ok(expanded.into_token_stream(cx)?)
67}
68
69/// Write a display representation of a format specification.
70///
71/// # Examples
72///
73/// ```rune
74/// let value = #[builtin] format!("Hello", fill = '0', width = 10);
75/// assert_eq!(format!("{value}"), "Hello00000");
76/// ```
77#[rune::function(keep, instance, protocol = DISPLAY_FMT)]
78fn format_display_fmt(format: &Format, f: &mut Formatter) -> VmResult<()> {
79    vm_try!(format.spec.format(&format.value, f, &mut EnvProtocolCaller));
80    VmResult::Ok(())
81}
82
83/// Write a debug representation of a format specification.
84///
85/// # Examples
86///
87/// ```rune
88/// let value = #[builtin] format!("Hello", fill = '0', width = 10);
89/// let string = format!("{value:?}");
90/// assert!(string is String);
91/// ```
92#[rune::function(keep, instance, protocol = DEBUG_FMT)]
93fn format_debug_fmt(format: &Format, f: &mut Formatter) -> VmResult<()> {
94    vm_write!(f, "{format:?}")
95}
96
97/// Clones a format specification.
98///
99/// # Examples
100///
101/// ```rune
102/// let value = #[builtin] format!("Hello", fill = '0', width = 10);
103/// let vlaue2 = value.clone();
104/// assert_eq!(format!("{value}"), "Hello00000");
105/// ```
106#[rune::function(keep, instance, protocol = CLONE)]
107fn format_clone(this: &Format) -> VmResult<Format> {
108    VmResult::Ok(vm_try!(this.try_clone()))
109}
rune/modules/fmt.rs

rune/modules/
fmt.rs
