path: root/fconfig.py

#/***************************************************************************
#                             fconfig.h
#                             -----------
#    begin                : sam nov 2 2002
#    copyright            : (C) 1992-2004 by Fabian Padilla
#    email                : fp@bridgethink.com
# ***************************************************************************/

# /***************************************************************************
#  *                                                                         *
#  *   This program is free software; you can redistribute it and/or modify  *
#  *   it under the terms of the Foundation Public License as published by   *
#  *   bridgethink sarl; either version 2 of the License, or                 *
#  *   (at your option) any later version.                                   *
#  *                                                                         *
#  ***************************************************************************/

#
#  from C++ to python by Jeremy Zurcher <jeremy@asynk.ch>
#


"""/** Class done to open or load and close or save the config in tree files
  (XML now, but nobody what's would be in the future, ex: LDAP).
  function : It is the access to a tree of information needed by the class which inheritate from Fconfig.
  This class can be modified if the datas are stored in another system than a file.
  The file can be a stream or every other input stream data (better in a tree like XML or LDAP).

  description :
  - Methods start and startNew will connect Fconfig to a tree (XML in this example, but can be a
     LDAP or other tree style).
  - Method end will enable to save the tree (not always needed).
  - Method resetCurrent will reset the current pointer to the node when last method start as been called.
  - Methods gotoNext, gotoPrev, gotoChildren, gotoParent enable to move inside the tree.
  - Methods Find and FindNext enable to search by name an tree Node.

  Fconfig is a generic caller for a tree access. This enable to change the type of supported tree XML,
    LDAP or others, without having to update the evenja kernel.  
  
  *@author Fabian Padilla
  */"""

__all__ = ["Fconfig"]

try:
	import libxml2
except:
	print "libxml2 not available ... aborting !!"
	import sys
	sys.exit(1)

from flist import Flist
from fstringhash import FstringHash
import returncodes as RC
import evenjastrings as ES

class Fconfig(FstringHash):
	""" This class gives you the ability to walk around and through an XML document.
	This document can be created from sratch, read from a file, completed and modified, and so on.
	You can also execute some research queries... Everything seems to be safe /~\/~\."""

	def __init__(self):
		FstringHash.__init__(self)	# force contrustor
		self.fileName = None            # yeah, this is it !
		self.doc = None			# the document
		self.root = None		# the root node
		self.firstCurrent = None	# the first node of the tree
		self.current = None		# the current node
		self.stackCurrent = Flist()     # a stack used to push and pop self.current

	def __str__(self):
		return "\t"+FstringHash.__str__(self) +\
				" Fconfig - File : "+str(self.fileName)+\
				" - Current_Name : "+str(self.getName())+\
				" - Current_Content : "+str(self.getContent())+"\n"
	
	def startXml(self, param):
		"""/** Read an XML tree, param may be a file name or an xmlNode. */"""
		if isinstance(param,str):
			# a filename is given, parse this file
			self.fileName = param
			try:
				self.doc = libxml2.parseFile(param)
			except:
				return RC.RET_CANNOTACCESS
			param = self.doc.children
		# a node is given or we have one now
		if not isinstance(param,libxml2.xmlNode):
			return RC.RET_CANNOTACCESS
		self.root = param.doc.children
		self.firstCurrent = param
		self.current = param
		if self.gotoChildren() != RC.RET_OK:
			return RC.RET_NOTEXIST
		# find <evenja_name> tag and put it's content in our FstringHash
		if self.Find(ES.XML_NAME, False) != RC.RET_OK:
			return RC.RET_NONAME
		string = self.getContent()
		if string == RC.RET_NONODESELECTED:		# don't need this ...
			return RC.RET_NONAME
		self.setString(string)
		self.resetCurrent()
		return RC.RET_OK

	def startNewXml(self, fileName = None):
		"""/** Create a new XML tree. */"""
		if fileName:
			self.fileName = fileName
		else:
			self.fileName = None
		try:
			self.doc = libxml2.newDoc(ES.XML_VERSION)
			self.doc.newChild(None, ES.XML_XML, None)
		except:
			return RC.RET_CANNOTCREATE
		self.root = self.doc.children
		self.firstCurrent = self.root
		self.current = self.root
		self.setString(ES.TXT_NEW)
		return RC.RET_OK
	
	def endXml(self):
		"""/** Close the XML tree. Save it if a file name exists. */"""
		if self.doc and self.fileName:
			if self.doc.saveFile(self.fileName) == -1:
				return RC.RET_CANNOTEND
		if self.doc:
			self.doc.freeDoc()
		self.doc = None
		self.root = None
		self.firstCurrent = None
		self.current = None
		self.fileName = None
		return RC.RET_OK
	
	def getCurrent(self):
		"""/** Get the current node. */"""
		return self.current
  
# WALKING METHODS

	def resetCurrent(self, fromRoot = False):
		"""/** Set current node to the root one if fromRoot, otherwise to the first one. */"""
		if fromRoot:
			self.current = self.root
		else:
			self.current = self.firstCurrent
		
	def gotoFirst(self):
		"""/** Go to the first node of the current branch. */"""
		if not self.current:
			return RC.RET_NONODESELECTED
		self.current = self.current.parent.children
		if self.current.type != "element":
			return self.gotoNext()
		return RC.RET_OK
		
	def gotoLast(self):
		"""/** Go to the last node of the current branch. */"""
		if not self.current:
			return RC.RET_NONODESELECTED
		self.current = self.current.parent.last
		if self.current.type != "element":
			return self.gotoPrev()
		return RC.RET_OK
		
	def gotoNext(self):
		"""/** Go to the next node of the current branch. */"""
		if not self.current:
			return RC.RET_NONODESELECTED
		if not self.current.next:
			return RC.RET_NOTEXIST
		node = self.current.next
		while node.type != "element" and node.next:	# walk 'till you find
			node = node.next
		if node.type == "element":
			self.current = node
			return RC.RET_OK
		return RC.RET_NOTEXIST
		
	def gotoPrev(self):
		"""/** Go to the previous node of the current branch. */"""
		if not self.current:
			return RC.RET_NONODESELECTED
		if not self.current.prev:
			return RC.RET_NOTEXIST
		node = self.current.prev
		while node.type != "element" and node.prev:	# walk 'till you find
			node = node.prev
		if node.type == "element":
			self.current = node
			return RC.RET_OK
		return RC.RET_NOTEXIST
		
	def gotoChildren(self):
		"""/** Go to the children node of the current node. */"""
		if not self.current:
			return RC.RET_NONODESELECTED
		if not self.current.children:
			return RC.RET_NOTEXIST
		tmp = self.current
		self.current = self.current.children
		if self.current.type == "element":
			return RC.RET_OK
		ret = self.gotoNext()
		if ret == RC.RET_NOTEXIST:
			self.current = tmp
		return ret
		
	def gotoParent(self):
		"""/** Go to the parent node of the current node. */"""
		if not self.current:
			return RC.RET_NONODESELECTED
		if not self.current.parent:
			return RC.RET_NOTEXIST
		tmp = self.current
		self.current = self.current.parent
		if self.current.type == "element":
			return RC.RET_OK
		ret = self.gotoPrev()
		if ret == RC.RET_NOTEXIST:
			self.current = tmp
		return ret
		
	def Search(self, name, subTree = True):
		"""/** Find a name, with or without tree recusivity, using preorder path.
		self.current is saved from not_found case */"""
		if not self.current:
			return RC.RET_NONODESELECTED
		bkp = self.current						# save self.current
		while True:
			if self.getName() == name:
				return RC.RET_OK
			if subTree and self.current.children:			# maybe deeper ??
				if self.gotoChildren() == RC.RET_OK:
					if self.Search(name,subTree) == RC.RET_OK:
						return RC.RET_OK
					else:
						self.gotoParent()
			if RC.RET_OK !=self.gotoNext():				# maybe further ??
				self.current = bkp				# recover self.current
				return RC.RET_NOTFOUND
	
	def Find(self, name, subTree = True):
		"""/** Find a name from th etop of the tree, with or without tree recusivity. */"""
		ret = self.gotoFirst()
		if ret != RC.RET_OK:
			return ret
		return self.Search(name,subTree)
		
	def FindNext(self, name, subTree = True):
		"""/** Find next name, with or without tree recusivity. */"""
		ret = self.gotoNext()
		if ret != RC.RET_OK:
			return ret
		return self.Search(name,subTree)
		

# RETRIEVE INFORMATIONS

	def getName(self):
		"""/** Get the Name of the current Node. */"""
		if self.current:
			return self.current.name
		return RC.RET_NONODESELECTED
		
	def setName(self, name):
		"""/** Set the Name of the current Node. */"""
		if not self.current:
			return RC.RET_NONODESELECTED
		self.current.setName(name)
		return RC.RET_OK
		
	def getContent(self):
		"""/** Get the Content of the current Node. */"""
		if not self.current:
			return RC.RET_NONODESELECTED
		currentA = self.current.children
		if currentA:
			return currentA.content
		return ES.TXT_NULL
		
	def setContent(self, content):
		"""/** Set the Content of the current Node. */"""
		if not self.current:
			return RC.RET_NONODESELECTED
		if content <> None:
			self.current.setContent(content)
		else:
			self.current.setContent(ES.TXT_NULL)
		return RC.RET_OK

# CREATE ADN DELETE NODES

	def addChildren(self, name, content = None):
		"""/** Create a new node (the current node is the parent). */"""
		if not self.current:
			return RC.RET_NONODESELECTED
		self.current.newChild(None,name,content)
		if self.doc and not self.root:
			self.root = self.doc.children
			self.firstCurrent = self.root
			self.current = self.root
		return RC.RET_OK
		
	def removeCurrent(self):
		"""/** Remove the current node (recursively).
		After remove operation, goto the previous node if exists or to the next, or the parent*/"""
		str = self.getName()
		if str == RC.RET_NONODESELECTED or str is None:
			return RC.RET_NONODESELECTED
		if str.upper() == ES.XML_XML.upper():			# TzurTcH - case insensitive should be ok 
			return RC.RET_OK
		toRemove = self.current
		if self.current.prev:
			self.gotoPrev()
		elif self.current.next:
			self.gotoNext()
		elif self.current.parent:
			self.gotoParent()
		# maybe it will empty this tree ...
		if self.root == toRemove or self.firstCurrent == toRemove or self.root.doc.children == toRemove:
			self.root = None
			self.firstCurrent = None
			self.current = None
		toRemove.unlinkNode()
		toRemove.freeNode()
		return RC.RET_OK

# STACK MEMORY CAPABILITIES

	def pushCurrent(self):
		"""/** Push the Current position to the stack. */"""
		self.stackCurrent.add(self.current)

	def popCurrent(self):
		"""/** Pop the Current position from the stack. */"""
		if self.stackCurrent.getCount():
			self.current = self.stackCurrent.removeStack()
	
if __name__ == '__main__':

	import unittest
	from evenjastrings import *

	conf =  Fconfig()
	
	class FconfigTestCase(unittest.TestCase):
	
		def test1FileName(self):
			self.assertEquals(conf.startXml( "testezlog.xml"),RC.RET_OK)
			self.assertEquals(conf.endXml(),RC.RET_OK)
			
		def test2NewTree(self):
			self.assertEquals(conf.startNewXml(),RC.RET_OK)
			self.assertEquals(conf.endXml(),RC.RET_OK)
			self.assertEquals(conf.startNewXml( "testezlog_addnode.xml"),RC.RET_OK)
			self.assertEquals(conf.endXml(),RC.RET_OK)
		
		def test3StartNode(self):
			self.assertEquals(conf.startXml( "testezlog.xml"),RC.RET_OK)
			conf1 = Fconfig()
			conf1.startXml( conf.getCurrent())
			conf1.gotoChildren()
			self.assertEquals(ES.XML_NAME.upper(),conf1.getName().upper())
			conf1.endXml()
			self.assertEquals(conf.endXml(),RC.RET_OK)
		
		def test4Node(self):
			self.assertEquals(conf.startXml( "testezlog.xml"),RC.RET_OK)
			conf.gotoChildren()
			self.assertEquals(ES.XML_NAME, conf.getName())
			self.assertEquals("TEST00", conf.getContent())
			conf.gotoNext()
			self.assertEquals(ES.XML_ROOM, conf.getName())
			conf.gotoChildren()
			self.assertEquals(ES.XML_NAME, conf.getName())
			self.assertEquals("Room1", conf.getContent())
			conf.gotoNext()
			self.assertEquals(ES.XML_DOC, conf.getName())
			self.assertEquals("FirstRoom", conf.getContent())
			conf.gotoNext()
			conf.gotoPrev()
			self.assertEquals(ES.XML_DOC, conf.getName())
			self.assertEquals("FirstRoom", conf.getContent())
			conf.gotoPrev()
			conf.gotoNext()
			self.assertEquals(ES.XML_DOC, conf.getName())
			self.assertEquals("FirstRoom", conf.getContent())
			self.assertEquals(conf.endXml(),RC.RET_OK)
		
		def test5ParentChildren(self):
			self.assertEquals(conf.startXml( "testezlog.xml"),RC.RET_OK)
			self.assertEquals(ES.XML_XML.upper(), conf.getName().upper())
			self.assertEquals(conf.gotoChildren(),RC.RET_OK)
			
			self.assertEquals(ES.XML_NAME, conf.getName())
			self.assertEquals("TEST00", conf.getContent())
			self.assertEquals(conf.gotoChildren(),RC.RET_NOTEXIST)
			self.assertEquals(ES.XML_NAME, conf.getName())
			self.assertEquals("TEST00", conf.getContent())
			
			self.assertEquals(conf.gotoParent(),RC.RET_OK)
			self.assertEquals(ES.XML_XML.upper(), conf.getName().upper())
			self.assertEquals(conf.gotoParent(),RC.RET_NOTEXIST)
	
			conf.resetCurrent()
			self.assertEquals(conf.gotoChildren(),RC.RET_OK)
			self.assertEquals(ES.XML_NAME, conf.getName())
			self.assertEquals(conf.endXml(),RC.RET_OK)
		
		def test6FirstLast(self):
			self.assertEquals(conf.startXml( "testezlog.xml"),RC.RET_OK)
			conf.gotoChildren()
			conf.gotoNext()
			conf.gotoChildren()
			conf.gotoLast()
			self.assertEquals(ES.XML_CONF, conf.getName())
			self.assertEquals(conf.gotoNext(),RC.RET_NOTEXIST)
			conf.gotoFirst()
			self.assertEquals(ES.XML_NAME, conf.getName())
			self.assertEquals(conf.gotoPrev(),RC.RET_NOTEXIST)
			conf.gotoNext()
			self.assertEquals(ES.XML_DOC, conf.getName())
			self.assertEquals(conf.endXml(),RC.RET_OK)
		
		def test7Find(self):
			self.assertEquals(conf.startXml( "testezlog.xml"),RC.RET_OK)
			if conf.Find(ES.XML_NAME):
				self.assertEquals(ES.XML_NAME, conf.getName())
				self.assertEquals("Room1", conf.getContent())
				conf.pushCurrent()
				conf.FindNext(ES.XML_DOC)
				self.assertEquals(ES.XML_DOC, conf.getName())
				self.assertEquals("FirstRoom", conf.getContent())
				conf.popCurrent()
				conf.FindNext(ES.XML_DOC, false)
			self.assertEquals(conf.Find(ES.TXT_NULL),RC.RET_NOTFOUND)
			self.assertEquals(conf.endXml(),RC.RET_OK)
			
		def test8NewNode(self):
			self.assertEquals(conf.startNewXml( "testezlog_addnode.xml"),RC.RET_OK)
			conf.addChildren( ES.XML_NAME, "Room1")
			conf.addChildren( ES.XML_DOC, "FirstRoom")
			conf.addChildren( ES.XML_CONF, "REMOVETEST")

			conf.gotoChildren()
			conf.gotoLast()
			self.assertEquals(ES.XML_CONF, conf.getName())
			conf.removeCurrent()
			self.assertEquals(ES.XML_DOC, conf.getName())
			self.assertEquals("FirstRoom", conf.getContent())
			
			conf.gotoParent()	# XML
			self.assertEquals(ES.XML_XML, conf.getName())
			conf.addChildren(ES.XML_CONF, "REMOVETEST")
			conf.gotoChildren()
			conf.gotoLast()
			conf.gotoPrev()
			self.assertEquals(ES.XML_DOC, conf.getName())
			self.assertEquals("FirstRoom", conf.getContent())
			conf.removeCurrent()
			self.assertEquals(ES.XML_NAME, conf.getName())
			self.assertEquals("Room1", conf.getContent())
			
			conf.gotoParent()
			conf.addChildren(ES.XML_DOC, "FirstRoom")
			conf.gotoChildren()
			conf.removeCurrent()
			self.assertEquals(ES.XML_CONF, conf.getName())
			self.assertEquals("REMOVETEST", conf.getContent())
			
			self.assertEquals(conf.endXml(),RC.RET_OK)

		def testBigBuild(self):
			"""TzurTcH's test suite"""
			self.assertEquals(conf.startNewXml( "DEEP.xml"),RC.RET_OK)
			self.assertEquals(conf.getName(),XML_XML)
			self.assertEquals(conf.addChildren( ES.XML_NAME, "Room1"),RC.RET_OK)
			self.assertEquals(conf.addChildren( ES.XML_NAME, "Room2"),RC.RET_OK)
			self.assertEquals(conf.addChildren( ES.XML_NAME, "Room3"),RC.RET_OK)
			self.assertEquals(conf.addChildren( ES.XML_NAME, "Room4"),RC.RET_OK)
			self.assertEquals(conf.addChildren( ES.XML_NAME, "Room5"),RC.RET_OK)
			self.assertEquals(conf.gotoChildren(),RC.RET_OK)
			self.assertEquals(conf.getContent(),"Room1")
			
			self.assertEquals(conf.gotoLast(),RC.RET_OK)
			self.assertEquals(conf.getContent(),"Room5")
			self.assertEquals(conf.gotoLast(),RC.RET_OK)
			self.assertEquals(conf.getContent(),"Room5")
			
			self.assertEquals(conf.addChildren( ES.XML_DOC, "child_of_5"),RC.RET_OK)
			self.assertEquals(conf.gotoNext(),RC.RET_NOTEXIST)
			self.assertEquals(conf.getContent(),"Room5")
			
			self.assertEquals(conf.addChildren( ES.XML_DOC, "child_of_5_two"),RC.RET_OK)
			self.assertEquals(conf.addChildren( ES.XML_DOC, "child_of_5_three"),RC.RET_OK)
			self.assertEquals(conf.getContent(),"Room5")
			
			self.assertEquals(conf.gotoFirst(),RC.RET_OK)
			self.assertEquals(conf.getContent(),"Room1")
			self.assertEquals(conf.gotoFirst(),RC.RET_OK)
			self.assertEquals(conf.getContent(),"Room1")
			self.assertEquals(conf.addChildren( ES.XML_DOC, "child_of_1"),RC.RET_OK)
			self.assertEquals(conf.gotoPrev(),RC.RET_NOTEXIST)
			self.assertEquals(conf.getContent(),"Room1")
			
			self.assertEquals(conf.addChildren( ES.XML_DOC, "child_of_1_two"),RC.RET_OK)
			self.assertEquals(conf.getContent(),"Room1")
			self.assertEquals(conf.addChildren( ES.XML_DOC, "child_of_1_three"),RC.RET_OK)
			
			self.assertEquals(conf.gotoNext(),RC.RET_OK)
			self.assertEquals(conf.getContent(),"Room2")
			self.assertEquals(conf.gotoNext(),RC.RET_OK)
			self.assertEquals(conf.getContent(),"Room3")
			self.assertEquals(conf.gotoNext(),RC.RET_OK)
			self.assertEquals(conf.getContent(),"Room4")
			self.assertEquals(conf.addChildren( ES.XML_DOC, "child_of_4"),RC.RET_OK)
			self.assertEquals(conf.gotoPrev(),RC.RET_OK)
			self.assertEquals(conf.getContent(),"Room3")
			self.assertEquals(conf.gotoPrev(),RC.RET_OK)
			self.assertEquals(conf.getContent(),"Room2")
			self.assertEquals(conf.addChildren( ES.XML_DOC, "child_of_2"),RC.RET_OK)
			self.assertEquals(conf.gotoNext(),RC.RET_OK)
			self.assertEquals(conf.getContent(),"Room3")
			
			self.assertEquals(conf.addChildren( ES.XML_DOC, "child_of_3"),RC.RET_OK)
			self.assertEquals(conf.addChildren( "SEARCH", "child_of_3_two"),RC.RET_OK)
			
			conf.pushCurrent()
			self.assertEquals(conf.getContent(),"Room3")
			conf.resetCurrent(False)
			self.assertEquals(conf.getName(),XML_XML)
			self.assertEquals(conf.Find("SEARCH"),RC.RET_OK)
			conf.popCurrent()
			
			self.assertEquals(conf.addChildren( ES.XML_DOC, "child_of_3_three"),RC.RET_OK)
			self.assertEquals(conf.getContent(),"Room3")
			self.assertEquals(conf.gotoChildren(),RC.RET_OK)
			self.assertEquals(conf.getContent(),"child_of_3")
			self.assertEquals(conf.gotoLast(),RC.RET_OK)
			self.assertEquals(conf.getContent(),"child_of_3_three")
			self.assertEquals(conf.gotoChildren(),RC.RET_NOTEXIST)
			self.assertEquals(conf.getContent(),"child_of_3_three")
			
			self.assertEquals(conf.gotoParent(),RC.RET_OK)
			self.assertEquals(conf.getContent(),"Room3")
			self.assertEquals(conf.gotoParent(),RC.RET_OK)
			self.assertEquals(conf.gotoChildren(),RC.RET_OK)
			self.assertEquals(conf.getContent(),"Room1")
			
			self.assertEquals(conf.gotoParent(),RC.RET_OK)
			self.assertEquals(conf.getName(),ES.XML_XML)
			self.assertEquals(conf.gotoParent(),RC.RET_NOTEXIST)
			self.assertEquals(conf.gotoParent(),RC.RET_NOTEXIST)
			self.assertEquals(conf.getName(),ES.XML_XML)
			self.assertEquals(conf.removeCurrent(),RC.RET_OK)
			
			self.assertEquals(conf.gotoChildren(),RC.RET_OK)
			self.assertEquals(conf.getContent(),"Room1")
			self.assertEquals(conf.gotoChildren(),RC.RET_OK)
			self.assertEquals(conf.getContent(),"child_of_1")
			self.assertEquals(conf.gotoParent(),RC.RET_OK)
			self.assertEquals(conf.removeCurrent(),RC.RET_OK)
			self.assertEquals(conf.getContent(),"Room2")
			self.assertEquals(conf.Find("NOTHING"),RC.RET_NOTFOUND)
			self.assertEquals(conf.getContent(),"Room2")
			self.assertEquals(conf.FindNext("NOTHING"),RC.RET_NOTFOUND)
			self.assertEquals(conf.getContent(),"Room3")

			self.assertEquals(conf.gotoPrev(),RC.RET_OK)
			self.assertEquals(conf.FindNext("SEARCH"),RC.RET_OK)
			self.assertEquals(conf.getContent(),"child_of_3_two")
			self.assertEquals(conf.gotoParent(),RC.RET_OK)
			self.assertEquals(conf.FindNext("SEARCH"),RC.RET_NOTFOUND)
			self.assertEquals(conf.getContent(),"Room4")
			self.assertEquals(conf.getName(),ES.XML_NAME)
			self.assertEquals(conf.gotoNext(),RC.RET_OK)
			self.assertEquals(conf.getContent(),"Room5")

			self.assertEquals(conf.gotoParent(),RC.RET_OK)
			self.assertEquals(conf.getName(),XML_XML)
			self.assertEquals(conf.endXml(),RC.RET_OK)
			

	unittest.main()