5 releases

0.1.4 Jul 16, 2023
0.1.3 Jun 28, 2023
0.1.2 Jun 10, 2023
0.1.1 Jun 7, 2023
0.1.0 Apr 6, 2023

#16 in #format-macro

Download history 10/week @ 2023-11-04 4/week @ 2023-11-11 6/week @ 2023-11-18 23/week @ 2023-11-25 12/week @ 2023-12-02 4/week @ 2023-12-09 9/week @ 2023-12-16 15/week @ 2023-12-23 7/week @ 2023-12-30 4/week @ 2024-01-06 4/week @ 2024-01-13 3/week @ 2024-01-20 21/week @ 2024-01-27 3/week @ 2024-02-03 31/week @ 2024-02-10 106/week @ 2024-02-17

162 downloads per month
Used in cl-format

MIT license

25KB
234 lines

cl-format

cl-format s the Rust implementation of the Common Lisp format function.

TL;DR: Use several directives like ~a {} and flexible condition and loop control strings to format the string from arguments.

Here are several pages for you to have a general idea if you are not familiar with Common Lisp:

CAUTION: I haven't implemented all format directives yet. I am working on it. See below to find those that have been done.

BTW: I am trying to copy the behaviors of the format function of Common Lisp, but there might be some compromises.

Usage

There are two ways to use this library. You can use the cl_format! macro, or generate the control string and format your arguments by yourself for more flexibility.

First, add cl-format = "0.1" in your Cargo.toml.

Use macro

~a is the most common directive I like to use, so let's start from normal ~a:

let a = cl_format!("~a, ~a, ~a", &1_i32, &2, &3);
assert_eq!(String::from("1, 2, 3"), a.unwrap());

All arguments used for formatting have to be borrowed, and they must implement the TildeAble trait. Check the Implement for custom type section for more details.

Here is more usage of the macro. Escaping the double quote symbol for strings:

let s = String::from("abc");
let a = cl_format!("~a, ~a, ~a, ~S", &1_i32, &2, &3, &s);
assert_eq!(String::from("1, 2, 3, \"abc\""), a.unwrap());

Or not:

let a = cl_format!("start ~a, ~a, ~a, ~a, here", &1_i32, &2, &3, &s);
assert_eq!(String::from("start 1, 2, 3, abc, here"), a.unwrap());

Let's make some loops inside the control string like Lispers do:

let ll: Vec<&dyn TildeAble> = vec![&1, &2, &3];
let a = cl_format!("~a, ~a, ~a, ~{~a,~}", &1_i32, &2, &3, &ll);
assert_eq!(String::from("1, 2, 3, 1,2,3,"), a.unwrap());

Wait, we have an unnecessary comma at the end of the result, let's clean it up:

let a = cl_format!("~a, ~a, ~a, ~{~a~^,~}", &1_i32, &2, &3, &ll);
assert_eq!(String::from("1, 2, 3, 1,2,3"), a.unwrap());

I suddenly don't want to loop the Vec anymore:

let l = vec![&1 as &dyn TildeAble, &2, &3];
let a = cl_format!("The value is:\n ~a", &l);
assert_eq!(String::from("The value is:\n [1, 2, 3]"), a.unwrap());

Now, we have some inconsistency between Common Lisp and Rust. In Common Lisp, ~% in the control string is the new line, but we are in Rust now, so \n is going to work.

I think I am a bit tired of showing the type as &dyn TildeAble to elements inside Vec. But I haven't found a way to avoid it yet. If you know, let me know. So I added some macros:

let l = vec![tilde!(&1), &2, &3];
let a = cl_format!("The value is:\n ~a", &l);
assert_eq!(String::from("The value is:\n [1, 2, 3]"), a.unwrap());

As in Common Lisp, we can loop through all arguments instead of putting them inside a Vec:

let a = cl_format!("~@{~a~^, ~}", &1, &2, &3);
assert_eq!(String::from("1, 2, 3"), a.unwrap());

Now, let's try some condition control (you can get the meaning of the condition control string in the Conditional Formatting chapter of A Few FORMAT Recipes):

let l = vec![tilde!(&1), &2, &3];
let a = cl_format!("~{~a~#[~;, and ~:;, ~]~}", &l);
assert_eq!(String::from("1, 2, and 3"), a.unwrap());

let l = vec![tilde!(&1), &2, &3, &4];
let a = cl_format!("~{~a~#[~;, and ~:;, ~]~}", &l);
assert_eq!(String::from("1, 2, 3, and 4"), a.unwrap());

Manually

Using macros will generate the control string instance every time. It might be wasteful if you are trying to use a control string everywhere because it is flexible enough for multiple uses.

We can generate it by ourselves:

let cs = cl_format::ControlStr::from("~{~#[~;~a~;~a and ~a~:;~@{~a~#[~;, and ~:;, ~]~}~]~}").unwrap();

Then we can generate the Args for the control string to reveal:

let mut list = vec![];
let args = Args::new(vec![&list]);

Let's use it several times by giving different lengths of arguments:

// this equal cl_format!(cs, &list)
assert_eq!(cs.reveal(args).unwrap(), "".to_string());

list.push(&1);
let args = Args::new(vec![&list]);
assert_eq!(cs.reveal(args).unwrap(), "1".to_string());

list.push(&2);
let args = Args::new(vec![&list]);
assert_eq!(cs.reveal(args).unwrap(), "1 and 2".to_string());

list.push(&3);
let args = Args::new(vec![&list]);
assert_eq!(cs.reveal(args).unwrap(), "1, 2, and 3".to_string());

list.push(&4);
let args = Args::new(vec![&list]);
assert_eq!(cs.reveal(args).unwrap(), "1, 2, 3, and 4".to_string());

Implement for custom type

So far, we have only shown the basic types. It would be better if we could make our type be revealed as well.

Here is a demo on how to implement:

use cl_format::*;

// has to derive to Debug
#[derive(Debug)]
struct MyStruct {
    a: usize,
    b: String,
}

impl TildeAble for MyStruct {
	// there are a lot methods inside, but not every of them
	// we are need.
	
	// ~a is good enough
	fn into_tildekind_va(&self) -> Option<&dyn TildeKindVa> {
        Some(self)
    }
	
	// ~d just for show case
	fn into_tildekind_digit(&self) -> Option<&dyn TildeKindDigit> {
        Some(self)
    }
	
	// how many elements you want cl_format treat this type
	// 1 is enough. And this one has to implement
	fn len(&self) -> usize {
        1
    }
}

By now, your IDE should give you some errors, letting you implement TildeKindVa and TildeKindDigit.

impl TildeKindVa for MyStruct {
    fn format(&self, tkind: &TildeKind) -> Result<Option<String>, Box<dyn std::error::Error>> {
        Ok(Some(format!("a: {}, b: {}", self.a, self.b)))
    }
}

impl TildeKindDigit for MyStruct {
    fn format(&self, tkind: &TildeKind) -> Result<Option<String>, Box<dyn std::error::Error>> {
        Ok(Some(format!("{}", self.a)))
    }
}

Now MyStruct can be used by cl_format, but as you guessed, only for ~a and ~d

let s = MyStruct {
    a: 1,
    b: "b".to_string(),
};

assert_eq!("a: 1, b: b".to_string(), cl_format!("~a", &s).unwrap());
assert_eq!(
    "a: 1, b: b lalalal a: 1, b: b".to_string(),
    cl_format!("~a lalalal ~a", &s, &s).unwrap()
);

assert_eq!("1".to_string(), cl_format!("~d", &s).unwrap());
assert_eq!(
    "First: a: 1, b: b; Second: 1".to_string(),
    cl_format!("First: ~a; Second: ~d", &s, &s).unwrap()
);

Format directives

This is the table of which directives have been implemented:

tilde rust type
~a f32, f64, char, i32, i64, usize, bool, u32, u64, String
~s f32, f64, char, i32, i64, usize, bool, u32, u64, String
~d i32, i64, u32, u64, usize
~C char
~[~] (normal condition) bool, usize

TODO

  • doc

Dependencies

~320–770KB
~18K SLoC