hd-lang

#Glossary

This page is generated by pnpm run spec glossary --markdown. It collects the language glossary, the Standard Library glossary, and the terms the chapters define in bold that those glossaries do not list yet. Each term links to the rule, or the section, that defines it, and each definition is quoted from the specification.

#C

Term Definition Defined in
Cli trait The Cli trait reads typed command-line values over ArgParser. Typed Records (not in a hand-written glossary)

#U

Term Definition Defined in
using binding A binding, written using name = value, whose value's dispose! runs when its scope ends, in order with defer suites. Using Bindings

#A

Term Definition Defined in
access What an element reference or an element reference loop holds on its collection: from the reference's taking to the end of its call or loop, nothing may change the collection's length. ref.elem.access
active A driver context while its executor is evaluating or polling it on the current program-instance call stack. req.bang.active
available A trait method is available in a module when its trait is available to dot-call lookup there. names.visible.trait

#B

Term Definition Defined in
bare step A pipe step that is a name or path without _. expr.pipe.step-kinds
base seed hd test derives a property test case's base seed, the seed of its first case, from the test case's name. cli.test.seed (not in a hand-written glossary)
base tag A pseudo-version's base tag is the tag its form names, by the pseudo-version table, with the package's tag prefix. cli.dep.pseudo.base (not in a hand-written glossary)
bound method reference value::name, where value names a value, as a function value. fn.ref.bound
bound requirement key A requirement key that binds associated types, such as Store[Item = User]; its provider value has the trait value type dyn Store[Item = User]. Bound Requirement Keys
build directory The directory build in a package directory, where hd writes its build and cache output, such as build/debug/NAME.wasm. cli.build.directory
build profiles A program is built under one of three build profiles: debug, release, or test. Integer Arithmetic (not in a hand-written glossary)

#C

Term Definition Defined in
cache directory The one directory per user where hd keeps every fetched dependency version, read-only. Cache
call place A call v() whose callee's type implements Update, so v() = x and v() op= x store through it. Callable Values
callable value A value whose type implements Apply, read by calling it with no arguments, as in count(). Callable Values
capability grant What a program's host capability traits may touch at run time: for each trait, no limit, a total deny, or a list of scope entries. Capability Grants
cell The storage that a closure and its scope share for a captured variable. fn.capture.cell
cleanup bound The host waits under a cleanup bound, a host setting. req.entry.cancel.bound (not in a hand-written glossary)
compatibility line The versions of a package that must stay compatible: one major number, or 0.MINOR below 1.0. module.version.line
compiled entries hd stores its compiled entries in the directory obj of the cache directory. cli.cache.obj (not in a hand-written glossary)
compound assignment A statement place op= value, such as total += x, that combines an operator with a store. Compound Assignment
conflict Two or more members with one name at the smallest depth where that name occurs, including one member reached through two paths. names.conflict.definition
copy-update literal A struct literal with one leading spread, which builds a new value from an existing one. Copy-Update Literals
counted reference A reference of type *T or *mut T, which may be stored, returned, captured, and used as a type argument. ref.type.counted-forms

#D

Term Definition Defined in
Debug builders The DebugWriter methods that describe a value as a struct, tuple, list, or map. Debug Builders
declarations A declaration is an optionally public named declaration or an implementation: Declarations (not in a hand-written glossary)
default executable With no [[executable]] table in hd.toml, src/main.hd is the package's default executable, as Cargo's src/main.rs is. cli.exe.default-main (not in a hand-written glossary)
default profile hd FILE, hd run, a task, and the REPL use the default profile, which binds these traits: Host Capabilities (not in a hand-written glossary)
default type The type a literal class takes when it meets no type: i32 for integers when a member is a signed literal, usize otherwise, and f64 for floating-point literals. types.literal.local.default
dependency requirement A manifest entry PATH@VERSION that maps a dependency key to a host path and a minimum version. Dependency Requirements
depth The number of embedded fields on the path from a struct to one of its members. names.part.depth
derivation block An impl Trait for X by Structure: that applies a trait's template to one type, with optional member lines. Derivation Blocks
derived variance The variance an inherent impl parameter has in the implementation's target type, by which its methods are checked. types.variance.target.derived
dev dependency A dependency that the manifest declares in [dev-dependencies], which test code and tasks may use and a dependent never sees. module.test.dev-dependency
doc test A fenced hd block in a documentation comment of a module under the source root, compiled as its own program with one test case. module.test.doc.block
draw limit The per-case limit on draws from Choices; once it is spent, every draw returns its simplest value. std-testing.limit
driver context Where a bang call is valid: a suspending function or closure body, the host executor driving main!, or the top level of a script or REPL input. req.bang.driver-forms
duration literal A duration literal is a whole decimal integer followed by a duration unit. Duration Literals (not in a hand-written glossary)
dynamic provider A provider a closure gets at each call, because its row keeps the key. Lexical And Dynamic Providers

#E

Term Definition Defined in
element reference &xs[i] or &mut xs[i] with a list xs, or &m[k] or &mut m[k] with a map m: a reference to the slot or value, written only as an argument of one call. See ref.elem.place and ref.elem.call. ref.elem.place
embedded field A bare type-name member of a struct declaration, which embeds another struct as an inline field whose members are promoted. Data Embedding
engine The runtime that executes a program's compiled module; which engines exist is implementation-defined. cli.engine.define
entry module The module that a program starts from: a module that the toolchain selects in a package, or the file of a single-file program. module.init.entry-module.selected
entry point A public top-level function named main or main! with no parameters. module.entry.definition
enum A nominal sum type. data.kind.enum
error derivation Implementing Display, Error, and From for an error type from its @error lines. Error Derivation
error type An enum with a bare @error line, or a struct with an @error("...") or @error(transparent) line. annot.error.type
escaping A closure that is passed as an argument, returned, stored, or captured by an escaping closure. ref.elem.escaping
executable A program a package ships, declared by an [[executable]] table of hd.toml, or src/main.hd when the manifest declares none. See cli.exe.table and cli.exe.default-main. cli.exe.table
exhausted An iterator whose next has returned .None. flow.for.iterator-exhausted
exhausted iterator An iterator whose next has returned .None. What a later next returns is unspecified. flow.for.iterator-exhausted

#F

Term Definition Defined in
fact An ordinary value attached to a type, member, or variant for derivations to read. Facts
field lookup The steps that resolve x.name to one field from a module. Field Lookup
field shorthand A data_field_item that is a bare identifier is field shorthand: x means x: x, as in Point { x, y }. grammar.primary.field-shorthand (not in a hand-written glossary)
fields Its fields, including embedded fields named by their embedded type name, are found by field lookup. names.member.fields (not in a hand-written glossary)
fingerprint A test program's fingerprint changes whenever a change could change its outcome: a source file it reads, a dependency, a manifest setting, the hd version, or a test option such as --seed. cli.test.fingerprint (not in a hand-written glossary)
fixed elements The elements of a tuple type other than its rest element. types.tuple.rest.form
flag A command-line argument that std.cli reads as set or not set; it takes no value. std-cli.parser.arg
folder The directory that holds a source file, or for a file x.hd with child modules, the directory x/ that holds them; nested directories are separate folders. module.folder.holder
folder graph A package's folders, with an edge where a file in one folder uses a module in another. It must be acyclic. module.cycle.folder-edge

#G

Term Definition Defined in
generic call cycle A chain of calls that passes a type parameter on to the callee's type parameters until it reaches itself again. types.generic.call-cycle

#H

