hd-lang

Reference

#hd-lang Specification

This directory contains the normative language specification.

The numbered chapters describe one evolving language specification. Features are either specified, explicitly unsupported, or listed in the open-issues umbrella; hd-lang does not divide the language into versioned subsets.

#Contents

Chapter Scope
Lexical Structure source text, tokens, indentation, literals
Grammar consolidated EBNF
Names and Scopes declarations, bindings, use declarations, member lookup
Type System types, coercions, mut, value types and collection values, generics, variance
Expressions evaluation, operators, calls, literals, comprehensions
Control Flow blocks, conditionals, loops, matching, return
Functions parameters, receivers, closures, captures, trailing blocks
Data Types and Enums aggregate declaration, construction, embedding
Traits conformance, methods, static and dynamic dispatch
Modules packages, use declarations, visibility, entry points, Wasm boundary
Requirements and Suspension requirement rows, providers, fn!, Suspend[T]
Variadic Generics none: hd has no packs; where arity-generic code lives instead
Values And References counted reference types *T and *mut T, local reference types &T and &mut T, trait value references &dyn Tr, &e, &mut e, *e, places, writes through a reference, read-only references, identity (is) of references, element references and pins
Annotations decorators, function facts, member metadata, typed derivation, error derivation

These chapters are the language tier. The stdlib tier, std APIs that ordinary hd can implement, is specified in the Standard Library chapters. The CLI tier, how the hd command finds and runs a package or a single file, is specified in Command Line.

Deferred language design and the runtime, library, ABI, product, and tooling backlog are tracked in the open-issues umbrella.

Runtime and standard-library behavior that is not language semantics is sketched in the archived RUNTIME_AND_LIBRARY.md. The language tour remains the readable introduction; this directory is the formalization target.

Chapters are written to the Specification Style guide.

Parser and type-checker cases live in Conformance Fixtures. Run the repository-local specification checks with:

spec/check.sh

#Conformance Language

The key words must, must not, should, should not, and may are normative. Text marked as a note or example is explanatory unless it explicitly states otherwise.

#Normative Vocabulary

Chapters written in the specification style use these words and phrases with these meanings:

Word or phrase Meaning
must, must not An absolute requirement on a program or an implementation.
should, should not A recommendation. There may be valid reasons to depart from it, and doing so does not by itself make a program invalid.
may A permission: the program or implementation is allowed, but not required, to do it.
is an error, is a code error, "Error: code." The implementation diagnoses the program, as Diagnostics defines. When a code is named, the diagnostic carries that code.
is invalid, is rejected The implementation diagnoses the program. The rule names no specific code.
Why, Note A callout that explains the rules around it. It adds no requirement.

A rule may carry a stable rule ID, written r[data.field.unique] before the rule. A link cites it by the anchor r- followed by the ID, as Rule IDs describes.

#Diagnostics

Unless a rule explicitly calls for a lint finding, diagnose means reject the program with an error. A rule marked Warning: names optional advice reported by hd lint, not by ordinary checking, building, testing, REPL evaluation, or the playground. Diagnostic prose and source spans may improve, but the machine-readable code is stable. The table below is normative; cases.tsv maps each exercised code to its fixture.

Severity Stable diagnostic codes
Error alias-cycle, ambiguous-associated-type, ambiguous-import, ambiguous-method, ambiguous-promoted-member, ambiguous-row-pattern, ambiguous-type, argument-order, bang-call-outside-suspension, bare-parameter-impl-target, bare-variant-pattern, binding-not-yet-visible, boundary-private-field, break-value-context, cannot-infer-type, closure-parameter-needs-annotation, comparison-chaining, conflicting-access, cyclic-test-dependency, dbg-in-release, decorator-not-annotator, decorator-not-top-level, decorator-target-kind, default-order, denied-capability, derive-field-missing-trait, direct-variant-use, discarded-must-use-value, doc-comment-without-target, duplicate-argument, duplicate-associated-binding, duplicate-data-pattern-field, duplicate-embedded-field, duplicate-executable-name, duplicate-fact, duplicate-field, duplicate-inherent-member, duplicate-module-name, duplicate-pipe-placeholder, duplicate-supertrait, duplicate-test-name, duplicate-tests-block, duplicate-trait-member, dyn-member-unavailable, element-reference-outlives-call, embedded-non-data, embedding-cycle, embedding-too-deep, entry-point-parameters, extra-trait-member, fetch-failed, file-too-large, float-literal-range, folder-cycle, generic-kind-mismatch, generic-member-call, generic-requirement-key-collision, identity-requires-references, implicit-narrowing, incompatible-identity-operands, inspectable-requirement, instantiation-too-deep, integer-literal-range, invalid-assignment-target, invalid-default-variant, invalid-delegation, invalid-error-marker, invalid-escape, invalid-facts-of-target, invalid-impl-target, invalid-inline-decorator, invalid-literal-suffix, invalid-manifest, invalid-member-line, invalid-module-path, invalid-requirement, invalid-result-propagation, invalid-string-prefix, invalid-test-statement, invalid-variance, item-too-complex, let-else-falls-through, local-impl-nonlocal-pair, local-reference-escapes, map-value-not-addressable, marker-template, match-too-complex, member-not-derivable, misplaced-derivation, misplaced-test-case, misplaced-tests-block, missing-capability, missing-contextual-enum-type, missing-derived-bound, missing-entry-point, missing-let, missing-required-field, missing-requirement, missing-result-type, missing-return-value, missing-sum-entry, missing-supertrait-implementation, missing-trait-method, mixed-derived-law, mixed-signedness, multi-line-pipe-step, mut-on-primitive, mut-on-struct, mutable-field-modifier, mutable-impl-target, mutable-upgrade, nesting-too-deep, newtype-derivation-self, no-common-type, no-least-common-type, non-literal-test-argument, non-reassignable-binding, non-reassignable-parameter-binding, nonexhaustive-match, nonfinal-positional-spread, nonfinal-vararg, nonhost-entry-requirement, nonlocal-impl, not-suspending, not-writable, omitted-member-without-default, orphan-impl, overlapping-impl, package-cycle, partial-generic-arguments, pattern-arity, pattern-order, pipe-placeholder-in-closure, pipe-step-needs-placeholder, placeholder-outside-pipe, positional-spread-needs-vararg, possibly-uninitialized-binding, prelude-name-shadow, private-import, private-member, private-type-leak, public-test-item, qualified-string-prefix, re-export-loop, readonly-argument-to-mutable-parameter, recursive-function-needs-result-type, recursive-value-type, reference-equality, references-not-yet-checked, refutable-let-pattern, requirement-in-default, reserved-module-name, reserved-semicolon, return-outside-function, row-parameter-in-context, sealed-trait-implementation, shared-data-type-parameter, std-only-use, structure-outside-template, sum-mismatch, supertrait-cycle, suspending-pipe-step, suspension-forbidden-context, tab-whitespace, template-names-binding, test-only-use, too-many-embedded-fields, toolchain-too-old, top-level-read-before-initialization, trailing-block-ineligible, trailing-block-position, trait-method-signature, trait-method-visibility, trait-not-dynamically-safe, trait-resolution-depth, trait-used-as-type, trait-value-impl-target, type-too-large, type-used-as-value, unconstrained-impl-parameter, underivable-trait, unexpected-bom, uninhabited-binding, unknown-annotation-member, unknown-associated-type, unknown-import, unknown-manifest-key, unknown-module, unknown-named-argument, unknown-panic-category, unknown-version, unlisted-entry, unreachable-match-arm, unsatisfied-trait-bound, unsaturated-enum-constructor, variance-representation-change, variant-result-owner, variant-result-type-removed
Error defer-control-flow, defer-outside-cleanup-scope
Error (general) argument-count, break-outside-loop, duplicate-binding, duplicate-type, duplicate-variant, invalid-dedent, invalid-token, not-callable, syntax-error, type-mismatch, unclosed-delimiter, unexpected-indentation, unknown-field, unknown-method, unknown-name, unknown-trait, unknown-type, unknown-variant, unmatched-delimiter, unterminated-string
Lint finding (default warning) broken-doc-link, dbg-in-dependency, derivation-line-drift, mixed-script-identifier, private-main, redundant-let-mut, unreachable-code, unselected-main, unsigned-comparison-always, unused-debug-text, unused-derivation-fact, unused-local-binding, variant-binding-name-mismatch
Runtime panic The complete closed category list is defined in Control Flow.
Boundary failure boundary-cycle, boundary-decoder-panic

The general error codes cover failures that every front end detects but that no single chapter owns. Each applies only when no more specific code in the table describes the failure:

Code Meaning
syntax-error Source does not match the grammar, and no more specific lexical or layout code applies.
invalid-token A character sequence forms no token.
unterminated-string A string or character literal reaches the end of its line or file without closing.
unclosed-delimiter An opening (, [, or { has no matching close.
unmatched-delimiter A closing ), ], or } has no matching open, or closes a different kind.
unexpected-indentation A line is indented where layout does not open a suite, or the first body line of a nested suite inside brackets is not deeper than its header's line and the logical line containing the header.
invalid-dedent A dedent returns to a column that no enclosing suite uses.
unknown-name A value name, or an absolute path outside a use, resolves to no binding in scope.
unknown-type A type name resolves to no type in scope.
unknown-trait A trait name resolves to no trait in scope.
unknown-method Member lookup finds no method or field with that name.
unknown-field A data literal, pattern, or field access (including a tuple selection past the last element) names a field the type does not declare, or a variant construction or pattern names a payload field the enum variant does not declare.
unknown-variant An enum variant name resolves to no variant of the expected enum.
duplicate-binding One scope declares the same binding name twice where the language forbids it.
duplicate-type One module, or one generic parameter list, declares the same type name twice.
duplicate-variant One enum declares the same variant name twice.
type-mismatch A value's type is not assignable to the type its context requires.
argument-count A call supplies more or fewer arguments than the callee accepts, a race! call supplies no task, or a type-argument list has more positional arguments than its declaration has generic parameters.
not-callable A call's callee is not a function, closure, constructor, or callable value.
break-outside-loop break or continue appears outside a loop body.

A diagnostic is reported on the line where the smallest construct that breaks the rule begins. When a rule concerns one token of a larger construct, such as a duplicate field name, the smallest construct is that token's own element. Conformance fixtures place their marker on that line.

Note (normative): unsatisfied-trait-bound covers several trait requirements: a generic bound (including T < AnyVal, T < AnyRef, and T < mut Trait given readonly access), Display for string interpolation, Iterable for a for loop, and std.process.Termination for an entry point's or a test body's result. Because one code covers these origins, its message must name the type, the missing trait, and where the requirement comes from (the bound, the interpolation, the loop, the entry point, or the test).

Note (normative): the message of local-reference-escapes must name the position the local reference escapes to: a field, a collection element, a top-level binding, a result, a closure capture, a type argument, or a counted reference. It must also say that writing * for & makes the reference counted, as ref.local.escape.message states.

The identifier-security lint uses a moderately-restrictive mixed-script profile. It does not change identifier identity or program validity; deny changes the lint command’s status, as Linting specifies.

#Grammar Notation

The specification uses EBNF for lexical and syntactic grammar. In grammar productions:

  • name = expression ; defines a production.
  • Quoted text denotes a literal token.
  • A, B denotes concatenation.
  • A | B denotes alternatives.
  • [A] denotes an optional expression.
  • {A} denotes zero or more repetitions.
  • (A) groups expressions.
  • "a" ... "z" denotes an inclusive character range.
  • Uppercase names such as NEWLINE, INDENT, DEDENT, and SUITE_END denote tokens produced by lexical or layout processing.

The chapter Grammar contains the consolidated grammar. Other chapters repeat the productions relevant to the feature they specify. If a repeated production conflicts with the consolidated grammar, the conflict is a specification defect rather than an intentional precedence rule.

#Specification Status

The files currently form a draft. A rule is normative only when its chapter states it as a requirement. Explicitly open issues are not implementation freedom to guess silently: an implementation must diagnose unsupported syntax until the issue is resolved by a later specification revision.

Unresolved decisions are recorded in the open-issues umbrella. The draft is not complete until every issue required for parsing, type checking, or execution has either been specified or explicitly classified as unsupported or runtime and library work.

#Glossary

This glossary lists the terms that the numbered chapters and Command Line define in bold. Each entry links to the rule, or the section, that defines the term. The stdlib chapters' terms are in the Standard Library glossary.

Term Definition
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. See ref.elem.access.
active A driver context while its executor is evaluating or polling it on the current program-instance call stack. See req.bang.active.
available A trait method is available in a module when its trait is available to dot-call lookup there. See names.visible.trait.
bare step A pipe step that is a name or path without _. See expr.pipe.step-kinds.
bound method reference value::name, where value names a value, as a function value. See 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]. See 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. See cli.build.directory.
cache directory The one directory per user where hd keeps every fetched dependency version, read-only. See Cache.
call place A call v() whose callee's type implements Update, so v() = x and v() op= x store through it. See Callable Values.
callable value A value whose type implements Apply, read by calling it with no arguments, as in count(). See 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. See Capability Grants.
cell The storage that a closure and its scope share for a captured variable. See fn.capture.cell.
compatibility line The versions of a package that must stay compatible: one major number, or 0.MINOR below 1.0. See module.version.line.
compound assignment A statement place op= value, such as total += x, that combines an operator with a store. See 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. See names.conflict.definition.
copy-update literal A struct literal with one leading spread, which builds a new value from an existing one. See 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. See ref.type.counted-forms.
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. See types.literal.local.default.
dependency requirement A manifest entry PATH@VERSION that maps a dependency key to a host path and a minimum version. See Dependency Requirements.
depth The number of embedded fields on the path from a struct to one of its members. See 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. See Derivation Blocks.
derived variance The variance an inherent impl parameter has in the implementation's target type, by which its methods are checked. See 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. See 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. See module.test.doc.block.
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. See req.bang.driver-forms.
dynamic provider A provider a closure gets at each call, because its row keeps the key. See Lexical And Dynamic Providers.
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.
embedded field A bare type-name member of a struct declaration, which embeds another struct as an inline field whose members are promoted. See Data Embedding.
engine The runtime that executes a program's compiled module; which engines exist is implementation-defined. See 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. See module.init.entry-module.selected.
entry point A public top-level function named main or main! with no parameters. See module.entry.definition.
enum A nominal sum type. See data.kind.enum.
error derivation Implementing Display, Error, and From for an error type from its @error lines. See Error Derivation.
error type An enum with a bare @error line, or a struct with an @error("...") or @error(transparent) line. See annot.error.type.
escaping A closure that is passed as an argument, returned, stored, or captured by an escaping closure. See 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.
exhausted An iterator whose next has returned .None. See flow.for.iterator-exhausted.
exhausted iterator An iterator whose next has returned .None. What a later next returns is unspecified. See flow.for.iterator-exhausted.
fact An ordinary value attached to a type, member, or variant for derivations to read. See Facts.
field lookup The steps that resolve x.name to one field from a module. See Field Lookup.
fixed elements The elements of a tuple type other than its rest element. See types.tuple.rest.form.
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. See 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. See module.cycle.folder-edge.
generic call cycle A chain of calls that passes a type parameter on to the callee's type parameters until it reaches itself again. See types.generic.call-cycle.
handle A compiler-generated constant naming one member (Field[S, F]) or variant (Variant[S]) of a derivation's target. See Handles.
hidden item An item in a package interface that only the code of an instantiated template may name. See module.interface.hidden-item.
hides A member hides every member with the same name at a greater depth, in the same namespace. See 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. See 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. See cli.host.handles.exit.
infinite loop A while loop whose condition is the literal true. It completes normally only through a break that targets it. See flow.while.infinite.
inherent associated function A member of an inherent implementation without a self parameter, called through the type, as in User::guest(). See Inherent Members.
inherent method A member of an inherent implementation whose first parameter is a receiver, called with dot syntax. See 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. See Inspectable Types.
integration test module A module under the package's test root, which sees the package as a dependent does. See module.test.integration.
integration test program A file directly under the test root, compiled as its own program. See 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. See 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. See 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. See 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. See flow.for.iterator.value-state.
iterator adapters A stdlib term, in the Standard Library glossary.
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. See 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. See names.member.known-impl.
let-else A let statement with a refutable pattern and an else block, which runs when the pattern does not match and must diverge. See Let-Else Statements.
lexical provider A provider a closure fixes where it is written, by capturing the value of $.use. See Lexical And Dynamic Providers.
literal function A function marked @num_suffix or @str_prefix, which a suffixed literal or prefixed string calls. See Literal Suffixes.
literal class Unsuffixed literals with no expected type that meet one another; they take one width. See types.literal.local.class.
literal suffix A name written directly after a numeric literal's digits, which names a suffix function. See 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. See Local References.
local type names The name category of structs, enums, traits, aliases, and newtypes declared inside an executable suite. See names.category.local-type.
manifest hash The tree hash of a tree that holds only a dependency version's hd.toml. See cli.sum.manifest-hash.
manifest line An hd.sum line that records the manifest hash of a version that selection reads. See 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. See Member Lines.
member metadata The ordered list of values attached to a struct field, an enum variant, or a parameter. See Terminology.
member names The name category of struct fields, embedded fields, methods, enum variants, and tuple fields, within the namespace of their owning type. See names.category.member.
method lookup The steps that resolve x.name(args) to an own inherent method or a candidate. See Method Lookup.
method reference A method or associated function named as a function value, written Owner::name or value::name without arguments. See Method References.
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. See module.init.cycle.
minimal version selection Choosing, for each host path and compatibility line, the largest minimum that any reached manifest states. See Version Selection.
module names The name category of top-level types, traits, functions, and names introduced by use declarations. See 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. See req.mut.trait-changing.
non-reassignable A binding whose name cannot be rebound. See types.view.non-reassignable.
operator trait A std.ops trait, such as Add[Rhs = Self], whose implementation gives a type one operator. See Operator Traits.
package mode How a command works when the nearest hd.toml at or above its start directory declares a package. See cli.mode.package.nearest.
partially denied A trait whose grant is a list of scope entries; a call outside them returns a NotGranted error. See Partial Deny.
path requirement A manifest value { path = "DIR" } through which a package depends on the local package in DIR. See module.path-dep.form.
pin What an access holds on its collection while it lasts: while the collection is pinned, a change of its length panics. See ref.elem.access.pin.
pipe expression value |> step, which passes a value to a step. See Pipe Expressions.
place expression An expression that identifies a storage location, which may be read or, when it is writable, assigned. See expr.category.place.
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. See Positional Spreads.
prefix function A literal function marked @str_prefix, which a prefixed string calls. See expr.literal-fn.marker.
prefixed string An identifier followed directly by " or """, as in sql"...". See lex.prefix.form.
prelude The implicit scope of public standard-library names that every module has. See Prelude.
primitive types bool, the integer types i8 to i64 and u8 to u64, f32, f64, char, and string. See Primitive Types.
program instance One instantiated Wasm module graph with its module storage, provider bindings, and execution state. See module.init.program-instance.
promoted candidate Among the promoted inherent methods that lookup considers, the one with the called name at the smallest depth. See 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. See names.promote.member.
pseudo-version A version that names one untagged commit by a base version, its time, and its hash. See module.version.pseudo.
reference type A type written *T, *mut T, &T, or &mut T, whose values refer to a T that lives elsewhere. See Reference Types.
receiver A method's first parameter: self, mut self, &self, or &mut self. See fn.method.receiver-forms.
refutable A pattern that may fail to match its initializer, such as .Some(v); a let with one needs an else block. See flow.let.irrefutable.
requirement row The normalized unordered set of requirement keys on a callable signature. See req.row.definition.
requirement-free A default expression that uses no provider and does not suspend. See fn.default.requirement-free.
rest element A last tuple element List[T]..., which stands for any number of trailing T values. See Rest Elements.
rest member The one List[T] member that a rest tuple's Structure has for its rest element. See 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. See module.relative.root-file.
row alias A transparent alias that names a set of requirement keys. See Row Aliases.
row parameter A generic parameter whose values are requirement rows. See 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. See req.row.slot.
rule ID A stable dotted name for one normative rule. See Rule IDs.
runtime identity Two types share it when they are the same declaration applied to type arguments with the same runtime identity. See trait.identity.definition.
runtime profile A named compile-time set of host capability traits, their boundary adapters, and runtime choices such as panic exit statuses. See module.profile.definition.
the same compiled program Two builds whose compiler outputs are byte-identical. See req.determinism.same-program.
scalar boundary A byte offset of a string, from 0 to its length, that does not fall inside a scalar value's encoding. See types.string.boundary.
script An entry module with no main, whose top-level executable statements are the entry behavior. See module.init.script.
sealed trait A standard trait whose implementations only the compiler and the standard library supply. See Sealed Traits.
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. See Serialization.
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. See Self References.
shared test module A module in a subdirectory of the test root, which every integration test program may use. See module.test.integration.shared.
shape In generic code, the machine representation a value occupies. See Shapes and Generic Code.
signed literal An integer literal written directly after unary - or +, as in -1 or +5. See types.literal.local.signed.
single-file program One source file compiled with no package, which may use only std. See 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. See Spread Patterns.
struct A nominal product type with value semantics, declared with struct. See data.kind.struct.
substitution step A pipe step that contains _. See expr.pipe.step-kinds.
suffix function A literal function marked @num_suffix, which a suffixed literal calls. See expr.literal-fn.marker.
suffixed literal A numeric literal with a literal suffix, such as 250ms, which calls the suffix function, as ms(250). See Literal Suffixes.
task A development program of a package, a file tasks/NAME.hd that hd run NAME runs and the package never ships. See Tasks.
template A trait's one derived implementation, written impl[T] Trait for T by Structure: in the trait's module. See Templates.
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. See cli.test.env.grant.combined.
totally denied A trait whose grant is false; a module that imports it never starts. See Total Deny.
tuple template A trait's derivation for every tuple type, written impl[T < Tuple] Trait for T by Structure: in the trait's module. See Tuple 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. See Test Cases.
test code A package's tests: blocks, test modules, integration test modules, and doc tests, compiled only by a test build. See module.test.code.
test module A module whose file name ends in _test.hd. See Test Modules.
test position The top level of a tests: block, a test module, or an integration test module, where test-case calls go. See module.testing.test-position.
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. See module.testing.position-statements.
trait candidates The trait methods of the receiver's type with the called name whose trait is available at the call. See names.method-lookup.trait-candidates.
trait methods The methods of every trait that a known implementation implements for a type. See 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. See Trait Value References.
tree hash The h1: hash of a dependency version's files, which hd.sum records. See cli.sum.hash.
tree line An hd.sum line that records the tree hash of a selected version. See cli.sum.line.
type forms The kinds of type that hd-lang has, such as primitive types, tuples, optional types, and function types. See 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. See Type-Argument Defaults.
type-argument marker The :: before an explicit type-argument list in an expression, as in first::[string](names). See grammar.expr.type-arguments.marker.
typed derivation Implementing a trait for a struct or enum from its members through the trait's template. See 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. See annot.typed-fact.declare.
unaliased A collection that is a local binding or a value parameter, or a field or element of one, that no escaping closure captures. See ref.elem.unaliased.
unbound method reference Owner::name without an argument clause, where Owner names a type, a trait, or a type parameter. See fn.ref.unbound.
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. See 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. See annot.typed-fact.untyped.reference-values.
using binding A binding, written using name = value, whose value's dispose! runs when its scope ends, in order with defer suites. See Using Bindings.
value expression An expression that produces a value. See expr.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 names The name category of top-level executable bindings, parameters, local bindings, local named functions, loop bindings, pattern bindings, and captured values. See names.category.value.
vararg A final parameter written name...: T, which collects the call's remaining positional arguments into T. See 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. See names.visible.field-method.
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.
workspace A set of packages that one committed workspace manifest lists, selected as one graph. See Workspaces.
workspace mode How a command works at a workspace root, where the nearest hd.toml lists members and declares no package. See Workspace Mode.

View source on GitHub