Rappture.Library

constructors
    Rappture.Library()
    Rappture.Library(lib2)

methods
    lib.loadXml(xmltext)
    lib.loadFile(filename)
    lib.value(key[, ...])
    lib.diff(lib2)
    lib.remove(key)
    lib.xml()
    lib.outcome()
    lib.error()
    lib.result(status)
    lib.contains()

---------------------------------------

Rappture.Library()
    Purpose: construct an empty Rappture Library object
    Input Arguments: 0
    Return Value: empty Rappture Library object
    Notes: None
    Code Example:
    {{{
        lib = Rappture.Library()
    }}}

Rappture.Library(lib2)
    Purpose: construct a copy of a Rappture Library object
    Input Arguments: 1
        1. lib2 - Rappture Library object to be copied
    Return Value: copy of a Rappture Library object
    Notes: None
    Code Example:
    {{{
        lib2 = Rappture.Library()
        lib = Rappture.Library(lib2)
    }}}

lib.loadXml(xmltext)
    Purpose: parse the Rappture1.1 xml data in "xmltext".
                populate this library object with the Rappture
                objects described in the xml data.
    Input Arguments: 1
        1. xmltext - string of Rappture1.1 xml data
    Return Value: status of the object
    Notes: None
    Code Example:
    {{{
        xmltext = """
            <?xml version="1.0"?>
            <run>
                <tool>
                    <about>Press Simulate to view results.</about>
                    <command>@tool/fermi @driver</command>
                </tool>
                <input>
                    <number id=\"temperature\">
                        <about>
                            <label>Ambient temperature</label>
                            <description>Temperature of the environment.</description>
                        </about>
                        <units>K</units>
                        <min>0K</min>
                        <max>500K</max>
                        <default>300K</default>
                    </number>
                </input>
            </run>"""
        lib = Rappture.Library()
        lib.loadXml(xmltext)
    }}}

lib.loadFile(filename)
    Purpose: read the file "filename" and parse the
                Rappture1.1 xml data found inside of it.
                populate this library object with the Rappture
                objects described in the xml data.
    Input Arguments: 1
        1. filename - name of file containing Rappture1.1
                      xml data
    Return Value: status of the object
    Notes: None
    Code Example:
    {{{
        data = """
            <?xml version="1.0"?>
            <run>
                <tool>
                    <about>Press Simulate to view results.</about>
                    <command>@tool/fermi @driver</command>
                </tool>
                <input>
                    <number id=\"temperature\">
                        <about>
                            <label>Ambient temperature</label>
                            <description>Temperature of the environment.</description>
                        </about>
                        <units>K</units>
                        <min>0K</min>
                        <max>500K</max>
                        <default>300K</default>
                    </number>
                </input>
            </run>
        """

        filename = "driver1234.xml"
        fp = open(filename,"w")
        fp.write(data)
        fp.close()
        lib = Rappture.Library()
        lib.loadFile(filename)
    }}}

lib.value(key[, ...])
    Purpose: retrieve the value of the object named "key" and
                return it to the user. If there are hints,
                pass them along to the object being retrieved
                to tell it how the value should be configured.
    Input Arguments: at least 1
        1. key - name of the object being retrieved
        2. ... - hints listed as strings
    Return Value: value of the object named key
    Notes: hints are listed as strings of the form
            "hintKey=hintVal". hintKey is the key for the hint
            and hintVal is the value to be applied to the hint.
            generally, unrecognized hints are ignored. the hints
            should be listed as comma separated strings in the
            function's argument list.
    Code Example:
    {{{
        data = """
            <?xml version="1.0"?>
            <run>
                <tool>
                    <about>Press Simulate to view results.</about>
                    <command>@tool/fermi @driver</command>
                </tool>
                <input>
                    <number id="temperature">
                        <about>
                            <label>Ambient temperature</label>
                            <description>Temperature of the environment.</description>
                        </about>
                        <units>K</units>
                        <min>0K</min>
                        <max>500K</max>
                        <default>300K</default>
                    </number>
                </input>
            </run>
        """

        lib = Rappture::Library()
        lib.loadXml(data)
        temp = lib.value("temperature","units=F")
        print "temp = %s\n" % (temp)
        # temp = 80.33
    }}}

