# ext_format

A small, yet powerful, Rust crate for string interpolation. Inspired by Rust's macro rules, it provides two main macros: `ext_format!` and `ext_format_unindent!` \
The `ext_format_unindent!` macro works exactly like `ext_format!`, but first trims leading whitespace, to make working with multiline strings less painful.

## Installation

Add the following to your `Cargo.toml`:

```toml
[dependencies]
ext_format = "0.1.0"
```

## Usage

### Basic Interpolation

Use `$` for basic interpolation:

```rust
let name = "Alice";
let output = ext_format!("Hello, $name!");
```

### Binding new variable names
Use `{name:new_name}` to bind a new name to a variable.

```rust
let number = 42;
let output = ext_format!("Number: ${number:n} $n $n");
// Output: "Number: 42 42 42"
```


### Basic Repetition

- `$($var)*`: No separators
- `$($var),*`: Character as a separator
- `$($var)(...)*`: String as a separator (supports escaped characters)

```rust
let numbers = vec![1, 2, 3];
let output = ext_format!("Numbers: $($numbers),*");
// Output: "Numbers: 1, 2, 3"
```

For using newlines as separators:

```rust
let items = vec!["apple", "banana", "cherry"];
let output = ext_format!("Items:\n$($items)(\n)*");
// Output:
// Items:
// apple
// banana
// cherry
```

### Repetition with Hidden Variables

Use `@` to include variables that control the loop but aren't included in the output.

```rust
let items = vec!["apple", "banana"];
let counter = vec![1, 2];
let output = ext_format!("Items:\n$(@counter)$($items)\n)*");
// Output:
// Items:
// apple
// banana
```

### Repetition with named Iteration Variables

Use `{name:new_name}` to bind a Name to a Variable.

```rust
let numbers = vec![1, 2, 3];
let output = ext_format!("Numbers: $(${numbers:number} $number),*");
// Output: "Numbers: 1 1, 2 2, 3 3"
```

### Nested Repetitions

Repetitions can contain other repetitions, acting like nested for-loops:

```rust
let matrix = vec![vec![1, 2, 3], vec![4, 5, 6], vec![7, 8, 9]];
let output = ext_format!("Matrix:\n$(@{matrix:row}$($row) *)(\n)*");
// Output:
// Matrix:
// 1 2 3
// 4 5 6
// 7 8 9
```

### Zipped Variables

Variables in a single repetition layer are automatically zipped together, meaning they iterate in lockstep.

```rust
let names = vec!["Alice", "Bob"];
let ages = vec![30, 40];
let output = ext_format!("Profiles:\n$($names $ages)\n)*");
// Profiles:
// Alice 30
// Bob 40
```

### Multiline Strings

For multiline strings, `ext_format_unindented` can be used to avoid leading whitespace:

```rust
fn unindented() -> String {
    let matrix = vec![vec![1, 2, 3], vec![4, 5, 6], vec![7, 8, 9]];
    ext_format_unindented!(r#"
        void func3() {
            $(@{matrix:inner_matrix}printf("$($inner_matrix) *");)(\n    )*
        }
    "#)
}
let output = unindented();
// Output:
// void func3() {
//     printf("1 2 3");
//     printf("4 5 6");
//     printf("7 8 9");
// }
```

If the regular `ext_format` was used here, it would result in the following:
```rust
fn indented() -> String {
    let matrix = vec![vec![1, 2, 3], vec![4, 5, 6], vec![7, 8, 9]];
    ext_format!(r#"
        void func3() {
            $(@{matrix:inner_matrix}printf("$($inner_matrix) *");)(\n                    )*
        }
    "#)
}
let output = indented();
// Output:
//                void func3() {
//                    printf("1 2 3");
//                    printf("4 5 6");
//                    printf("7 8 9");
//                }
```
With the indentation of the resulting string depending on the indentation of the function itself.

## License

This project is licensed under the MIT License. See the [LICENSE.md](LICENSE.md) file for details.