Context Navigation

library @ 2979

Last change on this file since 2979 was 1619, checked in by dkearney, 15 years ago
updating python objects api with example code, fixes for tcl objects api
File size: 18.3 KB

Line
1	Rappture.Library
2
3	constructors
4	Rappture.Library()
5	Rappture.Library(lib2)
6
7	methods
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
21	Rappture.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
31	Rappture.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
43	lib.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
77	lib.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
119	lib.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
165	lib.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
263	lib.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
329	lib.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
384	lib.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
423	lib.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
462	lib.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
503	lib.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.

Download in other formats:

Original Format