I am grateful to Rocky Bernstein for breathing new life into FoxySheep in the form of a Python package. FoxySheep continues to evolve with Rocky's help at its new home on GitHub. This repository, the original, has suffered a little bit rot, but it feels right to leave it here as it is in case someone is interested in the Java target or has a use for it in its current state, prior to its evolution under a more focused vision.
Sincerely,
Robert Jacobson
FoxySheep is a collection of compiler technologies for Wolfram Language*. In particular, FoxySheep...
- is an ANTLR4 lexer and parser grammar for Wolfram Language.
- is a Wolfram Language expression to FullForm expression translator. In other words, the FoxySheep parser has a visitor for the parse tree it produces that emits the FullForm of the parsed expression. The FullForm of an expression is a functionally equivalent form of the expression in a lisp-like expression format (
Head[arg1, arg2, ...]). Thus FullForm is very easy to parse. - includes a trimmed down lexer/parse for parsing FullForm expressions. Both Java and Python target languages are supported. Users can use Mathematica itself or some other Wolfram Language parser to produce a FullForm expression and then use FoxySheep's FullForm parser to read the result into their own programs.
- (Planned) is a FullForm to Python translator.
If you are here looking for a Wolfram Language parser for your project, jump down to Similar Projects.
*In this document, Wolfram Language refers to the programming language used in Mathematica (and some other Wolfram Research products), and Mathematica refers to the computer algebra system (or its kernel) produced by Wolfram the company. FoxySheep and its author(s) are not affiliated with Wolfram.
For the Wolfram Language parser, I wanted something that is both fully functional and easy for students to understand, use in their own projects, modify, and contribute to. ANTLR4 is the perfect choice to achieve these goals. ANTLR4 produces parsers for Java, C#, Python 2&3, JavaScript, Go, C++, and Swift. The FoxySheep ANTLR4 grammars are language agnostic while the FullForm emitter comes in both Java and Python flavors. It would be easy to add support for another language.
For the Wolfram Language to Python translator, the goal is to be useful. My standard for usefulness is, it is sufficiently functional and easy to use that people, students especially, would want to use it to write simple programs in a Jupyter or Sage notebook.
Finally, for FoxySheep as a whole, my goal is that the project is helpful for students who are learning about compiler construction or Wolfram Language and helpful for me to learn how to teach those topics.
You can use it to...
- write a pretty printer for Wolfram Language code.
- write a Wolfram Language code rewriter that inputs code written using nasty language constructs and outputs the same program but using saner notation. (Ever try to read someone else's crazy Wolfram Language code?)
- add support for Wolfram Language to your favorite open source computer algebra system to make a Mathematica clone.
FoxySheep doesn't...
- Execute Wolfram Language code
- Interact with Mathematica
But nothing is stopping you from using FoxySheep in your own project to do the above!
This section is incomplete.
You will need ANTLR4 installed and available in your path. To check this, check that you can run antlr4 in a terminal.
You will need the ANTLR4 Python runtime somewhere in your site-packages. To check this, run python -c "import antlr4" in a terminal and make sure you don't get an ImportError.
To generate the Python target:
cd python_target
makeFoxySheep is in heavy development.
The FoxySheep parser has complete coverage of non-box-related language features, and sketchy untested coverage of box-related features. While it is a goal of the project, FoxySheep does not always have identical behavior to Mathematica for the language constructs that it implements.
The FoxySheep translator is not yet functional.
The table below summarizes the status of planned features of Phase 1.
| Feature | Status | Comments |
|---|---|---|
| Parses major language constructs | complete | |
| Parses box-related constructs | started | Low priority. |
| Java target | complete | Target language dependent components of the parser written in java. |
| Python target | complete | Target language dependent components of the parser written in python. |
| FullForm emitter (java) | complete | |
| FullForm emitter (python) | complete | |
| Develop test suite | not started | |
| Translator to another HIL | started | This is Phase 2 of development. See doc/TranslateToPythonNotes.md |
The table below summarizes the status of planned features of Phase 2. See Notes on Wolfram Language to Python Translation and the Translator Roadmap for the most up-to-date status information.
| Feature | Status | Comments |
|---|---|---|
| Skeleton of AST node types and construction | started | |
| Passes: Create Scopes and Verify Argument Patterns | not started | |
| Identify math expressions. | not started | |
| Transformations: Flatten, Thread Listables, Unwrap Iterated Functions | not started | |
| Passes: Convert [For | Do | NestWhile | FixedPoint | etc.] to While | not started | |
| Pass: Check Types | not started | |
| Python Emitter | not started | |
| AST-based FullForm Emitter | not started |
See CONTRIBUTING.md.
Here's what the open source Wolfram Language parser landscape looks like:
- FoxySheep! A relatively complete, easy to understand, easy to hack parser and FullForm emitter. And in the future, the only Wolfram Language translator to Python/Sage.
- Mathematica IntelliJ Plugin. If you want a mature, well-tested Wolfram Language parser for your project and aren't concerned with the issues described under "Motivation and Goals" above, this parser is probably your best choice. This isn't just a syntax highlighter, it's a complete, mature Wolfram Language parser capable of emitting FullForm and doing various code analysis. The parser is a beautiful example of a Pratt parser, a top down operator precedence parsing strategy first described by Vaughan Pratt in the 70s.
- Mathics: A free, light-weight alternative to Mathematica created by Jan Pöschko. A Mathematica clone written in Python, Mathics includes a complete parser, FullForm emitter, and evaluator.
- Mateusz Paprocki's Mathematica Parser in Scala: "A library for parsing Mathematica's programming language written in Scala. It uses parser combinators and packrat parsers from Scala's standard library. Currently only a subset of Mathematica's language is supported."
- MockMMA: By Richard Fateman written in Lisp. This one's an old classic and of historical interest.
- basicCAS: By Alex Gittens, a python Mathematica parser. It appears to have disappeared from the author's website, but it's still available elsewhere on the net for those interested in looking for it. This project is interesting because it includes Alex's notes regarding implementation.
- omath is similar in spirit to Mathics but is written in Java/Scala and appears to have had a 7 year hiatus from 2005 to 2012. The original parser "is mostly written by Yossi Farjoun, with some help from Scott Morrison" and is a generated parser using JavaCC and JJTree. There seems to be a newer parser written in Scala. The source code is distributed without a license. The historical repository lives at http://svn.omath.org/.
- Symja-parser is the Mathematica parser for Symja - Java Computer Algebra Library, "a general purpose Java library for symbolic mathematics" by Axel Kramer. Symja contains a Mathematica parser for a reasonable subset of Mathematica.
Author(s): Robert Jacobson
License: BSD license. See the file LICENSE.txt for details.