Return to doc.rst CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / gpl / axl / py-axl / doc

version 0.6.7

    1: :mod:`axl.Doc` --- PyAxlDoc class: XML document instance 
    2: ========================================================
    3: 
    4: .. currentmodule:: axl
    5: 
    6: 
    7: =====
    8: Intro
    9: =====
   10: 
   11: API documentation for axl.Doc object representing a XML document
   12: instance. 
   13: 
   14: There are several ways to create a document. The most easy to load it
   15: from a file. To do so you can use::
   16: 
   17:      # include axl module
   18:      import axl
   19: 
   20:      # load document
   21:      (doc, err) = axl.file_parse ("file.xml")
   22:      if err:
   23:      	print ("ERROR: found xml error: " + err.msg)
   24: 	return -1
   25: 
   26:      # dump document into console
   27:      (content, size) = doc.dump ()
   28:      print ("Content loaded: " + content)			
   29: 
   30: You can also create a document from a few strings::
   31: 
   32:      (doc, err) = axl.file_parse ("file.xml")
   33: 
   34: Finally, to create an empty document, you simply instance the class::
   35: 
   36:      # create a document with default version=None, default
   37:      # encoding=None and default standalone=axl_true configuration
   38:      doc = axl.Doc ()
   39: 
   40:      # set root node
   41:      doc.root = axl.Node ("test")
   42: 
   43: 
   44: ==========
   45: Module API
   46: ==========
   47: 
   48: .. class:: Doc
   49: 
   50:    .. method:: get (path)
   51:    
   52:       Allows to get a node at a particular location using a simplified
   53:       Xpath string. See axl_doc_get for more information::
   54: 
   55:       	    # get node an prints its content
   56:             node = doc.get ("/document/child/first")
   57: 
   58: 	    if node:
   59: 	       print ("Node name: " + node.name + ", with content: " + node.content)
   60: 
   61:       :param path: A path to the node that is retrieved
   62:       :type  path: String 
   63: 
   64:       :rtype: Returns an instance of axl.Node or None if no node was found.
   65: 
   66:    .. method:: dump ([tabular])
   67:    
   68:       Allows to dump the document loaded by the instance into an
   69:       string. The method receives an optional integer value that
   70:       activates the pretty print mode and providing the tabular value
   71:       to use on each level.
   72: 
   73:       For example, dumping the document without indentantion is done using::
   74: 
   75:           (content, size) = doc.dump ()
   76: 
   77:       However, dumping the same content indented in a more readable way use::
   78: 
   79:           (content, size) = doc.dump (4)
   80: 
   81:       See also axl_doc_dump and axl_doc_dump_pretty
   82: 
   83:       :param tabular: Optional integer value that activates the dump indentation support providing the tabular value to use on each level.
   84:       :type  tabular: Integer >= 0 
   85: 
   86:       :rtype: Returns a tumple (content, size) or an exception (TypeError or ValueError) in the case some error is found.
   87: 
   88:    .. method:: file_dump (path, [tabular])
   89:    
   90:       Allows to perform a dump operation sending the content to a file
   91:       located at the path provided. If provided optional argument
   92:       tabular will cause indentation to be activated.
   93: 
   94:       For example, to dump content into a file with a 4 space indentation on each level use::
   95: 
   96:           doc.file_dump ("/tmp/output.txt", 4):
   97: 
   98:       :param path: Path where the xml content will be dumped.
   99:       :type  path: String 
  100: 	  
  101:       :param tabular: Optional integer value that activates the dump indentation support providing the tabular value to use on each level.
  102:       :type  tabular: Integer >= 0 
  103: 
  104:       :rtype: Returns True or an exception (TypeError or ValueError) in the case some error is found.
  105: 
  106:    .. method:: has_pi (pi_name)
  107:    
  108:       Allows to check if the document contains a process instruction with the provided name.
  109: 
  110:       :param pi_name: Process instruction name to check.
  111:       :type  pi_name: String
  112: 
  113:       :rtype: Returns True if the process instruction is available, otherwise False is  returned.
  114: 
  115:    .. method:: pi (pi_name)
  116:    
  117:       Allows to get the Process instruction content with the provide pi_name.
  118: 
  119:       :param pi_name: Process instruction name to check.
  120:       :type  pi_name: String
  121: 
  122:       :rtype: Returns the process instruction content or None if nothing is found.
  123: 
  124:    .. attribute:: encoding
  125: 
  126:       (Read only attribute) (String) Allows to get document encoding.
  127: 
  128:    .. attribute:: standalone
  129: 
  130:       (Read only attribute) (True/False) Allows to get stand alone document configuration.
  131: 
  132:    .. attribute:: stand_alone
  133: 
  134:       Alias of standalone
  135: 
  136:    .. attribute:: root
  137: 
  138:       (Read/Write attribute) (axl.Node) allows to get/set the current document root node.
  139: