Character-Level Negation '^' Added (4.1)
========================================

A character-level negation operator ^ was added. This operator has the same
precedence level as !. It is used to match single characters that are not
matched by the machine it operates on. The expression ^m is equivalent to
(any-(m)). This machine makes sense only when applied to machines that match
single characters. Since subtraction is essentially a set difference, any
strings matched by m that are not of length 1 will be ignored by the
subtraction and have no effect.

Discontinued Plus Sign To Specifify Positive Literal Numbers (4.1)
==================================================================

The use of + to specify a literal number as positive has been removed. This
notation is redundant because all literals are positive by default. It was
unlikely to be used but was provided for consistency. This notation caused an
ambiguity with the '+' repetition operator. Due to this ambibuity, and the fact
that it is unlikely to be used and is completely unnecessary when it is, it has
been removed. This simplifies the design. It elimnates possible confusion and
removes the need to explain why the ambiguity exists and how it is resolved.

As a consequence of the removal, any expression (m +1) or (m+1) will now be
parsed as (m+ . 1) rather then (m . +1). This is because previously the scanner
handled positive literals and therefore they got precedence over the repetition
operator. 

Precedence of Subtraction Operator vs Negative Literals Changed (4.1)
=====================================================================

Previously the scanner located negative numbers and therefore gave a higher
priority to the use of - to specify a negative literal number. This has
changed, precedence is now given to the subtraction operator.

This change is for two reasons: A) The subtraction operator is far more common
than negative literal numbers. I have quite often been fooled by writing
(any-0) and having it parsed as ( any . -0 ) rather than ( any - 0 ) as I
wanted.  B) In the definition of concatentation I want to maintain that
concatenation is used only when there are no other binary operators separating
two machines.  In the case of (any-0) there is an operator separating the
machines and parsing this as the concatenation of (any . -0) violates this
rule.

Duplicate Actions are Removed From Action Lists (4.1)
=====================================================

In many cases effort is expended towards ensuring identical machines are not
uniononed together, causing duplicate actions to appear in the same action list
(transition or eof perhaps). Often this requires factoring out a machine or
specializing a machine's purpose. For example, consider the following machine:

  word = [a-z]+ >s $a %l;
  main :=
      ( word ' '  word ) |
      ( word '\t' word );

This machine must be rewritten as following to avoid duplicate actions.  This
is essentially refactoring the machine.

  main := word ( ' ' | '\t' ) word;

An alternative is to specialize the machines:

  word1 = [a-z]+ >s $a %l;
  word2 = [a-z]+;
  main :=
      ( word1 ' '  word1 ) |
      ( word2 '\t' word1 );

Since duplicating an action on a transition is never (in my experience) desired
and must be manually avoided, sometimes to the point of obscuring the machine
specification, it is now to be done automatically by Ragel. This change should
have no effect on existing code that is properly written and will allow the
programmer more freedom when writing new code.

New Frontend
============

The syntax for embedding Ragel statements into the host language has changed.
The primary motivation is a better interaction with Objective-C. Under the
previous scheme Ragel generated the opening and closing of the structure and
the interface. The user could inject user defined declarations into the struct
using the struct {}; statement, however there was no way to inject interface
declarations. Under this scheme it was also awkward to give the machine a base
class. Rather then add another statement similar to struct for including
declarations in the interface we take the reverse approach, the user now writes
the struct and interface and Ragel statements are injected as needed.

Machine specifications now begin with %% and are followed with an optional name
and either a single ragel statement or a sequence of statements enclosed in {}.
If a machine specification does not have a name then Ragel tries to find a name
for it by first checking if the specification is inside a struct or class or
interface.  If it is not then it uses the name of the previous machine
specification. If still no name is found then this is an error.

Since the user now specifies the fsm struct directly and since the current
state and stack variables are now of type integer in all code styles, it is
more appropriate for the user to manage the declarations of these variables.
Ragel no longer generates the current state and the stack data variables.  This
also gives the user more freedom in deciding how the stack is to be allocated,
and also permits it to be grown as necessary, rather than allowing only a fixed
stack size.

FSM specifications now persist in memory, so the second time a specification of
any particular name is seen the statements will be added to the previous
specification. Due to this it is no longer necessary to give the element or
alphabet type in the header portion and in the code portion. In addition there
is now an include statement that allows the inclusion of the header portion of
a machine it it resides in a different file, as well as allowing the inclusion
of a machine spec of a different name from the any file at all.

Ragel is still able to generate the machine's function declarations. This may
not be required for C code, however this will be necessary for C++ and
Objective-C code. This is now accomplished with the interface statement.

Ragel now has different criteria for deciding what to generate. If the spec
contains the interface statement then the machine's interface is generated. If
the spec contains the definition of a main machine, then the code is generated.
It is now possible to put common machine definitions into a separate library
file and to include them in other machine specifications.

To port Ragel 3.x programs to 4.x, the FSM's structure must be explicitly coded
in the host language and it must include the declaration of current state. This
should be called 'curs' and be of type int. If the machine uses the fcall
and fret directives, the structure must also include the stack variables. The
stack should be named 'stack' and be of type int*. The stack top should be
named 'top' and be of type int. 

In Objective-C, the both the interface and implementation directives must also
be explicitly coded by the user. Examples can be found in the section "New
Interface Examples".

Action and Priority Embedding Operators
=======================================

In the interest of simplifying the language, operators now embed strictly
either on characters or on EOF, but never both. Operators should be doing one
well-defined thing, rather than have multiple effects. This also enables the
detection of FSM commands that do not make sense in EOF actions.

This change is summarized by:
 -'%' operator embeds only into leaving characters.
 -All global and local error operators only embed on error character
  transitions, their action will not be triggerend on EOF in non-final states.
 -Addition of EOF action embedding operators for all classes of states to make
  up for functionality removed from other operators. These are >/ $/ @/ %/.
 -Start transition operator '>' does not imply leaving transtions when start
  state is final.

This change results in a simpler and more direct relationship between the
operators and the physical state machine entities they operate on. It removes
the special cases within the operators that require you to stop and think as
you program in Ragel.

Previously, the pending out transition operator % simultaneously served two
purposes. First, to embed actions to that are to get transfered to transitions
made going out of the machine. These transitions are created by the
concatentation and kleene star operators. Second, to specify actions that get
executed on EOF should the final state in the machine to which the operator is
applied remain final.

To convert Ragel 3.x programs: Any place where there is an embedding of an
action into pending out transitions using the % operator and the final states
remain final in the end result machine, add an embedding of the same action
using the EOF operator %/action.

Also note that when generating dot file output of a specific component of a
machine that has leaving transitions embedded in the final states, these
transitions will no longer show up since leaving transtion operator no longer
causes actions to be moved into the the EOF event when the state they are
embeeded into becomes a final state of the final machine.

Const Element Type
==================

If the element type has not been defined, the previous behaviour was to default
to the alphabet type. The element type however is usually not specified as
const and in most cases the data pointer in the machine's execute function
should be a const pointer. Therefore ragel now makes the element type default
to a constant version of the alphabet type. This can always be changed by using
the element statment. For example 'element char;' will result in a non-const
data pointer.

New Interface Examples
======================

---------- C ----------

struct fsm
{
    int curs;
};

%% fsm 
{
    main := 'hello world';
}

--------- C++ ---------

struct fsm
{
    int curs;
    %% interface;
};

%% main := 'hello world';

----- Objective-C -----

@interface Clang : Object
{
@public
     int curs;
};

%% interface;

@end

@implementation Clang

%% main := 'hello world';

@end

