.. index:: barcode generator

Barcode generator
=================

The Barcode generator makes it possible to generate barcode for RPN
programs. To use it you will need a Postscript level 2 (or later)
[#postscript]_ printer.
To read the barcode into the HP-41, an HP 82153A Wand is required.

.. running:: "Barcode generator" barcode
.. literalinclude:: gen/BarcodeSignOn.text
   :language: none

The input source file can either be an RPN source file or a raw binary
image (using ``.raw`` file extension).

Language
--------

The Barcode Generator will accept the same kind of source files as the
RPN compiler, see :ref:`sec-rpn-language`.
A source file that contains the ``.local`` directive is not accepted, see :ref:`sec:rpn-local-directive`.


Preprocessor
------------

The Barcode generator uses a full featured C preprocessor to handle the input
source file. The preprocessor provides the normal features you will
find in a C preprocessor, the ability to include header files, macro
expansions, conditional compilation and use of C style comments.

Wikipedia is a good place to look for an introduction with many
examples on how to use the
`C preprocessor <http://en.wikipedia.org/wiki/C_preprocessor>`_.

When used in the Barcode generator, the following macros are predefined:

.. index:: __CALYPSI_NUT__ (predefined symbol), predefined symbol; __CALYPSI_NUT__
.. index:: __CALYPSI_BARCODE__ (predefined symbol), predefined symbol; __CALYPSI_BARCODE__
.. index:: __CALYPSI_RAM_USE__ (predefined symbol), predefined symbol; __CALYPSI_RAM_USE__

.. table:: Predefined processor symbols
 :widths: 1 3
 :column-dividers: none single none

 +---------------------------------+----------------------------------+
 |Preprocessor symbol              |Description                       |
 +=================================+==================================+
 |``__CALYPSI_NUT__``              |An integer that is 1 when the Nut |
 |                                 |target (including NEWT variant)   |
 |                                 |is used.                          |
 +---------------------------------+----------------------------------+
 |``__CALYPSI_BARCODE__``          |An integer that is 1 when the     |
 |                                 |Barcode generator is used.        |
 +---------------------------------+----------------------------------+
 |``__CALYPSI_RAM_USE__``          |An integer that is 1 when the     |
 |                                 |Barcode generator is used.        |
 +---------------------------------+----------------------------------+



.. index:: RPN;branch length, branch length;RPN

Branches and labels
-------------------

Local branches are automatically selected depending on branch
distance. The distance for a compiled small branch is slightly shorter
in RAM compared to ROM, which is taken into account.

A fixed local ``GTO`` and ``XEQ`` instruction [#branch]_ in a program
has reserved space in the instruction to store the offset to its
destination label. The first time such instruction is executed, the
branch offset is unknown and the calculator will search for the
destination label. Once found, the offset is stored together with the
instruction to speed up execution the next time the instruction is
encountered.

However, some ``GTO`` instructions exists in a smaller (space saving
form) that only can store short offsets. The RPN compiler will encode
such branches in their long version if needed, to ensure that there is
room to store the compiled offset to the destination label.

.. rubric:: Footnotes
.. [#postscript]
   The reason it does not work with Postscript level 1 is that a
   feature to compensate for accumulating errors is used. Today, level
   1 printers are rare, level 2 was introduced in 1991.
.. [#branch]
   This excludes indirect branches and branches to alpha labels. Such
   branch instructions lack space to store the offset the the label.
