Crate compose_idents

Expand description

A macro for generating new identifiers (names of variables, functions, traits, etc.) by concatenating one or more arbitrary parts, applying other manipulations, and iteratively generating multiple variations of the supplied Rust code.

It was created as an alternative to macro_rules! that doesn’t allow creating new identifiers from the macro arguments and concat_idents! macro from the nightly Rust, which is limited in capabilities and has not been stabilized since 2015.

§Features

Identifier generation

Identifiers can be generated via concatenation of multiple parts. Arguments of the outer macro definitions and literals are supported for identifier definitions.
Code repetition

Generation of multiple variations of the user-provided code is natively supported via for ... in ... loop syntax.
Alternative invocation forms

Both function-style macro and attribute-style macro are available for different use-cases.
Functions

Functions can be applied when defining new identifiers for changing case and style.
String formatting

Strings can be formatted with % alias % syntax, which is useful for generating doc-attributes.
Unique identifier generation

Unique identifiers can be deterministically generated by using the hash() function, which is seeded uniquely for each invocation of the macro. This might be useful for generating unique global variables.

§Usage

This section contains various usage examples. For additional examples, see the tests/ directory of the repository.

§Quick start

compose! works by accepting definitions of aliases and a code block where aliases could be used as normal identifiers. When the macro is expanded, the aliases are replaced with their definitions (which may expand into identifiers, paths, expressions, and arbitrary Rust code):

use compose_idents::compose;

/// Generate getters, setters with docstrings for given struct
struct User {
    name: String,
    age: u32,
    email: Option<String>,
}

impl User {
    compose!(
        // Iterating over fields and their types, generating a new variation of the code per iteration
        for (field, type_) in [(name, String), (age, u32), (email, Option<String>)]

        // Definitions of additional aliases
        getter = field,
        setter = concat(set_, field),
        getter_mut = concat(field, _mut),
        {
            #[doc = "Get the % field % field"]
            pub fn getter(&self) -> &type_ {
                &self.field
            }

            #[doc = "Get mutable reference to % field % field"]
            pub fn getter_mut(&mut self) -> &mut type_ {
                &mut self.field
            }

            #[doc = "Set the % field % field"]
            pub fn setter(&mut self, value: type_) {
                self.field = value;
            }
        }
    );
}

let mut user = User { name: "Alice".into(), age: 30, email: None };
user.set_name("Bob".into());
user.set_email(Some("bob@example.com".into()));
assert_eq!(user.name(), "Bob");

§Generating tests for different types

A practical example for how to auto-generate names for macro-generated tests for different data types:

use compose_idents::compose_item;

pub trait Frobnicate {
  type Output;

  fn frobnicate(&self, value: Self) -> Self::Output;
}

impl Frobnicate for u32 {
  type Output = u32;

  fn frobnicate(&self, value: Self) -> Self::Output {
    self + value
  }
}

impl Frobnicate for &'static str {
  type Output = String;

  fn frobnicate(&self, value: Self) -> Self::Output {
    format!("{}_{}", self, value)
  }
}

// Generating tests for u32 and &'static str types
#[compose_item(
  for (type_, initial, input, expected_value) in [
    (u32, 0, 42_u32, 42_u32),
    (&'static str, "foo", "bar", "foo_bar".to_string()),
  ]

  // Notice - we are using normalize2() to make `&'static str` fit for
  // being part of the test function's identifier.
  test_fn = concat(test_frobnicate_, normalize2(type_)),
)]
fn test_fn() {
  let actual = (initial as type_).frobnicate(input);
  let expected = expected_value;

  assert_eq!(actual, expected);
}

test_frobnicate_u32();
// Notice - "&'static str" has been turned into just "static_str"
test_frobnicate_static_str();

§Reference

This is a complete reference to the functionality of this library split into thematic sections.

§Basic alias definition

You can define aliases with the syntax alias = concat(arg1, normalize(arg2), ...), alias = lower(ARG), alias = arg, etc., where args may be identifiers, string literals, integers, underscores, or any arbitrary sequences of tokens (like &'static str, My::Enum and so on - such values would be recognized as just tokens):

use compose_idents::compose;

compose!(
    // Literal strings are accepted as arguments and their content is parsed.
    my_fn_1 = concat(foo, _, bar),
    // The same applies to literal integers, underscores or free-form token sequences.
    my_fn_2 = concat(spam, _, 1, _, eggs),
    {
        fn my_fn_1() -> u32 {
            42
        }

        fn my_fn_2() -> u32 {
            42
        }
    },
);

assert_eq!(foo_bar(), 42);
assert_eq!(spam_1_eggs(), 42);

§Alias reuse

Aliases could also be reused in definitions of other aliases:

use compose_idents::compose;

compose!(
    base_alias = FOO,
    derived_alias = concat(BAR, _, base_alias),
    {
        static base_alias: u32 = 1;
        static derived_alias: u32 = base_alias;
    },
);

assert_eq!(FOO, 1);
assert_eq!(BAR_FOO, 1);

§Code repetition

Multiple code variants could be generated with for ... in [...] syntax. The loop variable can be used directly inside the block:

use compose_idents::compose_idents;

compose_idents!(for name in [foo, bar] {
    fn name() -> u32 {
        1
    }
});

assert_eq!(foo(), 1);
assert_eq!(bar(), 1);

§Attribute macro form

#[compose_item(...)] is an attribute macro equivalent to compose! { ... }, except it treats the annotated item as the code block. Otherwise, it works the same way:

use compose_idents::compose_item;

#[compose_item(
    my_fn = concat(foo, _, bar),
)]
pub fn my_fn() -> u32 {
    42
}

fn main() {
    assert_eq!(foo_bar(), 42);
}

§Functions

Functions can be applied to the arguments used for the alias definitions:

use compose_idents::compose;

compose!(
    my_const = concat(upper(foo), _, lower(BAR)),
    // Function calls can be arbitrarily nested and combined.
    my_static = upper(lower(BAZ)),
    {
        const my_const: u8 = 1;
        static my_static: &str = "hello";
    }
);

assert_eq!(FOO_bar, 1);
assert_eq!(BAZ, "hello");

You can find a complete description of all functions below under “Functions” heading.

§Casing manipulation

There are multiple functions for altering the naming convention of identifiers:

use compose_idents::compose;

compose!(
    MY_SNAKE_CASE_STATIC = snake_case(snakeCase),
    MY_CAMEL_CASE_STATIC = camel_case(camel_case),
    MY_PASCAL_CASE_STATIC = pascal_case(concat(pascal, _, case)),
    {
        static MY_SNAKE_CASE_STATIC: u32 = 1;
        static MY_CAMEL_CASE_STATIC: u32 = 2;
        static MY_PASCAL_CASE_STATIC: u32 = 3;
    },
);

assert_eq!(snake_case, 1);
assert_eq!(camelCase, 2);
assert_eq!(PascalCase, 3);

§Token normalization

normalize() function is useful for making valid identifiers out of arbitrary tokens:

use compose_idents::compose;

compose!(
    MY_NORMALIZED_ALIAS = concat(my, _, normalize(&'static str)),
    {
        static MY_NORMALIZED_ALIAS: &str = "This alias is made from a normalized argument";
    }
);

assert_eq!(
    my_static_str,
    "This alias is made from a normalized argument"
);

normalize2() is similar to normalize(), but it evaluates its single input value first and then normalizes the result into a valid identifier. Unlike normalize(), which operates on raw tokens, normalize2() accepts values of different types — ident, str, int, path, type, expr, and tokens — and always produces an ident:

use compose_idents::compose;

compose!(
    // Path -> ident
    A = normalize2(Foo::Bar),
    // Type with lifetime -> ident
    B = normalize2(&'static str),
    // Tokens (via raw fencing) -> ident
    C = normalize2(raw(Result<u32, String>)),
    {
        fn A() -> u32 { 1 }
        fn B() -> u32 { 2 }
        fn C() -> u32 { 3 }
    }
);

assert_eq!(Foo_Bar(), 1);
assert_eq!(static_str(), 2);
assert_eq!(Result_u32_String(), 3);

§String formatting

Aliases could be used in string formatting with % alias % syntax. This is useful for generating doc-attributes:

use compose_idents::compose;

compose!(
    my_fn = concat(foo, _, bar),
    MY_FORMATTED_STR = concat(FOO, _, BAR),
    {
        static MY_FORMATTED_STR: &str = "This is % MY_FORMATTED_STR %";

        // You can use % alias % syntax to replace aliases with their definitions
        // in string literals and doc-attributes.
        #[doc = "This is a docstring for % my_fn %"]
        fn my_fn() -> u32 {
            321
        }
    },
);

assert_eq!(FOO_BAR, "This is FOO_BAR");

§Generating unique identifiers

hash() function deterministically hashes the input within a single macro invocation. It means that within the same compose! call hash(foobar) will always produce the same output. But in another call - the output would be different (but also the same for the same input).

It could be used to avoid conflicts between identifiers of global variables, or any other items that are defined in global scope.

use compose_idents::compose;

macro_rules! create_static {
    () => {
        compose!(
            MY_UNIQUE_STATIC = hash(1),
            MY_OTHER_UNIQUE_STATIC = hash(2),
            {
                static MY_UNIQUE_STATIC: u32 = 42;
                static MY_OTHER_UNIQUE_STATIC: u32 = 42;
            }
        );
    };
}

create_static!();
create_static!();

This example roughly expands to this:

use compose_idents::compose;
static __5360156246018494022: u32 = 42;
static __1421539829453635175: u32 = 42;
static __17818851730065003648: u32 = 42;
static __10611722954104835980: u32 = 42;

§Concatenating multiple arguments

The concat() function takes multiple arguments and concatenates them together. It provides explicit concatenation that can be either nested within other function calls or to aggregate results of other function calls:

use compose_idents::compose;

compose!(
    // Basic example
    basic_fn = concat(foo, _, bar, _, baz),
    // Mixed with other functions
    upper_fn = upper(concat(hello, _, world)),
    // Complex example
    complex_fn = concat(to_ident("prefix_"), normalize(&'static str), _, snake_case(CamelCase)),
    {
        fn basic_fn() -> u32 { 1 }
        fn upper_fn() -> u32 { 2 }
        fn complex_fn() -> u32 { 3 }
    }
);

assert_eq!(foo_bar_baz(), 1);
assert_eq!(HELLO_WORLD(), 2);
assert_eq!(prefix_static_str_camel_case(), 3);

§Syntax

§Expressions

Expressions consist of values (foo, Foo::Bar, 1 + 1, "bar", 123, etc) and function calls (concat(foo, _, bar), camel_case(foo_bar), etc).

§Values

A value can represent any sequence of tokens - it could be a simple identifier like foo, a path like std::vec::Vec, a literal like "foo" or 42, or more complex constructs.

Values are typed, types of values are detected automatically, values are silently coerced between some of the types (see the “Types” section below). Most of the time a user doesn’t need to care about types or explicitly casting between them. For explicit casting, see functions described in the “Functions” → “Type casting” section below.

Examples of values of different types could be found in the “Types” section.

§String formatting

String literals could be formatted using % alias % syntax. This is especially useful for generating doc-attributes.

§Function calls

A function call consists of a function name and the argument-list enclosed in parentheses. Arguments are separated by commas. Arguments themselves are arbitrary expressions.

A reference of the available functions could be found in the “Functions” section below.

§Comma-containing arguments

If an argument contains commas - the system would try hard to parse it correctly and determine the argument boundaries, but if it’s not possible - use raw() function to fence the complex argument.

§Function overloading

Functions could be overloaded and have multiple signatures. For example concat(...) could work for strings, integers and for arbitrary tokens as well. All overloads are listed in the “Functions” section.

§Aliases

An alias is an identifier assigned an arbitrary expression: alias = <expr>. Alias-definitions are separated by commas.

// Alias can be defined as any expression.

// It could be just a simple value.
alias1 = foo,
// Or a function call.
alias2 = concat(foo, _, bar),
// Function calls could be nested.
alias3 = upper(snake_case(fooBarBaz)),
// Complex (often - comma containing) expressions could be fenced using `raw()`.
alias4 = concat(Result<, raw(u32,), String>),
// Any value could be converted to valid identifiers using `normalize()` function.
alias5 = concat(my, _, fn, _, normalize(My::Enum)),

§Alias re-use

Aliases could be re-used in subsequent (but not preceding) definitions of other aliases:

alias1 = foo,
alias2 = concat(alias1, _, bar), // alias1 is re-used here

§Types

Type	Example	Description
`ident`	`foo`	Identifier type.
`type`	`Result<u32, Error>`	Type type.
`path`	`foo::bar`	Path type.
`expr`	`2 + 2`, `if c { 1 } else { 0 }`	Expression type.
`str`	`"foo"`	Literal string type.
`int`	`123`	Literal integer type.
`tokens`	`mod foo { fn bar() -> u32 { 0 } }`	Arbitrary evaluated token-sequence. If used as a function argument - terminated by a comma, and if it contains expressions - they are evaluated.
`raw`	`mod foo { fn bar() -> u32 { 0 } }`	Raw unevaluated token-sequence. Only used as a type of a single input argument - doesn’t respect any delimiters, if contains expressions - they are treated as raw tokens and not evaluated.

§Coercion rules

Values are automatically coerced between compatible types when needed. Coercion is limited very limited by design, it doesn’t encompass all possible type conversion directions, only the most useful ones and the ones that are infallible.

From	To	Description
`ident`	`path`	Identifier to path (e.g., `foo` → `foo`)
`ident`	`type`	Identifier to type (e.g., `u32` → `u32`)
`ident`	`expr`	Identifier to expression (e.g., `foo` → `foo`)
any	`tokens`	Any value to tokens

§Functions

§Case manipulation

Functions that change the case or style.

Function	Description	Example	Example Result
`upper(str) -> str`	Converts the string argument to UPPER case.	`upper("foo")`	`"FOO"`
`upper(ident) -> ident`	Converts the ident argument to UPPER case.	`upper(foo)`	`FOO`
`lower(str) -> str`	Converts the string argument to lower case.	`lower("FOO")`	`"foo"`
`lower(ident) -> ident`	Converts the ident argument to lower case.	`lower(FOO)`	`foo`
`snake_case(str) -> str`	Converts the string argument to snake_case.	`snake_case("FooBar")`	`"foo_bar"`
`snake_case(ident) -> ident`	Converts the ident argument to snake_case.	`snake_case(FooBar)`	`foo_bar`
`camel_case(str) -> str`	Converts the string argument to camelCase.	`camel_case("foo_bar")`	`"fooBar"`
`camel_case(ident) -> ident`	Converts the ident argument to camelCase.	`camel_case(foo_bar)`	`fooBar`
`pascal_case(str) -> str`	Converts the string argument to PascalCase.	`pascal_case("foo_bar")`	`"FooBar"`
`pascal_case(ident) -> ident`	Converts the ident argument to PascalCase.	`pascal_case(foo_bar)`	`FooBar`

§Token manipulation

General purpose functions that perform useful operations on tokens.

Function	Description	Example	Example Result
`normalize(raw) -> ident`	Transforms raw input into a valid Rust identifier.	`normalize(&'static str)`	`static_str`
`normalize2(ident) -> ident`	Evaluates the ident and transforms it to a valid identifier.	`normalize2(FooBar)`	`FooBar`
`normalize2(str) -> ident`	Evaluates the string literal and transforms it to a valid identifier.	`normalize2("&'static str")`	`static_str`
`normalize2(int) -> ident`	Evaluates the integer literal and transforms it to a valid identifier.	`normalize2(123)`	`_123`
`normalize2(path) -> ident`	Evaluates the path and transforms it to a valid identifier.	`normalize2(Foo::Bar)`	`Foo_Bar`
`normalize2(type) -> ident`	Evaluates the type and transforms it to a valid identifier.	`normalize2(&'static str)`	`static_str`
`normalize2(expr) -> ident`	Evaluates the expression and transforms it to a valid identifier.	`normalize2(1 + 2)`	`_1_2`
`normalize2(tokens) -> ident`	Evaluates tokens and transforms them to a valid identifier.	`normalize2(raw(Result<u32, String>))`	`Result_u32_String`
`concat(ident...) -> ident`	Concatenates multiple idents into a single identifier.	`concat(foo, _, bar)`	`foo_bar`
`concat(ident, tokens...) -> ident`	Concatenates an ident and follow-up tokens arguments into a single identifier.	`concat(prefix, _, 123)`	`prefix_123`
`concat(str...) -> str`	Concatenates multiple strings into a single string.	`concat("foo", "_", "bar")`	`"foo_bar"`
`concat(int...) -> int`	Concatenates multiple integers into a single integer.	`concat(1, 2, 3)`	`123`
`concat(tokens...) -> tokens`	Concatenates multiple tokens arguments into a single tokens value.	`concat(Result<, raw(u32,), String, >)`	`Result<u32, String>`

§Special purpose

Functions for special use cases.

Function	Description	Example	Example Result
`hash(str) -> str`	Hashes the string deterministically within a single macro invocation.	`hash("input")`	`"12345678"`
`hash(ident) -> ident`	Hashes the ident deterministically within a single macro invocation.	`hash(input)`	`__12345678`
`hash(tokens) -> ident`	Hashes the tokens argument deterministically within a single macro invocation.	`hash(foo + bar)`	`__87654321`

§Type casting

These functions are useful whenever you need to explicitly cast an arbitrary value to a particular type.

Function	Description	Example	Example Result
`raw(raw) -> tokens`	Converts raw unevaluated input to a tokens value. Useful for noisy inputs that contain separators, etc.	`raw(Result<u32, Error>)`	`Result<u32, Error>`
`to_ident(tokens) -> ident`	Converts the tokens argument to an identifier.	`to_ident(lower("FOO"))`	`foo`
`to_path(tokens) -> path`	Converts the tokens argument to a path.	`to_path(concat(std, ::, vec))`	`std::vec`
`to_type(tokens) -> type`	Converts the tokens argument to a type.	`to_type(concat(Vec, <, u32, >))`	`Vec<u32>`
`to_expr(tokens) -> expr`	Converts the tokens argument to an expression.	`to_expr(concat(1, +, 2))`	`1 + 2`
`to_str(tokens) -> str`	Converts the tokens argument to a string.	`to_str(foo)`	`"foo"`
`to_int(tokens) -> int`	Converts the tokens argument to an integer.	`to_int(concat(4, 2))`	`42`
`to_tokens(tokens) -> tokens`	Identity function for tokens - useful for converting any value to tokens.	`to_tokens(foo)`	`foo`

§Backwards compatibility and deprecation

§Deprecation policy

As a general rule old functionality is not removed abruptly, but rather deprecated first and removed after a few releases. This applies to pre-1.0.0 releases as well.
Deprecation works through injection of #[deprecated] attributes to existing syntactic elements of generated code. It triggers deprecation warnings at compile time with text like this:
```
compose!: Feature XXX is deprecated, syntax `compose!(...)` is considered obsolete, please use...
```
Removal of a feature without a deprecation process is only possible in pre-1.0.0 releases and in such a case an explicit warning is issued in the changelog and the release notes.
A deprecated feature is kept for a reasonably long time, or until backwards-compatibility can’t be maintained anymore, or it becomes too costly, then it is removed completely.

§Migration guides

This section describes what to do to migrate code that uses deprecated features to up-to-date state.

§[≤ 0.0.4 → 0.0.5+]: Semicolon alias separator

§What changed?

Starting with v0.0.5 commas were introduced as a separator of alias definitions. The old semicolon separator is deprecated.

§How to migrate?

Before (≤ 0.0.4):

compose_idents!(
    my_fn  = concat(foo, bar);  // ← Notice usage of semicolons
    MY_VAR = concat(FOO, BAZ);
    {
        /* … */
    };
);

After (0.0.5+):

compose_idents!(
    my_fn  = concat(foo, bar),  // ← Notice usage of commas
    MY_VAR = concat(FOO, BAZ),
    {
        /* … */
    },
);

User should simply replace every semicolon separator in the macro invocation with a comma.

§[≤ 0.2.0 → 0.2.2]: Bracket-based alias syntax

§What changed?

v0.2.0 deprecated and v0.2.2 removed support for the square-bracket form: alias = [arg1, func(arg2), …], of alias definitions in favour of bare expressions without any special block delimiters: alias = concat(arg1, func(arg2), …), or alias = func(arg1), or alias = func(arg1), or just alias = arg.

§How to migrate?

Before (≤ 0.2.0):

compose_idents!(
    my_fn    = [foo, _, bar],  // Notice usage of brackets
    MY_CONST = [upper(baz)],
    {
        /* … */
    },
);

After (≥ 0.2.0, ≤ v0.2.2):

compose_idents!(
    my_fn    = concat(foo, _, bar),  // Notice - brackets are replaced with `concat()` call
    MY_CONST = upper(baz),  // No need for `concat()` since only a single argument is present
    {
        /* … */
    },
);

Wrap comma-separated arguments in concat( … ).
Or use the appropriate function (upper(), lower(), etc.) directly when only one argument is present.
Or Use the argument itself if no transformation is needed.

§[≤ 0.2.2 → 0.3.0]: Macro rename compose_idents! → compose!

§What changed?

Starting with v0.3.0 compose_idents! was renamed from to compose!.

§How to migrate?

Before (≤ 0.2.2):

use compose_idents::compose_idents;

compose_idents!(
    my_fn = concat(foo, _, bar),
    {
        fn my_fn() {}
    },
);

After (≥ 0.3.0):

use compose_idents::compose;

compose!(
    my_fn = concat(foo, _, bar),
    {
        fn my_fn() {}
    },
);

Simply replace use compose_idents::compose_idents; with use compose_idents::compose; and rename macro invocations from compose_idents!(...) to compose!(...).

§Alternatives

There are some other tools and projects dedicated to identifier manipulation:

A macro from Nightly Rust that allows to concatenate identifiers. It is limited in functionality and nowhere near to be stabilized: https://doc.rust-lang.org/std/macro.concat_idents.html
A very similar macro that doesn’t support multiple aliases and is not maintained: https://github.com/DzenanJupic/concat-idents
A macro that allows to define and refer to unique temporary variables: https://crates.io/crates/templest

§Development

The following standards are followed to maintain the project:

Macros§

compose: Compose identifiers from the provided parts and replace their aliases in the code block.
compose_identsDeprecated: Compose identifiers from the provided parts and replace their aliases in the code block.

Attribute Macros§

compose_item: Compose identifiers from the provided parts and replace their aliases in the decorated item.