# XML "function" nodes that transform their contents

import datetime

import re

import sre_constants

import warnings

import angles

import dates

import exc

import format

import maps

import sql

import strings

import term

import units

import util

import xml_dom

import xpath

##### Exceptions

class SyntaxError(exc.ExceptionWithCause):

    def __init__(self, cause):

        exc.ExceptionWithCause.__init__(self, 'Invalid XML function syntax',

            cause)

class FormatException(exc.ExceptionWithCause):

    def __init__(self, cause):

        exc.ExceptionWithCause.__init__(self, 'Invalid input value', cause)

##### Helper functions

def map_items(func, items):

    return [(name, func(value)) for name, value in items]

def cast(type_, val):

    '''Throws FormatException if can't cast'''

    try: return type_(val)

    except ValueError, e: raise FormatException(e)

def conv_items(type_, items):

    return map_items(lambda val: cast(type_, val),

        xml_dom.TextEntryOnlyIter(items))

def pop_value(items, name='value'):

    '''@param name Name of value param, or None to accept any name'''

    try: last = items.pop() # last entry contains value

    except IndexError: return None # input is empty and no actions

    if name != None and last[0] != name: return None # input is empty

    return last[1]

funcs = {}

structural_funcs = set()

##### Public functions

def is_func_name(name):

    return name.startswith('_') and name != '_' # '_' is default root node name

def is_func(node): return is_func_name(node.tagName)

def is_xml_func_name(name): return is_func_name(name) and name in funcs

def is_xml_func(node): return is_xml_func_name(node.tagName)

def process(node, on_error=exc.raise_, rel_funcs=None, db=None):

    '''Evaluates the XML functions in an XML tree.

    @param rel_funcs None|set(str...) Relational functions

        * container can be any iterable type

        * If != None: Non-relational functions are removed, or relational

          functions are treated specially, depending on the db param (below).

    @param db

        * If None: Non-relational functions other than structural functions are

          replaced with their last parameter (usually the value), not evaluated.

          This is used in column-based mode to remove XML-only functions.

        * If != None: Relational functions are evaluated directly. This is used

          in row-based mode to combine relational and XML functions.

    '''

    has_rel_funcs = rel_funcs != None

    assert db == None or has_rel_funcs # rel_funcs required if db set

    for child in xml_dom.NodeElemIter(node):

        process(child, on_error, rel_funcs, db)

    name = node.tagName

    if not is_func_name(name): return # not any kind of function

    # Change rel_funcs *after* processing child nodes, which needs orig value

    if not has_rel_funcs: rel_funcs = set()

    rel_funcs = set(rel_funcs)

    row_mode = has_rel_funcs and db != None

    column_mode = has_rel_funcs and db == None

    items = xml_dom.NodeTextEntryIter(node)

    if row_mode and name in rel_funcs: # row-based mode: evaluate using DB

        value = sql.put(db, name, dict(items))

    elif column_mode and not name in structural_funcs: # column-based mode

        if name in rel_funcs: return # preserve relational functions

        # otherwise XML-only, so just replace with last param

        value = pop_value(list(items), None)

    else: # local XML function

        try: value = funcs[name](items, node)

        except Exception, e: # also catch non-wrapped exceptions (XML func bugs)

            # Save in case another exception raised, overwriting sys.exc_info()

            exc.add_traceback(e)

            str_ = strings.ustr(node)

            exc.add_msg(e, 'function:\n'+str_)

            xml_dom.replace(node, xml_dom.mk_comment(node.ownerDocument,

                '\n'+term.emph_multiline(str_)))

            on_error(e)

            return # in case on_error() returns

    xml_dom.replace_with_text(node, value)

##### XML functions

# Function names must start with _ to avoid collisions with real tags

# Functions take arguments (items)

#### Structural

def _ignore(items, node):

    '''Used to "comment out" an XML subtree'''

    return None

funcs['_ignore'] = _ignore

structural_funcs.add('_ignore')

def _ref(items, node):

    '''Used to retrieve a value from another XML node

    @param items

        addr=<path> XPath to value, relative to the XML func's parent node

    '''

    items = dict(items)

    try: addr = items['addr']

    except KeyError, e: raise SyntaxError(e)

    value = xpath.get_value(node.parentNode, addr)

    if value == None:

        warnings.warn(UserWarning('_ref: XPath reference target missing: '

            +str(addr)))

    return value

funcs['_ref'] = _ref

structural_funcs.add('_ref')

#### Conditionals

def _eq(items, node):

    items = dict(items)

    try:

        left = items['left']

        right = items['right']

    except KeyError: return '' # a value was None

    return util.bool2str(left == right)

funcs['_eq'] = _eq

