*Last updated: 2018-06-03 22:49:34 +0100*

Upstream URL: `git clone http://chriswarbo.net/git/reduce-equations.git`

Contents of README follows

This package provides a command <code>reduce-equations</code> which reads in a list of equations from stdin, performs some simplification, and writes the results to stdout.

For example, given the equations <code>a = b</code>, <code>b = c</code> and <code>a = c</code>, one of these will be removed as it can be inferred from the other two. Similarly, given equations <code>f a = g</code>, <code>f b = g</code> and <code>a = b</code>, one of the first equations will be removed as it can be recovered by subtitution.

All of the real work is done by QuickSpec This package just provides stdio and machine-friendly formatting.

All IO is encoded in JSON. Both stdin and stdout should contain a single array of equations. The following example gives a single equation, which if written in a more human-friendly form, would be <code>plus x x = times x 2</code>:

<pre><code>[ {"relation": "~=", "lhs": {"role": "application", "lhs": {"role": "application", "lhs": {"role": "constant", "type": "Int -> Int -> Int", "symbol": "plus"}, "rhs": {"role": "variable", "type": "Int", "id": 0}}, "rhs": {"role": "variable", "type": "Int", "id": 0}}, "rhs": {"role": "application", "lhs": {"role": "application", "lhs": {"role": "constant", "type": "Int -> Int -> Int", "symbol": "times"}, "rhs": {"role": "variable", "type": "Int", "id": 0}}, "rhs": {"role": "constant", "type": "Int", "symbol": "two"}}} ]</code></pre>An equation is an object with the following values:

<ul> <li><code>relation</code>: This is used mostly to identify that we've got an equation. In practice, this is always <code>"~="</code> (what that means is up to you).</li> <li><code>lhs</code>: this is a <code>term</code>, supposedly the left-hand-side of the equation, although the only difference from <code>rhs</code> is the name.</li> <li><code>rhs</code>: this is a <code>term</code>, just like <code>lhs</code> except it's the right-hand-side.</li> </ul>Example:

<pre><code>{"relation": "~=", "lhs": {"role": "application", "lhs": {"role": "constant", "type": "Bool -> Bool", "symbol": "not"}, "rhs": {"role": "application", "lhs": {"role": "constant", "type": "Bool -> Bool", "symbol": "not"}, "rhs": {"role": "variable", "type": "Bool", "id": 0}}}, "rhs": {"role": "variable", "type": "Bool", "id": 0}}</code></pre>A term is an object containing a <code>role</code>, which is one of <code>"constant"</code>, <code>"variable"</code> or <code>"application"</code>. The other fields depend on what the term's <code>role</code> is:

<ul> <li>Constants <ul> <li><code>type</code>: The type of the constant, a string written in Haskell's type notation. This is taken from the given function descriptions. For example <code>"Int -> (Int -> Bool) -> IO Float"</code></li> <li><code>symbol</code>: The name of the constant, as a string. For example <code>"reverse"</code>.</li> </ul></li> <li>Variables <ul> <li><code>type</code>: The type of the variable, a string written in Haskell's type notation. The types can be made up, but they should be consistent (e.g. both sides of an equation should have the same type; application should be well-typed; etc.). Unification of polymorphic types isn't supported; types are identified syntactically. For example <code>"[Int]"</code>.</li> <li><code>"id"</code>: A numeric ID for the variable. IDs start at <code>0</code>. Used to distinguish between multiple variables of the same type. Variable ID only matters within a single equation. For example, to represent three integer variables we might use <code>{"role": "variable", "type": "Int", "id":0}</code>, <code>{"role": "variable", "type": "Int", "id":1}</code> and <code>{"role": "variable", "type": "Int", "id":2}</code>.</li> </ul></li> <li>Applications <ul> <li><code>lhs</code>: A term representing a function to apply.</li> <li><code>rhs</code>: A term representing the argument to apply the <code>lhs</code> function to. Functions are curried, so calling with multiple arguments should be done via a left-leaning tree.</li> </ul></li> </ul>We co-opt the equation-reducing machinery of the QuickSpec library to do the actual reduction. This relies heavily on existential types and Haskell's Typeable mechanism.

Since the incoming equations may have arbitrary types, and GHC doesn't let us define custom <code>Typeable</code> instances, we perform a conversion step:

<ul> <li>Once an array of equations has been parsed, we recurse through the terms and switch out each distinct type with a freshly-generated replacement, of the form <code>Z</code>, <code>S Z</code>, <code>S (S Z)</code>, etc. (these are just Peano numerals, e.g. see https://en.wikipedia.org/wiki/Successor_function )</li> <li>We provide special functions <code>getRep</code> and <code>getVal</code> to plumb these Peano types into QuickSpec's machinery, convincing it that we have a signature of well-typed terms.</li> <li>We reduce the given equations, with their switched-out types, to get a reduced set.</li> <li>We switch back the types for presentation purposes, pretty-printing to JSON.</li> </ul>