Crate litrs[−][src]

Expand description

Parsing and inspecting Rust literal tokens.

This library offers functionality to parse Rust literals, i.e. tokens in the Rust programming language that represent fixed values. The grammar for those is defined here.

This kind of functionality already exists in the crate syn. However, as you oftentimes don’t need (nor want) the full power of syn, litrs was built. This crate also offers a bit more flexibility compared to syn (only regarding literals, of course).

The main types of this library are Literal, representing any kind of literal, and *Lit, like StringLit or FloatLit, representing a specific kind of literal.

There are different ways to obtain such a literal type:

parse: parses a &str or String and returns Result<_, ParseError>. For example: Literal::parse and IntegerLit::parse.
From<proc_macro::Literal> for Literal: turns a Literal value from the proc_macro crate into a Literal from this crate.
TryFrom<proc_macro::Literal> for *Lit: tries to turn a proc_macro::Literal into a specific literal type of this crate. If the input is a literal of a different kind, Err(InvalidToken) is returned.
TryFrom<proc_macro::TokenTree>: attempts to turn a token tree into a literal type of this crate. An error is returned if the token tree is not a literal, or if you are trying to turn it into a specific kind of literal and the token tree is a different kind of literal.

All of the From and TryFrom conversions also work for reference to proc_macro types. Additionally, if the crate feature proc-macro2 is enabled (which it is by default), all these From and TryFrom impls also exist for the corresponding proc_macro2 types.

Note: true and false are Idents when passed to your proc macro. The TryFrom<TokenTree> impls check for those two special idents and return a BoolLit appropriately. For that reason, there is also no TryFrom<proc_macro::Literal> impl for BoolLit. The proc_macro::Literal simply cannot represent bool literals.

Examples

In a proc-macro:

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

#[proc_macro]
pub fn foo(input: TokenStream) -> TokenStream {
     let mut input = input.into_iter().collect::<Vec<_>>();
     if input.len() != 1 {
         // Please do proper error handling in your real code!
         panic!("expected exactly one token as input");
     }
     let token = input.remove(0);

     match FloatLit::try_from(token) {
         Ok(float_lit) => { /* do something */ }
         Err(e) => return e.to_compile_error(),
     }

     // Dummy output
     TokenStream::new()
}

Parsing from string:

use litrs::{FloatLit, Literal};

// Parse a specific kind of literal (float in this case):
let float_lit = FloatLit::parse("3.14f32");
assert!(float_lit.is_ok());
assert_eq!(float_lit.unwrap().type_suffix(), Some(litrs::FloatType::F32));
assert!(FloatLit::parse("'c'").is_err());

// Parse any kind of literal. After parsing, you can inspect the literal
// and decide what to do in each case.
let lit = Literal::parse("0xff80").expect("failed to parse literal");
match lit {
    Literal::Integer(lit) => { /* ... */ }
    Literal::Float(lit) => { /* ... */ }
    Literal::Bool(lit) => { /* ... */ }
    Literal::Char(lit) => { /* ... */ }
    Literal::String(lit) => { /* ... */ }
    Literal::Byte(lit) => { /* ... */ }
    Literal::ByteString(lit) => { /* ... */ }
}

Crate features

proc-macro2 (default): adds the dependency proc_macro2, a bunch of From and TryFrom impls, and InvalidToken::to_compile_error2.

Structs

ByteLit	A (single) byte literal, e.g. `b'k'` or `b'!'`.
ByteStringLit	A byte string or raw byte string literal, e.g. `b"hello"` or `br#"abc"def"#`.
CharLit	A character literal, e.g. `'g'` or `'🦊'`.
FloatLit	A floating point literal, e.g. `3.14`, `8.`, `135e12`, `27f32` or `1.956e2f64`.
IntegerLit	An integer literal, e.g. `27`, `0x7F`, `0b101010u8` or `5_000_000i64`.
InvalidToken	An error signaling that a different kind of token was expected. Returned by the various `TryFrom` impls.
ParseError	Errors during parsing.
StringLit	A string or raw string literal, e.g. `"foo"`, `"Grüße"` or `r#"a🦊c"d🦀f"#`.

Enums

BoolLit	A bool literal: `true` or `false`. Also see the reference.
FloatType	All possible float type suffixes.
IntegerBase	The bases in which an integer can be specified.
IntegerType	All possible integer type suffixes.
Literal	A literal. This is the main type of this library.

Traits

Buffer	A shared or owned string buffer. Implemented for `String` and `&str`. Implementation detail.
FromIntegerLiteral	Integer literal types. Implementation detail.

Type Definitions

OwnedLiteral	A literal which owns the underlying buffer.
SharedLiteral	A literal whose underlying buffer is borrowed.