/**
@mainpage RDF Specs

@section RUG The RDF Users Guide		         Version 0.0

The Radar Definition Format (RDF) was developed as part of the Advanced Radar
Technology Program (ART).   It was a proposal to help simplify the exchange of
radar system design information between various Section 334 design tools.
Although funding for the task was canceled before completion, a fair amount of
work was spent defining the file format and developing software to read and
edit these files.  Though the file format is neither new nor elaborate, it has
a potential for simplifying data transfer between radar system elements.


@section UGO 	Users Guide Organization

The Radar Definition Format (RDF) Users Guide is divided into three distinct
chapters.  The first chapter contains a description of the file format, its
advantages, and limitations.  The Second chapter describes the RDF Reader
software available to read, write, and edit RDF files.  The final chapter
presents conventions, restrictions and guidelines that different projects have
adopted when using the RDF files.


@section RFF	RDF File Format


The Radar Definition File is an ASCII file and is organized using a
Key = Value method.  In its simplest form, each line of the file contains a
parameter name, an operator such as Ô=Ô, and the value of the parameter.
Optional fields include the units of the parameter and any comments that one
wishes to make.  This method allows sufficient flexibility to handle complex
multi-mode systems as well as single string low cost radars.  Only the
parameters that are necessary for a particular system must be specified,
keeping the file size down and making the RDF much more readable,  The
ordering of parameters is not important, so they can appear in whatever
sequence makes the most sense for a given system.

@subsection DFC	Data File Components

RDF files can contain two kinds of logical records: a data record and a
comment record.  A data record consists of the following components:

	Keyword   (Units)   [dimensions]   {element}   Operator    Values   Comments


Although they must occur in the order shown above, the fields indicated by
Italics are considered optional.   A comment record consists of any line which
does not contain an operator field, including lines that are entirely blank.

@subsubsection kw		Keyword

All data in an RDF file are identified byunique Keywords.  The Keyword is
composed of any arbitrary string of printable ascii characters except for the
11 reserved characters listed in section 2.3.  Spaces (ascii #32) and tabs
contained within a keyword are considered part of the keyword and must be
present when making keyword searches. However, spaces and tabs are considered
equivalent.  Also, consecutive spaces and tabs within a keyword are equivalent
to a single character.  Spaces and tabs on the leading and trailing ends of
keywords are ignored.  Both upper and lower case letters are allowed, however,
no distinction is made between them and they are equivalent in a keyword
search.

@subsubsection units		Units


If present, the Units field must occur between the keyword and the operator.
It is distinguish from the key word by open and close parenthesis ( ).
The units are expressed as an ascii field.  The RDF certified list of units
can be found in appendix A.  They include measures of length, velocity, mass,
time, etc.  If a logical record contains more than one data value, a separate
unit can be specified for each value.  If there are more values than units,
the last unit specified applies to all the remaining values.


@subsubsection operator		Operator


The operator separates the keyword from the list of values.  The default value
is the equals sign, =.  The default operator can be change by the following:

       OPERATOR = string

where string is the desired string of characters to be used as the operator.
It must be present in every logical data record.

 
@subsubsection values		Values


The value field can consist of any printable ascii character except for the
comment deliminator (see following section). The ascii representation of
numeric data follows the FORTRAN conventions for integer, fix point, and
floating point data formats.  Floating point data uses an E to indicate the
exponent value.  Data values can be space or comma delimited.  When character
and numeric data occur within the same data field, and the character string
contains spaces or commas, the string must be enclosed by double quotes, Ò

@subsubsection comments		Comments


Any characters following the comment deliminator are considered a comment.
The default comment deliminator is an exclimation point, !.  The comment
deliminator can be change by specifing:

	    COMMENT = string


where string can be any ascii string.  There is no restriction on the content
of the comment following the comment deliminator.

@subsubsection dim		Dimensions (Format Extension)


@subsubsection el		Elements (Unused)


@subsection del	Delimiters


When multiple values occur in the Units or Value fields, the entries can be
separated from each other using: commas, tabs, or spaces.

@subsection RC 	Reserved Characters

The following characters are not allowed in keywords, units, dimensions, and
elements:  (,  ),   [,   ],   {,   },  <,  >,  =,  !,  and ;.   In addition,
the semicolon, ;,  is not allowed in the value field. If ascii data contains
spaces, commas or tabs, it must be enclosed by double quotes.  Finally, if the
last character of a physical record is a backslash, \, the logical record is
continued onto the following line (see section 2.5).

@subsection RK Reserved Keywords


The following keywords are reserved and cannot be used in a data file:

	COMMENT, OPERATOR, PREFIX, SUFFIX, and INCLUDE.


@subsection PS	Prefix/Suffix
	
	
Often, a group of keywords will begin with similar character strings.  An
alternative to typing the repetitious portion of the keyword over and over
for each record is to use the following Prefix command at the beginning of
the group of records:

    PREFIX   =   Repetitious portion at the START of a set of Keywords

This applies to all following keywords in the file until another prefix command
is encounter.  At the end of the group, the prefix can be turn off by putting
the following record in the file:

    PREFIX =

The PREFIX string is considered as if it were part of the key for all Keywords
between the two above PREFIX entries.  It is the combination of the PREFIX and
explicit keyword that must satisfy the uniqueness requirement.

Similarly, if the end of a group of keywords is repetitious, the following
entry can be used:

      SUFFIX = Repetitious portion at the END of a set of Keywords


@subsection INC	Include


The Include command provides a convenient way of combining RDF files without
actually merging them.  The syntax is as follows

	 INCLUDE = filename


The result is equivalent to inserting all the records of the included file
into the original RDF file with exception of the PREFIX and SUFFIX commands.
If a prefix or suffix is used in the original file, it is applied to the
included file as well.  If the include file also has a prefix or suffix, they
do not over write the original suffix/prefix.  Instead, the new prefix/suffix
gets combined with the original for all applicable records in the included
file.  Should the included file also have an include statement, the process
continues. The maximum depth of include files open at any one time is 10.

(italics indicates not yet implemented)

@subsection WRAP	Continuation Lines

If the last non-space character in a physical record is backslash, \, the
logical record is continued onto the following line.  The last character
before the backslash is immediately followed by the first non-space character
of the next line.  If the first non-space character on the following line is
also a backslash, then it is skipped and the line continues with the character
immediately after the backslash.  This construction allows the line breaks
to be made even in the middle of a string of spaces without any ambiguity.
For Instance:

    Example_Key  =  The rain in Spain falls mainly on the plain
    		 is equivalent to all of the following:

    Example_Key  =  The rain in Spa\
        in falls mainly on the plain

    Example_Key  =  The rain in Spain \
    		 falls mainly on the plain

    Example_Key  =  The rain in Spain \
        \falls mainly on the plain

    Example_Key  =  The rain in Spain\
    		 \ falls mainly on the plain



@section AA APPENDIX A

The original RDF unit spec, based on a FORTRAN-77 platform, was inadequate.
The python implementation is described within.



@section IMP Python Implementation

@subsection pandm Packages and Modules
uRDF.py     basic __u__-sers \n 
iRDF.py     advanced __i__-teractive stuff \n
eRDF.py     uncut __e__-xperiment stuff\n
parse.py    A script for processing an rdf file to stdout\n
read.py     generators that read rdf files\n
utils.py    non-rdf specific utilites\n\n
__data__ External object for data\n
	entries.py  Data structure for file lines\n
	files.py  Mapping object (RDF) for files\n
\n
__reserved__ Constants as primatives.\n
	glyphs.py  Constant character glyphs\n
	words.py Command WORDS\n
\n
__language__  Grammar and Lexicon \n
	errors.py Grammar Exceptions\n
\n
__language__/ __grammar__ Symbols and Parsing\n
		morpheme.py Self-aware morphemes (affixes)\n
		punctuation.py Self-aware punctuations\n
		syntax.py the Grammar object that knows how to read RDF\n
\n
__language__/ __lexis__ Words\n
		semantics.py Words that become things (Nouns)\n
		pragmatics.py Words that will an can change Grammar (Verbs)\n
\n
__units__/ Units \n
	   	 physical_quantity.py SI Units, Prefixes and all the basics\n
		 addendum.py Non SI and user units.
		 
@subsection how How it works:

RDF input is ASCII strings- usually from and RDF file. They are converted
to an rdf.data.files.RDF mapping objects as follows:

A src file name is passed to rdf.uRDF.rdf_include -which is the mothership.
Before processing begins, an rdf.language.grammar.syntax.Grammar object
is created-- it knows the default RDF spec.

Input lines are ingested, with continued lines unwrapped, and yielded
one-by-one by the likes of rdf.read.unwrap_file

The lines are passed to the grammar  -which knows how to interpret them.
There are procesed in rdf.language.grammar.syntax.Grammar.process which
loops through the possible input types in a chain of the iterable
constants: \n
rdf.language.lexis.pragmatics.VERBS \n
rdf.language.lexis.semantics.NOUNS \n
until the line is ID's as and instance of one of them. That instance
knows what to do: \n
Verbs change the grammar ans possibly recursivey include files \n
Nouns are Records or Comments. \n

In either case the grammar object does not know what to do, the Verb or
Noun object has that responsility.

All verb except rdf.language.lexis.pragmatics.Include return and empty tuple,
while the later returns a list of the conetents of the included file.

There are to Nouns: \n\n
rdf.language.lexis.semantics.Record \n
rdf.language.lexis.semantics.Comment \n\n
These become:\n\n
rdf.data.entries.RDFPreRecord \n
rdf.data.entries.RDFComment\n\n

Both of these are iterable. The former is a single object, and when
iterated, yields a rdf.data.entries.RDFRecord and is exhausted. \n
The later iterates like an empty tuple: it just disappears. The point being:
no matter what you get back from the rdf_include generator: you can iterate
it and it will yield 0, 1, or many rdf.data.entries.RDFRecord objects
(which is the fundamental data representation of an RDF Record).
Note: you really can't yield 0, so what happens is it moves to the next
rdf line, until a finite number of records is kicked put. Thus the generator
chains them all together seemlessy, no matter the depth of recursion- and that
can be unpacked into the rdf.data.files.RDF constructor.

Note: the RDFRecord is a fancy (Key, "value") pair, where the key is the
rdf-dictionary key, and the value is an rdf.data.entries.RDFField tuple.
Hence the dict (really collection.OrderedDict) constructor unpacks that
pair to make the rdf mapping.

The rdf.data.entries.RDFField is a tuple of:

    value (units) {dimensions} [element] !comments

with some extras-- for instance, when it is created, the units (if present)
are check against the rdf.units.units_.UNITS dictionary and converted to
base units. It also has an eval() method, which will do what it takes to
take the value from a string into its native type.

Finally the rdf.data.files.RDF object-- which is what users really put into
their programms-- has some features:\n

(1) failed attribute requests are passed to the underline mapping class- so
you can perferm OrderDict method calls on them.

(2) getitem is special: rdf[key] returns eval(value)-- so the numeric (or
whatever) version of value, while rdf.get(key) returns the whole rdf field.
Note: it may be smarter to call eval on construction-- that is TBD.


\section flowc Flow Chart
 The flow chart:

\image html rdf.tiff

<div><a href="rdf.pdf">and it's high resolution version </a></div>	
		
		
**/
