1 ///////////////////////////////////////////////////////////////////////////////
2 // Copyright (c) 2000-2014 Ericsson Telecom AB
3 // All rights reserved. This program and the accompanying materials
4 // are made available under the terms of the Eclipse Public License v1.0
5 // which accompanies this distribution, and is available at
6 // http://www.eclipse.org/legal/epl-v10.html
7 ///////////////////////////////////////////////////////////////////////////////
8 #ifndef _Ttcn_Template_HH
9 #define _Ttcn_Template_HH
12 #include "../Value.hh"
13 #include "../vector.hh"
14 #include "AST_ttcn3.hh"
15 #include "Templatestuff.hh"
19 using namespace Common;
23 class LengthRestriction;
27 class IndexedTemplate;
28 class IndexedTemplates;
30 /** Represents a (single or compound) template body. */
31 class Template : public GovernedSimple {
35 /** type of template */
37 TEMPLATE_ERROR, /**< erroneous template */
38 TEMPLATE_NOTUSED, /**< not used symbol (-) */
39 OMIT_VALUE, /**< omit */
40 ANY_VALUE, /**< any value (?) */
41 ANY_OR_OMIT, /**< any or omit (*) */
42 SPECIFIC_VALUE, /**< specific value */
43 TEMPLATE_REFD, /**< reference to another template */
44 TEMPLATE_INVOKE, /** template returning invoke */
45 TEMPLATE_LIST, /**< value list notation */
46 NAMED_TEMPLATE_LIST, /**< assignment notation */
47 INDEXED_TEMPLATE_LIST, /**< assignment notation with array indices */
48 VALUE_LIST, /**< value list match */
49 COMPLEMENTED_LIST, /**< complemented list match */
50 VALUE_RANGE, /**< value range match */
51 SUPERSET_MATCH, /**< superset match */
52 SUBSET_MATCH, /**< subset match */
53 PERMUTATION_MATCH, /**< permutation match */
54 ALL_FROM, /**< "all from" as part of a larger list e.g. permutation, superset, subset, etc. */
55 VALUE_LIST_ALL_FROM, /**< "all from" in a value list, itself in a larger list */
56 BSTR_PATTERN, /**< bitstring pattern */
57 HSTR_PATTERN, /**< hexstring pattern */
58 OSTR_PATTERN, /**< octetstring pattern */
59 CSTR_PATTERN, /**< character string pattern */
60 USTR_PATTERN /**< universal charstring pattern */
63 /** Status codes for the verification of template body completeness. */
65 C_MUST_COMPLETE, /**< the body must be completely specified */
66 C_MAY_INCOMPLETE, /**< the body may be incompletely specified */
67 C_PARTIAL /**< some parts of the body may be incomplete,
68 * the others must be complete */
72 /** Determines type of the template. Only this field is used at
73 * ANY_VALUE, ANY_OR_OMIT and OMIT_VALUE templates */
74 templatetype_t templatetype;
76 /** This union holds the ``body'' of the template. The
77 * templatetype field is used to select between different
80 /** Holds the concrete single value of the template for single
82 Value *specific_value;
85 Template *refd; /**< cache */
86 Template *refd_last; /**< cache */
88 /** Used for TEMPLATE_LIST, VALUE_LIST, COMPLEMENTED_LIST,
89 * SUPERSET_MATCH, SUBSET_MATCH and PERMUTATION_MATCH constructs. */
91 /** Used by NAMED_TEMPLATE_LIST */
92 NamedTemplates *named_templates;
93 /** Used by INDEXED_TEMPLATE_LIST */
94 IndexedTemplates *indexed_templates;
95 /** Used by ALL_FROM */
97 /** This is used for VALUE_RANGE template upper and lower
99 ValueRange *value_range;
100 /** Pattern contains basic string templates containing the any
101 * element (?), any element or no element (*) wildcards .
102 * Used by BSTR_PATTERN, HSTR_PATTERN, OSTR_PATTERN */
104 /** PatternString contains the character string pattern matching
105 * constructions (including references).
106 * Used by CSTR_PATTERN, USTR_PATTERN */
107 PatternString *pstring;
108 /** Used by TEMPLATE_INVOKE */
111 Ttcn::ParsedActualParameters *t_list;
112 Ttcn::ActualParList *ap_list;
116 /** This points to the type of the template */
119 /** Length restriction */
120 LengthRestriction *length_restriction;
122 /** Ifpresent flag. */
125 /** Indicates whether it has been verified that the template is free of
126 * matching symbols. */
127 bool specific_value_checked;
129 /** Indicates whether the embedded templates contain PERMUTATION_MATCH.
130 * Used only in case of TEMPLATE_LIST */
131 bool has_permutation;
133 /** If false, it indicates that some all from could not be computed
134 * at compile-time, so it will need to be computed at runtime.
135 * It starts out as true. TODO find a better name */
138 /** Pointer to the base template (or template field) that this
139 * template is derived from. It is set in modified templates
140 * (including in-line modified templates) and only if the
141 * compiler is able to determine the base template. It is NULL
143 Template *base_template;
145 /** Copy constructor. For Template::clone() only.
146 * This is a hit-and-miss affair. Some template types can be cloned;
147 * others cause an immediate FATAL_ERROR. */
148 Template(const Template& p);
150 /** Copy assignment disabled */
151 Template& operator=(const Template& p);
153 /** Destroys the innards of the template */
156 string create_stringRepr();
159 /** Constructor for TEMPLATE_ERROR, TEMPLATE_NOTUSED, OMIT_VALUE,
160 * ANY_VALUE, ANY_OR_OMIT and */
161 Template(templatetype_t tt);
163 /** Constructor for SPECIFIC_VALUE */
166 /** Constructor for TEMPLATE_REFD */
167 Template(Ref_base *p_ref);
169 /** Constructor for TEMPLATE_LIST, VALUE_LIST, COMPLEMENTED_LIST,
170 * SUPERSET_MATCH, SUBSET_MATCH and PERMUTATION_MATCH */
171 Template(templatetype_t tt, Templates *ts);
173 /** Constructor for ALL_FROM */
176 /** Constructor for VALUE_LIST_ALL_FROM
177 * Takes over the innards of \a t, then deletes it.
178 * @pre tt == VALUE_LIST_ALL_FROM */
179 Template(templatetype_t tt, Template *t);
181 /** Constructor for NAMED_TEMPLATE_LIST */
182 Template(NamedTemplates *nts);
184 /** Constructor for INDEXED_TEMPLATE_LIST */
185 Template(IndexedTemplates *its);
187 /** Constructor for VALUE_RANGE */
188 Template(ValueRange *vr);
190 /** Constructor for BSTR_PATTERN, HSTR_PATTERN and OSTR_PATTERN */
191 Template(templatetype_t tt, string *p_patt);
193 /** Constructor for CSTR_PATTERN. */
194 Template(PatternString *p_ps);
198 virtual Template* clone() const;
200 virtual void set_fullname(const string& p_fullname);
201 virtual void set_my_scope(Scope *p_scope);
202 void set_genname_recursive(const string& p_genname);
203 void set_genname_prefix(const char *p_genname_prefix);
204 void set_code_section(code_section_t p_code_section);
206 /** Transforms the template to type \a p_templatetype.
207 * Works only if the change is possible */
208 void set_templatetype(templatetype_t p_templatetype);
209 templatetype_t get_templatetype() const { return templatetype; }
210 /** Returns a C string containing the type (e.g. "any or omit")
211 * of the template. */
212 const char *get_templatetype_str() const;
214 /** Returns whether the template is a specific value containing a single
216 bool is_undef_lowerid();
217 /** If the embedded specific value contains a single identifier it converts
218 * that to a referenced value or referenced template. */
219 void set_lowerid_to_ref();
221 /** If this template is used in an expression, what is its return type? */
222 Type::typetype_t get_expr_returntype(Type::expected_value_t exp_val);
223 /** If this template is used in an expression, what is its governor?
224 * If has no governor, but is reference, then tries the
225 * referenced stuff... If not known, returns NULL. */
226 Type *get_expr_governor(Type::expected_value_t exp_val);
228 /** Sets the governor type. */
229 virtual void set_my_governor(Type *p_gov);
230 /** Gets the governor type. */
231 virtual Type* get_my_governor() const;
233 void set_length_restriction(LengthRestriction *p_lr);
234 LengthRestriction *get_length_restriction() const
235 { return length_restriction; }
236 bool is_length_restricted() const { return length_restriction != 0; }
238 void set_ifpresent(bool p_ifpr) { is_ifpresent = p_ifpr; }
239 bool get_ifpresent() const { return is_ifpresent; }
241 void set_base_template(Template *p_base) { base_template = p_base; }
242 Template *get_base_template() const { return base_template; }
244 /** Returns the condition for the completeness of template body \a this,
245 * which is a 'record of' or 'set of' template.
246 * Argument \a incomplete_allowed indicates whether incomplete template
247 * bodies are allowed in the context at all. */
248 completeness_t get_completeness_condition_seof(bool incomplete_allowed);
249 /** Returns the condition for the completeness of template body \a this,
250 * which is a union template.
251 * Argument \a incomplete_allowed indicates whether incomplete template
252 * bodies are allowed in the context at all. Argument \a p_fieldname points
253 * to a field of \a this that is examined. It is useful when \a this is
254 * erroneous and contains multiple fields. */
255 completeness_t get_completeness_condition_choice(bool incomplete_allowed,
256 const Identifier& p_fieldname);
258 void add_named_temp(NamedTemplate* nt);
260 Value *get_specific_value() const;
261 Ref_base *get_reference() const;
262 ValueRange *get_value_range() const;
263 PatternString* get_cstr_pattern() const;
264 PatternString* get_ustr_pattern() const;
265 size_t get_nof_comps() const;
266 Template *get_temp_byIndex(size_t n) const;
267 NamedTemplate *get_namedtemp_byIndex(size_t n) const;
268 IndexedTemplate *get_indexedtemp_byIndex(size_t n) const;
269 Template *get_all_from() const;
270 /** Returns the number of elements in a VALUE_LIST. The elements of
271 * embedded PERMUTATION_MATCH constructs are counted recursively. */
272 size_t get_nof_listitems() const;
273 /** Returns the \a n th element of a VALUE_LIST. The embedded
274 * PERMUTATION_MATCH constructs are also counted. */
275 Template *get_listitem_byIndex(size_t n) const;
277 Template* get_template_refd_last(ReferenceChain *refch=0);
278 Template* get_refd_sub_template(Ttcn::FieldOrArrayRefs *subrefs,
280 ReferenceChain *refch);
282 Template* get_template_refd(ReferenceChain *refch);
283 Template* get_refd_field_template(const Identifier& field_id,
284 const Location& loc, bool usedInIsbound, ReferenceChain *refch);
285 Template* get_refd_array_template(Value *array_index, bool usedInIsbound,
286 ReferenceChain *refch);
288 bool compile_time() const;
290 /** Returns whether \a this contains '*' as inside value. Applicable to:
291 * TEMPLATE_LIST, SUPERSET_MATCH, SUBSET_MATCH, PERMUTATION_MATCH */
292 bool temps_contains_anyornone_symbol() const;
293 /** Returns the number of elements not counting the '*'s. Applicable to:
294 * TEMPLATE_LIST, SUPERSET_MATCH, SUBSET_MATCH, PERMUTATION_MATCH */
295 size_t get_nof_comps_not_anyornone() const;
296 /** Returns whether the string pattern contains '*' as inside value.
297 * Applicable to: BSTR_PATTERN, HSTR_PATTERN, OSTR_PATTERN, CSTR_PATTERN */
298 bool pattern_contains_anyornone_symbol() const;
299 /** Returns the length of string pattern not counting the '*'s.
300 * Applicable to: BSTR_PATTERN, HSTR_PATTERN, OSTR_PATTERN, CSTR_PATTERN */
301 size_t get_min_length_of_pattern() const;
303 /** Returns whether the template can be converted to a value
304 * (i.e. it is a specific value without wildcards). */
305 bool is_Value() const;
306 /** Converts the template to a value recursively. The returned
307 * value is newly allocated (i.e. the caller is responsible for
309 * If the template type was SPECIFIC_VALUE, the value returned is
310 * extracted from the template, which becomes TEMPLATE_ERROR. */
313 /** Returns whether the template consists of a single reference
314 * (i.e. it is a single specific value with an embedded
315 * non-parameterized reference). */
317 /** Converts the template to a reference. The returned reference
318 * is newly allocated (i.e. the caller is responsible for the
322 /** Checks for circular references within embedded templates */
323 void chk_recursions(ReferenceChain& refch);
325 /** Checks whether the template (including the embedded fields) contains
326 * no matching symbols. Argument \a allow_omit is used because OMIT_VALUE
327 * is allowed only in embedded fields. */
328 void chk_specific_value(bool allow_omit);
329 void chk_specific_value_generic();
332 /** Copy template elements from the "all from" into the template.
334 * @param from_permutation \a true if the "all from" occurs inside
335 * a permutation_match (in which case the target of the "all from"
336 * is allowed to be AnyElementsOrNone).
337 * @return \a false if some elements could not be computed at compile time,
340 bool flatten(bool from_permutation);
341 bool is_flattened() const { return flattened; }
342 bool has_allfrom() const;
344 static Templates *harbinger(Template *t, bool from_permutation, bool killer);
346 /** helper functions used by definitions which check their template restr.*/
347 /** returns the restriction name token */
348 static const char* get_restriction_name(template_restriction_t tr);
349 /** if a template has restriction \a tr then what is the restriction
351 static template_restriction_t get_sub_restriction(
352 template_restriction_t tr, Ref_base* ref);
353 /** returns C++ code that checks the restriction */
354 static char* generate_restriction_check_code(char* str,
355 const char* name, template_restriction_t tr);
356 /** Return if the required template restriction \a needed_tr is
357 * not satisfied by the given \a refd_tr */
358 static bool is_less_restrictive(template_restriction_t needed_tr,
359 template_restriction_t refd_tr);
361 /** helper functions used by chk_restriction() */
362 bool chk_restriction_named_list(const char* definition_name,
363 map<string, void>& checked_map, size_t needed_checked_cnt);
364 bool chk_restriction_refd(const char* definition_name,
365 template_restriction_t template_restriction);
367 /** Checks if this template conforms to the restriction, return value:
368 * false = always satisfies restriction -> no runtime check needed or
369 * never satisfies restriction -> compiler error(s)
370 * true = possibly violates restriction, cannot be determined at compile
371 * time -> runtime check needed and compiler warning given when
372 * inadequate restrictions are used, in other cases there's
374 * The return value is used by code generation to avoid useless checks */
375 bool chk_restriction(const char* definition_name,
376 template_restriction_t template_restriction);
378 /** Public entry points for code generation. */
379 /** Generates the equivalent C++ code for the template. It is used
380 * when the template is part of a complex expression
381 * (e.g. argument of a function that accepts a template). The
382 * generated code fragments are appended to the fields of visitor
384 void generate_code_expr(expression_struct *expr,
385 template_restriction_t template_restriction = TR_NONE);
386 /** Generates a C++ code sequence, which initializes the C++
387 * object named \a name with the contents of the template. The
388 * code sequence is appended to argument \a str and the resulting
389 * string is returned. */
390 char *generate_code_init(char *str, const char *name);
391 /** Walks through the template recursively and appends the C++
392 * initialization sequence of all (directly or indirectly)
393 * referenced non-parameterized templates to \a str and returns
394 * the resulting string. Templates imported from other modules
395 * are not visited. */
396 char *rearrange_init_code(char *str);
399 /** Private helper functions for code generation. */
401 /** Helper function for \a generate_code_init_refd(). Returns whether
402 * the string returned by \a get_single_expr() can be used to initialize
403 * the template instead of using the re-arrangement algorithm.
404 * Applicable to referenced templates only. */
405 bool use_single_expr_for_init();
407 /** Helper function for \a generate_code_init(). It handles the
408 * referenced templates. */
409 char *generate_code_init_refd(char *str, const char *name);
410 char *generate_code_init_invoke(char *str, const char *name);
411 /** Generates the C++ equivalent of \a this into \a expr and
412 * performs the necessary reordering: appends the initializer
413 * sequence of the dependent templates to \a str and returns the
414 * resulting string. It is used when \a this is a referenced
415 * template that is embedded into the body of a non-parameterized
416 * template. Note that the final content of \a expr is not
417 * necessarily identical to the C++ equivalent of \a
419 char *generate_rearrange_init_code_refd(char *str, expression_struct *expr);
420 /** Helper function for \a generate_code_init(). It handles the value list
421 * notation and the assignment notation with array indices (for 'record
422 * of' and 'set of' types). Embedded permutation matching constructs are
424 char *generate_code_init_seof(char *str, const char *name);
425 /** Helper function for \a generate_code_init_seof(). Used when \a this is
426 * a member of a value list notation or an embedded permutation match.
427 * Parameter \a name contains the C++ reference that points to the parent
428 * template. Parameter \a index is a straightened index in case of
429 * embedded permutations. Parameter \a element_type_genname contains a
430 * C++ class name that represents the element type of the 'record of' or
431 * 'set of' construct (which is the governor of \a this); if a temporary
432 * variable is created, this would be used as its type. */
433 char *generate_code_init_seof_element(char *str, const char *name,
434 const char* index, const char *element_type_genname);
435 /** Helper function for \a generate_code_init(). It handles the
436 * assignment notation for record/set/union types. */
437 char *generate_code_init_se(char *str, const char *name);
438 /** Helper function for \a generate_code_init(). It handles the
439 * value list and complemented list matching constructs. Flag \a
440 * is_complemented is set to true for complemented lists and
441 * false for value lists. */
442 char *generate_code_init_list(char *str, const char *name,
443 bool is_complemented);
444 /** Helper function for \a generate_code_init(). It handles the superset
445 * and subset constructs. Flag \a is_superset is set to true for superset
446 * and false for subset. Note that both constructs have similar data
447 * representations in runtime. */
448 char *generate_code_init_set(char *str, const char *name,
451 char *generate_code_init_all_from(char *str, const char *name);
452 char *generate_code_init_all_from_list(char *str, const char *name);
454 /** Helper function for \a generate_code_expr() and get_single_expr().
455 * It handles the invoke operation. */
456 void generate_code_expr_invoke(expression_struct *expr);
458 /** Helper function for \a rearrange_init_code(). It handles the
459 * referenced templates (i.e. it does the real work). */
460 char *rearrange_init_code_refd(char *str);
461 char *rearrange_init_code_invoke(char *str);
463 /** Returns whether the C++ initialization sequence requires a
464 * temporary variable reference to be introduced for efficiency
466 bool needs_temp_ref();
469 /** Returns whether the template can be represented by an in-line
471 bool has_single_expr();
472 /** Returns the equivalent C++ expression. It can be used only if
473 * \a has_single_expr() returns true. Argument \a cast_needed
474 * indicates whether the generic wildcards have to be explicitly
475 * converted to the appropriate type. */
476 string get_single_expr(bool cast_needed);
478 virtual void dump(unsigned level) const;
481 /** Represents an in-line template. Consists of:
483 * - an optional template reference with or without actual parameter list
484 * (in case of in-line modified template)
485 * - a mandatory template body
487 class TemplateInstance : public Node, public Location {
488 private: // all pointers owned
489 Type *type; // type before the colon, may be null
490 Ref_base *derived_reference; // base template, may be null
491 Template *template_body; // must not be null
493 /** Copy constructor disabled. */
494 TemplateInstance(const TemplateInstance& p);
495 /** Copy assignment disabled. */
496 TemplateInstance& operator=(const TemplateInstance& p);
500 * @param p_type type (the one before the colon, optional)
501 * @param p_ref reference to the base template (for a modified template)
502 * @param p_body template body (must not be NULL)
504 TemplateInstance(Type *p_type, Ref_base *p_ref, Template *p_body);
507 virtual TemplateInstance *clone() const;
508 virtual void set_fullname(const string& p_fullname);
509 virtual void set_my_scope(Scope *p_scope);
511 Type* get_Type() const { return type; }
512 Ref_base* get_DerivedRef() const { return derived_reference; }
513 Template* get_Template() const { return template_body; }
514 // it can return null pointer
515 Def_Template* get_Referenced_Base_Template();
517 /** Give up ownership of \a type, \a derived_reference and
518 * \a template_body */
521 /** If this template instance is used in an expression, what is its
523 Type::typetype_t get_expr_returntype(Type::expected_value_t exp_val);
524 /** If this template instance is used in an expression, what is its
525 * governor? Returns NULL if the governor cannot be determined. */
526 Type *get_expr_governor(Type::expected_value_t exp_val);
528 /** Checks the entire template instance against \a governor. */
529 void chk(Type *governor);
530 /** Checks the member \a type (if present) against \a governor.
531 * Returns the type that shall be considered in further checks. */
532 Type *chk_Type(Type *governor);
533 /** Checks the derived reference against \a governor.
534 * If \a governor is NULL it is checked against the \a type member.
535 * Returns the type that shall be considered when checking
536 * \a template_body. */
537 Type *chk_DerivedRef(Type *governor);
538 /** Checks for circular references. */
539 void chk_recursions(ReferenceChain& refch);
541 bool is_string_type(Type::expected_value_t exp_val);
543 bool chk_restriction(const char* definition_name,
544 template_restriction_t template_restriction);
546 /** Returns whether the template instance can be represented by an in-line
548 bool has_single_expr();
549 void set_code_section(GovernedSimple::code_section_t p_code_section);
550 bool needs_temp_ref();
551 void generate_code(expression_struct *expr,
552 template_restriction_t template_restriction = TR_NONE);
553 /** Appends the initialization sequence of the referred templates
554 * to \a str. Only those templates are considered that are in
555 * the same module as \a this. */
556 char *rearrange_init_code(char *str);
558 /** Appends the string representation of the template instance to
560 void append_stringRepr(string& str) const;
562 virtual void dump(unsigned level) const;
564 /** Returns the single value if the template is single value or NULL. */
565 Value* get_specific_value() const;
567 bool is_only_specific_value() const {
568 return (derived_reference==NULL &&
569 template_body->get_templatetype()==Template::SPECIFIC_VALUE &&
570 !template_body->is_length_restricted() &&
571 !template_body->get_ifpresent());
577 #endif // _Ttcn_Template_HH