# Weld
`weld!` is the single entrypoint for the crate. It accepts any valid Rust item — structs, functions, trait implementations, constants, string literals — and processes any `@[...]` interpolators it finds within, emitting their result. The interpolator syntax is intentionally minimal: tokens go in, a chain of `|` separates modifiers and transforms the previous result in the chain, and an identifier or string value comes out.
## Groups
Inside `@[...]`, you can organise tokens into named groups and apply modifiers to them. There are two kinds.
### Single-value groups `(...)`
Tokens inside `()` are concatenated into a single value before any modifiers are applied. Think of it as: *everything in here is one thing*.
```rust,ignore
weld!(
const @[(super duper) | snek] = "";
// renders: const super_duper = "";
);
```
### List groups `[...]`
Tokens inside `[]` are kept as a *collection*. Modifiers that work on individual values (casing, replace, trim, etc.) are applied to each item independently. Modifiers that work on structure (reverse, join, slice, etc.) operate on the collection as a whole.
```rust,ignore
weld!(
const @[([er sup] | reverse) _duper] = "";
// renders: const super_duper = "";
// ('reverse' flips the order of items in the list, not the characters within them)
);
```
Groups can be nested, and modifiers chain naturally across levels:
```rust,ignore
weld!(
struct @[([([er sup] | reverse) -duper] | camel) | pascal] {
pub id: i64,
};
// renders: struct SuperDuper { ... }
);
```
This is a contrived example — but the point is that you can compose arbitrarily, and as long as the final result is a valid Rust identifier, the compiler will be perfectly happy and won't ask any questions.
## Raw Indentifiers
Raw identifiers are handled automatically. If a token is a reserved word, you can pass it in using Rust's `r#` prefix — `r#loop`, `r#type`, and so on — and `weld!` will accept it without complaint. In the other direction, if the result of a modifier chain happens to land on a reserved word, the `r#` prefix will be added for you. If you passed a raw identifier in but the transformations produced something that no longer needs it, the prefix is quietly removed. You shouldn't have to think about it either way.
## Modifiers
Modifiers are chained with `|` inside a group. Each one receives the output of the previous step.
### Casing
Casing modifiers use the [`heck`](https://docs.rs/heck) crate under the hood.
| Modifier | Aliases | Example output |
|-------------------|-----------------------------|----------------|
| `lowercase` | `lower` | `hello_world` |
| `uppercase` | `upper` | `HELLO_WORLD` |
| `pascalcase` | `pascal`, `uppercamelcase` | `HelloWorld` |
| `camelcase` | `camel`, `lowercamelcase` | `helloWorld` |
| `snakecase` | `snek`, `snake`, `snekcase` | `hello_world` |
| `titlecase` | `title` | `Hello World` |
| `kebabcase` | `kebab` | `hello-world` |
| `traincase` | `train` | `Hello-World` |
| `shoutykebabcase` | `shoutykebab` | `HELLO-WORLD` |
| `shoutysnakecase` | `shoutysnake`, `shoutysnek` | `HELLO_WORLD` |
> **A note on tokens vs strings:** When applied to identifiers (function names, struct names, etc.), `kebabcase`, `traincase`, and `shoutykebabcase` won't work — hyphenated identifiers aren't valid Rust. `titlecase` will behave like `pascalcase` in that context. When applied to string literals, all of them work as intended.
### `singular` / `plural`
`singular` strips a trailing `s`; `plural` adds one. No linguistic analysis is happening here — it's string manipulation wearing a vocabulary waistcoat.
```rust,ignore
weld!(
pub struct @[Users | singular | pascal] { pub id: i64 }
// renders: pub struct User { ... }
);
```
---
### `replace{pattern, replacement}`
Replaces all non-overlapping occurrences of a pattern with a replacement string.
```rust,ignore
weld!(const @[(a long ident) | replace{"long", "small"} | snek] = "");
// renders: const a_small_ident = "";
```
---
### `substr{start?, end?}` / `substring`
Returns the substring from `start` up to (not including) `end`. Both are optional. Indexes are zero-based.
```rust,ignore
weld!(const @[(a long identifier) | substr{, 9} | snek] = "");
// renders: const a_long_ident = "";
```
---
### `reverse` / `rev`
On a single value: reverses the characters.
On a list group: reverses the order of items (not the characters within them).
```rust,ignore
weld!(const @[(no lemon no melon) | reverse | snek] = "");
// renders: const nolem_on_nomel_on = "";
```
---
### `repeat{n}` / `rep` / `times`
Creates a new value by repeating the current value `n` times.
```rust,ignore
weld!(const rawhide = @[",rolling' " | timess{3} | substr{1}]);
// renders: const rawhide = "rolling' ,rolling' ,rolling' ";
```
---
### `split{separator}`
Splits the value by a character, string, or index (any integer > 0).
The behaviour differs between group types:
- In a **single-value group** `(...)`: splits the concatenated value into pieces.
- In a **list group** `[...]`: splits each item individually, adding the results back into the collection at that position.
**Splitting by character or string:**
```rust,ignore
// Single-value group: splits on '-', lowercases each part, joins with ", "
weld!(const val = @[(("get-one" two - "3-4" Struct) | split{'-'} | lower | join{", "})]);
// renders: const val = "get, onetwo, 3, 4struct";
// List group: each item is split individually
weld!(const val = @[["get-one" two - "3-4" Struct] | split{"-"} | lower | join{", "}]);
// renders: const val = "get, one, two, 3, 4, struct";
```
**Splitting by index:**
Splits the value every N characters. If the index is larger than the value's length, the argument is ignored.
```rust,ignore
weld!(const val = @[(("get-" Test - Struct) | split{6} | lower | join{"_"})]);
// renders: const val = "get-te_st-struct";
weld!(const val = @[["get-" Test - Struct] | split{2} | lower | join{","}]);
// renders: const val = "ge,t-,te,st,-,st,ruct";
```
---
### `join{separator?}`
Flattens a list into a single value, with an optional separator between items. If the current value is already a single value, it passes through unchanged.
```rust,ignore
weld!(const val = @[["get-" Test - Struct] | join{","}]);
// renders: const val = "get-,Test,-,Struct";
```
---
### `padstart{length, pad}` / `padleft` / `padl`
Pads from the **start** of the value until it reaches `length` characters. The pad string is repeated and/or truncated as needed. If the value is already at or beyond `length`, it's returned unchanged.
```rust,ignore
weld!(const val = @[("get-" Test-Struct) | padleft{20, "-"}]);
// renders: const val = "-----get-Test-Struct"
// (total length 20, padded with '-' on the left)
```
---
### `padend{length, pad}` / `padright` / `padr`
Same as `padstart`, but pads from the **end**.
```rust,ignore
weld!(const val = @[("get-" Test-Struct) | padright{20, "-"}]);
// renders: const val = "get-Test-Struct-----"
```
---
### `slice{start?, end?}`
Extracts a portion of the string. Both positions are optional and support **negative indexing** (counting backwards from the end). If `start` is greater than `end`, returns an empty value.
```rust,ignore
weld!(const val = @["get_" Test_Struct | slice{5}]);
// renders: const val = "get_Struct"
weld!(const val = @[("_get_" Test_Struct) | slice{1, -4}]);
// renders: const val = "get_Test_St"
weld!(const val = @[("_get_" Test_Struct) | slice{-6, -4}]);
// renders: const val = "St"
weld!(const val = @["get_" Test_Struct | slice{-4, -6}]);
// renders: const val = "" (start > end)
```
---
### `splice{mode, start?, end?, replacement?}`
The most involved modifier. Removes a range from the value, optionally replaces it with new content, and returns either the modified value or the removed portion — depending on the mode.
**Modes:**
| Mode keywords | Returns |
|------------------------|-------------------------------------------------------|
| `into`, `val`, `value` | The modified string (with the range removed/replaced) |
| `out`, `removed`, `rm` | The removed portion |
**Basic removal:**
```rust,ignore
// Remove from position 1 onwards → return the result
weld!(const val = @[("get_" Test_Struct) | splice{into, 1}]);
// renders: const val = "g"
// Remove from position 1 onwards → return what was removed
weld!(const val = @[("get_" Test_Struct) | splice{out, 1}]);
// renders: const val = "et_Test_Struct"
```
**Removing a range:**
```rust,ignore
weld!(const val = @[("get_" Test_Struct) | splice{into, 1, 4}]);
// renders: const val = "gTest_Struct"
weld!(const val = @[("get_" Test_Struct) | splice{out, 1, 4}]);
// renders: const val = "et_"
```
**Replacing a range:**
```rust,ignore
weld!(const val = @[("get_" Test_Struct) | splice{value, 1, 4, "ot_"}]);
// renders: const val = "got_Test_Struct"
// Omit start to replace from the beginning
weld!(const val = @[("get_" Test_Struct) | splice{val, , 4, "got_"}]);
// renders: const val = "got_Test_Struct"
// Omit end to replace to the end of the string
weld!(const val = @[("get_" Test_Struct) | splice{value, 1, , "ot_"}]);
// renders: const val = "got_"
// Omit both to replace the entire value
weld!(const val = @[("get_" Test_Struct) | splice{val, , , "new"}]);
// renders: const val = "new"
```
**Negative positions** count from the end:
```rust,ignore
weld!(const val = @[("get_" Test_Struct) | splice{into, -4}]);
// renders: const val = "get_Test_St"
weld!(const val = @[("get_" Test_Struct) | splice{into, -4, -1, "<->"}]);
// renders: const val = "get_Test_St<->t"
```
**Aliases:** `splice_into` and `splice_out` are shorthand for `splice{into, ...}` and `splice{out, ...}`:
```rust,ignore
weld!(const val = @[("get_" Test_Struct) | splice_out{-4, -1}]);
// renders: const val = "ruc"
weld!(const val = @[("get_" Test_Struct) | splice_into{-4, -1, "<->"}]);
// renders: const val = "get_Test_St<->t"
```
---
## A More Complete Example
Here's what the modifier chain looks like when used for something you might actually want to do:
```rust,ignore
use tweld::weld;
weld! {
pub struct @[Users | singular | pascal] {
pub id: i64,
}
impl @[Users | singular | pascal] {
// Generates: pub fn get_user_profile_by_id(id: i64)
pub fn @[((get_ UserProfiles) | replace{"s", ""} | snek) _by_id](id: i64) {
println!("Fetching @[Users | singular | lower] {}...", id);
}
}
}
```
The modifiers don't need to be tidy on the inside. They just need to produce something valid on the outside — which is, when you think about it, a reasonable standard to hold most things to.
---
## Status
Tweld is currently in **alpha (RC2)**. The feature set for `1.0` is complete and testing is still an ongoing endeavor. The API may still shift before stabilisation.
Bug reports, feature requests, and strong opinions about identifier naming are all welcome.
---
## License
Licensed under either of [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE) at your option.