Symbolic Language
=================

Symbolic is a high-level programming language designed for mathematical expressiveness,
symbolic computation, and domain-specific abstraction. It provides first-class support
for algebraic manipulation, pattern matching, multi-tier execution, and an extensible
domain plug-in architecture.

.. code-block:: symbolic

   # Define a recursive algebraic function
   factorial(n) = n <= 1 ? 1 : n * factorial(n - 1)

   # Symbolic computation with domain blocks
   domain math {
       @equ x^2 - x - 2 == 0
       @d/dx sin(x)
   }

   # Pattern-driven control flow
   match value {
       Number(n) if n > 0 => f"positive: {n}";
       Number(0)          => "zero";
       _                  => "other"
   }

----

Getting Started
---------------

.. toctree::
   :maxdepth: 1
   :caption: Getting Started

   installation
   quickstart
   first_steps
   tutorial

Language Reference
------------------

.. toctree::
   :maxdepth: 2
   :caption: Language Guide

   language_guide/index
   language_guide/syntax
   language_guide/types
   language_guide/functions
   language_guide/control_flow
   language_guide/pattern_matching
   language_guide/modules
   language_guide/async
   language_guide/error_handling

Advanced Topics
---------------

.. toctree::
   :maxdepth: 1
   :caption: Advanced Topics

   advanced/symbolic_computation
   advanced/metaprogramming
   advanced/performance
   advanced/interop

API Reference
-------------

.. toctree::
   :maxdepth: 1
   :caption: API Reference

   api/builtins
   api/standard_library
   api/runtime

Examples
--------

.. toctree::
   :maxdepth: 1
   :caption: Examples

   examples/mathematical
   examples/data_processing
   examples/scientific_computing
   examples/web_development

Development Tools
-----------------

.. toctree::
   :maxdepth: 1
   :caption: Tools

   tools/repl
   tools/editor_support
   tools/debugging
   tools/testing

Community
---------

.. toctree::
   :maxdepth: 1
   :caption: Community

   contributing
   changelog
   roadmap
   faq

----

Design Principles
-----------------

**Mathematical notation as first-class syntax.**
   Symbolic expressions, algebraic function definitions, and domain-specific
   constructs are part of the core language grammar, not library add-ons.

**Gradual typing with inference.**
   Type annotations are optional. The type system operates silently when not
   needed and provides precise enforcement when annotations are present.

**Pattern matching over branching.**
   The ``match`` construct is the idiomatic way to handle conditional logic and
   data destructuring throughout the language.

**Extensible by design.**
   Domain plug-ins integrate at the parser, type-system, and runtime levels,
   allowing mathematics, physics, finance, and custom domains to expose
   native syntax without modifying the language core.

----

Indices
-------

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`