def _if(items, node):

    items = dict(items)

    try:

        cond = items['cond']

        then = items['then']

    except KeyError, e: raise SyntaxError(e)

    else_ = items.get('else', None)

    cond = bool(cast(strings.ustr, cond))

    if cond: return then

    else: return else_

funcs['_if'] = _if

#### Combining values

def _alt(items, node):

    items = list(items)

    items.sort()

    try: return items[0][1] # value of lowest-numbered item

    except IndexError: return None # input got removed by e.g. FormatException

funcs['_alt'] = _alt

def _merge(items, node):

    items = list(conv_items(strings.ustr, items))

        # get *once* from iter, check types

    items.sort()

    return maps.merge_values(*[v for k, v in items])

funcs['_merge'] = _merge

def _label(items, node):

    items = dict(conv_items(strings.ustr, items))

        # get *once* from iter, check types

    value = items.get('value', None)

    if value == None: return None # input is empty

    try: label = items['label']

    except KeyError, e: raise SyntaxError(e)

    return label+': '+value

funcs['_label'] = _label

#### Transforming values

def _collapse(items, node):

    '''Collapses a subtree if the "value" element in it is NULL'''

    items = dict(items)

    try: require = cast(strings.ustr, items['require'])

    except KeyError, e: raise SyntaxError(e)

    value = items.get('value', None)

    if xpath.get_value(value, require, allow_rooted=False) == None: return None

    else: return value

funcs['_collapse'] = _collapse

types_by_name = {None: strings.ustr, 'str': strings.ustr, 'float': float}

def _nullIf(items, node):

    items = dict(conv_items(strings.ustr, items))

    try: null = items['null']

    except KeyError, e: raise SyntaxError(e)

    value = items.get('value', None)

    type_str = items.get('type', None)

    try: type_ = types_by_name[type_str]

    except KeyError, e: raise SyntaxError(e)

    null = type_(null)

    try: return util.none_if(value, null)

    except ValueError: return value # value not convertible, so can't equal null

funcs['_nullIf'] = _nullIf

def repl(repls, value):

    '''Raises error if value not in map and no special '*' entry

    @param repls dict repl:with

        repl "*" means all other input values

        with "*" means keep input value the same

        with "" means ignore input value

    '''

    try: new_value = repls[value]

    except KeyError, e:

        # Save traceback right away in case another exception raised

        fe = FormatException(e)

        try: new_value = repls['*']

        except KeyError: raise fe

    if new_value == '*': new_value = value # '*' means keep input value the same

    return new_value

def _map(items, node):

    '''See repl()

    @param items

        <last_entry> Value

        <other_entries> name=value Mappings. Special values: See repl() repls.

    '''

    items = conv_items(strings.ustr, items) # get *once* from iter, check types

    value = pop_value(items)

    if value == None: return None # input is empty

    return util.none_if(repl(dict(items), value), u'') # empty value means None

funcs['_map'] = _map

def _replace(items, node):

    items = conv_items(strings.ustr, items) # get *once* from iter, check types

    value = pop_value(items)

    if value == None: return None # input is empty

    try:

        for repl, with_ in items:

            if re.match(r'^\w+$', repl):

                repl = r'(?<![^\W_])'+repl+r'(?![^\W_])' # match whole word

            value = re.sub(repl, with_, value)

    except sre_constants.error, e: raise SyntaxError(e)

    return util.none_if(value.strip(), u'') # empty strings always mean None

funcs['_replace'] = _replace

#### Quantities

def _units(items, node):

    items = conv_items(strings.ustr, items) # get *once* from iter, check types

    value = pop_value(items)

    if value == None: return None # input is empty

    quantity = units.str2quantity(value)

    try:

        for action, units_ in items:

            units_ = util.none_if(units_, u'')

            if action == 'default': units.set_default_units(quantity, units_)

            elif action == 'to':

                try: quantity = units.convert(quantity, units_)

                except ValueError, e: raise FormatException(e)

            else: raise SyntaxError(ValueError('Invalid action: '+action))

    except units.MissingUnitsException, e: raise FormatException(e)

    return units.quantity2str(quantity)

funcs['_units'] = _units

def parse_range(str_, range_sep='-'):

    default = (str_, None)

    start, sep, end = str_.partition(range_sep)

    if sep == '': return default # not a range

    if start == '' and range_sep == '-': return default # negative number

    return tuple(d.strip() for d in (start, end))

def _rangeStart(items, node):

    items = dict(conv_items(strings.ustr, items))

    try: value = items['value']

    except KeyError: return None # input is empty

    return parse_range(value)[0]

funcs['_rangeStart'] = _rangeStart

def _rangeEnd(items, node):

    items = dict(conv_items(strings.ustr, items))

    try: value = items['value']

    except KeyError: return None # input is empty

    return parse_range(value)[1]

funcs['_rangeEnd'] = _rangeEnd

def _range(items, node):

    items = dict(conv_items(float, items))

    from_ = items.get('from', None)

    to = items.get('to', None)

    if from_ == None or to == None: return None

    return str(to - from_)

funcs['_range'] = _range

def _avg(items, node):

    count = 0

    sum_ = 0.

    for name, value in conv_items(float, items):

        count += 1

        sum_ += value

    if count == 0: return None # input is empty

    else: return str(sum_/count)

funcs['_avg'] = _avg

class CvException(Exception):

    def __init__(self):

        Exception.__init__(self, 'CV (coefficient of variation) values are only'

            ' allowed for ratio scale data '

            '(see <http://en.wikipedia.org/wiki/Coefficient_of_variation>)')

def _noCV(items, node):

    try: name, value = items.next()

    except StopIteration: return None

    if re.match('^(?i)CV *\d+$', value): raise FormatException(CvException())

    return value

funcs['_noCV'] = _noCV

#### Dates

def _date(items, node):

    items = dict(conv_items(strings.ustr, items))

        # get *once* from iter, check types

    try: str_ = items['date']

    except KeyError:

        # Year is required

        try: items['year']

        except KeyError, e:

            if items == {}: return None # entire date is empty

            else: raise FormatException(e)

        # Convert month name to number

        try: month = items['month']

        except KeyError: pass

        else:

            if not month.isdigit(): # month is name

                try: items['month'] = str(dates.strtotime(month).month)

                except ValueError, e: raise FormatException(e)

        items = dict(conv_items(format.str2int, items.iteritems()))

        items.setdefault('month', 1)

        items.setdefault('day', 1)

        for try_num in xrange(2):

            try:

                date = datetime.date(**items)

                break

            except ValueError, e:

                if try_num > 0: raise FormatException(e)

                    # exception still raised after retry

                msg = strings.ustr(e)

                if msg == 'month must be in 1..12': # try swapping month and day

                    items['month'], items['day'] = items['day'], items['month']

                else: raise FormatException(e)

    else:

        try: year = float(str_)

        except ValueError:

            try: date = dates.strtotime(str_)

            except ImportError: return str_

            except ValueError, e: raise FormatException(e)

        else: date = (datetime.date(int(year), 1, 1) +

            datetime.timedelta(round((year % 1.)*365)))

    try: return dates.strftime('%Y-%m-%d', date)

    except ValueError, e: raise FormatException(e)

funcs['_date'] = _date

def _dateRangeStart(items, node):

    items = dict(conv_items(strings.ustr, items))

    try: value = items['value']

    except KeyError: return None # input is empty

    return dates.parse_date_range(value)[0]

funcs['_dateRangeStart'] = _dateRangeStart

def _dateRangeEnd(items, node):

    items = dict(conv_items(strings.ustr, items))

    try: value = items['value']

    except KeyError: return None # input is empty

    return dates.parse_date_range(value)[1]

funcs['_dateRangeEnd'] = _dateRangeEnd

#### Names

_name_parts_slices_items = [

    ('first', slice(None, 1)),

    ('middle', slice(1, -1)),

    ('last', slice(-1, None)),

]

name_parts_slices = dict(_name_parts_slices_items)

name_parts = [name for name, slice_ in _name_parts_slices_items]

def _name(items, node):

    items = dict(items)

    parts = []

    for part in name_parts:

        if part in items: parts.append(items[part])

    return ' '.join(parts)

funcs['_name'] = _name

def _namePart(items, node):

    out_items = []

    for part, value in items:

        try: slice_ = name_parts_slices[part]

        except KeyError, e: raise SyntaxError(e)

        out_items.append((part, ' '.join(value.split(' ')[slice_])))

    return _name(out_items, node)

funcs['_namePart'] = _namePart

#### Angles

def _compass(items, node):

    '''Converts a compass direction (N, NE, NNE, etc.) into a degree heading'''

    items = dict(conv_items(strings.ustr, items))

    try: value = items['value']

    except KeyError: return None # input is empty

    if not value.isupper(): return value # pass through other coordinate formats

    try: return util.cast(str, angles.compass2heading(value)) # ignore None

    except KeyError, e: raise FormatException(e)

funcs['_compass'] = _compass

#### Paths

def _simplifyPath(items, node):

    items = dict(items)

    try:

        next = cast(strings.ustr, items['next'])

        require = cast(strings.ustr, items['require'])

        root = items['path']

    except KeyError, e: raise SyntaxError(e)

    node = root

    while node != None:

        new_node = xpath.get_1(node, next, allow_rooted=False)

        if xpath.get_value(node, require, allow_rooted=False) == None: # empty

            xml_dom.replace(node, new_node) # remove current elem

            if node is root: root = new_node # also update root

        node = new_node

    return root

funcs['_simplifyPath'] = _simplifyPath