#!/usr/bin/env python

"""

Parsing of vCard, vCalendar and iCalendar files.

Copyright (C) 2005, 2006, 2007, 2008 Paul Boddie <paul@boddie.org.uk>

This program 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.

This program 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 this program.  If not, see <http://www.gnu.org/licenses/>.

--------

References:

RFC 2445: Internet Calendaring and Scheduling Core Object Specification

          (iCalendar)

          http://rfc.net/rfc2445.html

RFC 2425: A MIME Content-Type for Directory Information

          http://rfc.net/rfc2425.html

RFC 2426: vCard MIME Directory Profile

          http://rfc.net/rfc2426.html

"""

try:

    set

except NameError:

    from sets import Set as set

# Encoding-related imports.

import base64, quopri

# Tokenisation help.

import re

# Simple reader class.

class Reader:

    "A simple class wrapping a file, providing simple pushback capabilities."

    SEPARATORS = re.compile('[;:"]')

    SEPARATORS_PLUS_EQUALS = re.compile('[=;:"]')

    def __init__(self, f, non_standard_newline=0):

        """

        Initialise the object with the file 'f'. If 'non_standard_newline' is

        set to a true value (unlike the default), lines ending with CR will be

        treated as complete lines.

        """

        self.f = f

        self.non_standard_newline = non_standard_newline

        self.lines = []

        self.line_number = 0

    def pushback(self, line):

        """

        Push the given 'line' back so that the next line read is actually the

        given 'line' and not the next line from the underlying file.

        """

        self.lines.append(line)

        self.line_number -= 1

    def readline(self):

        """

        If no pushed-back lines exist, read a line directly from the file.

        Otherwise, read from the list of pushed-back lines.

        """

        self.line_number += 1

        if self.lines:

            return self.lines.pop()

        else:

            # NOTE: Sanity check for broken lines (\r instead of \r\n or \n).

            line = self.f.readline()

            while line.endswith("\r") and not self.non_standard_newline:

                line += self.f.readline()

            if line.endswith("\r") and self.non_standard_newline:

                return line + "\n"

            else:

                return line

    def read_until(self, targets):

        """

        Read from the stream until one of the 'targets' is seen. Return the

        string from the current position up to the target found, along with the

        target string, using a tuple of the form (string, target). If no target

        was found, return the entire string together with a target of None.

        """

        # Remember the entire text read and the index of the current line in

        # that text.

        lines = []

        line = self.readline()

        lines.append(line)

        start = 0

        # Remember the first target.

        first = None

        first_pos = None

        in_quoted_region = 0

        # Process each line, looking for the targets.

        while line != "":

            match = targets.search(line, start)

            # Where nothing matches, get the next line.

            if match is None:

                line = self.readline()

                lines.append(line)

                start = 0

            # Where a double quote matches, toggle the region state.

            elif match.group() == '"':

                in_quoted_region = not in_quoted_region

                start = match.end()

            # Where something else matches outside a region, stop searching.

            elif not in_quoted_region:

                first = match.group()

                first_pos = match.start()

                break

            # Otherwise, keep looking for the end of the region.

            else:

                start = match.end()

        # Where no more input can provide the targets, return a special result.

        else:

            text = "".join(lines)

            return text, None

        # Push back the text after the target.

        after_target = lines[-1][first_pos + len(first):]

        self.pushback(after_target)

        # Produce the lines until the matching line, together with the portion

        # of the matching line before the target.

        lines[-1] = lines[-1][:first_pos]

        text = "".join(lines)

        return text, first

class StreamParser:

    "A stream parser for content in vCard/vCalendar/iCalendar-like formats."

    def __init__(self, f):

        "Initialise the parser for the given file 'f'."

        self.f = f

    def __iter__(self):

        "Return self as the iterator."

        return self

    def next(self):

        """

        Return the next content item in the file as a tuple of the form

        (name, parameters, values).

        """

        return self.parse_content_line()

    # Internal methods.

    def parse_content_line(self):

        """

        Return the name, parameters and a list containing value information for

        the current content line in the file being parsed.

        """

        f = self.f

        parameters = {}

        name, sep = f.read_until(f.SEPARATORS)

        name = name.strip()

        if not name and sep is None:

            raise StopIteration

        while sep == ";":

            # Find the actual modifier.

            parameter_name, sep = f.read_until(f.SEPARATORS_PLUS_EQUALS)

            parameter_name = parameter_name.strip()

            if sep == "=":

                parameter_value, sep = f.read_until(f.SEPARATORS)

                parameter_value = parameter_value.strip()

            else:

                parameter_value = None

            # Append a key, value tuple to the parameters list.

            parameters[parameter_name] = parameter_value

        # Get the value content.

        if sep != ":":

            raise ValueError, f.line_number

        # Strip all appropriate whitespace from the right end of each line.

        # For subsequent lines, remove the first whitespace character.

        # See section 4.1 of the iCalendar specification.

        line = f.readline()

        value_lines = [line.rstrip("\r\n")]

        line = f.readline()

        while line != "" and line[0] in [" ", "\t"]:

            value_lines.append(line.rstrip("\r\n")[1:])

            line = f.readline()

        # Since one line too many will have been read, push the line back into the

        # file.

        f.pushback(line)

        # Decode the value.

        value = self.decode("".join(value_lines), parameters)

        return name, parameters, value

    def decode(self, value, parameters):

        "Decode the 'value' using the given 'parameters'."

        encoding = parameters.get("ENCODING")

        charset = parameters.get("CHARSET")

        # NOTE: Introducing newline conversions.

        # Replace quoted characters (see 4.3.11 in RFC 2445).

        value = value.replace("\r", "").replace("\\N", "\n").replace("\\n", "\n").replace("\\,", ",").replace("\\;", ";")

        if encoding == "QUOTED-PRINTABLE":

            return unicode(quopri.decodestring(value), charset or "iso-8859-1")

        elif encoding == "BASE64":

            return base64.decodestring(value)

        else:

            return value

class ParserBase:

    "An abstract parser for content in vCard/vCalendar/iCalendar-like formats."

    def __init__(self):

        "Initialise the parser."

        self.names = []

    def parse(self, f, parser_cls=None):

        "Parse the contents of the file 'f'."

        parser = (parser_cls or StreamParser)(f)

        for name, parameters, value in parser:

            if name == "BEGIN":

                self.names.append(value)

                self.startComponent(value, parameters)

            elif name == "END":

                start_name = self.names.pop()

                if start_name != value:

                    raise ParseError, "Mismatch in BEGIN and END declarations (%r and %r) at line %d." % (

                        start_name, value, f.line_number)

                self.endComponent(value)

            else:

                self.handleProperty(name, parameters, value)

class Parser(ParserBase):

    "A SAX-like parser for vCard/vCalendar/iCalendar-like formats."

    def __init__(self):

        ParserBase.__init__(self)

        self.components = []

    def startComponent(self, name, parameters):

        """

        Add the component with the given 'name' and 'parameters', recording an

        empty list of children as part of the component's content.

        """

        component = self.handleProperty(name, parameters, [])

        self.components.append(component)

        return component

    def endComponent(self, name):

        """

        End the component with the given 'name' by removing it from the active

        component stack.

        """

        if len(self.components) > 1:

            return self.components.pop()

        elif self.components:

            return self.components[-1]

    def handleProperty(self, name, parameters, value):

        """

        Record the property with the given 'name', 'parameters' and 'value' as

        part of the current component's children.

        """

        component = self.makeComponent(name, parameters, value)

        self.attachComponent(component)

        return component

    # Component object construction/manipulation methods.

    def attachComponent(self, component):

        "Attach the given 'component' to its parent."

        if self.components:

            component_name, component_parameters, component_children = self.components[-1]

            component_children.append(component)

    def makeComponent(self, name, parameters, value):

        """

        Make a component object from the given 'name', 'parameters' and 'value'.

        """

        return (name, parameters, value)

    # Public methods.

    def parse(self, f, parser_cls=None):

        "Parse the contents of the file 'f'."

        ParserBase.parse(self, f, parser_cls)

        return self.components[0]

# Public functions.

def parse(f, non_standard_newline=0, parser_cls=None):

    """

    Parse the resource data found through the use of the file object 'f', which

    should provide Unicode data. (The codecs module can be used to open files or

    to wrap streams in order to provide Unicode data.)

    The optional 'non_standard_newline' can be set to a true value (unlike the

    default) in order to attempt to process files with CR as the end of line

    character.

    As a result of parsing the resource, the root node of the imported resource

    is returned.

    """

    reader = Reader(f, non_standard_newline)

    parser = (parser_cls or Parser)()

    return parser.parse(reader)

def iterparse(f, non_standard_newline=0, parser_cls=None):

    """

    Parse the resource data found through the use of the file object 'f', which

    should provide Unicode data. (The codecs module can be used to open files or

    to wrap streams in order to provide Unicode data.)

    The optional 'non_standard_newline' can be set to a true value (unlike the

    default) in order to attempt to process files with CR as the end of line

    character.

    An iterator is returned which provides event tuples describing parsing

    events of the form (name, parameters, value).

    """

    reader = Reader(f, non_standard_newline)

    parser = (parser_cls or StreamParser)(reader)

    return iter(parser)

# vim: tabstop=4 expandtab shiftwidth=4