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.1     ! misho       1: :mod:`axl` --- 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: