FoxySheep 1.2.3
Mathematica parser and translator

.. image:: https://travis-ci.org/rocky/FoxySheep2.svg?branch=master
    :target: https://travis-ci.org/rocky/FoxySheep2

This is the Robert Jacobson's Python implementation of the FoxySheep parser and lexer for Mathematica. It has been stripped down and reorganized a bit.

Examples
--------

When installed, the command-line translator is called ``foxy-sheep``
which can convert `Mathematica InputForm
<https://reference.wolfram.com/language/ref/InputForm.html>`_ to
`Mathematica FullForm
<https://reference.wolfram.com/language/ref/FullForm.html>`_ without
having Mathematica installed: To run the code interactively:

::

   $ foxy-sheep
   Enter a Mathematica expression. Enter either an empty line, Ctrl-C, or Ctrl-D to exit.
   In[1]:= 1+2
   Plus[1,2]
   In[1]:=D[4 x^2]
   D[Times[4,Power[x,2]]]
   In[1]:=
   $

The first few examples from `Fast Introduction for Math Students <https://www.wolfram.com/language/fast-introduction-for-math-students/en/entering-input/>`_

::

   foxy-sheep -o python
   Enter a Mathematica expression. Enter either an empty line, Ctrl-C, or Ctrl-D to exit.
   In[1]:= 2 + 2
   (2 + 2)

   Out[1]=4
   In[2]:= 1 + 2 + 3
   (1 + 2 + 3)

   Out[2]=6
   In[3]:= % + 4
   (Out() + 4)

   Out[3]=10
   In[4]:= 5 + 2 * 3 - 7.5
   (5 + 2 * 3 -
   decimal.Decimal(7.5))

   In[5]:= ((5 - 3) ^ (1 + 2))/ 4
   ((5 - 3) ** (1 + 2) / 4)

   Out[5]=2.0
   In[6]:= GCD[12,15]
   math.gcd(12, 15)

   Out[6]=3
   In[7]:= {1, 2, 3}
   [1, 2, 3]

   Out[7]=[1, 2, 3]


To call from Python:

.. code:: python

   from FoxySheep import if2ff, if2python
   print(if2ff("x^2-3x+4")
   # Prints: Plus[Power[x,2],Times[-1,3,x],4]
   print(if2ff("x^2-3x+4")
   # Prints (x ** 2 + -1 * 3)


For more demos run ``foxy-sheep --file pytest/parse_expressions/SO1.m`` or with other
Mathamatica files in ``pytest/parse_expressions``.

For help on ``foxy-sheep``, run ``foxy-sheep --help``.


Conversion to Python
--------------------

A very crude translator to Python has been started. While there are
still a lot of details to be filled out, some of the basics are there.

Here are some examples:

::

   167.5 -> decimal.Decimal(167.5)
   15^^8 -> int(15, 8)
   132`  -> (132)
   1 / 10 3 -> (1 / 10 * 3)
   x^2 + y^2 -> (x ** 2 + y ** 2)
   GCD[12, 15] -> math.gcd(12, 15)
   Range[10] -> range(10)
   {a, b, c, d}[[3]] -> [a, b, c, d][2]  # Handles 0-1 conversion
   {a, b, c, d, e, f}[[2 ;; 4]] -> [a, b, c, d, e, f][1:3] # ditto

Conversion to Python is done via transforming "InputForm" input to an
"OutputForm" parse tree, and then using that to convert to a Python AST.
Finally a Python module, `astor <https://pypi.org/project/astor/>`_, is used to dump this to text.

Why do we go through this more complicated for translating one string to another?

By keeping the structure as an AST we can contemplate more powerful
transformations and make use of routines that exist for working with Python AST's.

For example, translating `{1,2,3} + 2` into Python, while not handled now, can
be done by looking at the types of the operands of plus, and noticing one is a scalar
while the other is a list.


Regenerating the lexer/parser
-----------------------------

To change the grammar you'll need the ANTLR Parser Generator
(``antlr4``), version 4.7.x installed.

To (re)generate the lexer/parser you need to

::

   $ make


The resulting files are placed in ``FoxySheep/generated``.

Files generated by ANTLR4 are assumed to be in a subdirectory called ``generated`` containing an empty ``__init__.py`` file. See the Makefile for details.

FoxySheepLexer Must Subclass Lexer
++++++++++++++++++++++++++++++++++

In order for the generated antlr4 lexer to work we need to patch the generated Python lexer ``FoxySheep.lexer.py``; The patch file ``FoxySheep.lexer.py.patch`` does this.
The Makefile target for ``FoxySheepParser.py`` contains the ``patch`` command.

If patching is not done you'll get an ``AttributeError`` exception in the lexer you try to run it such as through ``foxy-sheep``.

::

   AttributeError: 'FoxySheepLexer' object has no attribute 'checkAdditiveOp'


See Also
--------

`FoxySheep <https://github.com/rljacobson/FoxySheep>`_