NB: Work in progress (25.th of August 2013)

-----------------------------------------------------------------

1. ........... The structure of a keyword
  1.1 ........ Records
  1.2 ........ How many records in a keyword
  1.3 ........ The content of a record: items
2. ........... The classes involved
  2.1 ........ Parser / ParserKeyword / ParserRecord / ParserItem
  2.2 ........ RawDeck / RawKeyword / RawRecord
  2.3 ........ Deck / DeckKeyword / DeckRecord / DeckItem
3. ........... Configuring the keywords with Json.


Keywords is the most important aspect of the ECLIPSE datafile
parser.

1. The structure of a keyword
-----------------------------

1.1 Records
-----------

The data content of a keyword comes as a collection of
records. Records are a collection of 'data', terminated by a '/'. Here
are three examples of records:

   'METRES'  /

   1  'OFF'  100  '*'  24.0  /

   0.26 0.27 0.26 0.78
   0.82 0.66 0.27 0.78
   0.76 0.56 0.23 0.67   /

From these examples we see that:

  1. One record can contain a mix of integer, float and string values.
  2. Records typically correspond to one line in the data-file, but
     that is purely convention; the records can be sprinkled with
     newlines.
  3. Each record is terminated with a '/'


1.2 How many records in a keyword
---------------------------------

One of the first structural elements which must be configured into the
the parser keywords is the number of records in the different
keywords, this is closely related to how the keyboard is
terminated. Here comes three typical examples of keywords:


  GRID

  WCONHIST
    ... /
    ... /
    ... /
  /

  EQLDIMS
    ....   /

  EQUIL
    .... /
    .... /


In the list above here the GRID keyword has zero records, i.e. no data
at all. The WCONHIST keyword has three records of data, the EQLDIMS
keyword has one record and the EQUIL keyword has two records of
data. When it comes to record size and termination the keywords can be
split in three groups:

  1. Keywords with a fixed number of records. Both the GRID keyword
     and the EQLDIMS keyword have a fixed number of records, zero and
     one respectively. These keywords are therefor not explicitly
     terminated in any way.

  2. Keywords with a variable number of records like the
     WCONHIST. Becase the number of records is not known in advance
     this keyword must be explicitly terminated with a '/'.

  3. Keywords where the number of records is inferred from the content
     of another keyword; this is the case with EQUIL which reads the
     number of records from the xxx item of the EQLDIMS keyword. Since
     the number of records is known in advance (indirectly through the
     EQLDIMS keyword) the EQUIL keyword is not explicitly terminated
     with a '/'.

1.3 The content of a record: items

[ Disclaimer: The initial defintion of a item could be configured to
  have a fixed number of elements greater than one, that possibility
  has now been removed. However the code, and in particular the
  configuration shows this heritage.]

The different elements in a record are organized in items. An item can
either consist of one single element from the record, or alternatively
all the elements in the record. An item has a name, a data type and
optionally a default value.


2. The classes involved
-----------------------

The library contains classes along two dimensions:

   +----------------+     +----------------+     +----------------+ 
   | Parser         |     | RawDeck        |     | Deck           | 
   +----------------+     +----------------+     +----------------+ 
  		       		      	      		    
   +----------------+     +----------------+     +----------------+ 
   | ParserKeyword  |     | Rawkeyword     |     | DeckKeyword    | 
   +----------------+     +----------------+     +----------------+ 
  		       		      	      		    
   +----------------+     +----------------+     +----------------+ 
   | ParserRecord   |     | RawRecord      |     | DeckRecord     | 
   +----------------+     +----------------+     +----------------+ 
        		             		            		    
   +----------------+     		         +----------------+ 
   | ParserItem     |     		         | DeckItem       | 
   +----------------+     		         +----------------+ 
  







3. Configuring a parser keyword
-------------------------------