Term Definition Defined in
handle A compiler-generated constant naming one member (Field[S, F]) or variant (Variant[S]) of a derivation's target. Handles
heap The heap is an array of bytes in one program instance, at the usize addresses from 0. module.rt.memory.heap (not in a hand-written glossary)
hidden item An item in a package interface that only the code of an instantiated template may name. module.interface.hidden-item
hides A member hides every member with the same name at a greater depth, in the same namespace. names.hide.depth
holds A type holds a local reference when it is a local reference type, or a tuple type or type alias whose type holds one. ref.local.holds
host handle A value that a default profile provider opens and keeps in the host, such as a Net socket; hd run closes the ones a program leaves open, and hd test reports them. cli.host.handles.exit
host operations A host operation is a bang method call that the host completes, such as send! on the host's Http provider. Host Operations (not in a hand-written glossary)

#I

Term Definition Defined in
infinite loop A while loop whose condition is the literal true. It completes normally only through a break that targets it. flow.while.infinite
inherent associated function A member of an inherent implementation without a self parameter, called through the type, as in User::guest(). Inherent Members
inherent method A member of an inherent implementation whose first parameter is a receiver, called with dot syntax. Inherent Members
inspectable types The types for which the compiler supplies Inspectable: primitives, module-level declarations, collections and tuples of inspectable types, and matching dynamic values. Inspectable Types
integration test module A module under the package's test root, which sees the package as a dependent does. module.test.integration
integration test program A file directly under the test root, compiled as its own program. module.test.integration.program
intrinsic method An implementation method written after @intrinsic, with no body, whose body the compiler supplies. Only the standard library declares one, for a primitive operation such as integer addition. Intrinsic Methods
irrefutable A pattern that alone covers its initializer's type, so a let with it needs no else. Any other pattern is refutable. flow.let.irrefutable
iterable A value whose type implements Iterable[T], such as a List, a Map, or a range a..b. An Iterator is not iterable, though for takes an iterator value or mutable reference directly. flow.for.accepts-owned-cursor
iterator A value implementing the prelude Iterator[T] trait, whose next method advances its stored traversal state. A mutable reference or borrowed cursor shares that state. flow.for.iterator.value-state
iterator adapters Methods of the prelude Iterator[T] that wrap an iterator in a new one, or drain it. Iterator Adapters

#K

Term Definition Defined in
known facts A member's decorator values and the elements of the list literals its member lines write, whose types the checker knows before the program runs. annot.impl-fact.skips.known
known implementation An implementation in the program's dependency graph whose target matches a type; a local one counts only where its methods are available. names.member.known-impl

#L

Term Definition Defined in
let-else A let statement with a refutable pattern and an else block, which runs when the pattern does not match and must diverge. Let-Else Statements
lexical provider A provider a closure fixes where it is written, by capturing the value of $.use. Lexical And Dynamic Providers
literal class Unsuffixed literals with no expected type that meet one another; they take one width. types.literal.local.class
literal function A function marked @num_suffix or @str_prefix, which a suffixed literal or prefixed string calls. Literal Suffixes
literal suffix A name written directly after a numeric literal's digits, which names a suffix function. Literal Suffixes
local reference A reference of type &T or &mut T, lent to a call and never stored, returned, captured, or used as a type argument. Local References
local type names The name category of structs, enums, traits, aliases, and newtypes declared inside an executable suite. names.category.local-type

#M

Term Definition Defined in
manifest hash The tree hash of a tree that holds only a dependency version's hd.toml. cli.sum.manifest-hash
manifest line An hd.sum line that records the manifest hash of a version that selection reads. cli.sum.manifest-line
member line A line of a derivation block that edits one member's facts or omits it, or a line of a derivation block with no trait that edits its metadata. Member Lines
member metadata The ordered list of values attached to a struct field, an enum variant, or a parameter. Terminology
member names The name category of struct fields, embedded fields, methods, enum variants, and tuple fields, within the namespace of their owning type. names.category.member
method lookup The steps that resolve x.name(args) to an own inherent method or a candidate. Method Lookup
method reference A method or associated function named as a function value, written Owner::name or value::name without arguments. Method References
methods Its methods are found by method lookup. names.member.methods (not in a hand-written glossary)
minimal version selection Choosing, for each host path and compatibility line, the largest minimum that any reached manifest states. Version Selection
module cycle A strongly connected component of the use graph: modules that use each other, or one module alone as a trivial cycle, initialized together. module.init.cycle
module names The name category of top-level types, traits, functions, and names introduced by use declarations. names.category.module
mutable requirement trait A trait that declares or inherits a mut self or &mut self method; its providers always have mutable access. req.mut.trait-changing

#N

Term Definition Defined in
named only in bounds A type parameter of a call is named only in bounds when no parameter type names it but a bound of another type parameter does. types.generic.infer.bound (not in a hand-written glossary)
non-reassignable A binding whose name cannot be rebound. types.view.non-reassignable

#O

Term Definition Defined in
operator trait A std.ops trait, such as Add[Rhs = Self], whose implementation gives a type one operator. Operator Traits
option A command-line argument that std.cli reads with one value. std-cli.parser.arg

#P

Term Definition Defined in
package mode How a command works when the nearest hd.toml at or above its start directory declares a package. cli.mode.package.nearest
pad bits The low bits of the last base64 symbol that encode no byte; they are zero. std-encoding.base64.encode.pad-bits
padding The one or two = characters that end a base64 text. std-encoding.base64.decode.padding
part A part of S is a value reached from S through one or more embedded fields. names.part.definition (not in a hand-written glossary)
partially denied A trait whose grant is a list of scope entries; a call outside them returns a NotGranted error. Partial Deny
path requirement A manifest value { path = "DIR" } through which a package depends on the local package in DIR. module.path-dep.form
pattern That type argument is the fact type's pattern, a type over the fact type's own type parameters, such as T, List[T], or fn(T) -> R. annot.typed-fact.pattern (not in a hand-written glossary)
pin What an access holds on its collection while it lasts: while the collection is pinned, a change of its length panics. ref.elem.access.pin
pipe expression value |> step, which passes a value to a step. Pipe Expressions
pipeline A pipeline is the way an implementation generates code for a build. Pipelines (not in a hand-written glossary)
place expression An expression that identifies a storage location, which may be read or, when it is writable, assigned. expr.category.place
positional A command-line argument that is not a flag or an option; std.cli reads it by position. std-cli.parser.arg
positional spread An argument x... that passes the value x in place of separate arguments: a tuple fills the callee's remaining inputs, and a vararg takes a value of its own type. Positional Spreads
prefix function A literal function marked @str_prefix, which a prefixed string calls. expr.literal-fn.marker
prefixed string An identifier followed directly by " or """, as in sql"...". lex.prefix.form
prelude The implicit scope of public standard-library names that every module has. Prelude
primitive types bool, the integer types i8 to i64 and u8 to u64, f32, f64, char, and string. Primitive Types
program instance One instantiated Wasm module graph with its module storage, provider bindings, and execution state. module.init.program-instance
promoted candidate Among the promoted inherent methods that lookup considers, the one with the called name at the smallest depth. names.method-lookup.promoted-candidate
promoted member A pub field or pub inherent method of an embedded field's type, or an embedded field of that type, reached from the outer struct through its embedded fields. names.promote.member
property test A test case whose body runs on inputs drawn from a Choices source. Property Tests
pseudo-version A version that names one untagged commit by a base version, its time, and its hash. module.version.pseudo

#R

Term Definition Defined in
range pattern A range pattern takes one of five forms: a..=b, a..b, a.., ..=b, or ..b. grammar.pattern.range (not in a hand-written glossary)
receiver A method's first parameter: self, mut self, &self, or &mut self. fn.method.receiver-forms
reference expressions A reference expression is a prefix operator and its operand. Reference Expressions (not in a hand-written glossary)
reference type A type written *T, *mut T, &T, or &mut T, whose values refer to a T that lives elsewhere. Reference Types
refutable A pattern that may fail to match its initializer, such as .Some(v); a let with one needs an else block. flow.let.irrefutable
requirement row The normalized unordered set of requirement keys on a callable signature. req.row.definition
requirement-free A default expression that uses no provider and does not suspend. fn.default.requirement-free
rest element A last tuple element List[T]..., which stands for any number of trailing T values. Rest Elements
rest member The one List[T] member that a rest tuple's Structure has for its rest element. annot.tuple.rest
root file src/lib.hd, src/main.hd, or an integration test program, whose relative lookup starts at its root and which has no super. module.relative.root-file
row alias A transparent alias that names a set of requirement keys. Row Aliases
row parameter A generic parameter whose values are requirement rows. req.row.parameter
row slot A place in a type that takes a requirement row, written after $: $.Context[...], the row argument of Fn, and a type argument for a row parameter. req.row.slot
rule ID A stable dotted name for one normative rule. Rule IDs
runtime identity Two types share it when they are the same declaration applied to type arguments with the same runtime identity. trait.identity.definition
runtime modules The runtime modules hold the standard library's own runtime: the code that reports an entry's result, and the memory intrinsics that a linear-memory runtime is written over. Runtime Modules (not in a hand-written glossary)
runtime profile A named compile-time set of host capability traits, their boundary adapters, and runtime choices such as panic exit statuses. module.profile.definition

#S

Term Definition Defined in
safe A fix-it is safe when applying it adds no syntax error and no new diagnostic. cli.fix.safe (not in a hand-written glossary)
scalar boundary A byte offset of a string, from 0 to its length, that does not fall inside a scalar value's encoding. types.string.boundary
script An entry module with no main, whose top-level executable statements are the entry behavior. module.init.script
sealed trait A standard trait whose implementations only the compiler and the standard library supply. Sealed Traits
self reference A member's or variant's self_ref: whether its type needs the type being derived (.Required), only refers to it (.Optional), or neither (.Absent), computed from its type alone. Self References
serialization opt-in A type's implementation of std.serde.Serialize or std.serde.Deserialize, one permission for every format to write or build its values, private members included. Serialization
shape In generic code, the machine representation a value occupies. Shapes and Generic Code
shared task module A module in a subdirectory of tasks, such as tasks/shared/zip.hd, is a shared task module. cli.task.shared (not in a hand-written glossary)
shared test module A module in a subdirectory of the test root, which every integration test program may use. module.test.integration.shared
signed literal An integer literal written directly after unary - or +, as in -1 or +5. types.literal.local.signed
single-file program One source file compiled with no package, which may use only std. Single-File Programs
spread pattern A last tuple-pattern element, a name or _ followed by ..., that matches a rest element's list, as in let (a, xs...) = t. Spread Patterns
struct A nominal product type with value semantics, declared with struct. data.kind.struct
substitution step A pipe step that contains _. expr.pipe.step-kinds
suffix function A literal function marked @num_suffix, which a suffixed literal calls. expr.literal-fn.marker
suffixed literal A numeric literal with a literal suffix, such as 250ms, which calls the suffix function, as ms(250). Literal Suffixes
summary An item's summary is the first sentence of its documentation, or empty when it has none. cli.doc.summary (not in a hand-written glossary)

#T

Term Definition Defined in
target parameter That parameter is the fact type's target parameter, and it is inferred as the target's whole type. annot.typed-fact.pattern.trivial (not in a hand-written glossary)
task A development program of a package, a file tasks/NAME.hd that hd run NAME runs and the package never ships. Tasks
template A trait's one derived implementation, written impl[T] Trait for T by Structure: in the trait's module. Templates
test case One test, registered by a call of the prelude function it in test position, by one row of an it_each call, or by an it_prop or it_prop_with call. Test Cases
test code A package's tests: blocks, test modules, integration test modules, and doc tests, compiled only by a test build. module.test.code
test grant The capability grant of an integration test case or a doc test, built from [capabilities] plus [dev-capabilities], the flags of hd test, and fixed file system entries. cli.test.env.grant.combined
test module A module whose file name ends in _test.hd. Test Modules
test position The top level of a tests: block, a test module, or an integration test module, where test-case calls go. module.testing.test-position
test program A test program is a program that hd test builds to run test cases: one per module with unit tests or doc tests, and one per integration test module. cli.test.program (not in a hand-written glossary)
test registration call A direct call of it, it_each, it_prop, or it_prop_with; only such a call may stand in test position. module.testing.position-statements
the same compiled program Two builds whose compiler outputs are byte-identical. req.determinism.same-program
totally denied A trait whose grant is false; a module that imports it never starts. Total Deny
trait candidates The trait methods of the receiver's type with the called name whose trait is available at the call. names.method-lookup.trait-candidates
trait methods The methods of every trait that a known implementation implements for a type. names.member.trait-methods
trait value reference A trait value that is a reference, written &dyn Tr or &mut dyn Tr, or counted, *dyn Tr or *mut dyn Tr. Trait Value References
tree hash The h1: hash of a dependency version's files, which hd.sum records. cli.sum.hash
tree line An hd.sum line that records the tree hash of a selected version. cli.sum.line
trivial pattern A pattern that is one of those parameters alone, as T in @annotate::[T](lang/.Field), is a trivial pattern. annot.typed-fact.pattern.trivial (not in a hand-written glossary)
tuple template A trait's derivation for every tuple type, written impl[T < Tuple] Trait for T by Structure: in the trait's module. Tuple Templates
type forms The kinds of type that hd-lang has, such as primitive types, tuples, optional types, and function types. Type Forms
type-argument default A type written with = after a generic parameter's bound, used when a use site leaves the parameter unsolved or a written type omits it. Type-Argument Defaults
type-argument marker The :: before an explicit type-argument list in an expression, as in first::[string](names). grammar.expr.type-arguments.marker
typed derivation Implementing a trait for a struct or enum from its members through the trait's template. Typed Derivation
typed fact type A fact type whose @annotate decorator writes a type argument, a pattern such as T in @annotate::[T](.Field) or fn(T) -> R. The pattern's parameters are inferred from a target's type as a call's are, and a value on that target checks against the fact type at them. annot.typed-fact.declare

#U

Term Definition Defined in
unaliased A collection that is a local binding or a value parameter, or a field or element of one, that no escaping closure captures. ref.elem.unaliased
unbound method reference Owner::name without an argument clause, where Owner names a type, a trait, or a type parameter. fn.ref.unbound
unit pattern () is the unit pattern. grammar.pattern.unit (not in a hand-written glossary)
unit test A test case in a tests: block or a test module, wherever its file lies, whose body gets TestRunner alone from the runner. module.testing.unit-row.anywhere
untyped fact type A fact type whose annotate type argument is the default *dyn Any, as in @annotate(.Field), so its values stay unchecked. annot.typed-fact.untyped.reference-values

#V

Term Definition Defined in
value expression An expression that produces a value. expr.category.value
value names The name category of top-level executable bindings, parameters, local bindings, local named functions, loop bindings, pattern bindings, and captured values. names.category.value
value type A type whose values have no identity: binding a value copies it, and nothing shares it. Structs, lists and maps are value types. See Value Types and Collection Values. Value Types
vararg A final parameter written name...: T, which collects the call's remaining positional arguments into T. fn.vararg.form
visible A field or inherent method is visible from a module that declares it, and from every module when it is pub. names.visible.field-method

#W

Term Definition Defined in
wire name A member's wire name is its name in a document format. Member Names (not in a hand-written glossary)
workspace A set of packages that one committed workspace manifest lists, selected as one graph. Workspaces
workspace mode How a command works at a workspace root, where the nearest hd.toml lists members and declares no package. Workspace Mode
writable A place that a struct field write or a &mut may change: a let mut binding, a mut parameter or mut self, a value reached through a &mut reference, a struct field of a writable place, or an element of a list or a value of a map in a writable place. See types.value.writable-places and ref.place.writable. types.value.writable-places
written-out size The written-out size of a pattern is given by the table below, where s is the size of the repeated item. std-regex.time.size (not in a hand-written glossary)