Raven language reference
This reference is both Raven's developer documentation and its working language specification. It explains the most commonly used syntax, behavior, and rules by feature, with examples intended to help developers write and understand Raven code.
It is not an exhaustive formal specification of every compiler behavior or edge case. Individual pages become more precise where a distinction affects normal programs, interoperability, or diagnostics.
Implementation details describing how Raven projects map to .NET are documented in dotnet-implementation.md.
An overview of available types, literal semantics, and conversions can be found in the type system.
Attached macro syntax and expansion rules are documented in macros.md.
Recommended source layout and spacing conventions are documented in the style guide.
Related reference documents
Use this page for shared conventions and the topic index below. The following specialized documents complement the feature pages:
- Type system
- Classes, structs, and interfaces
- Control flow
- Error handling
- Macros
- .NET implementation notes
- Grammar (non-normative EBNF)
Document conventions
- Requirements use key words such as “must”, “may”, and “should” when a rule needs to be stated precisely. The reference does not attempt to enumerate every valid or invalid program.
- Notes and tips highlight rationale, examples, or implementation remarks. They are informative rather than normative.
- Code snippets use the
.ravfile extension and omit surrounding boilerplate unless it is essential to the rule being described. - When behaviour is intentionally unspecified or still under design, this specification calls it out explicitly.
- Callout boxes use a small, consistent emoji set:
ℹ️Info for factual clarification and context.⚠️Warning for pitfalls or behavior likely to surprise.❗Important for distinctions that affect correctness or interpretation.🧭Disambiguation for parser/binder interpretation rules.❓Open Question for unresolved design choices that need follow-up.
Code samples
Representative sample programs live in the repository's sample
directory alongside runnable CLI demos.
Each sample intentionally exercises language features such as pattern matching, pipe operators, tuple flow, and .NET interop so
changes to the language can be validated with real code, not just unit tests. The top-level samples/README.md explains how to
run them with the Raven CLI.
Language topics
The pages are organized by feature and developer task so the relevant syntax and common rules are easy to find.
Language fundamentals
- Lexical structure
- Values and statements
- Namespaces, imports, and aliases
- Top-level code and entry points
- Grammar (non-normative EBNF)
Types
Expressions
- Expressions and type inference
- Fundamental expressions
- Collection expressions
- Tuple expressions
- Calls
- Pipe expressions
- Object creation
- Object initialization and copying
- Index, range, and bitwise operators
- Operator precedence and expression disambiguation
Declarations and members
- Local declarations
- Functions
- Async functions
- Classes, structs, and interfaces
- Type declarations and initialization
- Properties and events
- Inheritance and partial types
- Parameters, overloading, and operators
- Interfaces
- Extension members
Systems programming and .NET interoperability
These specialized topics are kept separate from the main language path:
- Systems programming and memory efficiency
- Spans and stack allocation
- Ref structs and ref safety
- Unsafe code and interoperability
Metaprogramming
Pattern matching
- Pattern matching overview
- Dictionary patterns and exhaustiveness
- Match forms
- Pattern forms and contexts
- Fundamental patterns
- Sequence and property patterns
- Deconstruction, member, and union patterns
Control flow
- Control flow overview
- Control-flow expressions and statements
- Lock statements
- Assignment and expression statements
- Match statements
- Return and yield
- Jumps and labels