ConfigFileFormats.html

Revision 7539, 6.7 kB (checked in by anonymous, 7 years ago)
This commit was manufactured by cvs2svn to create tag 'RELENG_1_0_5_RELEASE'.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`

Line
1	<HTML>
2	<HEAD>
3	<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
4	<META NAME="Author" CONTENT="Christopher Just">
5	<META NAME="Description" CONTENT="This file describes the file formats of the VRLib Configuration system.">
6	<META NAME="GENERATOR" CONTENT="Mozilla/4.05 [en] (X11; I; IRIX64 6.4 IP30) [Netscape]">
7	<TITLE>VRLib Configuration File Formats</TITLE>
8	</HEAD>
9	<BODY TEXT="#000000" BGCOLOR="#FFFFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
10
11	<H2>
12	VRLib Configuration File Formats</H2>
13	This document discusses the formats used for the VRLib Configuration files.
14	It includes ChunkDesc files (which define the available types of ConfigChunks)
15	and Chunk files (containing lists of ConfigChunks).
16
17	<P>The Chunk and ChunkDesc files are plaintext ASCII files,
18	<H3>
19	I. Description of ChunkDesc (ConfigChunk Description) files.</H3>
20	A ChunkDesc file includes descriptions of different kinds of ConfigChunks.
21	It is a way to configure the configuration system itself. For example,
22	here are two entries that you might find in a ChunkDesc file:
23	<PRE>        chunk flockobirds
24	port string 1 port "serial port address"
25	offset double 3 offset "tracker coord offset from origin"
26	baudrate int 1 baud "serial port rate"
27	end
28
29	chunk display
30	name string 1 name "descriptive name"
31	origin double 3 origin "other help text"
32	size int 2 size ""
33	SGIpipe int 1 SGIpipe ""
34	xdisplay string 1 xdisplay ""
35	stereo bool 1 stereo ""
36	lowerleft double 3 lowerleft ""
37	lowerright double 3 lowerright ""
38	upperleft double 3 upperleft ""
39	end</PRE>
40	The first entry defines a chunk type called "flockobirds" that contains
41	three properties ("port", "offset", and "baudrate"). The second defines
42	a chunktype called "display" which contains 9 properties.
43
44	<P>Each property has a type - for example, the values that "port" can take
45	will be strings, such as "/dev/ttyd45", while baudrate will always have
46	integer values.
47
48	<P>It is possible for a property to have a set of values. For example,
49	the "display" chunk's "lowerleft", "lowerright", and "upperleft" properties
50	are meant to represent positions in 3d space. These can be represented
51	by a sequence of three doubles for the x, y, and z coordinates. The number
52	of values a property supports is listed directly to the right of the type
53	- the "3" in the line for "lowerleft", or the "1" for "stereo." If a property
54	might have a variable number of entries (perhaps as a list of active displays,
55	or such), use the number -1.
56
57	<P>The fourth word on each property line is the actual token to be used
58	to represent this property when reading/writing config files. Most often
59	this will be the same as the name of the property (which is used internally
60	for querying a ConfigChunk), but the options is provided to make the config
61	files more flexible or readable.
62
63	<P>The last thing on a property line is a help string. If the help string
64	contains spaces or is empty, it must be in quotes.
65
66	<P>For int type properties, there is also an optional set of enumeration
67	values, which can be placed between the token name and the help string.
68	For example:
69	<PRE>        chunk C2Setup
70	ActiveWalls int -1 ActiveWalls { front back left right top
71	bottom } "list of walls to show"</PRE>
72	then in a config file, instead of having to say "ActiveWalls { 0 3 4 }"
73	you can say, more intuitively, "ActiveWalls { front right top }". Values
74	in an enum start at 0, but can also be explicitly stated: ActiveWalls int
75	-1 ActiveWalls { front=3 back left right=0 } ""
76
77	<P>then the values assigned to each enumeration item will be 3,4,5, and
78	0, from left to right. In addition to the explicitly listed properties,
79	every chunktype has a property called "type", which has a single string
80	value. This provides a way to query for the type of the ConfigChunk. For
81	our examples above, the values of the "type" property would be "flockobirds"
82	and "display", respectively. Once all the properties for a particular chunk
83	have been listed, the symbol "end" is used to close the description. Here's
84	the standard form of a ConfigDesc entry: chunk <typename><property1><type><numentries><token><property2>...
85	... <propertyn>... end <Typename>can be any string value (that
86	hasn't already been defined as a typename). <Propertyx>can be any
87	string, except "type" (and all the property names for a given chunk type
88	should be unique). <Numentries>is an integer, greater than 0 or -1. <Token>is
89	any string (although all tokens in a given chunk type should be unique).
90	A ChunkDesc file is simply zero or more of these entries, followed by a
91	final "end".
92	<H3>
93	II. Description of ConfigChunk files</H3>
94	A config file is zero or more ConfigChunk entries terminated with the word
95	"end". Here are some example chunks:
96	<PRE>display
97	name "c2 rear wall"
98	XDisplay ":0.0"
99	stereo false
100	sgipipe 1
101	size { 9 12 }
102	lowerleft { 3.4 6.555 9.9 }
103	origin { 3.3 1.0 5.5 }
104	end
105
106	display
107	name "c2 Front Wall"
108	XDisplay ":0.0"
109	stereo true
110	end
111
112	c2setup
113	c2width 3.3
114	walls { front left right top bottom }
115	c2height 3.5
116	end
117	End</PRE>
118
119	<PRE>- Notes on parsing:
120
121	Reserved words/tokens:
122
123	in Config files:
124	end
125	true
126	false
127	yes
128	no
129	in ChunkDesc files:
130	chunk
131	end
132	string
133	double
134	int
135	boolean
136	1. In order to have words that the parser will think are tokens interpreted
137	as strings, surround them with quotes ("").  This is also necessary
138	in order to have strings with whitespace considered as single strings.
139	2. bug - there's no way to include quotes inside a quoted string. (Is this
140	possible in non-quoted strings?).</PRE>
141
142	</BODY>
143	</HTML>

Note: See TracBrowser for help on using the browser.

root/juggler/tags/1.0.5/Doc/ConfigFileFormats.html

Download in other formats: