Crate proclet

Expand description

§proclet: proc macros made easy

⚠️ proclet is still in early development. It’s missing some basic features and may get major design changes, and documentation is a work in progress.

proclet can be used with either proc-macro or proc-macro2, or both. Most of the types of the proc-macro crates are abstracted into traits, and proclet’s types are generic over these traits. If you run into type inference issues, there’s proc-macro specific aliases for the proclet types in the pm1 and pm2 modules.

Here’s how you’d make a proc macro that takes a set of comma separated strings as arguments (last comma optional):

#[proc_macro]
pub fn my_proc_macro(input: TokenStream) -> TokenStream {
    proclet(input, |input| {
        let args = punctuated(StringLiteral::parser(), op(",")).parse_all(input)?;
        // ...
    })
}

The proclet function is an optional wrapper that converts the input to a TokenBuf ready for parsing, converts the output back into a TokenStream, and handles errors by making them nice spanned compiler errors instead of panics.

parse_all returns an error if there’s tokens left in the buffer after parsing. To leave the rest of the buffer for the next parser to parse, use the parse method instead.

You can combine parsers to parse more complex objects like punctuated does in the example above. Types that implement the Parse trait can be parsed directly:

let string = StringLiteral::parse(input)?;

The input is automatically advanced to point past the parsed object on success.

Modules§

pm1proc-macro: Type aliases for use with proc-macro.
pm2proc-macro2: Type aliases for use with proc-macro2.
prelude: The prelude imports all the crate’s traits with use ... as _.

Structs§

ByteCharacterLiteralliteral-value: A byte character literal. This can be converted to and from LiteralValue.
ByteStringLiteralliteral-value: A byte string literal. This can be converted to and from LiteralValue.
CStringLiteralliteral-value: A C string literal. This can be converted to and from LiteralValue.
CharacterLiteralliteral-value: A character literal. This can be converted to and from LiteralValue.
Error: An error.
F32Literalliteral-value: f32 suffixed floating point literal. This can be converted to and from LiteralValue.
F64Literalliteral-value: f64 suffixed floating point literal. This can be converted to and from LiteralValue.
FloatLiteralliteral-value: Unsuffixed floating point literal. This can be converted to and from LiteralValue.
I8Literalliteral-value: i8 suffixed integer literal. This can be converted to and from LiteralValue.
I16Literalliteral-value: i16 suffixed integer literal. This can be converted to and from LiteralValue.
I32Literalliteral-value: i32 suffixed integer literal. This can be converted to and from LiteralValue.
I64Literalliteral-value: i64 suffixed integer literal. This can be converted to and from LiteralValue.
I128Literalliteral-value: i128 suffixed integer literal. This can be converted to and from LiteralValue.
IntLiteralliteral-value: Unsuffixed integer literal. This can be converted to and from LiteralValue.
IsizeLiteralliteral-value: isize suffixed integer literal. This can be converted to and from LiteralValue.
Op: An operator. These can be parsed from tokens, and can also be used as parsers to parse one specific operator.
OpParser: Parser for specific sets of operators. Ops can be parsed via Parser or manually from Puncts.
OpParserInstance: An instance for doing manual parsing of operators.
Optional: Wrap a parser in this to make it always succeed and return an Option.
PM1proc-macro: Marker type for the proc-macro crate.
PM2proc-macro2: Marker type for the proc-macro2 crate.
Puncts: Iterator over Puncts.
Punctuated: Parsed punctuated values.
PunctuatedParser: Parser for punctuated values.
StringLiteralliteral-value: A string literal. This can be converted to and from LiteralValue.
TokenBuf: Borrowed version of TokenBuffer.
TokenBuffer: An owned buffer of tokens.
U8Literalliteral-value: u8 suffixed integer literal. This can be converted to and from LiteralValue.
U16Literalliteral-value: u16 suffixed integer literal. This can be converted to and from LiteralValue.
U32Literalliteral-value: u32 suffixed integer literal. This can be converted to and from LiteralValue.
U64Literalliteral-value: u64 suffixed integer literal. This can be converted to and from LiteralValue.
U128Literalliteral-value: u128 suffixed integer literal. This can be converted to and from LiteralValue.
UsizeLiteralliteral-value: usize suffixed integer literal. This can be converted to and from LiteralValue.

Enums§

DelimiterKind: Delimiter. This is exactly like proc_macro*::Delimiter, but doesn’t depend on which proc-macro crate you use.
LiteralValueliteral-value: A literal token. This is like Literal from proc-macro*, except that the value has already been parsed and is available at no cost. You can convert it to and from Literal with into.
Match: Match results.
TokenTreeKind: The kind of a TokenTree. This is like the enum in proc_macro*::TokenTree, but without any contained data. It doesn’t depend on which proc-macro crate you use.

Traits§

AsTokenBuf: Automatically implemented for types that implement Into<&TokenBuf> for &Type.
AsTokenBufMut: Automatically implemented for types that implement Into<&mut TokenBuf> for &mut Type.
DefaultParser: Trait for making a default parser. This is automatically implemented for objects that implement the Parse trait.
Delimiter: Delimiter API trait. See proc_macro::Delimiter.
DelimiterExt: Extensions for Delimiter.
Group: Group API trait. See proc_macro::Group.
GroupExt: Extensions for Group.
Ident: Ident API trait. See proc_macro::Ident.
IdentExt: Extensions for Ident.
IntoTokens: Trait for converting an object into its token representation.
Literal: Literal API trait. See proc_macro::Literal.
LiteralExt: Extensions for Literal.
MatchOpFn: Function for OpParser to use to match operators.
PM: Proc-macro selector for when there isn’t one specific proc-macro type to use.
PMExt: Enable extension traits for PM.
Parse: Parse from a TokenBuf.
Parser: A parser for parsing values from a TokenBuf.
ProcMacro: Base trait with associated type aliases for types from proc-macro/proc-macro2. See also ProcMacroExt.
ProcMacroExt: Adds extra bounds to the associated types of ProcMacro to enable extension traits.
Punct: Punct API trait. See proc_macro::Punct.
PunctExt: Extensions for Punct.
Spacing: Spacing API trait. See proc_macro::Spacing.
SpacingExt: Extensions for Spacing.
Span: Span API trait. See proc_macro::Span.
SpanExt: Extensions for Span.
ToTokenBuffer: Methods for making or extending a TokenBuffer with tokens representing this object. This is automatically implemented for types that implement the IntoTokens trait.
ToTokenStream: Methods for making or extending a TokenStream with a representation of this object.
ToTokens: Trait for getting the token representation of an object.
TokenStream: TokenStream API trait. See proc_macro::TokenStream.
TokenStreamExt: Extensions for TokenStream.
TokenTree: TokenTree API trait. See proc_macro::TokenTree.
TokenTreeExt: Extensions for TokenTree.

Functions§

op: Convenience function for calling Op::new_static. It can be used for parsing a specific op.
proclet: Optional wrapper for proc macros.
punctuated: Create a new parser for parsing things with main punctuated by delim. Convenience function for calling PunctuatedParser::new.