the exact string printed will be `Pressure:  35\r\n' (note the extra
    space). If instead `var' were equal to 1432, then the behaviour would
    be undefined, because 1432 has more than three digits. In that case
    it would be necessary to use `\4' instead.

    If the variable might be negative, then use `\-3d' (or `\-4d'
    etc.) instead. That will cause LDmicro to print a leading space for
    positive numbers, and a leading minus sign for negative numbers.

    If multiple formatted string instructions are energized at once
    (or if one is energized before another completes), or if these
    instructions are intermixed with the UART TX instructions, then the
    behaviour is undefined.

    It is also possible to use this instruction to output a fixed string,
    without interpolating an integer variable's value into the text that
    is sent over serial. In that case simply do not include the special
    escape sequence.

    Use `\\' for a literal backslash. In addition to the escape sequence
    for interpolating an integer variable, the following control
    characters are available:
        * \r   -- carriage return
        * \n   -- newline
        * \f   -- formfeed
        * \b   -- backspace
        * \xAB -- character with ASCII value 0xAB (hex)

    The rung-out condition of this instruction is true while it is
    transmitting data, else false. This instruction consumes a very
    large amount of program memory, so it should be used sparingly. The
    present implementation is not efficient, but a better one will
    require modifications to all the back-ends.


A NOTE ON USING MATH
====================

Remember that LDmicro performs only 16-bit integer math. That means
that the final result of any calculation that you perform must be an
integer between -32768 and 32767. It also mean that the intermediate
results of your calculation must all be within that range.

For example, let us say that you wanted to calculate y = (1/x)*1200,
where x is between 1 and 20. Then y goes between 1200 and 60, which
fits into a 16-bit integer, so it is at least in theory possible to
perform the calculation. There are two ways that you might code this:
you can perform the reciprocal, and then multiply:

   ||         {DIV  temp  :=}          ||
   ||---------{ 1 / x       }----------||
   ||                                  ||
   ||          {MUL  y  :=  }          ||
   ||----------{ temp * 1200}----------||
   ||                                  ||

Or you could just do the division directly, in a single step:

   ||           {DIV  y  :=}           ||
   ||-----------{ 1200 / x }-----------||

Mathematically, these two are equivalent; but if you try them, then you
will find that the first one gives an incorrect result of y = 0. That
is because the variable `temp' underflows. For example, when x = 3,
(1 / x) = 0.333, but that is not an integer; the division operation
approximates this as temp = 0. Then y = temp * 1200 = 0. In the second
case there is no intermediate result to underflow, so everything works.

