README

Daffodil

----------------
INTRODUCTION
----------------

Daffodil is a parser generator that follows the DFDL specification.

The generated parsers will translate into XML files that follow the format
described by an XML Schema with DFDL annotations.

It is a command line tool and a Java library.

----------------
REQUIREMENTS
----------------

Daffodil requires Java 1.6 or higher. All scripts provided for running and
testing are written in bash and tested in GNU Linux. Those scripts are not
required though, so Daffodil should be able to run in other platforms as long
as Java is installed.


SBT (0.12.1 or higher) is required for building using the provided script.

Daffodil requires Scala 2.10.4

----------------
RUNNING
----------------

The command line of Daffodil is invoked through an autogenerated bash script.
To generate the script run

  $ sbt stage

The script is created in daffodil-core/target/start, to execute daffodil:

  $ ./daffodil-core/target/start <options>

To determine the usage, execute the script with the --help option

  $ ./daffodil-core/target/start --help

----------------
BUILDING FROM SOURCE
----------------

See BUILD for detailed instructions on using the sbt scripts.

There are IDE's and eclipse plug-ins that can be used to build daffodil. See:

  http://www.scala-lang.org/node/91


---------------
PROJECT STRUCTURE
---------------

The project is broken down into three sub-projects:
- The daffodil-core sub-project contains most of the Daffodil code.
- The daffodil-lib contains utility classes used by Daffodil.
- The daffodil-propgen generates Scala code from the DFDL
  schema.

----------------
DOCUMENTATION
----------------

Documentation is provided in the directory 'doc' inside the Daffodil
installation directory. The following documents are included:

 * daffodil.pdf: A brief developers guide to Daffodil. It includes information
   on building and running, description of the files distributed, and
   description of the software architecture.
 * dfdl.odt: The DFDL specification followed by Daffodil, with comments on
   differences with the actual implementation.
 * api/index.html: The Scala API documentation.

----------------
EXAMPLES
----------------
TODO: Update this section.

Several examples are provided in the directory 'test'. They are in the form of
schema <XX.xsd>, input data files <XX###.in> and expected output <XX###.xml>.

----------------
COPYRIGHT NOTICE
----------------

Copyright (c) 2010 NCSA.  All rights reserved.
Developed by: NCSA Cyberenvironments and Technologies
              University of Illinois at Urbana-Champaign
              http://cet.ncsa.uiuc.edu/

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
deal with the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
  1. Redistributions of source code must retain the above copyright notice,
     this list of conditions and the following disclaimers.
  2. Redistributions in binary form must reproduce the above copyright
     notice, this list of conditions and the following disclaimers in the
     documentation and/or other materials provided with the distribution.
  3. Neither the names of NCSA, University of Illinois, nor the names of its
     contributors may be used to endorse or promote products derived from this
     Software without specific prior written permission.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
WITH THE SOFTWARE.