source: SHX/trunk/src/SeismicHandler/core/parser.py @ 233

# -*- coding: utf-8 -*-

#    This file is part of Seismic Handler eXtended (SHX).
#
#    SHX is free software: you can redistribute it and/or modify
#    it under the terms of the GNU Lesser General Public License as published
#    by the Free Software Foundation, either version 3 of the License, or
#    (at your option) any later version.
#
#    SHX is distributed in the hope that it will be useful,
#    but WITHOUT ANY WARRANTY; without even the implied warranty of
#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#    GNU Lesser General Public License for more details.
#
#    You should have received a copy of the GNU Lesser General Public License
#    along with SHX.  If not, see <http://www.gnu.org/licenses/>.

"""
These classes cover the processing of SH scripting language.

- "script" processes a stream (open file, stringIO, ...) of commands
- "parse" parses one command
- "translate" manages variable substitution
- "symbol" cares for local and global symbols

It's intended to be compatible with the original C code SH. Please file a ticket
at http://www.seismic-handler.org/ if there's something wrong or missing.
"""

import re
import inspect
from SeismicHandler.core import Settings, Logging
import SeismicHandler.commands as commands

class parse(object):
    """
    Parse SH scripting language.

    After successful parsing these attributes are set:
    - input (original input),
    - input_conv (maybe changed to upper case, depends on global setting),
    - parameter
    - qualifier
    - suspectedFilename (unix filenames contain slashes, it just a guess)

    These values can be also accessed via:
    - class attribute "parsed" (dictionary)
    - class attribute with "shx_" prefix (e.g. shx_input)

    The parser analyses the command string:
    >>> cmd = 'COMMAND /SWITCH1 PARAMETER1 /SWITCH2=4 PARAMETER2'
    >>> x = parse(cmd).parsed

    The parsed command name is always lower case. It's used for comparision with
    the "provides" attribute of the command classes.
    >>> x["shx_command"]
    'command'

    Switches may occur at any position, but are commonly placed following the
    command name:
    >>> sorted(x["shx_qualifiers"].keys())
    ['SWITCH1', 'SWITCH2']
    >>> x["shx_qualifiers"]["SWITCH1"]
    True
    >>> x["shx_qualifiers"]["SWITCH2"]
    '4'

    Parameter are returned as list in the order of occurrence:
    >>> x["shx_parameter"]
    ['PARAMETER1', 'PARAMETER2']

    One new feature is that the algorithm guesses a file name (slashes normally
    indicate qualifiers). This only works, if the switches follow directly after
    the command name!
    >>> cmd = 'DELAY+SUM/BLA/FOO=1 BAR /tmp/test /SW FOO'
    >>> x = parse(cmd).parsed
    >>> x["shx_parameter"]
    ['BAR', 'FOO']
    >>> x["shx_qualifiers"]["FOO"]
    '1'

    Please note that the "suspected" file name is also present as switch:
    >>> sorted(x["shx_qualifiers"].keys())
    ['BLA', 'FOO', 'SW', 'TEST', 'TMP']
    >>> x["shx_suspectedFilename"]
    '/TMP/TEST'

    If more than one "possible filename is given, only the first one is
    recognized. All following are only processed as qualifiers.
    >>> x = parse('COMMAND /tmp/x /tmp/y').parsed
    >>> x["shx_suspectedFilename"]
    '/TMP/X'

    The semicolon is an alternative separator that is mostly used to skip
    parameters:
    >>> x = parse("ECHO;;2 3 4 ;; 6 7").parsed
    >>> x["shx_parameter"]
    ['', '2', '3', '4', '', '6', '7']

    >>> x = parse('ECHO;;;;foo;bar;;').parsed
    >>> x["shx_parameter"]
    ['', '', '', 'FOO', 'BAR', '']
    """

    # regular expressions for parsing
    re_cmd = "[+\w]+"
    re_qual = "/[\w=]+"
    re_file = " (/\w+)+ ?"

    def __init__(self, input):
        self.input = input

        converted = False
        if Settings.swCapconv:
            # If a command starts with @, no conversion to upper case is
            # performed but the indicator char is removed.
            if input.startswith("@"):
                input = input[1:]
            else:
                input = input.upper()
                converted = True

        c = re.compile(self.re_cmd)
        q = re.compile(self.re_qual)
        f = re.compile(self.re_file)

        cmd = c.search(input).group(0)
        qual = q.findall(input)

        # guess file
        try:
            sfile = f.search(input).group(0).strip()
        except:
            sfile = None

        qualifiers = {}
        # remove cmd and qualifiers from string
        cmd_par = input.replace(cmd, "")
        for qq in qual:
            cmd_par = cmd_par.replace(qq, "")

            # build dict of qualifiers
            i = qq.split("=")
            if len(i) > 1:
                qualifiers[i[0][1:]] = i[1]
            else:
                qualifiers[i[0][1:]] = True

        par = cmd_par.split()

        # check for semicolon placeholders
        parameter = []
        for j in par:
            if ";" in j:
                j = j.split(";")

                # correct leading and trailing
                if j[:2] == ['','']:
                    j = j[1:]
                if j[-2:] == ['','']:
                    j = j[:-1]

                parameter.extend(j)
            else:
                parameter.append(j)

        self.__parsed = {
                "shx_input": self.input,
                "shx_input_conv": input,
                "shx_command": cmd.lower(), # command always in lower case
                "shx_converted": converted, # indicates cap conversion
                "shx_parameter": parameter,
                "shx_qualifiers": qualifiers,
                "shx_suspectedFilename": sfile,
        }

    def __getattr__(self, name):
        if name.startswith("shx_"):
            return self.__parsed[name]

        if "shx_%s" % name in self.__parsed.keys():
            return self.__parsed["shx_%s" % name]

        if name == "parsed":
            return self.__parsed

        try:
            return self.__dict__[name]
        except KeyError:
            raise AttributeError(name)

class script(object):
    """
    Read commands from stream.

    GOTO targets are cached and removed from stream so that any GOTO command
    must be handled inside this class.

    Also the IF condition is evaluated here.

    All other commands are promoted to their handler or treated as new script.

    For testing purposes we use a stream and fill it with commands. Also a
    symbol set is needed. To echo the commands, the global "Echo" switch must
    be turned on.
    >>> from StringIO import StringIO
    >>> strm = StringIO("echo line1\\necho line2\\n")
    >>> symb = symbol()
    >>> Settings.swEcho = True
    >>> x = script(strm, symb)
    >>> x.run()
    echo line1
    echo line2

    It's possible to add more commands at runtime. The script will continue
    there.
    >>> x.feed(StringIO("echo line3\\n"))
    >>> x.run()
    echo line3
    """

    def __init__(self, input, symbols, parameters=None):
        """
        Read in stream, skip empty lines and comments. Remember GOTO targets.

        Input parameters are:
        - stream object having readline function
        - symbol class instance (containing global and local variables
        """

        self.content = []
        self.targets = {}

        self.pointer = 0
        self.symbols = symbols

        # If a script is initially called there might be parameters and
        # also qualifiers.
        if parameters:
            self.parameters = translate(parameters, self)

        try:
            if hasattr(input, "read"):
                stream = input
            elif type(input) == str:
                stream = open("input", "r")
            _ = stream
        except:
            # cannot open
            raise Exception("Input not readable!")

        # Cache self-handled commands. These methods begin with "command".
        commands = []
        for i in inspect.getmembers(self, lambda x: inspect.ismethod(x)):
            if i[0].startswith("command"):
                commands.append(i[0][7:].lower())

        self.commands = commands

        self.feed(stream)

    def feed(self, stream):
        """
        Method for populating command list.

        This method can be run several times in order to run commands from
        interactive input. The local symbol set is hereby not changed.

        Execution of commands will automatically continue after the last
        command.

        So it's no possible to use loops also in interactive scripts. But be
        warned: It's not easy to get a proper exit GOTO target!
        """

        content = self.content
        targets = self.targets
        skipped = 0

        for line, cmdstr in enumerate(stream):
            cmdstr = cmdstr.strip()

            # skip empty lines or comments
            if len(cmdstr) and cmdstr[0] not in "!#-":
                # remember goto target line?
                if cmdstr.split()[0][-1] == ":":
                    targets[cmdstr.upper()] = line - skipped

                content.append(cmdstr)
            else:
                skipped += 1

        self.content = content
        self.targets = targets

    def run(self):
        while True:
            try:
                cmd = self.next()

                if Settings.swEcho:
                    print cmd

                cmd = parse(cmd).parsed

                # Execute command...
                if cmd["shx_command"] in commands.list:
                    # translate variables
                    _ = translate(cmd, self)

                    if Settings.swVerify:
                        print cmd["shx_translated"]
                    
                    # also supply recent symbolset
                    commands.list[cmd["shx_command"]](shx_symbols=self.symbols, \
                                 *cmd["shx_parameter"], **cmd["shx_qualifiers"])

                # .. or start script.
                else:
                    symb = symbol()
                    try:
                        ns = script(cmd["shx_command"], symb, parameters=cmd)
                        ns.run()
                    except Exception, e:
                        msg = "Cannot run script '%s'!" % cmd["shx_command"]

                        # Respect global settings:
                        if Settings.swSherrstop:
                            import sys
                            print >> sys.stderr, msg
                            quit()

                        if Settings.swCmderrstop:
                            raise Exception(msg)

                        if not Settings.swNoerrmsg:
                            import warnings
                            warnings.warn(msg)

            except StopIteration:
                break

    def next(self):
        """
        Iterate over commands.
        """

        try:
            # skip goto targets
            while self.pointer in self.targets.values():
                self.pointer += 1

            pnt = self.pointer
            self.pointer += 1

            return self.content[pnt]
        except IndexError:
            # lower pointer
            self.pointer -= 1
            raise StopIteration

    def commandGoto(self, target):
        try:
            self.pointer = self.targets[target.upper()]
        except KeyError:
            raise NameError(target.upper())

    def commandIf(self, cmd):
        pass

    def IfGoto(self, cmd):
        # cast format
        cast = {
                "S": str,
                "I": int,
                "R": float
                }

        cmp, check = cmd.p[2].value, cmd.p[2].value[:2]

        var1 = cast[cmp[-1]](cmd.p[1].value)
        var2 = cast[cmp[-1]](cmd.p[3].value)

        # comparison
        try:
            comp = {
                    "EQ": var1.__eq__,
                    "NE": var1.__ne__,
                    "GT": var1.__gt__,
                    "GE": var1.__ge__,
                    "LT": var1.__lt__,
                    "LE": var1.__le__,
                    }
        except AttributeError:
            # in python 2.5 integers have no __eq__, __gt__, ... methods :(
            comp = {
                    "EQ": lambda x: var1 == x,
                    "NE": lambda x: var1 != x,
                    "GT": lambda x: var1 > x,
                    "GE": lambda x: var1 >= x,
                    "LT": lambda x: var1 < x,
                    "LE": lambda x: var1 <= x,
                    }

        # check condition
        if comp[check](var2):
            self.Goto(cmd.p[5].value)

