Quick Start
===========

This page demonstrates the core language features in the shortest practical path.
For a full treatment of each topic, follow the links into the :doc:`language_guide/index`.

----

Hello, World
------------

Save the following to ``hello.sym`` and run it with ``symbolic hello.sym``:

.. code-block:: symbolic

   print("Hello, World!");

----

The Interactive REPL
--------------------

Start the REPL with no arguments:

.. code-block:: bash

   symbolic

The REPL supports syntax highlighting, tab completion, and multi-line input.
Use arrow keys to navigate history. Special commands begin with ``%``:

.. list-table::
   :widths: 25 75
   :header-rows: 1

   * - Command
     - Description
   * - ``%help``
     - Display help and a list of available commands
   * - ``%version``
     - Print the runtime version
   * - ``%magic``
     - List all REPL magic commands
   * - ``%clear``
     - Clear the terminal screen
   * - ``%history``
     - Show the command history for this session
   * - ``%exit``
     - Exit the REPL

----

Variables and Literals
-----------------------

.. code-block:: symbolic

   # Integers, floats, complex numbers
   n        = 42
   pi_approx = 3.14159
   z         = 3 + 4i
   big       = 1_000_000
   sci       = 6.022e23
   hex_val   = 0xFF
   bin_val   = 0b1010

   # Strings
   name      = "Alice"
   raw       = r"C:\Users\name"
   multiline = """
   Line one
   Line two
   """

   # Interpolation
   greeting  = f"Hello, {name}! n is {n}."

   # Collections
   nums  = [1, 2, 3, 4, 5]
   point = (10, 20)
   tags  = {"alpha", "beta", "gamma"}
   cfg   = {"host": "localhost", "port": 8080}

----

Functions
---------

Three syntactic forms are available, each suited to different contexts:

.. code-block:: symbolic

   # Keyword form — explicit body, supports full statements
   fn add(x, y) {
       return x + y;
   }

   # Algebraic form — implicit return, mirrors mathematical notation
   square(x) = x ^ 2

   # Lambda form — anonymous, for use as values
   double = ((x) -> x * 2)

   # With type annotations and contract clauses
   fn divide(a: Integer, b: Integer) -> Fraction
       requires b != 0
       ensures result * b == a {
       return a / b;
   }

   # Async function
   async fn fetch(url) {
       response = await http.get(url);
       return response.json();
   }

----

Control Flow
------------

.. code-block:: symbolic

   # Conditionals
   if x > 0 {
       print("positive");
   } else if x < 0 {
       print("negative");
   } else {
       print("zero");
   }

   # Inline ternary
   label = x >= 0 ? "non-negative" : "negative"

   # While loop
   while i < 10 {
       i += 1;
   }

   # For-in loop (iterator style)
   for item in [1, 2, 3, 4, 5] {
       print(item);
   }

   # Range loop with exclusive upper bound
   for i in 0..<10 {
       print(i);
   }

   # C-style loop: initializer, condition, step
   for i = 0, i < 10, 1 {
       print(i);
   }

   # Infinite loop
   loop {
       if done { stop; }
   }

   # Repeat-until (do-while equivalent)
   repeat {
       x += 1;
   } until x >= 100;

----

Pattern Matching
----------------

.. code-block:: symbolic

   fn classify(value) {
       match value {
           Number(n) if n > 0  => f"{n} is positive";
           Number(0)           => "zero";
           Number(n)           => f"{n} is negative";
           String(s)           => f"string: {s}";
           [head, *tail]       => f"list starting with {head}";
           _                   => "unknown"
       }
   }

----

Error Handling
--------------

.. code-block:: symbolic

   # Structured try-catch
   try {
       result = risky_operation();
   } catch err {
       ValueError        { print(f"Value error: {err}"); }
       ZeroDivisionError { print("Division by zero"); }
       _                 { print(f"Unexpected: {err}"); }
   }

   # Try operator — inline fallback
   value = try parse_int(input) ?? 0

----

Classes
-------

.. code-block:: symbolic

   class Point extends (Object) {
       fn __init__(self, x, y) {
           self.x = x;
           self.y = y;
       }

       fn distance_to(self, other) {
           dx = self.x - other.x;
           dy = self.y - other.y;
           return (dx^2 + dy^2).sqrt();
       }

       static fn origin() = Point(0, 0)
   }

   p1 = Point(3, 4)
   p2 = Point.origin()
   print(p1.distance_to(p2))    # 5

----

Imports
-------

.. code-block:: symbolic

   import math;
   import math::integration;
   import math::functions::{sin, cos, exp};
   import math::constants::*;
   import math::integration as integ;

----

Mathematical Domains
--------------------

The ``domain math`` block enables extended mathematical syntax:

.. code-block:: symbolic

   domain math {
       @var x

       # Equation and derivative
       @equ x^2 - x - 2 == 0
       @d/dx sin(x^2)

       # Definite integral: ∫₀¹ x² dx
       @integral [x=0 to 1] x^2, dx

       # Summation: Σ k² for k=1..n
       @sum {k=1}^{n} k^2

       # Matrix
       A = @matrix [[1, 2], [3, 4]]
   }

----

Next Steps
----------

.. list-table::
   :widths: 30 70
   :header-rows: 0

   * - :doc:`language_guide/syntax`
     - Complete syntax reference: literals, operators, comments, identifiers
   * - :doc:`language_guide/functions`
     - All function forms, parameters, closures, contracts
   * - :doc:`language_guide/pattern_matching`
     - Structural, type, and guard patterns; exhaustiveness
   * - :doc:`language_guide/types`
     - Built-in numeric types, strings, collections, and the type system
   * - :doc:`examples/mathematical`
     - Worked examples using the mathematics standard library2