# YAML Tags Reference

This document provides a comprehensive reference for all YAML tags provided by `yayaml`.
These tags allow you to create Python objects directly within YAML files.

## Built-in Function Tags

These tags apply Python built-in functions to their arguments.

### Aggregation Functions

| Tag | Description | Example | Result |
|-----|-------------|---------|--------|
| `!any` | Returns `True` if any element is truthy | `!any [false, 0, true]` | `True` |
| `!all` | Returns `True` if all elements are truthy | `!all [true, 5, 0]` | `False` |
| `!min` | Returns the minimum value | `!min [1, 2, 3]` | `1` |
| `!max` | Returns the maximum value | `!max [1, 2, 3]` | `3` |
| `!sum` | Returns the sum of elements | `!sum [1, 2, 3]` | `6` |
| `!prod` | Returns the product of elements | `!prod [2, 3, 4]` | `24` |
| `!sorted` | Returns sorted list (ascending) | `!sorted [2, 1, 3]` | `[1, 2, 3]` |
| `!isorted` | Returns sorted list (descending) | `!isorted [2, 1, 3]` | `[3, 2, 1]` |
| `!len` | Returns length of sequence/mapping | `!len [[1, 2, 3]]` | `3` |

**Note on `!len` syntax:** The `!len` tag requires a wrapper list around its argument. This enables composability with nested constructors:

```yaml
# Length of a plain list (note the double brackets)
list_len: !len [[1, 2, 3]]           # 3

# Length of a dict
dict_len: !len [{a: 1, b: 2}]        # 2

# Length of a string
str_len: !len [foobar]               # 6

# Works with nested constructors
range_len: !len [!range 10]          # 10
sorted_len: !len [!sorted [3, 1, 2]] # 3
```

### Scalar Functions

| Tag | Description | Example | Result |
|-----|-------------|---------|--------|
| `!abs` | Absolute value | `!abs -1` | `1.0` |
| `!int` | Convert to integer | `!int 1.23` | `1` |
| `!round` | Round to nearest integer | `!round 9.87` | `10` |


## Operator Tags

These tags provide access to Python operators.

### Arithmetic Operators

| Tag | Description | Example | Result |
|-----|-------------|---------|--------|
| `!add` | Addition (`+`) | `!add [1, 2]` | `3` |
| `!sub` | Subtraction (`-`) | `!sub [5, 3]` | `2` |
| `!mul` | Multiplication (`*`) | `!mul [3, 4]` | `12` |
| `!truediv` | True division (`/`) | `!truediv [3, 2]` | `1.5` |
| `!floordiv` | Floor division (`//`) | `!floordiv [3, 2]` | `1` |
| `!mod` | Modulo (`%`) | `!mod [3, 2]` | `1` |
| `!pow` | Power (`**`), optional modulo | `!pow [2, 4]` | `16` |
| `!negate` | Negation (`-x`) | `!negate [1]` | `-1` |

The `!pow` tag also supports a third argument for modular exponentiation:

```yaml
pow_mod: !pow [2, 4, 3]  # pow(2, 4, 3) = 16 % 3 = 1
```

### Logical Operators

| Tag | Description | Example | Result |
|-----|-------------|---------|--------|
| `!not` | Logical NOT | `!not [true]` | `False` |
| `!and` | Bitwise AND | `!and [true, false]` | `False` |
| `!or` | Bitwise OR | `!or [true, false]` | `True` |
| `!xor` | Bitwise XOR | `!xor [true, true]` | `False` |
| `!invert` | Bitwise inversion (`~`) | `!invert [true]` | `-2` |

### Comparison Operators

| Tag | Description | Example | Result |
|-----|-------------|---------|--------|
| `!lt` | Less than (`<`) | `!lt [1, 2]` | `True` |
| `!le` | Less than or equal (`<=`) | `!le [2, 2]` | `True` |
| `!eq` | Equal (`==`) | `!eq [3, 3]` | `True` |
| `!ne` | Not equal (`!=`) | `!ne [3, 1]` | `True` |
| `!neq` | Not equal (alias for `!ne`) | `!neq [3, 1]` | `True` |
| `!ge` | Greater than or equal (`>=`) | `!ge [2, 2]` | `True` |
| `!gt` | Greater than (`>`) | `!gt [4, 3]` | `True` |

### Container Operators

| Tag | Description | Example | Result |
|-----|-------------|---------|--------|
| `!contains` | Check membership (`in`) | `!contains [[1, 2, 3], 2]` | `True` |
| `!concat` | Concatenate sequences | `!concat [[1, 2], [3, 4]]` | `[1, 2, 3, 4]` |


## String Tags

These tags provide string manipulation capabilities.

| Tag | Description | Example | Result |
|-----|-------------|---------|--------|
| `!format` | String formatting | `!format ["{} + {} = {}", 1, 2, 3]` | `"1 + 2 = 3"` |
| `!join` | Join strings | `!join [", ", [a, b, c]]` | `"a, b, c"` |
| `!split` | Split string | `!split ["a b c", " "]` | `["a", "b", "c"]` |
| `!oneline` | Collapse whitespace | `!oneline "foo  bar\n  baz"` | `"foo bar baz"` |
| `!collapse-whitespace` | Collapse whitespace (same as `!oneline`) | `!collapse-whitespace "foo  bar"` | `"foo bar"` |

### Format Examples

The `!format` tag supports both positional and keyword arguments:

```yaml
# Positional arguments
greeting: !format ["{} is not {}", foo, bar]  # "foo is not bar"

# Keyword arguments via mapping
message: !format
  fstr: "{name}: {value}"
  name: fish
  value: spam
# Result: "fish: spam"

# Nested formatting
stats: !format
  fstr: "results: {stats[mean]:.2f} +/- {stats[std]:.2f}"
  stats:
    mean: 1.632
    std: 0.026
# Result: "results: 1.63 +/- 0.03"
```


## Type Tags

These tags create Python type objects.

| Tag | Description | Example | Result |
|-----|-------------|---------|--------|
| `!slice` | Create slice object | `!slice [0, 10, 2]` | `slice(0, 10, 2)` |
| `!range` | Create range object | `!range [5, 10, 2]` | `range(5, 10, 2)` |
| `!deepcopy` | Deep copy value | `!deepcopy 123` | `123` |

### Slice Syntax

```yaml
slices:
  - !slice 5           # slice(5) - equivalent to [:5]
  - !slice [5]         # slice(5)
  - !slice [0, ~]      # slice(0, None) - equivalent to [0:]
  - !slice [~, 0]      # slice(None, 0) - equivalent to [:0]
  - !slice [0, 10, 2]  # slice(0, 10, 2) - equivalent to [0:10:2]
```

### Range Syntax

```yaml
ranges:
  - !range 10          # range(10)
  - !range [10]        # range(10)
  - !range [5, 10]     # range(5, 10)
  - !range [5, 10, 2]  # range(5, 10, 2)
```


## List Generation Tags

### `!listgen`

Generate lists with various options:

```yaml
# Simple range-based generation
simple: !listgen [0, 10, 2]  # [0, 2, 4, 6, 8]

# Advanced options via mapping
advanced: !listgen
  from_range: [0, 10, 3]
  unique: true
  append: [100]
  remove: [0]
  sort: true
# Result: [3, 6, 9, 100]
```


## NumPy Tags

These tags create NumPy arrays or lists of values.

| Tag | Description | Example | Result |
|-----|-------------|---------|--------|
| `!array` | Create NumPy array | `!array [[1, 2, 3]]` | `np.array([1, 2, 3])` |
| `!linspace` | Evenly spaced values | `!linspace [-1, 1, 5]` | `[-1., -0.5, 0., 0.5, 1.]` |
| `!logspace` | Logarithmically spaced | `!logspace [1, 4, 4]` | `[10., 100., 1000., 10000.]` |
| `!arange` | Values with step | `!arange [0, 1, 0.2]` | `[0., 0.2, 0.4, 0.6, 0.8]` |

Note: `!linspace`, `!logspace`, and `!arange` return Python lists (not NumPy arrays) for better YAML serialization.


## Conditional Tags

These tags allow conditional value selection.

| Tag | Description | Example | Result |
|-----|-------------|---------|--------|
| `!if-else` | Conditional selection | `!if-else [true, "yes", "no"]` | `"yes"` |
| `!if-unix-else` | Unix platform check | `!if-unix-else ["unix", "other"]` | `"unix"` on Linux/macOS |
| `!if-windows-else` | Windows platform check | `!if-windows-else ["win", "other"]` | `"win"` on Windows |

### Combining with Operators

Conditionals can be combined with comparison operators:

```yaml
# Check if 8 != 9
result: !if-else [!ne [8, 9], "8 is not 9", "8 is 9"]
# Result: "8 is not 9"
```


## Environment Variable Tags

These tags read environment variables.

| Tag | Description | Example | Result |
|-----|-------------|---------|--------|
| `!getenv` | Get env var (required) | `!getenv PATH` | Value of `$PATH` |
| `!env` | Alias for `!getenv` | `!env HOME` | Value of `$HOME` |
| `!getboolenv` | Get env var as boolean | `!getboolenv [DEBUG, "false"]` | `False` |
| `!boolenv` | Alias for `!getboolenv` | `!boolenv [DEBUG, "0"]` | `False` |

### With Fallback Values

```yaml
# With fallback (returns fallback if var not set)
username: !getenv [USER, "unknown_user"]

# Boolean env vars (parses strings like "true", "1", "yes", "on")
debug_mode: !getboolenv [DEBUG, "false"]
```


## Path Tags

These tags help with file path manipulation.

| Tag | Description | Example | Result |
|-----|-------------|---------|--------|
| `!expanduser` | Expand `~` in path | `!expanduser ~/some/path` | `/home/user/some/path` |
| `!joinpath` | Join path components | `!joinpath [foo, bar, baz.txt]` | `foo/bar/baz.txt` |

### Path Examples

```yaml
# Expand user home directory
config_path: !expanduser ~/.config/myapp

# Join path components
data_file: !joinpath
  - "~"
  - data
  - output
  - results.csv
# Result: "~/data/output/results.csv"
```


## Expression Tag

The `!expr` tag evaluates simple mathematical expressions:

```yaml
expressions:
  simple: !expr 1 + 2 * 3       # 7
  power: !expr 2**4             # 16
  parens: !expr (2 + 3) * 4     # 20
  scientific: !expr 1e-10       # 0.0000000001
  infinity: !expr inf           # float('inf')
  nan: !expr NaN                # float('nan')
```

**Supported operations:**
- Basic arithmetic: `+`, `-`, `*`, `/`, `**`
- Parentheses for grouping
- Scientific notation: `1e10`, `1E-5`
- Special values: `inf`, `-inf`, `NaN`


## Utility Tags

| Tag | Description | Example | Result |
|-----|-------------|---------|--------|
| `!str-to-bool` | Convert string to bool | `!str-to-bool "yes"` | `True` |
| `!deepcopy` | Deep copy any value | `!deepcopy *anchor` | Copy of anchored value |

### Boolean String Values

The following strings are recognized as boolean values by `!str-to-bool` and `!getboolenv`:

- **True:** `true`, `yes`, `on`, `1`
- **False:** `false`, `no`, `off`, `0`

(Case-insensitive)