Introduction

This document is the Rue Language Specification. It defines the syntax and semantics of the Rue programming language.

Scope

This specification describes the Rue programming language as implemented by the reference compiler. It covers:

• Lexical structure (tokens, comments, whitespace)
• Types (integers, booleans, arrays, structs)
• Expressions and operators
• Statements
• Items (functions, struct definitions)
• Runtime behavior

This specification does not cover:

• The standard library (when one exists)
• Compiler implementation details
• Platform-specific behavior beyond what is explicitly documented

Conformance

A conforming implementation must implement all normative requirements of this specification.

Paragraphs marked with rule categories are normative unless explicitly marked as informative. The following categories are used:

Normative Language

This specification uses terminology from RFC 2119 to indicate requirement levels. The key words are interpreted as follows:

MUST and SHALL: An absolute requirement. A conforming implementation is required to satisfy this.

MUST NOT and SHALL NOT: An absolute prohibition. A conforming implementation is required not to do this.

SHOULD and RECOMMENDED: There may be valid reasons to ignore this requirement, but the implications must be understood.

SHOULD NOT and NOT RECOMMENDED: There may be valid reasons to accept this behavior, but the implications must be understood.

MAY and OPTIONAL: An item is truly optional. Implementations may or may not include it.

These keywords appear in bold throughout this specification to distinguish normative requirements from descriptive text.

Definitions

The following terms are used throughout this specification:

Expression: A syntactic construct that evaluates to a value.

Statement: A syntactic construct that performs an action but does not produce a value.

Item: A top-level definition in a program, such as a function or struct.

Type: A classification that determines what values an expression can produce and what operations are valid on those values.

Normative: Content that defines required behavior for conforming implementations.

Informative: Content that provides explanation or context but does not define required behavior.

Value: An instance of a type. Expressions evaluate to values.

Coercion: An implicit type conversion that occurs automatically during type checking. See section 3.4 for the complete set of coercions in Rue.

Compatible type: A type is compatible with another type if they are the same type, or if the first type can be coerced to the second type.

Panic: A runtime error condition that terminates program execution with a specific exit code. See Appendix B for the complete list of panic conditions.

Notation

Spec paragraph identifiers follow the format {chapter}.{section}:{paragraph}. For example, 3.1:5 refers to Chapter 3, Section 1, Paragraph 5.

Grammar rules use Extended Backus-Naur Form (EBNF) notation:

• = defines a production
• | separates alternatives
• { } indicates zero or more repetitions
• [ ] indicates optional elements
• " " indicates literal text
• UPPERCASE indicates terminal symbols (tokens)

if_expr = "if" expression "{" block "}" [ "else" "{" block "}" ] ;

Organization

This specification is organized as follows:

• Chapter 2: Lexical Structure - Tokens, comments, whitespace, keywords
• Chapter 3: Types - Integer types, booleans, unit, never, arrays, structs
• Chapter 4: Expressions - Operators, control flow, function calls
• Chapter 5: Statements - Variable bindings, assignment
• Chapter 6: Items - Functions, struct definitions
• Chapter 7: Arrays - Fixed-size array behavior
• Chapter 8: Runtime Behavior - Overflow, bounds checking, panics
• Appendix A: Grammar - Complete EBNF grammar
• Appendix B: Runtime Panics - Summary of panic conditions
• Appendix C: Implementation Limits - Minimum limits for conforming implementations

Version

This specification corresponds to version 0.1.0 of the Rue language.