IronMeta User Manual

Version 1.4

IronMeta provides a programming language and application for generating pattern matchers on arbitrary streams of objects. It is an implementation of Alessandro Warth's OMeta system for C# on .NET.

IronMeta is available under the terms of the BSD License.

• The IronMeta Language
• The IronMeta Grammar
• The IronMeta SourceForge page

Contributors

IronMeta 1.4 was written entirely by Gordon Tisher.

Features

• Although the most common use for IronMeta is to build parsers on streams of text for use in compiling or other text processing, IronMeta can generate pattern matchers (more accurately, transducers) for any input and output type. You can use C# syntax directly in grammar rules to specify objects to match.
• IronMeta-generated parsers can function with strict Parsing Expression Grammar semantics, or can function as fully-backtracking recursive-descent parsers.
• Generated parsers are implemented as C# partial classes, allowing you to keep ancillary code in a separate file from your grammar.
• Unrestricted use of C# in semantic conditions and match actions.
• Higher-order rules: you can pass rules as parameters, and then use them in a pattern.
• Pattern matching on rule arguments: you can apply different rule bodies depending on the number and types of parameters.
• Flexible variables: variables in an IronMeta rule may be used to:
  • get the input of an expression they are bound to.
  • get the result or result list of an expression they are bound to.
  • match a rule passed as a parameter.
  • pass a rule on to another rule.
• As an enhancement over the base OMeta, IronMeta allows unlimited left-recursion, using Warth, Douglass and Millstein's algorithm, for all rules, even within parameter matching.

Current limitations:

• Error reporting is currently quite rudimentary. The software internally collects data regarding all failed matches, but the main program currently only reports the last error that ocurred at the rightmost position in the input.
• Performance is quite slow, as not much optimization has been done to date.

Changelog

1.4: Bug fixes and sample

• Fixed a bug when passing rules in a base class to another rule.
• Added a sample that parses a data file and produces an XmlDocument.

1.3: Optimization pass

• IronMeta is now about an order of magnitude faster.
• Fixed a bug when handling C# string literals.

1.2: Bug fixes and miscellaneous enhancements.

• Added a simple interactive shell to the Calc program.
• Fixed a bug that caused redundant evaluation of involved rules.
• Fixed a bug with parsers that don't declare a base class.
• Added "::=" as alternative to "=" for rules.
• Changed condition operator to single question mark to conform to other OMetas.
• C# object literals must be surrounded by curly braces.

1.1:

• Can now handle IEnumerable literals (e.g. strings, for a matcher of characters).

1.0: Initial release

Get IronMeta

IronMeta is currently only available for Windows.

You can download a zip file containing IronMeta binaries at the SourceForge site.

Programming with IronMeta

In order to use IronMeta, run IronMeta.exe on your IronMeta file.

In order to use an IronMeta-generated parser in your C# program, do the following:

• Compile the C# file. If your parser is named Foo, the generated class will be named Foo.FooMatcher.
• Create an object of type Foo.FooMatcher.
• If you wish to use the parser as a fully-backtracking recursive-descent parser, set the Matcher<TInput,TResult>.StrictPEG property to false.
• Create an IEnumerable<TInput> with your input data.
• Call the function Matcher<TInput,TResult>.Match() or Matcher<TInput,TResult>.AllMatches(), with your input stream and the name of the top-level rule you wish to use. These return an object (or IEnumerable) of type Matcher<TInput,TResult>.MatchResult, which contains information about the possible results.

Note:

If your parser is using the default strict PEG mode, there will only be one result. If you have turned off strict PEG mode, there may be more than one possible parse, in which case you will need to call AllMatches() to access all the possibilities. Note that if you are timing the program, parsing is deferred until you read each match from the enumerable.

Reporting Bugs

If you come across a bug in IronMeta, please fill out a bug report at the SourceForge bug tracker.

Contributing to IronMeta

In order to build IronMeta, you must download the source code using a Subversion client. The following branches are available:

• Version 1.4: this branch contains the latest stable release of IronMeta:

   https://ironmeta.svn.sourceforge.net/svnroot/ironmeta/tags/1.4 
  

• HEAD: Check out this branch to get the very latest code. This branch is where new development takes place. Note that code in this branch may not always work correctly!

   https://ironmeta.svn.sourceforge.net/svnroot/ironmeta/trunk 
  

The top folder of the source code contains a Visual Studio 2008 solution file called IronMeta.sln. This includes three projects:

• IronMeta.Matcher: a library that contains the main packrat parsing functionality.
• IronMeta: the main IronMeta program.
• Calc: an example of the usual calculator program, made purposely more complicated so as to demonstrate some of IronMeta's advanced features.

Please send patches to the project admin listed at the SourceForge website or the IronMeta Development list, also available from SourceForge.