class translate(object):
    """
    Translate variables in command. If a script class is used as second
    parameter, it's symbol set will be used (e.g. for global symbols).

    There are five basic types of variables:
    1. user-defined symbols start with a quote: "foo
    2. system variables start with a dollar sign: $DSPTRCS
    3. trace variables start with a caret: ^delta(3)
    4. passed options to command procedures start with a hash: #1
    5. data from file access start with a percent: %filename(1)

    After translation all parameter and qualifiers are replaced.
    
    If the global option "Verify" is set the translated command string is saved
    into "shx_translated". This string is rebuild from the translated parts,
    so qualifiers may appear not in original order.

    In order to test this class, we define a dummy command object.
    >>> Settings.swVerify = True
    >>> cmd = {
    ...    'shx_command': 'echo',
    ...    'shx_converted': True,
    ...    'shx_parameter': ['$PI', '$EXCLAMATION'],
    ...    'shx_qualifiers': {'FOO': '$DOLLAR', 'BAR': True},
    ... }
    >>> _ = translate(cmd)
    >>> cmd['shx_translated']
    'ECHO 3.1415926535897931 ! /FOO=$ /BAR'
    """

    system = {
        "DOLLAR": "$",
        "PI": "3.1415926535897931",
        "SLASH": "/",
        "HAT": "^",
        "EXCLAMATION": "!",

        # XXX todo
        "DSPTRCS": lambda: None,
        "TOTTRCS": lambda: None,
    }

    def __init__(self, cmd, script=None):
        self.script = script
        
        # translate parameters
        for i, p in enumerate(cmd["shx_parameter"]):
            if p[0] not in '"$^#%':
                continue

            id = p[0]
            # system
            if id == "$":
                cmd["shx_parameter"][i] = self.handleSystem(p[1:])
            # symbols
            elif id == '"':
                cmd["shx_parameter"][i] = self.handleSymbol(p[1:])
            # trace XXX
            elif id == '^':
                cmd["shx_parameter"][i] = self.handleTrace(p[1:])
            # options at startup XXX
            elif id == '#':
                cmd["shx_parameter"][i] = self.handleOption(p[1:])
            # file XXX
            elif id == '%':
                cmd["shx_parameter"][i] = self.handleFile(p[1:])

        # translate qualifiers
        for q in cmd["shx_qualifiers"]:
            p = cmd["shx_qualifiers"][q]

            # Skip qualifiers that act as switches.
            if type(p) == bool:
                continue

            id = p[0]

            if id == "$":
                cmd["shx_qualifiers"][q] = self.handleSystem(p[1:])
            elif id == '"':
                cmd["shx_qualifiers"][q] = self.handleSymbol(p[1:])
            elif id == '^':
                cmd["shx_qualifiers"][q] = self.handleTrace(p[1:])
            elif id == '#':
                cmd["shx_qualifiers"][q] = self.handleOption(p[1:])
            elif id == '%':
                cmd["shx_qualifiers"][q] = self.handleFile(p[1:])

        # Actually this is only for debugging purposes.
        if not Settings.swVerify:
            return
        
        qual = []
        for q in cmd["shx_qualifiers"]:
            if type(cmd["shx_qualifiers"][q]) == bool:
                qual.append(q)
            else:
                qual.append("%s=%s" % (q, cmd["shx_qualifiers"][q]))
            
        cmd["shx_translated"] = " ".join([
            cmd["shx_converted"] and cmd["shx_command"].upper() or cmd["shx_command"],
            " ".join(cmd["shx_parameter"]),
            len(qual) and "/" + " /".join(qual) or "",
        ])

    def handleSystem(self, name):
        try:
            x = self.system[name.upper()]
        except KeyError:
            raise NameError("System variable '%s' not found!" % name)

        if callable(x):
            return x()
        else:
            return x

    def handleSymbol(self, name):
        try:
            return getattr(self.script.symbols, name)
        except:
            raise NameError("Symbol '%s' not found!" % name)

    def handleTrace(self, name):
        raise NotImplementedError

    def handleOption(self, name):
        raise NotImplementedError

    def handleFile(self, name):
        raise NotImplementedError

class symbol(object):
    """
    This class holds locals symbols. Access to global symbols is granted.

    Important note: All symbol names are converted into upper case!

    >>> s = symbol()
    >>> s.foo = 1
    >>> s.foo
    1
    >>> s.setGlobal("bar", "qux")
    >>> s.bar
    'qux'

    Local symbols mask global ones! This can be undone by deleting the symbol.
    >>> s.bar = 5
    >>> s.bar
    5
    >>> del s.bar
    >>> s.bar
    'qux'

    If no local symbol exists, the global one will be removed.
    >>> del s.bar
    >>> s.bar #doctest: +ELLIPSIS
    Traceback (most recent call last):
    ...
    Exception: Symbol BAR not found!

    If one wants to delete a global symbol but keep the local symbol:
    >>> s.setGlobal("bar", "global")
    >>> s.bar
    'global'
    >>> s.bar = "local"
    >>> s.deleteGlobal("bar")
    >>> s.bar
    'local'
    """

    def __init__(self):
        self.__dict__["__globals"] = Settings.Globals

    def __getattr__(self, name):
        name = name.upper()
        try:
            return self.__dict__[name]
        except KeyError:
            pass

        try:
            return self.__dict__["__globals"][name]
        except KeyError:
            pass

        raise Exception("Symbol %s not found!" % name)

    def __setattr__(self, name, value=None):
        name = name.upper()

        self.__dict__[name] = value

    def __delattr__(self, name):
        name = name.upper()

        # delete local symbol
        try:
            del self.__dict__[name]
        except KeyError:
            pass
        else:
            return

        try:
            del self.__dict__["__globals"][name]
        except KeyError:
            pass
        else:
            return

        raise Exception("Symbol %s not found!" % name)

    def setGlobal(self, name, value=None):
        name = name.upper()

        self.__dict__["__globals"][name] = value

    def deleteGlobal(self, name):
        name = name.upper()

        del self.__dict__["__globals"][name]

if __name__ == "__main__":
    import doctest
    doctest.testmod(exclude_empty=True)