[](https://crates.io/crates/compose-idents)
[](https://docs.rs/compose-idents)
[](https://github.com/rust-lang/rust/releases/tag/1.80.0)
# compose-idents
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!`][1] macro from the nightly Rust, which is limited in capabilities and has not been stabilized
[since 2015][2].
[1]: https://doc.rust-lang.org/std/macro.concat_idents.html
[2]: https://github.com/rust-lang/rust/issues/29599
## 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):
```rust
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:
```rust
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):
```rust
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:
```rust
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:
```rust
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:
```rust
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:
```rust
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:
```rust
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:
```rust
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`:
```rust
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:
```rust
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.
```rust
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:
```rust
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:
```rust
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.
```plain,ignore
// 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:
```plain,ignore
alias1 = foo,
alias2 = concat(alias1, _, bar), // alias1 is re-used here
```
#### Types
| `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.
| `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.
| `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.
| `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.
| `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.
| `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:
```text,ignore
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):
```rust,ignore
compose_idents!(
my_fn = concat(foo, bar); // ← Notice usage of semicolons
MY_VAR = concat(FOO, BAZ);
{
/* … */
};
);
```
After (0.0.5+):
```rust,ignore
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):
```rust,ignore
compose_idents!(
my_fn = [foo, _, bar], // Notice usage of brackets
MY_CONST = [upper(baz)],
{
/* … */
},
);
```
After (≥ 0.2.0, ≤ v0.2.2):
```rust,ignore
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
{
/* … */
},
);
```
1. Wrap comma-separated arguments in `concat( … )`.
2. Or use the appropriate function (`upper()`, `lower()`, etc.) directly when only one argument is present.
3. 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):
```rust,ignore
use compose_idents::compose_idents;
compose_idents!(
my_fn = concat(foo, _, bar),
{
fn my_fn() {}
},
);
```
After (≥ 0.3.0):
```rust,ignore
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:
- <https://www.conventionalcommits.org/en/v1.0.0/>
- <https://semver.org/>
- <https://keepachangelog.com/en/1.1.0/>
- <https://adr.github.io/madr/>