"""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)
