    """CSVParser.py

    A parser for CSV files.

    """

    import types

    # The states of the parser
    StartRecord        = 0
    StartField         = 1
    InField            = 2
    QuoteInField       = 3
    InQuotedField      = 4
    QuoteInQuotedField = 5
    EndQuotedField     = 6

    # State handlers can return Finished to terminate parsing early
    Finished           = 10

    class ParseError(Exception):
        pass

    class CSVParser:
        """Parser for CSV files.

        Parses CSV files including all subtleties such as:
            * commas in fields
            * double quotes in fields
            * embedded newlines in fields
                - Examples of programs that produce such beasts include
                  MySQL and Excel

        For a higher-level, friendlier CSV class with many conveniences,
        see DataTable (which uses this class for its parsing).

        Example:
            records = []
            parse = CSVParser().parse
            for line in lines:
                results = parse(line)
                if results is not None:
                    records.append(results)

        CREDIT

        The algorithm was taken directly from the open source Python
        C-extension, csv:
            http://www.object-craft.com.au/projects/csv/

        It would be nice to use the csv module when present, since it is
        substantially faster. Before that can be done, it needs to support
        allowComments and stripWhitespace, and pass the TestCSVParser.py
        test suite.

        """

        def __init__(self, allowComments=1, stripWhitespace=1, fieldSep=',',
                autoReset=1, doubleQuote=1):
            """Create a new CSV parser.

            allowComments: If true (the default), then comment lines using
                the Python comment marker are allowed.
            stripWhitespace: If true (the default), then left and right whitespace
                is stripped off from all fields.
            fieldSep: Defines the field separator string (a comma by default).
            autoReset: If true (the default), recover from errors automatically.
            doubleQuote: If true (the default), assume quotes in fields are
                escaped by appearing doubled.

            """
            # settings
            self._allowComments = allowComments
            self._stripWhitespace = stripWhitespace
            self._doubleQuote = doubleQuote
            self._fieldSep = fieldSep
            self._autoReset = autoReset

            # Other
            self._state = StartRecord
            self._fields = []
            self._hadParseError = 0
            self._field = [] # a list of chars for the cur field
            self.addChar = self._field.append

            # The handlers for the various states
            self._handlers = [
                self.startRecord,
                self.startField,
                self.inField,
                self.quoteInField,
                self.inQuotedField,
                self.quoteInQuotedField,
                self.endQuotedField,
            ]

        ## Parse ##

        def parse(self, line):
            """Parse a single line and return a list of string fields.

            Returns None if the CSV record contains embedded newlines and
            the record is not yet complete.

            """
            if self._autoReset and self._hadParseError:
                self.reset()
            handlers = self._handlers

            i = 0
            lineLen = len(line)
            while i < lineLen:
                c = line[i]
                if c == '\r':
                    i += 1
                    if i == lineLen:
                        break # Mac end of line
                    c = line[i]
                    if c == '\n':
                        i += 1
                        if i == lineLen:
                            break # Win end of line

                    self._hadParseError = 1
                    raise ParseError('Newline inside string')

                elif c == '\n':
                    i += 1
                    if i == lineLen:
                        break # unix end of line

                    self._hadParseError = 1
                    raise ParseError('Newline inside string')

                else:
                    if handlers[self._state](c) == Finished:
                        break # process a character

                i += 1

            handlers[self._state]('\0') # signal the end of the input

            if self._state == StartRecord:
                fields = self._fields
                self._fields = []
                if self._stripWhitespace:
                    fields = [field.strip() for field in fields]
                return fields
            else:
                return None # indicates multi-line record; e.g. not finished

        ## Reset ##

        def reset(self):
            """Reset the parser.

            Resets the parser to a fresh state in order to recover from
            exceptions. But if autoReset is true (the default), this is
            done automatically.

            """
            self._fields = []
            self._state = StartRecord
            self._hadParseError = 0

        ## State Handlers ##

        def startRecord(self, c):
            if c != '\0': # not empty line
                if c == '#' and self._allowComments:
                    return Finished
                else:
                    self._state = StartField
                    self.startField(c)

        def startField(self, c):
            if c == '"':
                self._state = InQuotedField # start quoted field
            elif c == self._fieldSep:
                self.saveField() # save empty field
            elif c == ' ' and self._stripWhitespace:
                pass # skip over preceding whitespace
            elif c == '\0':
                self.saveField() # save empty field
                self._state = StartRecord
            else:
                self.addChar(c) # begin new unquoted field
                self._state = InField

        def inField(self, c):
            # in unquoted field
            if c == self._fieldSep:
                self.saveField()
                self._state = StartField
            elif c == '\0':
                self.saveField() # end of line
                self._state = StartRecord
            elif c == '"' and self._doubleQuote:
                self._state = QuoteInField
            else:
                self.addChar(c) # normal character

        def quoteInField(self, c):
            self.addChar('"')
            if c == '"':
                self._state = InField # save "" as "
            elif c == '\0':
                self.saveField() # end of line
                self._state = StartRecord
            elif c == self._fieldSep:
                self.saveField()
                self._state = StartField
            else:
                self.addChar(c) # normal character
                self._state = InField

        def inQuotedField(self, c):
            if c == '"':
                if self._doubleQuote:
                    self._state = QuoteInQuotedField
                else:
                    self.saveField() # end of field
                    self._state = EndQuotedField
            elif c == '\0':
                self.addChar('\n') # end of line
            else:
                self.addChar(c) # normal character

        def quoteInQuotedField(self, c):
            if c == '"':
                self.addChar('"') # save "" as "
                self._state = InQuotedField
            elif c == self._fieldSep:
                self.saveField()
                self._state = StartField
            elif c == ' ' and self._stripWhitespace:
                pass # skip it
            elif c == '\0':
                self.saveField() # end of line
                self._state = StartRecord
            else:
                self._hadParseError = 1 # illegal
                raise ParseError, '%s expected after "' % self._fieldSep

        def endQuotedField(self, c):
            if c == self._fieldSep: # seen closing " on quoted field
                self._state = StartField # wait for new field
            elif c == '\0':
                self._state = StartRecord # end of line
            else:
                self._hadParseError = 1
                raise ParseError, '%s expected after "' % self._fieldSep

        def saveField(self):
            self._fields.append(''.join(self._field))
            self._field = []
            self.addChar = self._field.append

    # Call the global function parse() if you like the default settings of the CSVParser
    _parser = CSVParser()
    parse = _parser.parse

    def joinCSVFields(fields):
        """Return a CSV record (e.g. a string) from a sequence of fields.

        Fields containing commands (,) or double quotes (") are quoted and
        double quotes are escaped (""). The terminating newline is NOT included.

        """
        newFields = []
        for field in fields:
            assert type(field) is types.StringType
            if field.find('"') != -1:
                newField = '"' + field.replace('"', '""') + '"'
            elif field.find(',') != -1:
                newField = '"' + field + '"'
            else:
                newField = field
            newFields.append(newField)
        return ','.join(newFields)