lib.diff(lib2)
    Purpose: find the difference between two library objects
    Input Arguments: 1
        1. lib2 - other object used in comparison
    Return Value: List of differences
    Notes: None
    Code Example:
    {{{
        data1 = """
            <?xml version="1.0"?>
            <run>
                <tool>
                    <about>Press Simulate to view results.</about>
                    <command>@tool/fermi @driver</command>
                </tool>
                <input>
                    <number id="temperature">
                        <about>
                            <label>Ambient temperature</label>
                            <description>Temperature of the environment.</description>
                        </about>
                        <units>K</units>
                        <min>0K</min>
                        <max>500K</max>
                        <default>300K</default>
                    </number>
                    <number id="forel">
                        <about>
                            <label>Forel</label>
                            <description>Environment</description>
                        </about>
                        <units>cm</units>
                        <min>4cm</min>
                        <max>183cm</max>
                        <default>72cm</default>
                    </number>
                    <integer id="toops">
                        <about>
                            <label>Toops</label>
                            <description>Icks hafra doec weple</description>
                        </about>
                        <default>33</default>
                    </integer>
                </input>
            </run>
        """

        data2 = """
            <?xml version="1.0"?>
            <run>
                <tool>
                    <about>Press Simulate to view results.</about>
                    <command>@tool/fermi @driver</command>
                </tool>
                <input>
                    <integer id="toops">
                        <about>
                            <label>Toops</label>
                            <description>Icks hafra doec weple</description>
                        </about>
                        <default>33</default>
                    </integer>
                    <number id="Ef">
                        <about>
                            <label>Fermi Level</label>
                            <description>Energy at center of distribution.</description>
                        </about>
                        <units>eV</units>
                        <min>-10eV</min>
                        <max>10eV</max>
                        <default>0eV</default>
                    </number>
                    <number id="forel">
                        <about>
                            <label>Forel</label>
                            <description>Environment</description>
                        </about>
                        <units>cm</units>
                        <min>4cm</min>
                        <max>183cm</max>
                        <default>109cm</default>
                    </number>
                </input>
            </run>
        """

        lib1 = Rappture::Library()
        lib1.loadXml(data1)

        lib2 = Rappture::Library()
        lib2.loadXml(data2)

        diffs = lib1.diff(lib2)
        # - input.number(temperature) 300K
        # c input.number(forel) 72cm 109cm
        # + input.number(Ef)  0eV
    }}}

lib.remove(key)
    Purpose: remove the object from this library named "key"
    Input Arguments: 1
        1. key - name of the object to remove
    Return Value: None
    Notes: The object is removed and it's memory is deleted
    Code Example:
    {{{
        data = """
            <?xml version="1.0"?>
            <run>
                <tool>
                    <about>Press Simulate to view results.</about>
                    <command>@tool/fermi @driver</command>
                </tool>
                <input>
                    <number id="temperature">
                        <about>
                            <label>Ambient temperature</label>
                            <description>Temperature of the environment.</description>
                        </about>
                        <units>K</units>
                        <min>0K</min>
                        <max>500K</max>
                        <default>300K</default>
                    </number>
                    <number id="Ef">
                        <about>
                            <label>Fermi Level</label>
                            <description>Energy at center of distribution.</description>
                        </about>
                        <units>eV</units>
                        <min>-10eV</min>
                        <max>10eV</max>
                        <default>0eV</default>
                    </number>
                </input>
            </run>
        """

        lib = Rappture::Library()
        lib.loadXml(data)
        lib.remove("Ef")
        print lib.xml()

        # <?xml version="1.0"?>
        # <run>
        #     <tool>
        #         <about>Press Simulate to view results.</about>
        #         <command>@tool/fermi @driver</command>
        #     </tool>
        #     <input>
        #         <number id="temperature">
        #             <about>
        #                 <label>Ambient temperature</label>
        #                 <description>Temperature of the environment.</description>
        #             </about>
        #             <units>K</units>
        #             <min>0K</min>
        #             <max>500K</max>
        #             <default>300K</default>
        #         </number>
        #     </input>
        # </run>
    }}}

lib.xml()
    Purpose: return the Rappture1.1 xml representation of the
                objects stored in this library.
    Input Arguments: 0
    Return Value: None
    Notes: user is responsible for free'ing returned memory?
    Code Example:
    {{{
        data = """
            <?xml version="1.0"?>
            <run>
                <tool>
                    <about>Press Simulate to view results.</about>
                    <command>@tool/fermi @driver</command>
                </tool>
                <input>
                    <number id="temperature">
                        <about>
                            <label>Ambient temperature</label>
                            <description>Temperature of the environment.</description>
                        </about>
                        <units>K</units>
                        <min>0K</min>
                        <max>500K</max>
                        <default>300K</default>
                    </number>
                </input>
            </run>
        """

        lib = Rappture::Library()
        lib.loadXml(data)
        print lib.xml()

        # <?xml version="1.0"?>
        # <run>
        #     <tool>
        #         <about>Press Simulate to view results.</about>
        #         <command>@tool/fermi @driver</command>
        #     </tool>
        #     <input>
        #         <number id="temperature">
        #             <about>
        #                 <label>Ambient temperature</label>
        #                 <description>Temperature of the environment.</description>
        #             </about>
        #             <units>K</units>
        #             <min>0K</min>
        #             <max>500K</max>
        #             <default>300K</default>
        #         </number>
        #     </input>
        # </run>
    }}}

lib.outcome()
    Purpose: return the status of the object
    Input Arguments: 0
    Return Value: status of the object
    Notes: None
    Code Example:
    {{{
        data = """
            <?xml version="1.0"?>
            <run>
                <tool>
                    <about>Press Simulate to view results.</about>
                    <command>@tool/fermi @driver</command>
                </tool>
                <input>
                    <number id=\"temperature\">
                        <about>
                            <label>Ambient temperature</label>
                            <description>Temperature of the environment.</description>
                        </about>
                        <units>K</units>
                        <min>0K</min>
                        <max>500K</max>
                        <default>300K</default>
                    </number>
                </input>
            </run>
        """

        lib = Rappture::Library()
        lib.loadXml(data)
        if (lib.error() != 0) {
            print "there was an error while loading xml data"
            outcome = lib.outcome()
            sys.stderr.write(outcome.context())
            sys.stderr.write(outcome.remark())
        }
    }}}

lib.error()
    Purpose: return the status of the object
    Input Arguments: 0
    Return Value: status of the object
    Notes: None
    Code Example:
    {{{
        data = """
            <?xml version="1.0"?>
            <run>
                <tool>
                    <about>Press Simulate to view results.</about>
                    <command>@tool/fermi @driver</command>
                </tool>
                <input>
                    <number id="temperature">
                        <about>
                            <label>Ambient temperature</label>
                            <description>Temperature of the environment.</description>
                        </about>
                        <units>K</units>
                        <min>0K</min>
                        <max>500K</max>
                        <default>300K</default>
                    </number>
                </input>
            </run>
        """

        lib = Rappture::Library()
        lib.loadXml(data)
        if (lib.error() != 0) {
            print "there was an error while loading xml data"
            outcome = lib.outcome()
            sys.stderr.write(outcome.context())
            sys.stderr.write(outcome.remark())
        }
    }}}

lib.result(status)
    Purpose: write the stored objects to a data file and
                signal the end of processing.
    Input Arguments: 1
        1. int status - status of the simulation
    Return Value: None
    Notes: currently data file are written out as Rappture1.1
            xml. this function generates the RAPPTURE-RUN=>
            signal.
    Code Example:
    {{{
        data = """
            <?xml version="1.0"?>
            <run>
                <tool>
                    <about>Press Simulate to view results.</about>
                    <command>@tool/fermi @driver</command>
                </tool>
                <input>
                    <number id="temperature">
                        <about>
                            <label>Ambient temperature</label>
                            <description>Temperature of the environment.</description>
                        </about>
                        <units>K</units>
                        <min>0K</min>
                        <max>500K</max>
                        <default>300K</default>
                    </number>
                </input>
            </run>
        """

        lib = Rappture::Library()
        lib.loadXml(data)
        lib.result()
        # internal xml objects free'd
        # driver file written to disk
        # =RAPPTURE-RUN=>driver1234.xml signal sent to stdout
    }}}

lib.contains()
    Purpose: return a list of the Rappture objects
                stored in this library.
    Input Arguments: 0
    Return Value: list of the Rappture objects stored in
                    this library.
    Notes: None
    Code Example:
    {{{
        data = """
            <?xml version=\"1.0\"?>
            <run>
                <tool>
                    <about>Press Simulate to view results.</about>
                    <command>@tool/fermi @driver</command>
                </tool>
                <input>
                    <number id=\"temperature\">
                        <about>
                            <label>Ambient temperature</label>
                            <description>Temperature of the environment.</description>
                        </about>
                        <units>K</units>
                        <min>0K</min>
                        <max>500K</max>
                        <default>300K</default>
                    </number>
                    <number id=\"Ef\">
                        <about>
                            <label>Fermi Level</label>
                            <description>Energy at center of distribution.</description>
                        </about>
                        <units>eV</units>
                        <min>-10eV</min>
                        <max>10eV</max>
                        <default>0eV</default>
                    </number>
                </input>
            </run>
        """

        lib = Rappture::Library()
        lib.loadXml(data)
        xmlObjs = lib.contains()
        len xmlObjs
        # 2
        # xmlObjs contains objects (pointers or copies of objects?)
        print xmlObjs
        # ::Rappture::Number ::Rappture::Number
        foreach obj in xmlObjs {
            obj.vvalue()
        }
        # 300
        # 0
    }}}