source: SHX/trunk/SeismicHandler/modules/parse.py @ 530

# -*- 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 os
import re
import inspect
import traceback
from copy import copy
import SeismicHandler.commands as commands
from SeismicHandler.basics import AttribDict
from SeismicHandler.basics.error import ShxError
from SeismicHandler.config import Settings
from SeismicHandler.basics.messages import logMessage, msgs
from SeismicHandler.core import Traces, Hidden


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_string, switches=None):
        if switches is None:
            switches = Switches()

        self.switches = switches
        # treat everything after ! as comment
        input_string = input_string.split("!")[0]
        self.input = input_string

        converted = False
        if self.switches.Capcnv:
            # If a command starts with @, no conversion to upper case is
            # performed but the indicator char is removed.
            if input_string.startswith("@"):
                input_string = input_string[1:]
            else:
                input_string = input_string.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_string).group(0)
        qual = q.findall(input_string)

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

        qualifiers = {}
        # remove cmd and qualifiers from string
        cmd_par = input_string.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_string,
            "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):
        try:
            p = object.__getattribute__(self, "_parsed")

            if name.startswith("shx_"):
                return p[name]

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

            if name == "parsed":
                return p
        except AttributeError:
            pass

        try:
            return object.__getattribute__(self, name)
        except AttributeError:
            raise ShxError("Attribute '%s' not found!" % 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()
    >>> sw = Switches()
    >>> sw.Echo = True
    >>> x = Script(strm, symb, sw)
    >>> 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, inputdata, symbols, switches, parameters=None, **kwargs):
        """
        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
        - switches class instance
        """

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

        self.pointer = 0
        self.symbols = symbols
        self.switches = switches

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

        # current working directory
        self.searchpath = ["."]

        # additional paths
        if "searchpath" in kwargs:
            self.searchpath += kwargs["searchpath"]

        # use default search path from configuration
        self.searchpath += Settings.config.paths.scripts

        try:
            if hasattr(inputdata, "read"):
                stream = inputdata
            elif type(inputdata) == str:
                # no extension -> add default
                try:
                    _ = inputdata.index(".")
                except ValueError:
                    inputdata = inputdata + ".SHC"

                if self.switches.Capcnv:
                    inputdata = inputdata.upper()

                self.filename = inputdata

                # look for file in search path
                for folder in self.searchpath:
                    try:
                        stream = open(os.path.join(folder, inputdata), "r")
                    except IOError:
                        pass
                    else:
                        break

            _ = stream
        except:
            # cannot open
            raise ShxError("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.internal_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 traceBack(self, error, msg = ""):
        # This allows debugging as python users are used to it.
        print "\n" + "*"*72
        print self.__recent
        print "*"*72
        traceback.print_exc()
        print "*"*72
        msg = ";".join(error.args)

        # Respect global settings:
        if self.switches.Sherrstop:
            import sys
            print >> sys.stderr, error, msg
            quit()

        if self.switches.Cmderrstop:
            raise ShxError(msg)

        if not self.switches.Noerrmsg:
            logMessage("error.traceback", msg)

    def run(self):
        self.__recent = None
        while True:
            try:
                cmd = self.next()
            except StopIteration:
                break

            if self.switches.Echo:
                print cmd

            cmd = Parse(cmd, switches=self.switches).parsed

            # translate variables
            _ = Translate(cmd, self, switches=self.switches)
            self.__recent = cmd.get("shx_translated", cmd["shx_input_conv"])

            # Check for internal command ...
            if cmd["shx_command"] in self.internal_commands:
                try:
                    x = getattr(self, "command"+cmd["shx_command"].capitalize())
                    x(*cmd["shx_parameter"], **cmd["shx_qualifiers"])
                except Exception, e:
                    self.traceBack(e)

            # or execute command...
            elif cmd["shx_command"] in commands.list:
                if self.switches.Verify:
                    print cmd["shx_translated"]

                try:
                    # also supply recent symbolset
                    commands.list[cmd["shx_command"]](
                        shx_symbols=self.symbols,
                        shx_switches=self.switches,
                        *cmd["shx_parameter"],
                        **cmd["shx_qualifiers"]
                    )
                except Exception, e:
                    self.traceBack(e)

            # .. or start script.
            else:
                # use new symbols and switches set
                symb = Symbol()
                swit = Switches()
                try:
                    ns = Script(
                        cmd["shx_command"],
                        symb,
                        swit,
                        parameters=cmd,
                        searchpath=self.searchpath,
                    )
                    ns.run()
                except Exception, e:
                    msg = "Cannot run script '%s'!" % cmd["shx_command"]
                    self.traceBack(e, msg)

    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 commandReturn(self):
        # jump to end of script
        self.pointer = len(self.content)

    def commandDefault(self, *args):
        """
        Query default values.

        Since this statement manipulates script option variables, it's not done
        as command class.

        Note: No qualifiers are supported! Input is read from stdin.
        """

        # no parameters given at all -> request user input
        # set as class attribute for caching.
        try:
            self.userreq = self.userreq and True or \
                                     len(self.parameters["shx_parameter"]) == 0
        except AttributeError:
            self.userreq = len(self.parameters["shx_parameter"]) == 0

        id = int(args[0])-1
        default = args[1]

        val = None
        try:
            val = self.parameters["shx_parameter"][id]
        except IndexError:
            if self.userreq:
                # request user input
                if len(default):
                    q = " [default: %s]: " % default
                else:
                    q = " : "

                userinput = raw_input(" ".join(args[2:]) + q)
                if userinput:
                    default = userinput

        if not val:
            # fill from default
            try:
                self.parameters["shx_parameter"][id] = default
            except IndexError:
                self.parameters["shx_parameter"].append(default)

    def commandGoto(self, target):
        try:
            self.pointer = self.targets[target.upper()]
            msgs.sendMessage("command.run", cmd="goto", args=[target,])
        except KeyError:
            raise ShxError("GOTO target not found: %s" % target.upper())

    def commandQuit(self, *args):
        if not args:
            yesno = raw_input("  Leave program [yN]? ")
        else:
            yesno = args[0]

        msgs.sendMessage("command.run", cmd="quit")
        if yesno.lower() == "y":
            quit()

    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.
    >>> sw = Switches()
    >>> sw.Verify = True
    >>> cmd = {
    ...    'shx_command': 'echo',
    ...    'shx_converted': True,
    ...    'shx_parameter': ['$PI', '$EXCLAMATION'],
    ...    'shx_qualifiers': {'FOO': '$DOLLAR', 'BAR': True},
    ... }
    >>> _ = Translate(cmd, switches=sw)
    >>> cmd['shx_translated']
    'ECHO 3.1415926535897931 ! /FOO=$ /BAR'
    """

    system = {
        "BLANK": " ",
        "EXCLAMATION": "!",
        "QUOTES": '"',
        "DOLLAR": "$",
        "PERCENT": "%",
        "HAT": "^",
        "BAR": "|",
        "SLASH": "/",
        "NUMBER": "#",
        "PI": "3.1415926535897931",
        "SH_ID": lambda: "SH_%i_" % os.getpid(),
        "X": "$X", # really no idea for what this is good for...
        "DSPTRCS": "_internalvars",
        "TOTTRCS": "_internalvars",
        "STATUS": "_internalvars",

        # XXX todo
        "SYSTIME": None,
        "VERSION": None,
        "DSP_X": None,
        "DSP_Y": None,
        "DSP_W": None,
        "DSP_H": None,
        "DSP_XMAX": None,
        "DSP_YMAX": None,
        "TITLESTYLE": None,
        "TRCINFOSTYLE": None,
        "ZEROTRCSTYLE": None,
        "TIMEAXISSTYLE": None,
        "MARKSTYLE": None,
        "PMSTYLE": None,

        # special treatment necessary
        # syntax is HEXCHAR3B
        "HEXCHAR": None,
    }

    def __init__(self, cmd=None, script=None, switches=None):
        self.script = script

        if switches is None:
            switches = Switches()

        self.switches = switches

        # If no command structure is found, return silently.
        if not cmd:
            return

        # translate parameters
        for i, p in enumerate(cmd["shx_parameter"]):
            cmd["shx_parameter"][i] = self._translate(p)

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

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

            cmd["shx_qualifiers"][q] = self._translate(p)

        # Actually this is only for debugging purposes.
        if not switches.Verify:
            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 _translate(self, value):
        if not value:
            return ''

        idmap = {
            '$': self.__handleSystem,
            '"': self.__handleSymbol,
            '^': self.__handleTrace,
            '#': self.__handleOption,
            '%': self.__handleFile,
        }

        id = value[0]

        # concat operator
        if id == "|":
            parts = filter(None, value.split("|"))
            newparts = [self._translate(i) for i in parts]
            return "".join(newparts)

        # nothing to translate
        if id not in idmap.keys():
            return value

        value = value[1:]

        try:
            return idmap[id](value)
        except NotImplementedError:
            raise NotImplementedError
        except:
            raise ShxError("'%s' could not be translated!" % value)

    def __handleSystem(self, name):
        name = self._translate(name)
        try:
            x = self.system[name.upper()]
        except KeyError:
            if not name.upper()[:-2] == "HEXCHAR":
                raise ShxError("System variable '%s' not found!" % name)
            else:
                try:
                    x = chr(int(name[-2:], 16))
                except:
                    raise ShxError("Invalid hexadecimal value: %s" % name[-2:])

        if x == None:
            raise NotImplementedError

        if callable(x):
            return x()
        else:
            x = getattr(self, x, x)
            if callable(x):
                return x(name)
            else:
                return x

    def __handleSymbol(self, name):
        name = self._translate(name)
        try:
            return getattr(self.script.symbols, name)
        except:
            raise ShxError("Symbol '%s' not found!" % name)

    def __handleTrace(self, name):
        try:
            name, traceno = name.split("(")
        except:
            traceno = "1"

        name = self._translate(name)
        traceno = int(self._translate(traceno.split(")")[0]))

        if traceno < 1:
            logMessage("warning.parse", "Trace numbering starts with '1'")
            traceno = 1

        try:
            # internal counting starts from zero
            trace = Traces[traceno - 1]
        except:
            logMessage("error.parse", "Trace number %u not present" % traceno)

        try:
            res = trace._shxInfo(name)
            return res
        except NameError:
            logMessage("error.trace", "undefined info entry name '%s'" % name)

    def __handleOption(self, name):
        """
        Return parameters set on procedure call.

        Possible values:
        #0 - filename
        #1..#99 - parameter number xx
        #name - qualifier "name"
        """
        if name.isdigit():
            id = int(name)-1
            if id >= 0:
                return self.script.parameters['shx_parameter'][id]
            else:
                return self.script.filename
        else:
            name = self._translate(name)
            return self.script.parameters['shx_qualifiers'][name]

    def __handleFile(self, name):
        # split line count (if any)
        try:
            f, lineno = name.split("(")
        except ValueError:
            lineno = "1"
            f = name
        else:
            lineno = lineno[:-1]

        f = self._translate(f)
        lineno = int(self._translate(lineno))

        # if file not found, try fallback
        flist = [f, os.path.join(Settings.config.paths.globals[0], f)]

        for i, f in enumerate(flist):
            p, f = os.path.split(f)
            try:
                _ = f.index(".")
            except ValueError:
                f += ".STX"

            flist[i] = os.path.join(p, f)

        for f in flist:
            try:
                for cnt, line in enumerate(open(f, "r").readlines()):
                    if cnt + 1 == lineno:
                        return line.strip()
            except IOError:
                continue

        if lineno == 0:
            return str(cnt+1)
        else:
            raise ShxError("Line %d not found in file '%s'!" % (lineno, f))

    @staticmethod
    def _internalvars(name):
        return Settings.Runtime[name.lower()]


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):
    ...
    ShxError: 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):
        # this is a singleton
        self.__dict__["_globals"] = Settings.Globals

    def __getattr__(self, name):
        """
        This method is called only, if the requested name was not found in
        __dict__
        """
        name = name.upper()

        # local vars (but changed case)
        try:
            return self.__dict__[name]
        except KeyError:
            pass

        # next try inside globals
        try:
            return self._globals[name]
        except KeyError:
            raise ShxError("Symbol '%s' not found!" % name)

    def __setattr__(self, name, value):
        self.__dict__[name.upper()] = value

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

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

        self.deleteGlobal(name)

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

    def deleteGlobal(self, name):
        try:
            del self._globals[name.upper()]
        except KeyError:
            raise ShxError("Symbol %s not found!" % name)


class Switches(object):
    """
    This class holds Seismic Handler's switches.

    Support for global switches is present via runtime's attributes.

    >>> sw = Switches()
    >>> sw.keeptraces
    False

    Only certain switches are allowed:
    >>> sw.test #doctest: +ELLIPSIS
    Traceback (most recent call last):
    ...
    ShxError: no such switch: Test

    It's not possible to create new switches:
    >>> sw.bar = 1 #doctest: +ELLIPSIS
    Traceback (most recent call last):
    ...
    ShxError: Unsupported switch: Bar

    "on" and True indicate switch activation:
    >>> sw.keeptraces = "on"
    >>> sw.keeptraces
    True

    All other values will set switch to False:
    >>> sw.capcnv = "foo"
    >>> sw.capcnv
    False
    """

    def __init__(self):
        """
        On init global switches are used by default.
        """
        self._switches = copy(Settings._Switches)

    def __getattr__(self, name):
        if name.startswith("_"):
            return object.__getattribute__(self, name)
        else:
            name = name.capitalize()

            try:
                return object.__getattribute__(self, "_switches")[name]
            except:
                raise ShxError("no such switch: %s" % name)

    def __setattr__(self, name, value):
        """
        Only certain switches are allowed.

        "on" and True: True
        other: False
        """
        name = name.capitalize()
        if name.startswith("_"):
            object.__setattr__(self, name, value)
        elif name in self._switches.keys():
            sw = self._switches
            if value is True or (hasattr(value, "lower") and value.lower() == "on"):
                sw[name] = True
            else:
                sw[name] = False
        else:
            raise ShxError("Unsupported switch: %s" % name)

    def keys(self):
        """
        Simulate dict's keys method.
        """
        return self._switches.keys()


def getVar(name, symbolset=None, switches=None):
    """
    Helper function to translate any variable.

    name: variable to translate ($pi, "foo, ^length(1), ...
    """

    if not symbolset:
        s = Translate(switches=switches)
    else:
        x = AttribDict()
        x.symbols = symbolset
        s = Translate(None, x, switches=switches)

    return s._translate(name)


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