Pippin and Roog

Pippin is a high level XML Schema based tool for:

Marshaling Ruby Objects to XML
Unmarshaling XML into Ruby Objects.

If you are familiar with other Ruby XML tools, you may want to know how Pippin differs from REXML (www.germane-software.com/software/rexml/). Pippin is a layer on top of REXML that makes it even easier to work with XML documents that are described by XML schemas. Using Pippin is not much harder than digesting the XML schema, and pointing Pippin to an instance file to unmarshal, or an Object graph to marshal. Examples are shown in a later section.

Pippin relies on Roog determine how to map Objects and XML. There are two different categories of Objects that Pippin can marshal/unmarshal:

Traditional domain objects, belonging to classes created by Roog, from definitions in an XML Schema. This is your best choice when behaviors are required.
Framelets or HashedFramelets: classes of objects that can look like any other class. Framelets and HashedFramelets don’t have any specialized behaviors, just behaviors inherited from Object, and attribute access methods. These are the easiest to use option when behaviors are not required.

Roog (Ruby Object Ontology Generator) analyzes an XML schema and determines how to map its data onto Ruby Objects. As a side effect, it builds an in-memory database of meta-information related to this mapping. Once this has been done, you can either:

Query Roog regarding either Object meta-information, or the relationship between Objects and XML. Mapping information is useful to marshaling/unmarshaling tools like Pippin. Structural information is useful for slot-and-frame like systems such as those wrapped by the GenericFrameProtocol described by this paper: www.ai.sri.com/~gfp/gfp2-spec.ps.
Ask Roog to generate a file containing class definitions. These class definitions are purely structural: they contain attributes, and may have sub-classes, but they have no behaviors. Ruby makes it easy to add the behaviors later: for an example of this, see the OffspringViewer, where Behavior_IPC2581.rb and Rendering_IPC2581.rb add (respectively) domain behaviors and rendering behaviors to the domain structures defined in the Roog-generated IPC2581.rb file. By adding two new classes (a Namer and a Generator) you should be able to generate class structures for other languages (such as Java, Python, or PHP) if you so desire.

Status

Pippin and Roog are currently pre-release software, which has not yet undergone internal reviews.

Pippin and Roog were originally made as part of the OffspringViewer for the IPC-2581 format. They have also been used for a Gerber-to-2581 translator, and a reverse translator. They have also been used for a viewer for Semi E120 files. Although some effort has been made to keep Roog and Pippin general, XML Schemas are complicated (some would say excessively). To determine if Roog can handle your schema, attempt to analyze the schema, and examine the warnings:

      require 'nist/pippin/roog'
      Roog::Analyzer.analyze 'path-to-XMLSchema'

Installation

Pippin can be downloaded in several forms:

A RubyGem, containing only Pippin and Roog. Due to lack of resources, the RubyGem is untested.
A development snapshot containing Pippin and nearly everything it depends on, in a .tgz or .zip archive. The snapshot contains a complete Amber development environment. Before using the development snapshot, you need to:
1. Setup Amber (included in the snapshot): see ReadMe_Amber.txt
2. Install libraries required by Pippin:
```
    cd $DevRoot/Projects/pippin
    rake install_lib
```

Using Roog

 require 'nist/pippin/roog'

 # Set attributes in roog_policy to modify Roog
 # behavior, if desired

 Roog::Analyzer.analyze 'path-to-XMLSchema'
 Roog::Semantics_Ruby.specialize
 Roog::Generator_Ruby.writeTo 'name-of-outputFile.rb'

 # If everything went well, you now have a file of
 # Ruby sourcecode that defines Objects described by
 # the input schema.

Using Pippin

 require 'nist/pippin/pippin'
 require 'nist/pippin/roog'
 require 'class-definitions-produced-by-Roog'

 # Set attributes in roog_policy and
 # Pippin::Policy.default if desired.

 # Prepare a Roog::Analyzer
 Roog::Analyzer.analyze 'path-to-XMLSchema'
 Roog::Semantics_Ruby.specialize
 analyzer = Roog::Analyzer.detach

 # Make a parser and a writer
 parser = Pippin::Parser.new analyzer
 writer = Pippin::Writer2.new analyzer

 # Unmarshal an XML file into an Object graph
 domainObject = parser.parse 'path-to-instance-doc'

 # If you would like to examine the result:
 domainObject.treeDump

 # Marshal an Object graph into an XML file
 writer.write  domainObject, 'path-to-output-file'

Author: A. Griesser