
This directory contains a collection of examples of a proposed GGF
DFDL.

Each example file is intended to illustrate one or a small number of
DFDL concepts, or to be a example of how to express some realistic
example.

The contents of this directory are intended to be self-consistent, so
if you want to propose an alternative or variation then do not add
individual files, but rather, create a whole new directory which
contains files, all of which are consistent with your proposed
variation.

Conventions:

In order to facilitate structured discussion of these proposals,
variations should be in directories which are named as follows.

mjb20040627 - a root proposal. initials of an author and date (yyyymmdd).
mjb20040627-01 - variation on the root
mjb20040627-02 - variation on the variation
mjb20040627-03 - next variation on the variation
mjb20040627-02-mw-01 - branch from the mjb20040627-02 variant
mjb20040627-02-mw-02 - variation on the branch
mjb20040627-02-mw-03 - variation on the variation on the  branch
mjb20040627-02-mw-02-ac-01 - branch on the variation on the branch
mjb20040627-02-mw-02-ac-02 - ...variation
mjb20040627-02-mw-02-ac-03 - ...variation

This naming structure naturally creates a tree of branches where any
proposal can be returned to and discussed further at any time. All
versions are simultaneously available and visible for comparison and
contrasting. When the names get too long, you can introduce another
root directory to represent a branch that is interesting enough to
warrant shortening its name.

The directories should be stored on gridforge using ".zip" format to
make them easy to download and upload.

The remainder of this file describes the individual example files and
their purposes:

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

stored-length example

This example shows how the length of one field can be represented by
the value of another field, and how DFDL expresses the reference from
one to the other.

(factored from the 'clever-string' example, which is no longer included)

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

integer example

This somewhat contrived example shows how to calculate the value of an
element based on quantities in the rep, by using the example of
bigEndian and little Endian 4-byte integers. It also illustrates how
we refer to a metadata characteristic of the data from within the
run-time calculation.

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

unicode-char-code example

This somewhat contrived example shows how a calculation can decode a
complex representation, that of the utf-8 character encoding
scheme. Specifically, this illustrates how we must compute both a
value, and also compute the length of the underlying data rep that we
are consuming.

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

cobol-choice example

This illustrates use of the choice item, and how one provides an
expression to discriminate the choice.  It is drawn from a realistic
cobol example.

(replaces the choice aspects of the 'clever-string' example, which is
no longer included)

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

complex-date example

Illustrates layering via the calculation of the various attributes of
a logical date type from a representation which is a single integer
containing days since 1970.

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

scatter-gather example

Illustrates layering where the adjacency properties of the logical
layer are not preserved in the representation.

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

run-length-encoding example

Beyond scatter-gather which this example also illustrates, the
efficient translation from a RLE representation requires that data
structures be initialized and used repreatedly; hence, this example
motivates the creation of intermediate structures that are referenced
repeatedly in the transformation from rep to logical.

This example also illustrates call outs to external functions.

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

filter-stream example

Deals with "stream filters" like C-style comments, that are completely
unrelated to the shape of the logical data.

(factored from the prior 'matrix-with-dynamic-size' discussions)

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

TBD: 
- more examples, or pulling the above apart into smaller factors.
- need: multi-dimensional arrays
