Return to doc.rst CVS log

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

Annotation of gpl/axl/py-axl/doc/doc.rst, revision 1.1.1.2

1.1.1.2 ! misho       1: :mod:`axl.Doc` --- PyAxlDoc class: XML document instance 
        !             2: ========================================================
1.1       misho       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: