Language Guide
==============

This guide provides a complete reference to the Symbolic programming language.
Sections are ordered to build understanding progressively, but each page can be
read independently as reference material.

----

.. toctree::
   :maxdepth: 1

   syntax
   types
   functions
   control_flow
   pattern_matching
   modules
   async
   error_handling

----

Overview
--------

Syntax
   Lexical structure: comments, identifiers, keywords, literals, operators,
   operator precedence, and string interpolation.

Types
   The built-in numeric hierarchy (``Integer``, ``Float``, ``Fraction``, ``Complex``),
   strings, collections, booleans, and the optional type annotation system.

Functions
   Keyword (``fn``), algebraic, and lambda definition forms; parameters,
   default values, varargs, keyword-only parameters; closures; contract clauses
   (``requires`` / ``ensures``); generators; and higher-order patterns.

Control Flow
   Conditional expressions and statements; all loop variants (``for``, ``while``,
   ``loop``, ``repeat … until``); ``stop`` and ``skip``; the ternary and
   null-coalesce operators.

Pattern Matching
   The ``match`` expression; literal, type, structural, and wildcard patterns;
   guard expressions; list and tuple destructuring; view patterns.

Modules
   Import syntax, path resolution, wildcard imports, aliasing, grouped imports,
   and the module system layout.

Async
   ``async fn`` definitions; ``await`` expressions; parallel await with
   ``await all``; structured concurrency patterns.

Error Handling
   ``try`` / ``catch`` blocks; the ``try … ??`` operator; ``raise``; custom
   exception types; ``assert``.

----

Language Characteristics
------------------------

Symbolic is expression-oriented: every construct evaluates to a value. Statements
are expressions whose value may be discarded. Semicolons are used to delimit
statements but are frequently optional when the statement boundary is unambiguous.

The language is case-sensitive. Identifiers beginning with an underscore are
conventional for private bindings; the runtime does not enforce visibility.

Unicode identifiers in the Greek alphabet (``α``, ``θ``, ``Δ``, etc.) are valid
and frequently used in mathematical contexts.

----

Conventions Used in This Guide
--------------------------------

Code samples use the ``symbolic`` lexer for syntax highlighting. Lines prefixed
with ``#`` or ``//`` are comments; neither is part of the output. Where the output
of an expression is shown, it appears in a separate block labeled ``output``:

.. code-block:: symbolic

   result = 2 ^ 8

.. code-block:: text

   256