
"""
==========================
Mel To Python Translator
==========================

Convert mel scripts into python scripts.


Known Limitations
=================

array index assignment
----------------------

In mel, you can directly assign the value of any element in an array, and all intermediate elements will be
automatically filled. This is not the case in python: if the list index is out of range an IndexError will be
raised. I've added fixes for several common array assignment conventions:

append new element
~~~~~~~~~~~~~~~~~~

**MEL**

.. python::

    string $strArray[];
    $strArray[`size $strArray`] = "foo";

Python

>>> strArray = []                #doctest: +SKIP
>>> strArray.append("foo")       #doctest: +SKIP

assignment relative to end of array
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**MEL**

.. python::

    strArray[`size $strArray`-3] = "foo";

Python

>>> strArray[-3] = "foo"        #doctest: +SKIP

However, since the translator does not track values of variables, it does not know if any given index is out of
range or not. so, the following would raise a 'list assignment index out of range' error when converted to
python and would need to be manually fixed:

.. python::

    string $strArray[];
    for ($i=0; $i<5; $i++)
        $strArray[$i] = "foo"


for(init; condition; update)
----------------------------

    the closest equivalent to this in python is something akin to:

        >>> for i in range(start, end):    #doctest: +SKIP

    in order for this type of for loop to be translated into a python for loop it must meet several requirements:

        1. the initialization, condition, and update expressions must not be empty.

            not translatable:

            .. python::

                  for(; ; $i++) print $i;

        2. there can be only one conditional expression.

            not translatable:

            .. python::

                  for($i=0; $i<10, $j<20; $i++) print $i;

        3. the variable which is being updated and tested in the condition (aka, the iterator) must exist alone on one