source: trunk/examples/objects/api/python/library

Last change on this file was 1619, checked in by dkearney, 11 years ago

updating python objects api with example code, fixes for tcl objects api

File size: 18.3 KB
Line 
1Rappture.Library
2
3constructors
4    Rappture.Library()
5    Rappture.Library(lib2)
6
7methods
8    lib.loadXml(xmltext)
9    lib.loadFile(filename)
10    lib.value(key[, ...])
11    lib.diff(lib2)
12    lib.remove(key)
13    lib.xml()
14    lib.outcome()
15    lib.error()
16    lib.result(status)
17    lib.contains()
18
19---------------------------------------
20
21Rappture.Library()
22    Purpose: construct an empty Rappture Library object
23    Input Arguments: 0
24    Return Value: empty Rappture Library object
25    Notes: None
26    Code Example:
27    {{{
28        lib = Rappture.Library()
29    }}}
30
31Rappture.Library(lib2)
32    Purpose: construct a copy of a Rappture Library object
33    Input Arguments: 1
34        1. lib2 - Rappture Library object to be copied
35    Return Value: copy of a Rappture Library object
36    Notes: None
37    Code Example:
38    {{{
39        lib2 = Rappture.Library()
40        lib = Rappture.Library(lib2)
41    }}}
42
43lib.loadXml(xmltext)
44    Purpose: parse the Rappture1.1 xml data in "xmltext".
45                populate this library object with the Rappture
46                objects described in the xml data.
47    Input Arguments: 1
48        1. xmltext - string of Rappture1.1 xml data
49    Return Value: status of the object
50    Notes: None
51    Code Example:
52    {{{
53        xmltext = """
54            <?xml version="1.0"?>
55            <run>
56                <tool>
57                    <about>Press Simulate to view results.</about>
58                    <command>@tool/fermi @driver</command>
59                </tool>
60                <input>
61                    <number id=\"temperature\">
62                        <about>
63                            <label>Ambient temperature</label>
64                            <description>Temperature of the environment.</description>
65                        </about>
66                        <units>K</units>
67                        <min>0K</min>
68                        <max>500K</max>
69                        <default>300K</default>
70                    </number>
71                </input>
72            </run>"""
73        lib = Rappture.Library()
74        lib.loadXml(xmltext)
75    }}}
76
77lib.loadFile(filename)
78    Purpose: read the file "filename" and parse the
79                Rappture1.1 xml data found inside of it.
80                populate this library object with the Rappture
81                objects described in the xml data.
82    Input Arguments: 1
83        1. filename - name of file containing Rappture1.1
84                      xml data
85    Return Value: status of the object
86    Notes: None
87    Code Example:
88    {{{
89        data = """
90            <?xml version="1.0"?>
91            <run>
92                <tool>
93                    <about>Press Simulate to view results.</about>
94                    <command>@tool/fermi @driver</command>
95                </tool>
96                <input>
97                    <number id=\"temperature\">
98                        <about>
99                            <label>Ambient temperature</label>
100                            <description>Temperature of the environment.</description>
101                        </about>
102                        <units>K</units>
103                        <min>0K</min>
104                        <max>500K</max>
105                        <default>300K</default>
106                    </number>
107                </input>
108            </run>
109        """
110
111        filename = "driver1234.xml"
112        fp = open(filename,"w")
113        fp.write(data)
114        fp.close()
115        lib = Rappture.Library()
116        lib.loadFile(filename)
117    }}}
118
119lib.value(key[, ...])
120    Purpose: retrieve the value of the object named "key" and
121                return it to the user. If there are hints,
122                pass them along to the object being retrieved
123                to tell it how the value should be configured.
124    Input Arguments: at least 1
125        1. key - name of the object being retrieved
126        2. ... - hints listed as strings
127    Return Value: value of the object named key
128    Notes: hints are listed as strings of the form
129            "hintKey=hintVal". hintKey is the key for the hint
130            and hintVal is the value to be applied to the hint.
131            generally, unrecognized hints are ignored. the hints
132            should be listed as comma separated strings in the
133            function's argument list.
134    Code Example:
135    {{{
136        data = """
137            <?xml version="1.0"?>
138            <run>
139                <tool>
140                    <about>Press Simulate to view results.</about>
141                    <command>@tool/fermi @driver</command>
142                </tool>
143                <input>
144                    <number id="temperature">
145                        <about>
146                            <label>Ambient temperature</label>
147                            <description>Temperature of the environment.</description>
148                        </about>
149                        <units>K</units>
150                        <min>0K</min>
151                        <max>500K</max>
152                        <default>300K</default>
153                    </number>
154                </input>
155            </run>
156        """
157
158        lib = Rappture::Library()
159        lib.loadXml(data)
160        temp = lib.value("temperature","units=F")
161        print "temp = %s\n" % (temp)
162        # temp = 80.33
163    }}}
164
165lib.diff(lib2)
166    Purpose: find the difference between two library objects
167    Input Arguments: 1
168        1. lib2 - other object used in comparison
169    Return Value: List of differences
170    Notes: None
171    Code Example:
172    {{{
173        data1 = """
174            <?xml version="1.0"?>
175            <run>
176                <tool>
177                    <about>Press Simulate to view results.</about>
178                    <command>@tool/fermi @driver</command>
179                </tool>
180                <input>
181                    <number id="temperature">
182                        <about>
183                            <label>Ambient temperature</label>
184                            <description>Temperature of the environment.</description>
185                        </about>
186                        <units>K</units>
187                        <min>0K</min>
188                        <max>500K</max>
189                        <default>300K</default>
190                    </number>
191                    <number id="forel">
192                        <about>
193                            <label>Forel</label>
194                            <description>Environment</description>
195                        </about>
196                        <units>cm</units>
197                        <min>4cm</min>
198                        <max>183cm</max>
199                        <default>72cm</default>
200                    </number>
201                    <integer id="toops">
202                        <about>
203                            <label>Toops</label>
204                            <description>Icks hafra doec weple</description>
205                        </about>
206                        <default>33</default>
207                    </integer>
208                </input>
209            </run>
210        """
211
212        data2 = """
213            <?xml version="1.0"?>
214            <run>
215                <tool>
216                    <about>Press Simulate to view results.</about>
217                    <command>@tool/fermi @driver</command>
218                </tool>
219                <input>
220                    <integer id="toops">
221                        <about>
222                            <label>Toops</label>
223                            <description>Icks hafra doec weple</description>
224                        </about>
225                        <default>33</default>
226                    </integer>
227                    <number id="Ef">
228                        <about>
229                            <label>Fermi Level</label>
230                            <description>Energy at center of distribution.</description>
231                        </about>
232                        <units>eV</units>
233                        <min>-10eV</min>
234                        <max>10eV</max>
235                        <default>0eV</default>
236                    </number>
237                    <number id="forel">
238                        <about>
239                            <label>Forel</label>
240                            <description>Environment</description>
241                        </about>
242                        <units>cm</units>
243                        <min>4cm</min>
244                        <max>183cm</max>
245                        <default>109cm</default>
246                    </number>
247                </input>
248            </run>
249        """
250
251        lib1 = Rappture::Library()
252        lib1.loadXml(data1)
253
254        lib2 = Rappture::Library()
255        lib2.loadXml(data2)
256
257        diffs = lib1.diff(lib2)
258        # - input.number(temperature) 300K
259        # c input.number(forel) 72cm 109cm
260        # + input.number(Ef)  0eV
261    }}}
262
263lib.remove(key)
264    Purpose: remove the object from this library named "key"
265    Input Arguments: 1
266        1. key - name of the object to remove
267    Return Value: None
268    Notes: The object is removed and it's memory is deleted
269    Code Example:
270    {{{
271        data = """
272            <?xml version="1.0"?>
273            <run>
274                <tool>
275                    <about>Press Simulate to view results.</about>
276                    <command>@tool/fermi @driver</command>
277                </tool>
278                <input>
279                    <number id="temperature">
280                        <about>
281                            <label>Ambient temperature</label>
282                            <description>Temperature of the environment.</description>
283                        </about>
284                        <units>K</units>
285                        <min>0K</min>
286                        <max>500K</max>
287                        <default>300K</default>
288                    </number>
289                    <number id="Ef">
290                        <about>
291                            <label>Fermi Level</label>
292                            <description>Energy at center of distribution.</description>
293                        </about>
294                        <units>eV</units>
295                        <min>-10eV</min>
296                        <max>10eV</max>
297                        <default>0eV</default>
298                    </number>
299                </input>
300            </run>
301        """
302
303        lib = Rappture::Library()
304        lib.loadXml(data)
305        lib.remove("Ef")
306        print lib.xml()
307
308        # <?xml version="1.0"?>
309        # <run>
310        #     <tool>
311        #         <about>Press Simulate to view results.</about>
312        #         <command>@tool/fermi @driver</command>
313        #     </tool>
314        #     <input>
315        #         <number id="temperature">
316        #             <about>
317        #                 <label>Ambient temperature</label>
318        #                 <description>Temperature of the environment.</description>
319        #             </about>
320        #             <units>K</units>
321        #             <min>0K</min>
322        #             <max>500K</max>
323        #             <default>300K</default>
324        #         </number>
325        #     </input>
326        # </run>
327    }}}
328
329lib.xml()
330    Purpose: return the Rappture1.1 xml representation of the
331                objects stored in this library.
332    Input Arguments: 0
333    Return Value: None
334    Notes: user is responsible for free'ing returned memory?
335    Code Example:
336    {{{
337        data = """
338            <?xml version="1.0"?>
339            <run>
340                <tool>
341                    <about>Press Simulate to view results.</about>
342                    <command>@tool/fermi @driver</command>
343                </tool>
344                <input>
345                    <number id="temperature">
346                        <about>
347                            <label>Ambient temperature</label>
348                            <description>Temperature of the environment.</description>
349                        </about>
350                        <units>K</units>
351                        <min>0K</min>
352                        <max>500K</max>
353                        <default>300K</default>
354                    </number>
355                </input>
356            </run>
357        """
358
359        lib = Rappture::Library()
360        lib.loadXml(data)
361        print lib.xml()
362
363        # <?xml version="1.0"?>
364        # <run>
365        #     <tool>
366        #         <about>Press Simulate to view results.</about>
367        #         <command>@tool/fermi @driver</command>
368        #     </tool>
369        #     <input>
370        #         <number id="temperature">
371        #             <about>
372        #                 <label>Ambient temperature</label>
373        #                 <description>Temperature of the environment.</description>
374        #             </about>
375        #             <units>K</units>
376        #             <min>0K</min>
377        #             <max>500K</max>
378        #             <default>300K</default>
379        #         </number>
380        #     </input>
381        # </run>
382    }}}
383
384lib.outcome()
385    Purpose: return the status of the object
386    Input Arguments: 0
387    Return Value: status of the object
388    Notes: None
389    Code Example:
390    {{{
391        data = """
392            <?xml version="1.0"?>
393            <run>
394                <tool>
395                    <about>Press Simulate to view results.</about>
396                    <command>@tool/fermi @driver</command>
397                </tool>
398                <input>
399                    <number id=\"temperature\">
400                        <about>
401                            <label>Ambient temperature</label>
402                            <description>Temperature of the environment.</description>
403                        </about>
404                        <units>K</units>
405                        <min>0K</min>
406                        <max>500K</max>
407                        <default>300K</default>
408                    </number>
409                </input>
410            </run>
411        """
412
413        lib = Rappture::Library()
414        lib.loadXml(data)
415        if (lib.error() != 0) {
416            print "there was an error while loading xml data"
417            outcome = lib.outcome()
418            sys.stderr.write(outcome.context())
419            sys.stderr.write(outcome.remark())
420        }
421    }}}
422
423lib.error()
424    Purpose: return the status of the object
425    Input Arguments: 0
426    Return Value: status of the object
427    Notes: None
428    Code Example:
429    {{{
430        data = """
431            <?xml version="1.0"?>
432            <run>
433                <tool>
434                    <about>Press Simulate to view results.</about>
435                    <command>@tool/fermi @driver</command>
436                </tool>
437                <input>
438                    <number id="temperature">
439                        <about>
440                            <label>Ambient temperature</label>
441                            <description>Temperature of the environment.</description>
442                        </about>
443                        <units>K</units>
444                        <min>0K</min>
445                        <max>500K</max>
446                        <default>300K</default>
447                    </number>
448                </input>
449            </run>
450        """
451
452        lib = Rappture::Library()
453        lib.loadXml(data)
454        if (lib.error() != 0) {
455            print "there was an error while loading xml data"
456            outcome = lib.outcome()
457            sys.stderr.write(outcome.context())
458            sys.stderr.write(outcome.remark())
459        }
460    }}}
461
462lib.result(status)
463    Purpose: write the stored objects to a data file and
464                signal the end of processing.
465    Input Arguments: 1
466        1. int status - status of the simulation
467    Return Value: None
468    Notes: currently data file are written out as Rappture1.1
469            xml. this function generates the RAPPTURE-RUN=>
470            signal.
471    Code Example:
472    {{{
473        data = """
474            <?xml version="1.0"?>
475            <run>
476                <tool>
477                    <about>Press Simulate to view results.</about>
478                    <command>@tool/fermi @driver</command>
479                </tool>
480                <input>
481                    <number id="temperature">
482                        <about>
483                            <label>Ambient temperature</label>
484                            <description>Temperature of the environment.</description>
485                        </about>
486                        <units>K</units>
487                        <min>0K</min>
488                        <max>500K</max>
489                        <default>300K</default>
490                    </number>
491                </input>
492            </run>
493        """
494
495        lib = Rappture::Library()
496        lib.loadXml(data)
497        lib.result()
498        # internal xml objects free'd
499        # driver file written to disk
500        # =RAPPTURE-RUN=>driver1234.xml signal sent to stdout
501    }}}
502
503lib.contains()
504    Purpose: return a list of the Rappture objects
505                stored in this library.
506    Input Arguments: 0
507    Return Value: list of the Rappture objects stored in
508                    this library.
509    Notes: None
510    Code Example:
511    {{{
512        data = """
513            <?xml version=\"1.0\"?>
514            <run>
515                <tool>
516                    <about>Press Simulate to view results.</about>
517                    <command>@tool/fermi @driver</command>
518                </tool>
519                <input>
520                    <number id=\"temperature\">
521                        <about>
522                            <label>Ambient temperature</label>
523                            <description>Temperature of the environment.</description>
524                        </about>
525                        <units>K</units>
526                        <min>0K</min>
527                        <max>500K</max>
528                        <default>300K</default>
529                    </number>
530                    <number id=\"Ef\">
531                        <about>
532                            <label>Fermi Level</label>
533                            <description>Energy at center of distribution.</description>
534                        </about>
535                        <units>eV</units>
536                        <min>-10eV</min>
537                        <max>10eV</max>
538                        <default>0eV</default>
539                    </number>
540                </input>
541            </run>
542        """
543
544        lib = Rappture::Library()
545        lib.loadXml(data)
546        xmlObjs = lib.contains()
547        len xmlObjs
548        # 2
549        # xmlObjs contains objects (pointers or copies of objects?)
550        print xmlObjs
551        # ::Rappture::Number ::Rappture::Number
552        foreach obj in xmlObjs {
553            obj.vvalue()
554        }
555        # 300
556        # 0
557    }}}
Note: See TracBrowser for help on using the repository browser.