1 /*
  2  * 	Copyright (C) 2012-2013 DFKI GmbH
  3  * 	Deutsches Forschungszentrum fuer Kuenstliche Intelligenz
  4  * 	German Research Center for Artificial Intelligence
  5  * 	http://www.dfki.de
  6  * 
  7  * 	Permission is hereby granted, free of charge, to any person obtaining a 
  8  * 	copy of this software and associated documentation files (the 
  9  * 	"Software"), to deal in the Software without restriction, including 
 10  * 	without limitation the rights to use, copy, modify, merge, publish, 
 11  * 	distribute, sublicense, and/or sell copies of the Software, and to 
 12  * 	permit persons to whom the Software is furnished to do so, subject to 
 13  * 	the following conditions:
 14  * 
 15  * 	The above copyright notice and this permission notice shall be included 
 16  * 	in all copies or substantial portions of the Software.
 17  * 
 18  * 	THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS 
 19  * 	OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 
 20  * 	MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 
 21  * 	IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 
 22  * 	CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 
 23  * 	TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 
 24  * 	SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 25  */
 26 
 27 
 28 define(
 29 	/**
 30 	 * This module holds functions / classes for template parsing.
 31 	 * 
 32 	 * <p>
 33 	 * This module contains definitions for constants used in the Template Parser and Renderer.
 34 	 * 
 35 	 * 
 36 	 * 
 37 	 * @namespace
 38 	 * @name mmir.parser
 39 	 * @example
 40 	 * //access the parser module
 41 	 * // (it is a sub-module of mmir!)
 42 	 * var someConst = mmir.parser.element.INCLUDE_SCRIPT;
 43 	 * ...
 44 	 * 
 45 	 */
 46 	function(
 47 ){
 48 
 49 	
 50 var parser = {
 51 	/**
 52 	 * @namespace
 53 	 * @name mmir.parser.element
 54 	 */
 55 	element: {
 56 
 57 	//TODO detect&use Object.defineProperty (if positively detected), e.g.:
 58 //		Object.defineProperty(parser.element, 'INCLUDE_SCRIPT', {value : 0, writable : false, configurable : false, enumerable : true});
 59 
 60 	/**
 61 	 * Constant for template expression type <tt>include script</tt>.
 62 	 * 
 63 	 * <p>
 64 	 * The template expression generates a script TAG.
 65 	 * 
 66 	 * <p>
 67 	 * Properties of {@link mmir.parser.ParsingResult} objects with type INCLUDE_SCRIPT:
 68 	 * <ul>
 69 	 * 	<li><strong>scriptPath</strong>: the path / URL to the resource</li>
 70 	 * 	<li><strong>scriptPathType</strong>: the type of the <tt>scriptPath</tt>
 71 	 * 		 field: one of <code>StringLiteral</code>, <code>Identifier</code>, <code>IdentifierNameAmpersatStart</code></li>
 72 	 * </ul>
 73 	 * 
 74 	 * @memberOf @memberOf mmir.parser.element
 75 	 * @constant
 76 	 * @type Number
 77 	 * @public
 78 	 */
 79 	INCLUDE_SCRIPT 		: 0,
 80 	/**
 81 	 * Constant for template expression type <tt>include style</tt>.
 82 	 * 
 83 	 * <p>
 84 	 * The template expression generates a style reference, i.e.
 85 	 * a link TAG with <tt>rel</tt> attribute <code>stylesheet</code>.
 86 	 * 
 87 	 * <p>
 88 	 * Properties of {@link mmir.parser.ParsingResult} objects with type INCLUDE_STYLE:
 89 	 * <ul>
 90 	 * 	<li><strong>stylePath</strong>: </li>
 91 	 * 	<li><strong>stylePathType</strong>: the type of the <tt>stylePath</tt>
 92 	 * 		 field: one of <code>StringLiteral</code>, <code>Identifier</code>, <code>IdentifierNameAmpersatStart</code></li>
 93 	 * </ul>
 94 	 * 
 95 	 * @memberOf mmir.parser.element
 96 	 * @constant
 97 	 * @type Number
 98 	 * @public
 99 	 */
100 	INCLUDE_STYLE 		: 2,
101 	/**
102 	 * Constant for template expression type <tt>localize</tt>.
103 	 * 
104 	 * <p>
105 	 * The template expression inserts a localized String.
106 	 * 
107 	 * <p>
108 	 * Properties of {@link mmir.parser.ParsingResult} objects with type LOCALIZE:
109 	 * <ul>
110 	 * 	<li><strong>name</strong>: the name/identifier for the localized String</li>
111 	 * 	<li><strong>nameType</strong>: the type of the <tt>name</tt>
112 	 * 		 field: one of <code>StringLiteral</code>, <code>Identifier</code>, <code>IdentifierNameAmpersatStart</code></li>
113 	 * </ul>
114 	 * 
115 	 * @memberOf mmir.parser.element
116 	 * @constant
117 	 * @type Number
118 	 * @public
119 	 */
120 	LOCALIZE	 		: 4,
121 	/**
122 	 * Constant for template expression type <tt>yield declaration</tt>.
123 	 * 
124 	 * <p>
125 	 * The template expression declares a yield section.
126 	 * 
127 	 * <p>
128 	 * Properties of {@link mmir.parser.ParsingResult} objects with type YIELD_DECLARATION:
129 	 * <ul>
130 	 * 	<li><strong>name</strong>: the name/identifier for the yield section</li>
131 	 * 	<li><strong>nameType</strong>: the type of the <tt>name</tt>
132 	 * 		 field: one of <code>StringLiteral</code>, <code>Identifier</code>, <code>IdentifierNameAmpersatStart</code></li>
133 	 * </ul>
134 	 * 
135 	 * @memberOf mmir.parser.element
136 	 * @constant
137 	 * @type Number
138 	 * @public
139 	 */
140 	YIELD_DECLARATION 	: 8,
141 	/**
142 	 * Constant for template expression type <tt>yield content</tt>.
143 	 * 
144 	 * <p>
145 	 * The template expression specifies the content of a yield section.
146 	 * 
147 	 * <p>
148 	 * A yield section corresponds to a {@link ContentElement}:
149 	 * Its content can itself contain HTML content as well as template expressions.
150 	 * 
151 	 * @memberOf mmir.parser.element
152 	 * @constant
153 	 * @type Number
154 	 * @public
155 	 */
156 	YIELD_CONTENT 		: 16,
157 	/**
158 	 * Constant for template expression type <tt>code block</tt>.
159 	 * 
160 	 * <p>
161 	 * The template expression represents a compiled code block (script).
162 	 * 
163 	 * <p>
164 	 * Properties of {@link mmir.parser.ParsingResult} objects with type BLOCK:
165 	 * <ul>
166 	 * 	<li><strong>scriptContent</strong> {String}: <tt>OPTIONALLY</tt> the script code as a String</li>
167 	 * 	<li><strong>scriptEval</strong> {Function}: the compiled script code in form of a function. The 
168 	 * 							function takes one argument: the current data-object.</li>
169 	 * </ul>
170 	 * 
171 	 * @memberOf mmir.parser.element
172 	 * @constant
173 	 * @type Number
174 	 * @public
175 	 */
176 	BLOCK 				: 32,
177 	/**
178 	 * Constant for template expression type <tt>code statement</tt>.
179 	 * 
180 	 * <p>
181 	 * The template expression represents a compiled code statement (script).
182 	 * 
183 	 * <p>
184 	 * Properties of {@link mmir.parser.ParsingResult} objects with type STATEMENT:
185 	 * <ul>
186 	 * 	<li><strong>scriptContent</strong> {String}: <tt>OPTIONALLY</tt> the script code as a String</li>
187 	 * 	<li><strong>scriptEval</strong> {Function}: the compiled script code in form of a function. The 
188 	 * 							function takes one argument: the current data-object.</li>
189 	 * </ul>
190 	 * 
191 	 * @memberOf mmir.parser.element
192 	 * @constant
193 	 * @type Number
194 	 * @public
195 	 */
196 	STATEMENT 			: 64,
197 	/**
198 	 * Constant for template expression type <tt>helper</tt>.
199 	 * 
200 	 * <p>
201 	 * The template expression will invoke a function in the {@link Helper} instance
202 	 * (depending of the {@link Controller}, in which's view definition this template expression is used).
203 	 * 
204 	 * <p>
205 	 * Properties of {@link mmir.parser.ParsingResult} objects with type HELPER:
206 	 * <ul>
207 	 * 	<li><strong>helper</strong>: the name of the helper function</li>
208 	 * 	<li><strong>helperType</strong>: the type of the <tt>helper</tt>
209 	 * 		 field: one of <code>StringLiteral</code>, <code>Identifier</code>, <code>IdentifierNameAmpersatStart</code></li>
210 	 * 	<li><strong>argsEval</strong> {Function}: OPTIONALLY compiled getter Function for retrieving the current ARGS 
211 	 * 			(optional argument) of the helper expression. The function takes one argument: the current data-object.</li>
212 	 * </ul>
213 	 * 
214 	 * @memberOf mmir.parser.element
215 	 * @constant
216 	 * @type Number
217 	 * @public
218 	 */
219 	HELPER	 			: 128,
220 	/**
221 	 * Constant for template expression type <tt>if</tt>.
222 	 * 
223 	 * <p>
224 	 * The template expression represents an if-expression, including the content-block
225 	 * that follows the condition-statement of the if-expression.
226 	 * 
227 	 * <p>
228 	 * Properties of {@link mmir.parser.ParsingResult} objects with type IF:
229 	 * <ul>
230 	 * 	<li><strong>ifEval</strong> {Function}: the condition statement, that was compiled into a Function. The 
231 	 * 							function takes one argument: the current data-object.</li>
232 	 * 	<li><strong>content</strong> {ContentElement}: the HTML / template content that should be render, in case the
233 	 * 					if-expression evaluates to <code>true</code>.</li>
234 	 *  <li><strong>elseContent</strong> {@link mmir.parser.ParsingResult}: OPTIONALLY a ParsingResult
235 	 *  					representing an else-expression, see {@link mmir.parser.element.ELSE}.</li>
236 	 * </ul>
237 	 * 
238 	 * @memberOf mmir.parser.element
239 	 * @constant
240 	 * @type Number
241 	 * @public
242 	 */
243 	IF		 			: 256,
244 	/**
245 	 * Constant for template expression type <tt>else</tt>.
246 	 * 
247 	 * <p>
248 	 * The template expression represents an else-expression (including its content-block);
249 	 * an else-expression may occur in combination with an if-expression, see {@link mmir.parser.element.IF}.
250 	 * 
251 	 * <p>
252 	 * Properties of {@link mmir.parser.ParsingResult} objects with type ELSE:
253 	 * <ul>
254 	 * 	<li><strong>content</strong> {ContentElement}: the HTML / template content that should be render, in case the
255 	 * 					if-expression (to which the else-expression belongs) evaluates to <code>false</code>.</li>
256 	 * </ul>
257 	 * 
258 	 * @memberOf mmir.parser.element
259 	 * @constant
260 	 * @type Number
261 	 * @public
262 	 */
263 	ELSE	 			: 512,
264 	/**
265 	 * Constant for template expression type <tt>for</tt>.
266 	 * 
267 	 * <p>
268 	 * The template expression represents for-expression (including its content-block);
269 	 * 
270 	 * <p>
271 	 * Properties of {@link mmir.parser.ParsingResult} objects with type FOR:
272 	 * <ul>
273 	 * 	<li><strong>forControlType</strong> {String}: the type of for-loop, either <code>FORITER</code> or <code>FORSTEP</code></li>
274 	 * 	<li><strong>forInitEval</strong> {Function}: the initialization statement of the for-expression, compiled into
275 	 * 									a Function. The function takes one argument: the current data-object.</li>
276 	 * 		
277 	 * 	<li><code>FORITER</code>: <code>@for(PROP in OBJ){ ... }@</code>
278 	 * 	 <ul>
279 	 * 		<li><strong>forIterator</strong> {Object}: an iterator object with functions <code>hasNext() : Boolean</code> and
280 	 * 					<code>next() : String</code> (which returns the name of the property currently iterated).</li>
281 	 * 		<li><strong>forPropName</strong> {String}: the variable name for the property which is currently iterated over.</li>
282 	 * 	 </ul>
283 	 * 	</li>
284 	 * 	<li><code>FORSTEP</code>: <code>@for(INIT; CONDITION; INCREMENT){ ... }@</code>
285 	 * 	 <ul>
286 	 * 		<li><strong>forConditionEval</strong> {Function}: the condition statement of the for-expression, compiled into
287 	 * 											a Function. The function takes one argument: the current data-object.</li>
288 	 * 		<li><strong>forIncrementEval</strong> {Function}: the increment statement of the for-expression, compiled into
289 	 * 											a Function. The function takes one argument: the current data-object.</li>
290 	 * 	 </ul>
291 	 * 	</li>
292 	 * 	<li><strong>content</strong> {ContentElement}: the HTML / template content that should be rendered
293 	 * 								 during each iteration of the for-loop.</li>
294 	 * </ul>
295 	 * 
296 	 * @memberOf mmir.parser.element
297 	 * @constant
298 	 * @type Number
299 	 * @public
300 	 */
301 	FOR		 			: 1024,
302 	/**
303 	 * Constant for template expression type <tt>render</tt>.
304 	 * 
305 	 * <p>
306 	 * The template expression renders a <tt>partial view</tt> into a view.
307 	 * 
308 	 * 
309 	 * <p>
310 	 * Properties of {@link mmir.parser.ParsingResult} objects with type RENDER:
311 	 * <ul>
312 	 * 	<li><strong>partial</strong>: the name of the partial view</li>
313 	 * 	<li><strong>partialType</strong>: the type of the <tt>partial</tt>
314 	 * 		 field: one of <code>StringLiteral</code>, <code>Identifier</code>, <code>IdentifierNameAmpersatStart</code></li>
315 	 * 	<li><strong>controller</strong>: the name of the controller, to which the partial view definition belongs</li>
316 	 * 	<li><strong>controllerType</strong>: the type of the <tt>controller</tt>
317 	 * 		 field: one of <code>StringLiteral</code>, <code>Identifier</code>, <code>IdentifierNameAmpersatStart</code></li>
318 	 * 	<li><strong>argsEval</strong> {Function}: OPTIONALLY compiled getter Function for retrieving the current ARGS 
319 	 * 								(optional argument) of the render expression. The function takes one argument: the current data-object.</li>
320 	 * </ul>
321 	 * 
322 	 * @memberOf mmir.parser.element
323 	 * @constant
324 	 * @type Number
325 	 * @public
326 	 */
327 	RENDER	 			: 2048,
328 	/**
329 	 * Constant for template expression type <tt>escape enter</tt>.
330 	 * 
331 	 * <p>
332 	 * The template expression represents an escape statement (when entering a template expression);
333 	 * escaping means, that the following sequence is not interpreted as template expression.
334 	 * 
335 	 * <p>
336 	 * Properties of {@link mmir.parser.ParsingResult} objects with type ESCAPE_ENTER:
337 	 * <ul>
338 	 * 	<li><strong>text</strong> {String}: the text that will be rendered (i.e. without the escape-character(s) itself).</li>
339 	 * </ul>
340 	 * 
341 	 * @memberOf mmir.parser.element
342 	 * @constant
343 	 * @type Number
344 	 * @public
345 	 */
346 	ESCAPE_ENTER		: 4096,
347 	/**
348 	 * Constant for template expression type <tt>escape exit</tt>.
349 	 * 
350 	 * <p>
351 	 * The template expression represents an escape statement (when exiting a template expression);
352 	 * escaping means, that the following sequence is not interpreted as template expression.
353 	 * 
354 	 * <p>
355 	 * Properties of {@link mmir.parser.ParsingResult} objects with type ESCAPE_EXIT:
356 	 * <ul>
357 	 * 	<li><strong>text</strong> {String}: the text that will be rendered (i.e. without the escape-character(s) itself).</li>
358 	 * </ul>
359 	 * 
360 	 * @memberOf mmir.parser.element
361 	 * @constant
362 	 * @type Number
363 	 * @public
364 	 */
365 	ESCAPE_EXIT			: 8192,
366 
367 	/**
368 	 * Constant for for-expression type <tt>iter</tt> ("iteration").
369 	 * 
370 	 * <p>
371 	 * This type identifies an ITERATION type for-expression.
372 	 * 
373 	 * 
374 	 * @memberOf mmir.parser.element
375 	 * @constant
376 	 * @type Number
377 	 * @public
378 	 * 
379 	 * @see parser.element.FOR
380 	 */
381 	FOR_TYPE_ITER		: 16384,
382 	/**
383 	 * Constant for for-expression type <tt>step</tt> ("step-wise").
384 	 * 
385 	 * <p>
386 	 * This type identifies an STEP-wise type for-expression.
387 	 * 
388 	 * 
389 	 * @memberOf mmir.parser.element
390 	 * @constant
391 	 * @type Number
392 	 * @public
393 	 * 
394 	 * @see parser.element.FOR
395 	 */
396 	FOR_TYPE_STEP		: 32768,
397 
398 	/**
399 	 * Constant for template expression type <tt>variable declaration</tt>.
400 	 * 
401 	 * <p>
402 	 * The template expression represents a variable declaration.
403 	 * 
404 	 * <p>
405 	 * Properties of {@link mmir.parser.ParsingResult} objects with type VAR_DECLARATION:
406 	 * <ul>
407 	 * 	<li><strong>name</strong>: the name for the variable (without the leading <tt>@</tt> of template variables)</li>
408 	 * 	<li><strong>nameType</strong>: the type of the <tt>name</tt> field: <code>StringLiteral</code></li>
409 	 * </ul>
410 	 * 
411 	 * @memberOf mmir.parser.element
412 	 * @constant
413 	 * @type Number
414 	 * @public
415 	 */
416 	VAR_DECLARATION		: 65536,
417 	/**
418 	 * Constant for template expression type <tt>variable reference</tt>.
419 	 * 
420 	 * <p>
421 	 * This template expression is used within JavaScript code blocks / statements,
422 	 * in order to replace the occurrence of the <tt>template variable</tt> by an
423 	 * appropriate getter function, that retrieves the current value of the variable
424 	 * during the execution of the script code.
425 	 * 
426 	 * <p>
427 	 * NOTE: this is used during compilation of the Function objects, used e.g. by BLOCK, STATEMENT, FOR etc.
428 	 * 
429 	 * <p>
430 	 * NOTE: the name of the variable is extracted from the raw-template text during processing/compilation
431 	 * 		 of the Functions.
432 	 * 
433 	 * @memberOf mmir.parser.element
434 	 * @constant
435 	 * @type Number
436 	 * @public
437 	 */
438 	VAR_REFERENCE		: 131072,
439 
440 	/**
441 	 * Constant for template expression type <tt>comment</tt>.
442 	 * 
443 	 * <p>
444 	 * The template expression represents a template-comment: the content of the comment will be ignored
445 	 * (that is: removed during processing of the template).
446 	 * 
447 	 * @memberOf mmir.parser.element
448 	 * @constant
449 	 * @type Number
450 	 * @public
451 	 */
452 	COMMENT				: 262144,
453 
454 	/**
455 	 * Constant for <tt>data</tt> name that is used to hold the <tt>current data</tt>:
456 	 * this name will be used for the argument name of generated/compiled Functions, and in the Function code block
457 	 * appropriate getter/setter expression will be inserted.
458 	 * 
459 	 * @memberOf mmir.parser.element
460 	 * @constant
461 	 * @type String
462 	 * @public
463 	 */
464 	DATA_NAME				: '__$$DATA$$__',
465 	/**
466 	 * Constant for the name of the reserved <tt>data</tt> variable: the optional data argument is passed in 
467 	 * into rendering-calls for views, layouts etc. (see PresentationManager)
468 	 * 
469 	 * @memberOf mmir.parser.element
470 	 * @constant
471 	 * @type String
472 	 * @public
473 	 */
474 	DATA_ARGUMENT_NAME		: '@data',
475 	/**
476 	 * Constant for the name of the reserved <tt>argument</tt> variable: some template expressions
477 	 * have an (optional) <tt>argument</tt> argument, which can be accessed using the variable name
478 	 * within the template expressions inner content-/code-blocks. 
479 	 * 
480 	 * @memberOf mmir.parser.element
481 	 * @constant
482 	 * @type String
483 	 * @public
484 	 */
485 	ARGUMENT_ARGUMENT_NAME	: '@argument'
486 	
487 	}//END element: {...
488 
489 };//END: parser: {...
490 
491 return parser;
492 });
493