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:

# 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:

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:

# 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

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

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:

# 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:

# 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

# 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

# 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:

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)