.. include:: ../global.rst

Reader Functions
----------------


.. _`read`:

.. idio:function:: read [handle]


   read an Idio expression from `handle`			
   							
   :param handle: handle to read from, defaults to the current input handle	
   :type handle: handle, optional				
   :return: object						


Reader Operators
----------------

Reader :ref:`operators <operators>` operate on the Abstract Syntax
Tree.  Their purpose is to rewrite the AST to normalize expressions.

Having read an expression in, the reader will scan it for operators
and apply the operator to the "before" and "after" parts of the
expression.  The operators job is to return a re-written expression
that has been normalised.

For example, commonly, arithmetic uses infix operators: :samp:`1 + 2`.
However, :lname:`Idio` only accepts functions as the first element of
a form so the original expression needs to be rewritten.

For many infix operators you can imagine that it is easy enough to
rewrite the expression with the symbol for the operator now in first
place :samp:`+ 1 2` as the symbol `+` will evaluate to the arithmetic
addition function.

The arithmetic :ref:`+ <+>` function handles a number of varargs
possibilities whereas we know that the infix `+` operator is a binary
addition function, that is it always has two arguments.  So, in this
particular case, the `+` infix operator rewrites the expressions as
:samp:`binary-+ 1 2` where :ref:`binary-+ <binary-+>` is expecting
exactly two arguments.

Standard Operators
^^^^^^^^^^^^^^^^^^

There are a number of standard operators and modules can define their
own.  An obvious operator for the :ref:`job-control module` to define
is ``|``.

.. csv-table::
   :widths: auto
   :align: left

   ``+`` ``-`` ``*`` ``/``, infix binary arithmetic
   ``lt`` ``le`` ``eq`` ``ge`` ``gt``, infix binary numeric comparison
   ``and`` ``or``, infix multiple logical sequence :ref:`and <and special form>` and :ref:`or <or special form>`
   ``=+`` ``+=``, infix :ref:`array-push! <array-push!>` and :ref:`array-unshift! <array-unshift!>` operators
   ``=-`` ``-=``, postfix :ref:`array-pop! <array-pop!>` and :ref:`array-shift! <array-shift!>` operators
   ``.``, infix :ref:`value-index <value-index>`

.. _`comments`:

Comments
--------

There are several comment forms in :lname:`Idio` -- none of which are
shell-like.  That's largely because the shell comment character,
``#``, is used to tell the reader that some interesting construction
is coming its way.

Line
^^^^

You can comment everything to the end of the line with ``;``.

S-exp
^^^^^

You can comment out an entire s-exp with ``#;``, including multi-line
s-exps.

S-exps are usually parenthesised expressions, :samp:`(...)`, which,
noting that :lname:`Idio` doesn't always use them, makes this kind of
comment less useful.

.. code-block:: idio

   a := 10

   #;(and my-debug-flag
	  (set! a 5))

   a			; 10

Multi-line
^^^^^^^^^^

There are two types of nestable multi-line comments:

* ``#* ... *#`` for regular commentary

* ``#| ... |#`` which is reserved for "semi-literate" comments

  These are a nod to :ref-author:`Donald Knuth`'s `literate
  programming`_ but inverted: code interspersed with natural language.

  That said, this form doesn't do anything other than act as another
  form of multi-line comment.  Some thought needs to be put into what
  to do with semi-literate commentary.  Currently, junk it!

The multi-line part of these forms should be self-explanatory, the
*nestable* part is more interesting.

In the first instance it means you can safely comment out any larger
block of code that already contains a multi-line comment:

.. code-block:: idio

   #*

   a := 10

   #*
   if my-debug-flag {
     a = 5
   }
   *#

   a
   *#

These two forms are mutually nestable meaning you can comment out
parts of your semi-literate commentary and put semi-literate
commentary in your comments.

Escaping
""""""""

There are always some corner cases where we might need to escape our
way out:

WARNING: the web page language interpreter doesn't handle these very
well!

.. code-block:: idio

   #*

   ; don't use the comment terminator, \*#, here

   *#

If you want to use something other than ``\`` for the escape
character, put the graphic character (ie., not whitespace) immediately
after the opening ``#*`` or ``#|``:

.. code-block:: idio

   #*%

   ; don't use the comment terminator, %*#, here

   *#




.. include:: ../commit.rst