1 /******************************************************************************
2 * Copyright (c) 2000-2016 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
16 * Zalanyi, Balazs Andor
18 ******************************************************************************/
19 #ifndef _Ttcn_Template_HH
20 #define _Ttcn_Template_HH
23 #include "../Value.hh"
24 #include "../vector.hh"
25 #include "AST_ttcn3.hh"
26 #include "Templatestuff.hh"
30 using namespace Common;
34 class LengthRestriction;
38 class IndexedTemplate;
39 class IndexedTemplates;
41 /** Represents a (single or compound) template body. */
42 class Template : public GovernedSimple {
46 /** type of template */
48 TEMPLATE_ERROR, /**< erroneous template */
49 TEMPLATE_NOTUSED, /**< not used symbol (-) */
50 OMIT_VALUE, /**< omit */
51 ANY_VALUE, /**< any value (?) */
52 ANY_OR_OMIT, /**< any or omit (*) */
53 SPECIFIC_VALUE, /**< specific value */
54 TEMPLATE_REFD, /**< reference to another template */
55 TEMPLATE_INVOKE, /** template returning invoke */
56 TEMPLATE_LIST, /**< value list notation */
57 NAMED_TEMPLATE_LIST, /**< assignment notation */
58 INDEXED_TEMPLATE_LIST, /**< assignment notation with array indices */
59 VALUE_LIST, /**< value list match */
60 COMPLEMENTED_LIST, /**< complemented list match */
61 VALUE_RANGE, /**< value range match */
62 SUPERSET_MATCH, /**< superset match */
63 SUBSET_MATCH, /**< subset match */
64 PERMUTATION_MATCH, /**< permutation match */
65 ALL_FROM, /**< "all from" as part of a larger list e.g. permutation, superset, subset, etc. */
66 VALUE_LIST_ALL_FROM, /**< "all from" in a value list, itself in a larger list */
67 BSTR_PATTERN, /**< bitstring pattern */
68 HSTR_PATTERN, /**< hexstring pattern */
69 OSTR_PATTERN, /**< octetstring pattern */
70 CSTR_PATTERN, /**< character string pattern */
71 USTR_PATTERN, /**< universal charstring pattern */
72 DECODE_MATCH /**< decoded content match */
75 /** Status codes for the verification of template body completeness. */
77 C_MUST_COMPLETE, /**< the body must be completely specified */
78 C_MAY_INCOMPLETE, /**< the body may be incompletely specified */
79 C_PARTIAL /**< some parts of the body may be incomplete,
80 * the others must be complete */
84 /** Determines type of the template. Only this field is used at
85 * ANY_VALUE, ANY_OR_OMIT and OMIT_VALUE templates */
86 templatetype_t templatetype;
88 /** This union holds the ``body'' of the template. The
89 * templatetype field is used to select between different
92 /** Holds the concrete single value of the template for single
94 Value *specific_value;
97 Template *refd; /**< cache */
98 Template *refd_last; /**< cache */
100 /** Used for TEMPLATE_LIST, VALUE_LIST, COMPLEMENTED_LIST,
101 * SUPERSET_MATCH, SUBSET_MATCH and PERMUTATION_MATCH constructs. */
102 Templates *templates;
103 /** Used by NAMED_TEMPLATE_LIST */
104 NamedTemplates *named_templates;
105 /** Used by INDEXED_TEMPLATE_LIST */
106 IndexedTemplates *indexed_templates;
107 /** Used by ALL_FROM */
109 /** This is used for VALUE_RANGE template upper and lower
111 ValueRange *value_range;
112 /** Pattern contains basic string templates containing the any
113 * element (?), any element or no element (*) wildcards .
114 * Used by BSTR_PATTERN, HSTR_PATTERN, OSTR_PATTERN */
116 /** PatternString contains the character string pattern matching
117 * constructions (including references).
118 * Used by CSTR_PATTERN, USTR_PATTERN */
119 PatternString *pstring;
120 /** Used by TEMPLATE_INVOKE */
123 Ttcn::ParsedActualParameters *t_list;
124 Ttcn::ActualParList *ap_list;
126 /** Used by DECODE_MATCH */
129 TemplateInstance* target;
133 /** This points to the type of the template */
136 /** Length restriction */
137 LengthRestriction *length_restriction;
139 /** Ifpresent flag. */
142 /** Indicates whether it has been verified that the template is free of
143 * matching symbols. */
144 bool specific_value_checked;
146 /** Indicates whether the embedded templates contain PERMUTATION_MATCH.
147 * Used only in case of TEMPLATE_LIST */
148 bool has_permutation;
150 /** If false, it indicates that some all from could not be computed
151 * at compile-time, so it will need to be computed at runtime.
152 * It starts out as true. TODO find a better name */
155 /** Pointer to the base template (or template field) that this
156 * template is derived from. It is set in modified templates
157 * (including in-line modified templates) and only if the
158 * compiler is able to determine the base template. It is NULL
160 Template *base_template;
162 /** Copy constructor. For Template::clone() only.
163 * This is a hit-and-miss affair. Some template types can be cloned;
164 * others cause an immediate FATAL_ERROR. */
165 Template(const Template& p);
167 /** Copy assignment disabled */
168 Template& operator=(const Template& p);
170 /** Destroys the innards of the template */
173 string create_stringRepr();
176 /** Constructor for TEMPLATE_ERROR, TEMPLATE_NOTUSED, OMIT_VALUE,
177 * ANY_VALUE, ANY_OR_OMIT and */
178 Template(templatetype_t tt);
180 /** Constructor for SPECIFIC_VALUE */
183 /** Constructor for TEMPLATE_REFD */
184 Template(Ref_base *p_ref);
186 /** Constructor for TEMPLATE_LIST, VALUE_LIST, COMPLEMENTED_LIST,
187 * SUPERSET_MATCH, SUBSET_MATCH and PERMUTATION_MATCH */
188 Template(templatetype_t tt, Templates *ts);
190 /** Constructor for ALL_FROM */
193 /** Constructor for VALUE_LIST_ALL_FROM
194 * Takes over the innards of \a t, then deletes it.
195 * @pre tt == VALUE_LIST_ALL_FROM */
196 Template(templatetype_t tt, Template *t);
198 /** Constructor for NAMED_TEMPLATE_LIST */
199 Template(NamedTemplates *nts);
201 /** Constructor for INDEXED_TEMPLATE_LIST */
202 Template(IndexedTemplates *its);
204 /** Constructor for VALUE_RANGE */
205 Template(ValueRange *vr);
207 /** Constructor for BSTR_PATTERN, HSTR_PATTERN and OSTR_PATTERN */
208 Template(templatetype_t tt, string *p_patt);
210 /** Constructor for CSTR_PATTERN. */
211 Template(PatternString *p_ps);
213 /** Constructor for DECODE_MATCH */
214 Template(Value* v, TemplateInstance* ti);
218 virtual Template* clone() const;
220 virtual void set_fullname(const string& p_fullname);
221 virtual void set_my_scope(Scope *p_scope);
222 void set_genname_recursive(const string& p_genname);
223 void set_genname_prefix(const char *p_genname_prefix);
224 void set_code_section(code_section_t p_code_section);
226 /** Transforms the template to type \a p_templatetype.
227 * Works only if the change is possible */
228 void set_templatetype(templatetype_t p_templatetype);
229 templatetype_t get_templatetype() const { return templatetype; }
230 /** Returns a C string containing the type (e.g. "any or omit")
231 * of the template. */
232 const char *get_templatetype_str() const;
234 /** Returns whether the template is a specific value containing a single
236 bool is_undef_lowerid();
237 /** If the embedded specific value contains a single identifier it converts
238 * that to a referenced value or referenced template. */
239 void set_lowerid_to_ref();
241 /** If this template is used in an expression, what is its return type? */
242 Type::typetype_t get_expr_returntype(Type::expected_value_t exp_val);
243 /** If this template is used in an expression, what is its governor?
244 * If has no governor, but is reference, then tries the
245 * referenced stuff... If not known, returns NULL. */
246 Type *get_expr_governor(Type::expected_value_t exp_val);
248 /** Sets the governor type. */
249 virtual void set_my_governor(Type *p_gov);
250 /** Gets the governor type. */
251 virtual Type* get_my_governor() const;
253 void set_length_restriction(LengthRestriction *p_lr);
254 LengthRestriction *get_length_restriction() const
255 { return length_restriction; }
256 bool is_length_restricted() const { return length_restriction != 0; }
258 void set_ifpresent(bool p_ifpr) { is_ifpresent = p_ifpr; }
259 bool get_ifpresent() const { return is_ifpresent; }
261 void set_base_template(Template *p_base) { base_template = p_base; }
262 Template *get_base_template() const { return base_template; }
264 /** Returns the condition for the completeness of template body \a this,
265 * which is a 'record of' or 'set of' template.
266 * Argument \a incomplete_allowed indicates whether incomplete template
267 * bodies are allowed in the context at all. */
268 completeness_t get_completeness_condition_seof(bool incomplete_allowed);
269 /** Returns the condition for the completeness of template body \a this,
270 * which is a union template.
271 * Argument \a incomplete_allowed indicates whether incomplete template
272 * bodies are allowed in the context at all. Argument \a p_fieldname points
273 * to a field of \a this that is examined. It is useful when \a this is
274 * erroneous and contains multiple fields. */
275 completeness_t get_completeness_condition_choice(bool incomplete_allowed,
276 const Identifier& p_fieldname);
278 void add_named_temp(NamedTemplate* nt);
280 Value *get_specific_value() const;
281 Ref_base *get_reference() const;
282 ValueRange *get_value_range() const;
283 PatternString* get_cstr_pattern() const;
284 PatternString* get_ustr_pattern() const;
285 size_t get_nof_comps() const;
286 Template *get_temp_byIndex(size_t n) const;
287 NamedTemplate *get_namedtemp_byIndex(size_t n) const;
288 IndexedTemplate *get_indexedtemp_byIndex(size_t n) const;
289 Template *get_all_from() const;
290 /** Returns the number of elements in a VALUE_LIST. The elements of
291 * embedded PERMUTATION_MATCH constructs are counted recursively. */
292 size_t get_nof_listitems() const;
293 /** Returns the \a n th element of a VALUE_LIST. The embedded
294 * PERMUTATION_MATCH constructs are also counted. */
295 Template *get_listitem_byIndex(size_t n) const;
297 Template* get_template_refd_last(ReferenceChain *refch=0);
298 Template* get_refd_sub_template(Ttcn::FieldOrArrayRefs *subrefs,
300 ReferenceChain *refch);
301 Value* get_string_encoding() const;
302 TemplateInstance* get_decode_target() const;
304 Template* get_template_refd(ReferenceChain *refch);
305 Template* get_refd_field_template(const Identifier& field_id,
306 const Location& loc, bool usedInIsbound, ReferenceChain *refch);
307 Template* get_refd_array_template(Value *array_index, bool usedInIsbound,
308 ReferenceChain *refch);
310 bool compile_time() const;
312 /** Returns whether \a this contains '*' as inside value. Applicable to:
313 * TEMPLATE_LIST, SUPERSET_MATCH, SUBSET_MATCH, PERMUTATION_MATCH */
314 bool temps_contains_anyornone_symbol() const;
315 /** Returns the number of elements not counting the '*'s. Applicable to:
316 * TEMPLATE_LIST, SUPERSET_MATCH, SUBSET_MATCH, PERMUTATION_MATCH */
317 size_t get_nof_comps_not_anyornone() const;
318 /** Returns whether the string pattern contains '*' as inside value.
319 * Applicable to: BSTR_PATTERN, HSTR_PATTERN, OSTR_PATTERN, CSTR_PATTERN */
320 bool pattern_contains_anyornone_symbol() const;
321 /** Returns the length of string pattern not counting the '*'s.
322 * Applicable to: BSTR_PATTERN, HSTR_PATTERN, OSTR_PATTERN, CSTR_PATTERN */
323 size_t get_min_length_of_pattern() const;
325 /** Returns whether the template can be converted to a value
326 * (i.e. it is a specific value without wildcards). */
327 bool is_Value() const;
328 /** Converts the template to a value recursively. The returned
329 * value is newly allocated (i.e. the caller is responsible for
331 * If the template type was SPECIFIC_VALUE, the value returned is
332 * extracted from the template, which becomes TEMPLATE_ERROR. */
335 /** Returns whether the template consists of a single reference
336 * (i.e. it is a single specific value with an embedded
337 * non-parameterized reference). */
339 /** Converts the template to a reference. The returned reference
340 * is newly allocated (i.e. the caller is responsible for the
344 /** Checks for circular references within embedded templates */
345 void chk_recursions(ReferenceChain& refch);
347 /** Checks whether the template (including the embedded fields) contains
348 * no matching symbols. Argument \a allow_omit is used because OMIT_VALUE
349 * is allowed only in embedded fields. */
350 void chk_specific_value(bool allow_omit);
351 void chk_specific_value_generic();
354 /** Copy template elements from the "all from" into the template.
356 * @param from_permutation \a true if the "all from" occurs inside
357 * a permutation_match (in which case the target of the "all from"
358 * is allowed to be AnyElementsOrNone).
359 * @return \a false if some elements could not be computed at compile time,
362 bool flatten(bool from_permutation);
363 bool is_flattened() const { return flattened; }
364 bool has_allfrom() const;
366 static Templates *harbinger(Template *t, bool from_permutation, bool killer);
368 /** helper functions used by definitions which check their template restr.*/
369 /** returns the restriction name token */
370 static const char* get_restriction_name(template_restriction_t tr);
371 /** if a template has restriction \a tr then what is the restriction
373 static template_restriction_t get_sub_restriction(
374 template_restriction_t tr, Ref_base* ref);
375 /** returns C++ code that checks the restriction */
376 static char* generate_restriction_check_code(char* str,
377 const char* name, template_restriction_t tr);
378 /** Return if the required template restriction \a needed_tr is
379 * not satisfied by the given \a refd_tr */
380 static bool is_less_restrictive(template_restriction_t needed_tr,
381 template_restriction_t refd_tr);
383 /** helper functions used by chk_restriction() */
384 bool chk_restriction_named_list(const char* definition_name,
385 map<string, void>& checked_map, size_t needed_checked_cnt,
386 const Location* usage_loc);
387 bool chk_restriction_refd(const char* definition_name,
388 template_restriction_t template_restriction, const Location* usage_loc);
390 /** Checks if this template conforms to the restriction, return value:
391 * false = always satisfies restriction -> no runtime check needed or
392 * never satisfies restriction -> compiler error(s)
393 * true = possibly violates restriction, cannot be determined at compile
394 * time -> runtime check needed and compiler warning given when
395 * inadequate restrictions are used, in other cases there's
397 * The return value is used by code generation to avoid useless checks
398 * @param usage_loc contains the location, where the template is used
399 * (errors are issued here, instead of where the template is declared) */
400 bool chk_restriction(const char* definition_name,
401 template_restriction_t template_restriction,
402 const Location* usage_loc);
404 /** Public entry points for code generation. */
405 /** Generates the equivalent C++ code for the template. It is used
406 * when the template is part of a complex expression
407 * (e.g. argument of a function that accepts a template). The
408 * generated code fragments are appended to the fields of visitor
410 void generate_code_expr(expression_struct *expr,
411 template_restriction_t template_restriction = TR_NONE);
412 /** Generates a C++ code sequence, which initializes the C++
413 * object named \a name with the contents of the template. The
414 * code sequence is appended to argument \a str and the resulting
415 * string is returned. */
416 char *generate_code_init(char *str, const char *name);
417 /** Walks through the template recursively and appends the C++
418 * initialization sequence of all (directly or indirectly)
419 * referenced non-parameterized templates and the default values of all
420 * parameterized templates to \a str and returns the resulting string.
421 * Only objects belonging to module \a usage_mod are initialized. */
422 char *rearrange_init_code(char *str, Common::Module* usage_mod);
425 /** Private helper functions for code generation. */
427 /** Helper function for \a generate_code_init_refd(). Returns whether
428 * the string returned by \a get_single_expr() can be used to initialize
429 * the template instead of using the re-arrangement algorithm.
430 * Applicable to referenced templates only. */
431 bool use_single_expr_for_init();
433 /** Helper function for \a generate_code_init(). It handles the
434 * referenced templates. */
435 char *generate_code_init_refd(char *str, const char *name);
436 char *generate_code_init_invoke(char *str, const char *name);
437 /** Generates the C++ equivalent of \a this into \a expr and
438 * performs the necessary reordering: appends the initializer
439 * sequence of the dependent templates to \a str and returns the
440 * resulting string. It is used when \a this is a referenced
441 * template that is embedded into the body of a non-parameterized
442 * template. Note that the final content of \a expr is not
443 * necessarily identical to the C++ equivalent of \a
445 char *generate_rearrange_init_code_refd(char *str, expression_struct *expr);
446 /** Helper function for \a generate_code_init(). It handles the value list
447 * notation and the assignment notation with array indices (for 'record
448 * of' and 'set of' types). Embedded permutation matching constructs are
450 char *generate_code_init_seof(char *str, const char *name);
451 /** Helper function for \a generate_code_init_seof(). Used when \a this is
452 * a member of a value list notation or an embedded permutation match.
453 * Parameter \a name contains the C++ reference that points to the parent
454 * template. Parameter \a index is a straightened index in case of
455 * embedded permutations. Parameter \a element_type_genname contains a
456 * C++ class name that represents the element type of the 'record of' or
457 * 'set of' construct (which is the governor of \a this); if a temporary
458 * variable is created, this would be used as its type. */
459 char *generate_code_init_seof_element(char *str, const char *name,
460 const char* index, const char *element_type_genname);
461 /** Helper function for \a generate_code_init(). It handles the
462 * assignment notation for record/set/union types. */
463 char *generate_code_init_se(char *str, const char *name);
464 /** Helper function for \a generate_code_init(). It handles the
465 * value list and complemented list matching constructs. Flag \a
466 * is_complemented is set to true for complemented lists and
467 * false for value lists. */
468 char *generate_code_init_list(char *str, const char *name,
469 bool is_complemented);
470 /** Helper function for \a generate_code_init(). It handles the superset
471 * and subset constructs. Flag \a is_superset is set to true for superset
472 * and false for subset. Note that both constructs have similar data
473 * representations in runtime. */
474 char *generate_code_init_set(char *str, const char *name,
477 char* generate_code_init_dec_match(char* str, const char* name);
479 char *generate_code_init_all_from(char *str, const char *name);
480 char *generate_code_init_all_from_list(char *str, const char *name);
482 /** Helper function for \a generate_code_expr() and get_single_expr().
483 * It handles the invoke operation. */
484 void generate_code_expr_invoke(expression_struct *expr);
486 /** Helper function for \a rearrange_init_code(). It handles the
487 * referenced templates (i.e. it does the real work). */
488 char *rearrange_init_code_refd(char *str, Common::Module* usage_mod);
489 char *rearrange_init_code_invoke(char *str, Common::Module* usage_mod);
491 /** Returns whether the C++ initialization sequence requires a
492 * temporary variable reference to be introduced for efficiency
494 bool needs_temp_ref();
497 /** Returns whether the template can be represented by an in-line
499 bool has_single_expr();
500 /** Returns the equivalent C++ expression. It can be used only if
501 * \a has_single_expr() returns true. Argument \a cast_needed
502 * indicates whether the generic wildcards have to be explicitly
503 * converted to the appropriate type. */
504 string get_single_expr(bool cast_needed);
506 virtual void dump(unsigned level) const;
509 /** Represents an in-line template. Consists of:
511 * - an optional template reference with or without actual parameter list
512 * (in case of in-line modified template)
513 * - a mandatory template body
515 class TemplateInstance : public Node, public Location {
516 private: // all pointers owned
517 Type *type; // type before the colon, may be null
518 Ref_base *derived_reference; // base template, may be null
519 Template *template_body; // must not be null
521 /** Copy constructor disabled. */
522 TemplateInstance(const TemplateInstance& p);
523 /** Copy assignment disabled. */
524 TemplateInstance& operator=(const TemplateInstance& p);
528 * @param p_type type (the one before the colon, optional)
529 * @param p_ref reference to the base template (for a modified template)
530 * @param p_body template body (must not be NULL)
532 TemplateInstance(Type *p_type, Ref_base *p_ref, Template *p_body);
535 virtual TemplateInstance *clone() const;
536 virtual void set_fullname(const string& p_fullname);
537 virtual void set_my_scope(Scope *p_scope);
539 Type* get_Type() const { return type; }
540 Ref_base* get_DerivedRef() const { return derived_reference; }
541 Template* get_Template() const { return template_body; }
542 // it can return null pointer
543 Def_Template* get_Referenced_Base_Template();
545 /** Give up ownership of \a type, \a derived_reference and
546 * \a template_body */
549 /** If this template instance is used in an expression, what is its
551 Type::typetype_t get_expr_returntype(Type::expected_value_t exp_val);
552 /** If this template instance is used in an expression, what is its
553 * governor? Returns NULL if the governor cannot be determined. */
554 Type *get_expr_governor(Type::expected_value_t exp_val);
556 /** Checks the entire template instance against \a governor. */
557 void chk(Type *governor);
558 /** Checks the member \a type (if present) against \a governor.
559 * Returns the type that shall be considered in further checks. */
560 Type *chk_Type(Type *governor);
561 /** Checks the derived reference against \a governor.
562 * If \a governor is NULL it is checked against the \a type member.
563 * Returns the type that shall be considered when checking
564 * \a template_body. */
565 Type *chk_DerivedRef(Type *governor);
566 /** Checks for circular references. */
567 void chk_recursions(ReferenceChain& refch);
569 bool is_string_type(Type::expected_value_t exp_val);
571 bool chk_restriction(const char* definition_name,
572 template_restriction_t template_restriction, const Location* usage_loc);
574 /** Returns whether the template instance can be represented by an in-line
576 bool has_single_expr();
577 void set_code_section(GovernedSimple::code_section_t p_code_section);
578 bool needs_temp_ref();
579 void generate_code(expression_struct *expr,
580 template_restriction_t template_restriction = TR_NONE);
581 /** Appends the initialization sequence of the referred templates
582 * and their default values to \a str. Only templates from module
583 * \a usage_mod are considered. */
584 char *rearrange_init_code(char *str, Common::Module* usage_mod);
586 /** Appends the string representation of the template instance to
588 void append_stringRepr(string& str) const;
590 virtual void dump(unsigned level) const;
592 /** Returns the single value if the template is single value or NULL. */
593 Value* get_specific_value() const;
595 bool is_only_specific_value() const {
596 return (derived_reference==NULL &&
597 template_body->get_templatetype()==Template::SPECIFIC_VALUE &&
598 !template_body->is_length_restricted() &&
599 !template_body->get_ifpresent());
605 #endif // _Ttcn_Template_HH