IronMeta Main Page

The IronMeta parser generator 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#.

IronMeta is available under the terms of the BSD License.

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

Contributors

IronMeta 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 use strict Parsing Expression Grammar semantics; they use ordered choice, are greedy and do not backtrack through productions.
• Generated parsers are implemented as C# partial classes, allowing you to keep ancillary code in a separate file from your grammar.
• You can use anonymously-typed object literals in rules; they are matched by comparing their properties with the input objects'.
• 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 direct and indirect left recursion, using Sérgio Medeiros et al's algorithm for all rules, even within parameter matching.

Current limitations:

• Error reporting is currently quite rudimentary, only reporting 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

3.0: April 9, 2013: VS 2012 and NuGet package.

• Now set up to build with Visual Studio 2012.
• Now distributed as a NuGet package.

2.3: February 27, 2012: Combining parsers.

• Made generated code more general so it is now possible to combine parsers by inheritance or encapsulation.
• Added the ability to use anonymous object literals in rules. They match by comparing their public properties with the input object's properties.
• Fixed a bug where string and char literals were not correctly handled in parsers whose input was not of type char.

2.2: February 21, 2012: Miscellaneous bug fixes.

• Fixed an off-by-one error in input enumerables.
• Now compiles with Mono.

2.1: July 1, 2011: Much refactoring, miscellaneous bug fixes.

• Better error handling.
• Added IronMeta.Matcher.CharMatcher.Input() and IronMeta.Matcher.CharMatcher.Trimmed() for more convenient string handling.
• Added min/max repeats syntax (e.g. 'a' {1, 3}).

2.0: December 4, 2010: Many internal improvements.

• Removed general backtracking functionality in favor of strict PEG semantics only.
• Changed from Warth et al's left-recursion to Sergio Queiroz de Medeiros's much simpler and more general one.
• Massive speedup.

1.4: July 18, 2009: Bug fixes and samples.

• 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: June 2, 2009: Optimization pass.

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

1.2: June 1, 2009: 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: May 16, 2009: Initial release

Get IronMeta

IronMeta is built for .NET 4.5, and is distributed using NuGet. Open the Package Manager for a project in Visual Studio 2012 and search for IronMeta. Installing the package in your project will install the needed DLLs.

Programming with IronMeta

Once you have installed the NuGet package, add a file with the extension .ironmeta to your project. Visual Studio will automatically generate a C# grammar class for you and include it in your project. The generated parser class is declared as partial, so you can add ancillary code in another file if you wish.

In addition to the Visual Studio addin, the IronMeta executable is included in the tools directory of the NuGet package installation directory.

In order to use the IronMeta executable, run IronMeta.exe on your IronMeta file, which must have the extension .ironmeta. You can specify the following arguments to the program:

• -f Force generation even if the input file is older than the output file.
• -n <namespace> Specify the namespace to use for the generated parser (defaults to the name of the directory the input file is in).
• -o <output> Specify the output file name (defaults to <input>.g.cs

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

• Create an instance of the generated parser class.
• Call the function GetMatch() with the input you wish to parse, and the function of the generated parser class that corresponds to the top-level rule you wish to use. This returns an object of type IronMeta.Matcher.MatchResult, which contains information about the result of the match, as well as errors that might have ocurred.

The following is a small sample program that uses the Calc The IronMeta Language demo parser that is included in the distribution.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace MyCalcProject
{
    class Program
    {

        static void Main(string[] args)
        {
            var parser = new Calc();
            var match = parser.GetMatch("2 * 7", parser.Expression);

            if (match.Success)
                Console.WriteLine("result: {0}", match.Result); // should print "14"
            else
                Console.WriteLine("error: {0}", match.Error); // shouldn't happen
        }

    }
}

Support and Reporting Bugs

There is a forum for asking questions about IronMeta at SourceForge.

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

Building IronMeta from Source

In order to build IronMeta, you must download the source code using a Mercurial client:

hg clone http://hg.code.sf.net/p/ironmeta/code ironmeta

The Source folder of the source code contains a Visual Studio 2012 solution file called IronMeta.sln. This includes several projects:

• Matcher: common functionality for parsing.
• Generator: library for generating C# code from an IronMeta grammar.
• Tests : unit tests for the parsing library.
• Samples\Calc: an example of a calculator program, made purposely more complicated than necessary so as to demonstrate some of IronMeta's advanced features.

If you would like to contribute to the development of IronMeta, please send patches or pull requests to the project admin listed at the SourceForge website or the IronMeta developers forum.