.. Copyright (c) 2026 Patrick Smith
   Use of this source code is subject to the MIT-style license in the LICENSE file.

The Wig programming language
============================

This is a description of the Wig programming language.

As yet, Wig is not much more than a gleam in the author's eye,
so expect this guide to be inconsistent, incomplete, and unusable.

Some goals for Wig:

- This is a personal project. Progress will be slow.
  Features may be included or excluded at the author's whim.
- Experiment with some ideas.
  Many of these may seem weird at first sight,
  but the point is to discover how well they work in practice.
- Wig will be an imperative language, with a declarative subset.
  How large that subset is remains to be seen.
- The concepts used by Wig will be built from a few very primitive notions.
  Even to the extent that we will use Wig to describe, for example,
  what integers are and how they behave.
- The initial version will be an interpreter written in Go.
- Eventually, the author hopes to replace that with a compiler written
  in Wig itself.

Getting started
---------------

To build Wig, you will need a `Go compiler`_.

.. _Go compiler: https://go.dev/learn/

The source code for Wig is available at https://github.com/pat42smith/wig.

.. admonition:: TODO

   Actually, it's not there yet.

After you have downloaded a copy of the source code, you can build Wig by going to
the top level directory and running the command :command:`go build`.
This should create an executable file named :file:`wig` (or :file:`wig.exe` on Windows)
in the current directory. You might want to copy this file to one of the
directories in your search path.

To run a simple program, copy this text into a file, say :file:`hello.wig`:

.. literalinclude:: examples/hello.wig
   :lines: 1-2

Now run the program with the command :command:`wig hello.wig`.
You should see this output::

   Hello, world!

A few notes on this program:

- Each program should contain a procedure named :code:`main`, which will be
  executed when the program is run.
- The single quote :code:`'` is used for scoping.
  When used by itself before a name, it indicates the name should be
  looked up in the standard library.
- :code:`'Println` is a standard library function that prints its arguments
  separated by spaces and followed by a newline character.
- Wig uses indentation to mark program structure,
  so the body of :code:`main` is indented.

.. admonition:: TODO

   Link to more information about scoping with single quotes.
   Link to more information about blocks.
   Link to more information about the standard library and Println.

Examples
--------

This document contains many small example programs.
These are copied from the Wig test suite.
The program above is part of one such example;
the full example reads:

.. literalinclude:: examples/hello.wig

Wig ignores the last line, because :code:`#` starts a comment.

.. admonition:: TODO

   Link to a fuller description of comments.

However, the test framework recognizes a line beginning with :code:`#>`,
and treats the rest of the line as output that should appear when
the example program is run.
A line beginning with :code:`#!` describes expected error output:

.. literalinclude:: examples/nonesuch.wig

You can run the full test suite by going to the top directory of the wig source tree
and running one of the commands :command:`./runtests` or :command:`go test`.
In either case, you must first install the :command:`invigilate` program
from https://github.com/pat42smith/invigilate.

.. admonition:: TODO

   Make these work.

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   parsing