-
Notifications
You must be signed in to change notification settings - Fork 34
/
FormatSpecification.txt
195 lines (195 loc) · 6.77 KB
/
FormatSpecification.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
/********************************************************************
*
* FORMAT
*
*********************************************************************
*
* FILE HEADER
* ===========================
* A grammar file must start with the grammar name and tier in the
* following format:
*
* ; grammar name MyGrammar
* ; grammar tier High
*
* Accepted values for the tier are Easy, Moderate, and High.
*
* After defining the grammar's name and tier, other grammar files
* can be imported with the following directives:
*
* ; load path/to/grammar/file.txt
* ; import path/to/grammar/file.txt
* ; import path/to/grammar/file.txt as $nonterminal
*
* The first directive loads all the non-terminals in the referred
* grammar file as if they were explicitly in the file being loaded
* with the same effect of concatenating both files. The second
* directive acts like the first one but skipping the $Main non-
* terminal of the second grammar, making non-terminals available for
* re-use, but not being attached to the production graph. In
* contrast the third directive makes accessible only the $Main rule
* of the imported grammar via $nonterminal (other imported rules are
* internally renamed).
*
*
* Remarks:
* - $nonterminal can be any valid non-terminal.
* - The path to the grammar file may be enclosed within double
* quotes and be a relative path. If the file cannot be found,
* a {void} wildcard (see below) will be used, specifying the
* nature of the error as meta-data.
*
*
*
* ROOT
* ===========================
* The root rule S of the grammar is the $Main Non-Terminal. In
* order for the grammar to be valid, it must contain at least
* one $Main rule.
*
*
*
* Non-Terminal identifiers
* ===========================
* A valid Non-Terminal identifier is a sequence of one or more
* letters, digits, or underscore characters (_). Spaces, punctuation
* marks, and symbols cannot be part of a Non-Terminal identifier.
*
*
*
* Wildcards
* ===========================
* Wilcards are strings within braces which are used during random
* sentence generation, replacing them by random values. The same
* random value may be specified for a set of wildcards by specifying
* an ID. Also, the type may be optionally specified. Syntax is as
* follows:
*
* {wildcard [type] [id] [where condition] [meta:[metadata]]}
*
* When the "where" literal string is found within a wildcard, the
* condition following it is evaluated while looking for replacements
* (see Filtering Results).
*
* When the "meta:" literal string is found within a wildcard, all
* text following it is addressed as metadata. While metadata is not
* part of the generated sentence, it can be used to display
* additional information.
*
* The following wildcards are defined:
* {category} An object category.
* Types are ignored.
* {gesture} A gesture name.
* Types are ignored.
* {location} Any location.
* Types may be [room|placement|beacon]
* {name} A person name.
* Types may be [male|female]
* {object} An object name.
* Types may be [known|alike]
* {question} The "question" literal string.
* Types are ignored. Metadata contains a question/answer
* from the predefined questions set.
* {void} Void construct used to inject metadata.
*
* Types are ignored.
*
*
* Also, the following alias are defined:
*
* {beacon} Alias for {location beacon}
* {aobject} Alias for {object alike}
* {female} Alias for {name female}
* {kobject} Alias for {object known}
* {male} Alias for {name male}
* {placement} Alias for {location placement}
* {room} Alias for {location room}
* {sobject} Alias for {object special}
*
*
*
* Filtering results
* ---------------------------
* Replacements can be filtered by adding conditions after the
* "where" literal string. Such replacements must target an specific
* property of the type used for wildcard replacement. For instance,
* consider the following examples:
*
* {kobject where Category="Food"}
* {object where Category="Food" and Type="Known"}
*
* Both wildcards are equivalent and will be replaced by a random
* known object from the Food category, if there is such category.
* Conditions support wildcard nesting, for which the following
* example is also valid.
*
* $Main = {object where Category="{category 1}""} belongs to
* {category 1 where Name!="Cleaning Stuff"}
*
* In cases when the query returns no results, the condition can't
* be met and another rule will be attempted. This is the case when
* a property is not present, so it can't be evaluated. Exceptions to
* this rule are 1) evaluating a property against literal "null"
* (without quotes), which is evaluated as true when the property is
* absent; and 2) evaluating an inexistent property against a boolean
* (true or false), which will implicitly assume that the property exists
* and has its value set to false.
*
*
*
*
* Obfuscating information
* ===========================
* A wildcard ended with a question mark will be replaced by an
* obfuscated value instead of the random value choosen by that
* wildcard, which will be included as metadata. The obfuscation is
* performed as follows (wildcards not shown can not be obfuscated):
*
* {category?} The "objects" literal string
* {location?} The "room" literal string for rooms, for placements
* and beacons, the room to which the location belongs.
* {object?} The category to which the object belongs.
*
*
*
* Referencing
* ===========================
*
* Pronouns
* ---------------------------
* Wildcards can be referenced with the {pron} construct.
* By default, the {pron} construct refers to the last wilcard found
* in the following order:
*
* - {name} wildcards
* - {object} wildcards
* - last wildcard found
*
* By default the {pron} construct is replaced with a Personal Pronoun
* (OBJECTIVE CASE), namely: him, her, it. Subjective cases of the
* personal pronoun (he, she, it) are also supported by setting the
* type of the {pron} construct to the `sub` value. Namely:
*
* {pron} Reference with pronoun, objective case.
* {pron obj} Reference with pronoun, objective case (explicit).
* {pron sub} Reference with pronoun, subjective case.
*
* Likewise, possessive pronouns can be specified in both cases,
* absolute (mine, yours, theirs) and adjective (my, your, their) which
* is default. Shortcuts are defined for convenience as shown below:
*
* {pron pos} Reference with possessive pronoun, adjective case.
* {pron pab} Reference with possessive pronoun, absolute case.
* {pron paj} Reference with possessive pronoun, adjective case.
* {pron posabs} Reference with possessive pronoun, absolute case.
* {pron posadj} Reference with possessive pronoun, adjective case.
*
*
*
* Commenting
* ===========================
* C/C++/Java comments are permitted.
* In addition, any words, spaces, or marks after # or % or ;
* are ignored
*
********************************************************************/