.. Mars Documentation
   Copyright (C) 2011 Matt Giuca

.. This program is free software: you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation, either version 3 of the License, or
   (at your option) any later version.

.. This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

.. You should have received a copy of the GNU General Public License
   along with this program.  If not, see <http://www.gnu.org/licenses/>.

:mod:`debug` --- Debugging functions
====================================

.. sectionauthor:: Matt Giuca <matt.giuca@gmail.com>
.. moduleauthor::  Matt Giuca <matt.giuca@gmail.com>

.. module:: debug
   :synopsis: Provides functions which help with debugging and testing
              software.

This module provides functions which help with debugging and testing software.

.. warning::

   Mars is, fundamentally, a pure language. Normally, functions cannot perform
   input/output unless they declare themselves to be ":keyword:`io`".

   The functions in this module break that purity by allowing functions to
   produce output, even if they do not declare themselves as :keyword:`io`.
   They should not be considered part of the language semantics, and are only
   intended for use in debugging and testing software (not as part of the
   normal operation of the software).

.. function:: trace_char(char :: Num) :: Num

   Writes *char* as a byte to standard error. It is an error if *char* is
   outside the range [0, 255]. Returns 0.

   This is the same as :func:`put_char`, except that a) it writes to standard
   error (rather than standard output), and b) it can be called from a
   non-:keyword:`io` context.

.. function:: trace(string :: Array(Num)) :: Num

   Writes *string* to standard error. This calls :func:`trace_char` on each
   element of *string*. It is an error if any element is outside the range [0,
   255]. Does not print a newline.

   This is the same as :func:`print_string`, except that a) it writes to
   standard error (rather than standard output), and b) it can be called from
   a non-:keyword:`io` context.