source: trunk/examples/objects/api/tcl/library @ 1619

Last change on this file since 1619 was 1610, checked in by dkearney, 14 years ago

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