[any](https://github.com/bazelbuild/starlark/blob/master/spec.md#any): returns true if any value in the iterable object have a truth value of true.
```
any([0, True]) == True
any([0, 1]) == True
any([0, 1, True]) == True
any([0, 0]) == False
any([0, False]) == False
```
`function` **attr**
Creates a field definition for a trait, with a type, optional default value, and optional description.
`default` must match the declared type. Mutable defaults (lists, dicts) are deep-copied
when a trait instance is created, so each instance gets its own independent copy.
Example:
```starlark theme={null}
BazelTrait = trait(host=str, port=attr(int, default = 80))
r = BazelTrait(host="localhost") # port defaults to 80
```
`function` **breakpoint**
Get a textual representation of the call stack.
This is intended only for debugging purposes to display to a human and
should not be considered stable or parseable.
strip\_frames will pop N frames from the top of the call stack, which can
be useful to hide non-interesting lines - for example, strip\_frames=1
will hide the call to and location of `call_stack()` itself.
`function` **call\_stack\_frame**
Get a structural representation of the n-th call stack frame.
With `n=0` returns `call_stack_frame` itself.
Returns `None` if `n` is greater than or equal to the stack size.
`function` **chr**
[chr](https://github.com/bazelbuild/starlark/blob/master/spec.md#bool): returns a string encoding a codepoint.
`chr(i)` returns a string that encodes the single Unicode code
point whose value is specified by the integer `i`. `chr` fails
unless `0 ≤ i ≤ 0x10FFFF`.
```
chr(65) == 'A'
chr(1049) == 'Й'
chr(0x1F63F) == '😿'
```
`function` **debug**
Print the value with full debug formatting. The result may not be stable over time. Intended for debugging purposes and guaranteed to produce verbose output not suitable for user display.
`function` **dir**
[dir](https://github.com/bazelbuild/starlark/blob/master/spec.md#dir): list attributes of a value.
`dir(x)` returns a list of the names of the attributes (fields and
methods) of its operand. The attributes of a value `x` are the names
`f` such that `x.f` is a valid expression.
```
"capitalize" in dir("abc")
```
`function` **enum**
The `enum` type represents one value picked from a set of values.
For example:
```python theme={null}
MyEnum = enum("option1", "option2", "option3")
```
This statement defines an enumeration `MyEnum` that consists of the three values `"option1"`, `"option2"` and `option3`.
Now `MyEnum` is defined, it's possible to do the following:
* Create values of this type with `MyEnum("option2")`. It is a runtime error if the argument is not one of the predeclared values of the enumeration.
* Get the type of the enum suitable for a type annotation with `MyEnum`.
* Given a value of the enum (for example, `v = MyEnum("option2")`), get the underlying value `v.value == "option2"` or the index in the enumeration `v.index == 1`.
* Get a list of the values that make up the array with `MyEnum.values() == ["option1", "option2", "option3"]`.
* Treat `MyEnum` a bit like an array, with `len(MyEnum) == 3`, `MyEnum[1] == MyEnum("option2")` and iteration over enums `[x.value for x in MyEnum] == ["option1", "option2", "option3"]`.
Enumeration types store each value once, which are then efficiently referenced by enumeration values.
`function` **enumerate**
[enumerate](https://github.com/bazelbuild/starlark/blob/master/spec.md#enumerate): return a list of (index, element) from an iterable.
`enumerate(x)` returns a list of `(index, value)` pairs, each containing
successive values of the iterable sequence and the index of the
value within the sequence.
The optional second parameter, `start`, specifies an integer value to
add to each index.
```
enumerate(["zero", "one", "two"]) == [(0, "zero"), (1, "one"), (2, "two")]
enumerate(["one", "two"], 1) == [(1, "one"), (2, "two")]
```
`function` **eval\_type**
Declares a feature — a composable behavior injector for the fragment system.
The `implementation` function receives a `FeatureContext` and runs after all
config.axl files have been evaluated. It can inject closures into fragment
hook lists via `ctx.fragments[FragmentType].hook.append(...)`.
Feature CLI args are injected into every task subcommand on the CLI. Only named
optional flags are supported — positional args and `required = true` are not
allowed because features apply globally and would break any task that doesn't
supply the flag.
Every feature automatically gets an `enabled` CLI arg. It shows up as
`--{name}:enabled` on the command line and is accessible as `ctx.args.enabled`
in the implementation. Set `enabled = False` for opt-in features.
## Naming
Features must be exported as **CamelCase** (`ArtifactUpload`).
This is enforced at definition time. Features are referenced as type keys
(`ctx.features[ArtifactUpload]`), mirroring Bazel's provider convention
(`dep[CcInfo]`); CamelCase signals this type-key role.
The `name` field sets the kebab-case slug used as a prefix for every CLI arg this
feature declares: a feature named `"artifact-upload"` with arg `mode` exposes
`--artifact-upload:mode`. The name is auto-derived from the CamelCase export name
via `to_command_name` (`ArtifactUpload` → `artifact-upload`) if not set explicitly.
`display_name` overrides the Title Case name shown in CLI help section headings.
## Arg names
Arg keys must be `snake_case` (`[a-z][a-z0-9_]*`). There are two kinds:
* **CLI args** (`args.string(...)`, `args.boolean(...)`, etc.) — exposed as
`--{name}-{arg}` flags on every task subcommand; must be optional.
* **Config-only args** (`args.custom(type, default = …)`) — set in `config.axl`
only, not shown in help.
Both kinds are accessible as `ctx.args.arg_name` in the implementation.
## Example
```starlark theme={null}
def _impl(ctx: FeatureContext):
ctx.fragments[BazelFragment].build_end.append(
lambda task_ctx, state: upload_artifacts(
task_ctx, ctx.args.bucket, ctx.args.mode
)
)
ArtifactUpload = feature(
summary = "Upload build artifacts to S3 storage",
implementation = _impl,
args = {
"bucket": args.custom(str | None, default = None), # config.axl only
"mode": args.string(default = "auto"), # CLI flag: --artifact-upload-mode
},
)
```
`function` **field**
Creates a field record. Used as an argument to the `record` function.
```
rec_type = record(host=field(str), port=field(int), mask=field(int, default=255))
rec = rec_type(host="localhost", port=80)
rec.port == 80
rec.mask == 255
```
`function` **filter**
Apply a predicate to each element of the iterable, returning those that match. As a special case if the function is `None` then removes all the `None` values.
```
filter(bool, [0, 1, False, True]) == [1, True]
filter(lambda x: x > 2, [1, 2, 3, 4]) == [3, 4]
filter(None, [True, None, False]) == [True, False]
```
`function` **getattr**
[getattr](https://github.com/bazelbuild/starlark/blob/master/spec.md#getattr): returns the value of an attribute
`getattr(x, name)` returns the value of the attribute (field or method)
of x named `name`. It is a dynamic error if x has no such attribute.
`getattr(x, "f")` is equivalent to `x.f`.
`getattr(x, "f", d)` is equivalent to `x.f if hasattr(x, "f") else d`
and will never raise an error.
```
getattr("banana", "split")("a") == ["b", "n", "n", ""] # equivalent to "banana".split("a")
```
`function` **hasattr**
[hasattr](https://github.com/bazelbuild/starlark/blob/master/spec.md#hasattr): test if an object has an attribute
`hasattr(x, name)` reports whether x has an attribute (field or method)
named `name`.
`function` **hash**
[hash](https://github.com/bazelbuild/starlark/blob/master/spec.md#hash): returns the hash number of a value.
`hash(x)` returns an integer hash value for x such that `x == y`
implies `hash(x) == hash(y)`.
`hash` fails if x, or any value upon which its hash depends, is
unhashable.
```
hash("hello") != hash("world")
```
`function` **isinstance**
Check if a value matches the given type.
This operation can be very fast or very slow depending on how it is used.
`isinstance(x, list)` is very fast,
because it is compiled to a special bytecode instruction.
`isinstance(x, list[str])` is `O(N)` operation
because it checks every element in this list.
`L = list; [isinstance(x, L) for x in y]` is slow when `L` is not a constant:
`isinstance()` first converts `list` to a type in a loop, which is slow.
But last operation can be optimized like this:
`L = eval_type(list); [isinstance(x, L) for x in y]`:
`eval_type()` converts `list` value into prepared type matcher.
`function` **len**
[len](https://github.com/bazelbuild/starlark/blob/master/spec.md#len): get the length of a sequence
`len(x)` returns the number of elements in its argument.
It is a dynamic error if its argument is not a sequence.
```
len(()) == 0
len({}) == 0
len([]) == 0
len([1]) == 1
len([1,2]) == 2
len({'16': 10}) == 1
len(True) # error: not supported
```
`function` **map**
Apply a function to each element of the iterable, returning the results.
```
map(abs, [7, -5, -6]) == [7, 5, 6]
map(lambda x: x * 2, [1, 2, 3, 4]) == [2, 4, 6, 8]
```
`function` **max**
[max](https://github.com/bazelbuild/starlark/blob/master/spec.md#max): returns the maximum of a sequence.
`max(x)` returns the greatest element in the iterable sequence x.
It is an error if any element does not support ordered comparison,
or if the sequence is empty.
The optional named parameter `key` specifies a function to be applied
to each element prior to comparison.
```
max([3, 1, 4, 1, 5, 9]) == 9
max("two", "three", "four") == "two" # the lexicographically greatest
max("two", "three", "four", key=len) == "three" # the longest
```
`function` **min**
[min](https://github.com/bazelbuild/starlark/blob/master/spec.md#min): returns the minimum of a sequence.
`min(x)` returns the least element in the iterable sequence x.
It is an error if any element does not support ordered comparison,
or if the sequence is empty.
```
min([3, 1, 4, 1, 5, 9]) == 1
min("two", "three", "four") == "four" # the lexicographically least
min("two", "three", "four", key=len) == "two" # the shortest
```
`function` **ord**
[ord](https://github.com/bazelbuild/starlark/blob/master/spec.md#ord): returns the codepoint of a character
`ord(s)` returns the integer value of the sole Unicode code point
encoded by the string `s`.
If `s` does not encode exactly one Unicode code point, `ord` fails.
Each invalid code within the string is treated as if it encodes the
Unicode replacement character, U+FFFD.
Example:
```
ord("A") == 65
ord("Й") == 1049
ord("😿") == 0x1F63F
```
`function` **partial**
A `record` type represents a set of named values, each with their own type.
For example:
```python theme={null}
MyRecord = record(host=str, port=int)
```
This above statement defines a record `MyRecord` with 2 fields, the first named `host` that must be of type `str`, and the second named `port` that must be of type `int`.
Now `MyRecord` is defined, it's possible to do the following:
* Create values of this type with `MyRecord(host="localhost", port=80)`. It is a runtime error if any arguments are missed, of the wrong type, or if any unexpected arguments are given.
* Get the type of the record suitable for a type annotation with `MyRecord.type`.
* Get the fields of the record. For example, `v = MyRecord(host="localhost", port=80)` will provide `v.host == "localhost"` and `v.port == 80`. Similarly, `dir(v) == ["host", "port"]`.
It is also possible to specify default values for parameters using the `field` function.
For example:
```python theme={null}
MyRecord = record(host=str, port=field(int, 80))
```
Now the `port` field can be omitted, defaulting to `80` is not present (for example, `MyRecord(host="localhost").port == 80`).
Records are stored deduplicating their field names, making them more memory efficient than dictionaries.
`function` **repr**
[repr](https://github.com/bazelbuild/starlark/blob/master/spec.md#repr): formats its argument as a string.
All strings in the result are double-quoted.
```
repr(1) == '1'
repr("x") == "\"x\""
repr([1, "x"]) == "[1, \"x\"]"
repr("test \"'") == "\"test \\\"'\""
repr("x\"y😿 \\'") == "\"x\\\"y\\U0001f63f \\\\'\""
```
`function` **reversed**
[sorted](https://github.com/bazelbuild/starlark/blob/master/spec.md#sorted): sort a sequence
`sorted(x)` returns a new list containing the elements of the iterable
sequence x, in sorted order. The sort algorithm is stable.
The optional named parameter `reverse`, if true, causes `sorted` to
return results in reverse sorted order.
The optional named parameter `key` specifies a function of one
argument to apply to obtain the value's sort key.
The default behavior is the identity function.
```
sorted([3, 1, 4, 1, 5, 9]) == [1, 1, 3, 4, 5, 9]
sorted([3, 1, 4, 1, 5, 9], reverse=True) == [9, 5, 4, 3, 1, 1]
sorted(["two", "three", "four"], key=len) == ["two", "four", "three"] # shortest to longest
sorted(["two", "three", "four"], key=len, reverse=True) == ["three", "four", "two"] # longest to shortest
```
`function` **task**
Declares a task — a named CLI command with an implementation function.
## Naming
Assign the result to a **snake\_case** variable. The CLI command name is derived
automatically by converting `_` to `-` (`axl_add` → `axl-add`).
Use `name = "explicit-name"` to override.
Command names must match `[a-z][a-z0-9-]*`.
## Args
Arg keys must be `snake_case` (`[a-z][a-z0-9_]*`). There are two kinds:
* **CLI args** (`args.string(...)`, `args.int(...)`, etc.) — exposed as `--kebab-flags` on
the CLI and accessible as `ctx.args.arg_name` in the implementation. Can be overridden
in `config.axl`; an explicit CLI flag always wins over a config override.
* **Config-only args** (`args.custom(type, default = …)`) — not shown in help; set by repo
maintainers in `config.axl` via `ctx.tasks["group/name"].args.arg_name = value`.
All args are read as `ctx.args.arg_name` in the implementation regardless of kind.
## Help text
* `summary` — one-liner shown in the task list; falls back to `" task defined in "`.
* `description` — extended prose shown in `--help` (replaces summary in that view).
* `friendly_kind` — Title Case label for help section headings; auto-derived from the kind.
## Aliases
Call `.alias(defaults = {...})` to declare a new top-level command
that shares this task's implementation but exposes overridden defaults
for one or more args. See the `task.alias` docstring for details.
## Example
```starlark theme={null}
def _impl(ctx: TaskContext) -> int:
ctx.std.io.stdout.write("Hello, " + ctx.args.recipient + "\n")
return 0
greet = task(
group = ["utils"],
summary = "Say hello",
implementation = _impl,
args = {
"recipient": args.string(default = "world", description = "Who to greet"),
"greeting": args.custom(str, default = "Hello", description = "Greeting word (config.axl only)"),
},
)
```
`function` **trait**
Creates a trait type — a shared configuration object that tasks opt into.
## Naming
Traits must be exported as **CamelCase** (`MyConfig`, `BazelTrait`). This is
enforced at definition time.
## Fields
Each field must be an `attr()` definition with a `default` value. The default is used
to construct the initial trait instance lazily on first access — there is no mechanism
to inject values before that construction, so all fields must have defaults.
## Example
```starlark theme={null}
BazelTrait = trait(
extra_flags = attr(list[str], default = [], description = "Extra Bazel flags for every build"),
profile_upload = attr(bool, default = False, description = "Upload Bazel profile after build"),
)
```
`function` **zip**
[zip](https://github.com/bazelbuild/starlark/blob/master/spec.md#zip): zip several iterables together
`zip()` returns a new list of n-tuples formed from corresponding
elements of each of the n iterable sequences provided as arguments to
`zip`. That is, the first tuple contains the first element of each of
the sequences, the second element contains the second element of each
of the sequences, and so on. The result list is only as long as the
shortest of the input sequences.
```
zip() == []
zip(range(5)) == [(0,), (1,), (2,), (3,), (4,)]
zip(range(5), "abc".elems()) == [(0, "a"), (1, "b"), (2, "c")]
```
`property` **False**