tag	1d17c3b97a7cf48348d87b090d0dedb1b58cb6ba
tagger	The Android Open Source Project <initial-contribution@android.com>	Wed Apr 24 20:12:34 2024 -0700
object	1169820683de6ea7dd90712491428d0c36ba028b

commit	1169820683de6ea7dd90712491428d0c36ba028b	[log] [tgz]
author	Matthew Maurer <mmaurer@google.com>	Thu Mar 09 18:06:54 2023 +0000
committer	Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com>	Thu Mar 09 18:06:54 2023 +0000
tree	4346f62ce0b8bb6c8f913a17f10e9747d7cc3fc5
parent	493574d322ce0448d01419f550c828a9d9225c51 [diff]
parent	14d4edba3781f9c22ce7a0e994b50efbc0f85f5e [diff]

tree: 4346f62ce0b8bb6c8f913a17f10e9747d7cc3fc5

README.md

`litrs`: parsing and inspecting Rust literals

litrs offers functionality to parse Rust literals, i.e. tokens in the Rust programming language that represent fixed values. For example: 27, "crab", bool. This is particularly useful for proc macros, but can also be used outside of a proc-macro context.

Why this library? Unfortunately, the proc_macro API shipped with the compiler offers no easy way to inspect literals. There are mainly two libraries for this purpose: syn and literalext. The latter is deprecated. And syn is oftentimes overkill for the task at hand, especially when developing function-like proc-macros (e.g. foo!(..)). This crate is a lightweight alternative. Also, when it comes to literals, litrs offers a bit more flexibility and a few more features compared to syn.

I'm interested in community feedback! If you consider using this, please speak your mind in this issue.

Example

In proc macro

use std::convert::TryFrom;
use proc_macro::TokenStream;
use litrs::Literal;

#[proc_macro]
pub fn foo(input: TokenStream) -> TokenStream {
    // Please do proper error handling in your real code!
    let first_token = input.into_iter().next().expect("no input");

    // `try_from` will return an error if the token is not a literal.
    match Literal::try_from(first_token) {
        // Convenient methods to produce decent errors via `compile_error!`.
        Err(e) => return e.to_compile_error(),

        // You can now inspect your literal!
        Ok(Literal::Integer(i)) => {
            println!("Got an integer specified in base {:?}", i.base());

            let value = i.value::<u64>().expect("integer literal too large");
            println!("Is your integer even? {}", value % 2 == 0);
        }
        Ok(other) => {
            println!("Got a non-integer literal");
        }
    }

    TokenStream::new() // dummy output
}

If you are expecting a specific kind of literal, you can also use this, which will return an error if the token is not a float literal.

FloatLit::try_from(first_token)

Parsing from a `&str`

Outside of a proc macro context you might want to parse a string directly.

use litrs::{FloatLit, Literal};

let lit = Literal::parse("'🦀'").expect("failed to parse literal");
let float_lit = FloatLit::parse("2.7e3").expect("failed to parse as float literal");

See the documentation or the examples/ directory for more examples and information.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option. Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

litrs: parsing and inspecting Rust literals

Example

In proc macro

Parsing from a &str

License

`litrs`: parsing and inspecting Rust literals

Parsing from a `&str`