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.
-
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.
This section contains various usage examples. For additional examples, see the tests/ directory of the repository.
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("[email protected]".into()));
assert_eq!(user.name(), "Bob");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();This is a complete reference to the functionality of this library split into thematic sections.
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);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);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);#[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 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.
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);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);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");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;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);Expressions consist of values (foo, Foo::Bar, 1 + 1, "bar", 123, etc) and
function calls (concat(foo, _, bar), camel_case(foo_bar), etc).
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 literals could be formatted using % alias % syntax. This is especially useful for generating doc-attributes.
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.
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.
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.
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)),
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
| 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. |
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 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 |
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> |
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 |
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 |
- 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.
This section describes what to do to migrate code that uses deprecated features to up-to-date state.
Starting with v0.0.5 commas were introduced as a separator of alias definitions. The old semicolon separator is
deprecated.
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.
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.
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.
Starting with v0.3.0 compose_idents! was renamed from to compose!.
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!(...).
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
The following standards are followed to maintain the project: