SWAG >> LSEdit

Bash2Py

Introduction

Bash2py is a Bash to Python script translator, implemented by modifying the bash 4.3.30 open-source C code, so that instead of executing bash commands,the modified tool simply emits (to the extent currently possible) the commands seen as equivalent Python statements.

Output may be either directly to a resulting python script (having the same name as the input bash script with a subsequent ".py extension), or to an html page (having the extension .html) that provides a side by side comparison of the input Bash commands and comments, and the corresponding output.

Bash2py is a high level script that permits multiple scripts under a given directory structure to be translated. Bash2pyengine is the actual tool, which when presented with a single Bash script emits the appropriate output.

Because Bash2py uses the same mechanisms for reading bash scripts as bash, it should produce the same syntactic error messages when illegal bash code is encountered.

Documentation

A rough attempt to document the intricacies of this program has been accomplished by appropriately annotating and modifying the Bash Reference Manual producing a corresponding Bash2py Reference Manual. Language constructs highlighted are green is believed to be largely converted correctly; those in orange not necessarily well supported; and those in red not yet addressed. Text in purple provides additional commentary. The definitive description of how this program performs translation can be derived from an examination of translate.c which performs high command and control structure translation, fix_string.c which makes a valiant attempt to translate the contents of commands to equivalent python instructions, and expr.c which has been heavily hacked to perform the translation of arithmetic expressions.

The paper describing this tool can be found here.

Examples

See the following examples of the output of bash2py when presented with a variety of open source bash scripts. See also the packaged test files under the directory tests and in particular tests/manual which test the behaviour of Bash2py on the various language constructs described in the Bash manual.

Video

.

If you cannot see this video you may be using a browser that does not recognise the MOV video format. If using alternative browsers does not resolve this problem, please download bash2py_demo.mov explicitly and view this video on your own machine using an appropriate viewer.

Download

The source for this software can be obtained from here. This source code is distributed under the same licensing constraints as imposed on the original Bash source.

Synopsis

bash2py [-h] [-f|-d] <filename>

bash/bash2pyengine [--html] <bashscript>

Options

-hGenerate comparative html output rather than python
-fThe filename is a regular file containing bash code
-dThe named directory should be scanned recursively for bash code

If neither -f or -d is specified the named script or directory is examined to determine its type and thus to infer the action to be performed.

Implementation

The bash2py program was developed by heavily hacking the open source code distribution for bash-4.3.30. It is built by using ./configure command provided with the Bash distribution, which has been modified to emit the BASH2PY preprocessor variable to the config.h, and then making this distribution. All modified code within the distribution is enabled as consequence of defining globally this single preprocessor variable. If this variable is not defined and a clean build then performed the original bash code will instead be compiled. This should make it trivial to identify all added, changed and omitted code.

Serious users of this tool are invited to further refine it so as to better meet their own translation requirements, be that to Python or some other scripting language.

Caveats

Almost all of the original bash code currently remains within bash2py, even though it is never called. Future work will remove this redundant logic from bash2py.

Any errors in bash, are are likely to be propagated unchanged into bash2py. Further, many of the subtle advanced capabilities available within Bash will not be translated correctly into Python. Our goal is to translate the majority of simple Bash constructs correctly; not to provide a translator capable of converting any arbitrary Bash logic into semantically equivalent Python logic.

Bash2py uses the bash parser to produce an initial abstract syntax tree which is then translated to python. High level command constructs are inferred from this tree, while low level string and variable translation is achieved by exploiting newly implemented code.

It is stressed that this translator is intended only to do the lion share of the translation effort. The output of this translator will be far for from perfect and will need to subsequently be hand massaged.

We assume no responsibility for the use made of this tool, and provide no assurance that this tool will produce syntactically and semantically correct Python output even when presented with correct bash input. For almost all input scripts it will not.

It is recommended that pylint be used to validate the syntactic correctness of any python script, prior to testing it. It is further recommended that the output of this program be checked very carefully for errors before any trust be placed in this output.

Credits

bash2py was designed and written by Ian J. Davis, who has retired. It is unsupported software.