If you are seeing problems with your math, then check intermediate
results for underflow (or overflow, which `wraps around'; for example,
32767 + 1 = -32768). When possible, choose units that put values in
a range of -100 to 100.

When you need to scale a variable by some factor, do it using a multiply
and a divide. For example, to scale y = 1.8*x, calculate y = (9/5)*x
(which is the same, since 1.8 = 9/5), and code this as y = (9*x)/5,
performing the multiplication first:

   ||         {MUL  temp  :=}          ||
   ||---------{ x * 9       }----------||
   ||                                  ||
   ||           {DIV  y  :=}           ||
   ||-----------{ temp / 5 }-----------||

This works for all x < (32767 / 9), or x < 3640. For larger values of x,
the variable `temp' would overflow. There is a similar lower limit on x.


CODING STYLE
============

I allow multiple coils in parallel in a single rung. This means that
you can do things like this:

   ||       Xa               Ya        ||
 1 ||-------] [--------------( )-------||
   ||                                  ||
   ||       Xb               Yb        ||
   ||-------] [------+-------( )-------||
   ||                |                 ||
   ||                |       Yc        ||
   ||                +-------( )-------||
   ||                                  ||

Instead of this:

   ||       Xa               Ya        ||
 1 ||-------] [--------------( )-------||
   ||                                  ||
   ||                                  ||
   ||                                  ||
   ||                                  ||
   ||       Xb               Yb        ||
 2 ||-------] [--------------( )-------||
   ||                                  ||
   ||                                  ||
   ||                                  ||
   ||                                  ||
   ||       Xb               Yc        ||
 3 ||-------] [--------------( )-------||
   ||                                  ||

This means that in theory you could write any program as one giant rung,
and there is no need to use multiple rungs at all. In practice that
would be a bad idea, because as rungs become more complex they become
more difficult to edit without deleting and redrawing a lot of logic.

Still, it is often a good idea to group related logic together as a single
rung. This generates nearly identical code to if you made separate rungs,
but it shows that they are related when you look at them on the ladder
diagram.

                  *                 *                  *

In general, it is considered poor form to write code in such a way that
its output depends on the order of the rungs. For example, this code
isn't very good if both Xa and Xb might ever be true:

   ||       Xa         {v  :=       }  ||
 1 ||-------] [--------{ 12      MOV}--||
   ||                                  ||
   ||       Xb         {v  :=       }  ||
   ||-------] [--------{ 23      MOV}--||
   ||                                  ||
   ||                                  ||
   ||                                  ||
   ||                                  ||
   ||      [v >]             Yc        ||
 2 ||------[ 15]-------------( )-------||
   ||                                  ||

I will break this rule if in doing so I can make a piece of code
significantly more compact, though. For example, here is how I would
convert a 4-bit binary quantity on Xb3:0 into an integer:

   ||                                   {v  :=       }  ||
 3 ||-----------------------------------{ 0       MOV}--||
   ||                                                   ||
   ||       Xb0                  {ADD  v  :=}           ||
   ||-------] [------------------{ v + 1    }-----------||
   ||                                                   ||
   ||       Xb1                  {ADD  v  :=}           ||
   ||-------] [------------------{ v + 2    }-----------||
   ||                                                   ||
   ||       Xb2                  {ADD  v  :=}           ||
   ||-------] [------------------{ v + 4    }-----------||
   ||                                                   ||
   ||       Xb3                  {ADD  v  :=}           ||
   ||-------] [------------------{ v + 8    }-----------||
   ||                                                   ||

If the MOV statement were moved to the bottom of the rung instead of the
top, then the value of v when it is read elsewhere in the program would
be 0. The output of this code therefore depends on the order in which
the instructions are evaluated. Considering how cumbersome it would be
to code this any other way, I accept that.


BUGS
====

LDmicro does not generate very efficient code; it is slow to execute, and
wasteful of flash and RAM. In spite of this, a mid-sized PIC or AVR can
do everything that a small PLC can, so this does not bother me very much.

The maximum length of variable names is highly limited. This is so that
they fit nicely onto the ladder diagram, so I don't see a good solution
to that.

If your program is too big for the time, program memory, or data memory
constraints of the device that you have chosen then you probably won't
get an error. It will just screw up somewhere.

Careless programming in the file load/save routines probably makes it
possible to crash or execute arbitrary code given a corrupt or malicious
.ld file.

Please report additional bugs or feature requests to the author.

Thanks to:
    * Marcelo Solano, for reporting a UI bug under Win98
    * Serge V. Polubarjev, for not only noticing that RA3:0 on the
      PIC16F628 didn't work but also telling me how to fix it
    * Maxim Ibragimov, for reporting and diagnosing major problems
      with the till-then-untested ATmega16 and ATmega162 targets
    * Bill Kishonti, for reporting that the simulator crashed when the
      ladder logic program divided by zero
    * Mohamed Tayae, for reporting that persistent variables were broken
      on the PIC16F628
    * David Rothwell, for reporting several user interface bugs and a
      problem with the "Export as Text" function


COPYING, AND DISCLAIMER
=======================

You may redistribute LDmicro in unmodified form however you would
like. You may not modify LDmicro. The source code to LDmicro is not
generally available. Commercial use is permitted, within the constraints
given above. Contact me for support or enhancements.

THIS PROGRAM IS DISTRIBUTED WITH NO WARRANTY, TO THE EXTENT PERMITTED BY
APPLICABLE LAW. DO NOT USE CODE GENERATED BY LDMICRO IN APPLICATIONS IN
WHICH SOFTWARE FAILURE COULD RESULT IN DANGER TO HUMAN LIFE OR DAMAGE
TO PROPERTY. THE AUTHOR ASSUMES NO LIABILITY FOR ANY DAMAGES RESULTING
FROM THE OPERATION OF LDMICRO OR CODE GENERATED BY LDMICRO.


Jonathan Westhues

Rijswijk      -- Dec 2004
Waterloo ON   -- Jun, Jul 2005
Cambridge MA  -- Sep, Dec 2005
                 Feb, Mar 2006
                 Feb 2007

Email: user jwesthues, at host cq.cx