Language Specification

The BWSL source repository now includes a canonical specification draft in docs/spec/, including a syntax-oriented BNF grammar at docs/spec/bwsl.bnf.

The public docs site explains stable authoring workflows. The source-tree spec is the place to look when you need exact syntax, parser coverage, or conformance guidance for compiler work, editor tooling, or third-party integrations.

Source-Tree Spec

The specification draft is kept next to the compiler implementation and regression suite so language behavior can be reviewed with the code that implements it.

Document map in the BWSL repo:

File	Scope
`docs/spec/00-status.md`	Draft status and provisional areas.
`docs/spec/01-lexical-structure.md`	Tokens, comments, literals, and lexical rules.
`docs/spec/02-program-structure.md`	File items, modules, pipelines, imports, and using declarations.
`docs/spec/03-types-and-declarations.md`	Types, resources, structs, aliases, and declarations.
`docs/spec/04-expressions.md`	Expressions, calls, operators, member access, and qualification.
`docs/spec/05-statements-and-control-flow.md`	Blocks, loops, branches, returns, discard, and switch.
`docs/spec/06-functions-modules-and-generics.md`	Functions, modules, constraints, and generic dispatch.
`docs/spec/07-enums-and-pattern-matching.md`	Enums, payload enums, methods, and pattern arms.
`docs/spec/08-pipelines-passes-and-shader-io.md`	Passes, stages, attributes, resources, varyings, and built-ins.
`docs/spec/09-intrinsics-and-builtins.md`	Intrinsics and built-in namespaces.
`docs/spec/10-conformance.md`	Conformance expectations and test coverage.
`docs/spec/bwsl.bnf`	Backus-Naur Form grammar for source syntax.

Normative Priority

Until BWSL has versioned language releases, use this priority order:

The docs/spec/ draft in the BWSL source repo.
The compiler implementation when the spec is incomplete.
Regression and error tests in tests/.

The public docs are still the right starting point for writing shaders, but they may simplify grammar details or omit edge cases that matter to parser and tooling authors.

BNF Grammar

The BNF file describes source syntax accepted by the current lexer and parser. It does not encode semantic checks such as duplicate block validation, overload resolution, stage availability, eval execution, resource validation, or backend lowering rules.

Use the BNF when you need to:

implement editor syntax support
inspect parser-level source forms
compare a proposed language change against existing grammar
debug whether a construct is syntactically accepted before semantic analysis

Editing Rule

When a language behavior changes in the compiler, update the matching spec section and regression tests with the implementation change. If the behavior is provisional or the spec is incomplete, call that out in docs/spec/00-status.md.