| Both sides previous revision Previous revision Next revision | Previous revision |
| user_guide:extend:rulefiles [2019/01/25 16:02] – ↷ Page moved from reference:rulefiles to user_guide:extend:rulefiles oroehrig | user_guide:extend:rulefiles [2021/01/12 15:38] (current) – external edit 127.0.0.1 |
|---|
| - scoped blocks like ''object'' or ''property_type''. Their body is enclosed in curly braces { ... } and can expand over arbitrarily many lines. Scope-like blocks can be nested, but must not intersect with plain text blocks. | - scoped blocks like ''object'' or ''property_type''. Their body is enclosed in curly braces { ... } and can expand over arbitrarily many lines. Scope-like blocks can be nested, but must not intersect with plain text blocks. |
| |
| [[reference:rules|Production rules]] constitute a special case in that they can be defined by a sequence of several blocks. The first block, usually a scoped one, comprising the main rule subroutine, may be followed by further single-line and scoped blocks defining its weight and preconditions. Empty lines and comments between the blocks in such a sequence are allowed and ignored. | [[user_guide:extend:rules|Production rules]] constitute a special case in that they can be defined by a sequence of several blocks. The first block, usually a scoped one, comprising the main rule subroutine, may be followed by further single-line and scoped blocks defining its weight and preconditions. Empty lines and comments between the blocks in such a sequence are allowed and ignored. |
| |
| ===== Compilation mode ===== | ===== Compilation mode ===== |
| .. Note that applications the current one really depends on, that is, //imported// or //used// ones, must not be listed in such guard. | .. Note that applications the current one really depends on, that is, //imported// or //used// ones, must not be listed in such guard. |
| ==== Configuration ==== | ==== Configuration ==== |
| Rulefiles may contain configurable settings, which can be filled automatically and manipulated by the user. There are two kinds of items related to configuration: [[:general#custom_variables|custom variables]] and auto-configuration blocks. Declarations of custom variables should be preceded with comments, which are copied into the user's settings files for the sake of better legibility. | Rulefiles may contain configurable settings, which can be filled automatically and manipulated by the user. There are two kinds of items related to configuration: [[:user_guide:howto:shell_custom#custom_variables|custom variables]] and auto-configuration blocks. Declarations of custom variables should be preceded with comments, which are copied into the user's settings files for the sake of better legibility. |
| |
| ? ''custom $var = default_value;'' | ? ''custom $var = default_value;'' |
| ? ''label'' name | ? ''label'' name |
| :: Introduces a top-level name for labels, used in definitions of production rules and user methods. | :: Introduces a top-level name for labels, used in definitions of production rules and user methods. |
| ? ''prefer'' [[:general#preferences|label expression]] | ? ''prefer'' [[:user_guide:howto:shell_custom#preferences|label expression]] |
| :: Establishes a default preference list for a certain group of competing rules or user methods. The syntax of the //label expression// is the same as in the interactive commands ''prefer'' and ''prefer_now'', but here you should not enclose it in quotes nor put a trailing semicolon. These are the lists that are re-established upon execution of a ''reset_preference'' command. | :: Establishes a default preference list for a certain group of competing rules or user methods. The syntax of the //label expression// is the same as in the interactive commands ''prefer'' and ''prefer_now'', but here you should not enclose it in quotes nor put a trailing semicolon. These are the lists that are re-established upon execution of a ''reset_preference'' command. |
| | |
| .. An optional //spec_name// can be assigned to the partial specialization in order to be able to reopen it later elsewhere in the rulebase. For the sake of well-formed documentation, it is required that any partial specialization that introduces any user-visible features (properties or user-methods) must be given an own name. Apart from that, the specialization name can't be used for anything; in particular, it can't be used as a type designator in property declarations, constructors, typeof expressions, etc. The specialization names are localized by the object type, so that it is possible to reuse the same name for similar specializations of distinct object types. | .. An optional //spec_name// can be assigned to the partial specialization in order to be able to reopen it later elsewhere in the rulebase. For the sake of well-formed documentation, it is required that any partial specialization that introduces any user-visible features (properties or user-methods) must be given an own name. Apart from that, the specialization name can't be used for anything; in particular, it can't be used as a type designator in property declarations, constructors, typeof expressions, etc. The specialization names are localized by the object type, so that it is possible to reuse the same name for similar specializations of distinct object types. |
| ? ''declare object_specialization'' spec_name '' = '' object_type ''{'' \\ ''precondition : '' SOURCE, ... { ... } \\ ... \\ ''}'' | ? ''declare object_specialization'' spec_name '' = '' object_type ''{'' \\ ''precondition : '' SOURCE, ... { ... } \\ ... \\ ''}'' |
| :: Introduces a //restricted// specialization for the given "big" object type. The rules, properties, and methods defined herein are only defined for objects fulfilling one or more [[reference:rules#preconditions|preconditions]]. The preconditions are written in exactly the same way as for production rules. Note that a partial specialization can be restricted by preconditions as well. | :: Introduces a //restricted// specialization for the given "big" object type. The rules, properties, and methods defined herein are only defined for objects fulfilling one or more [[rules#preconditions|preconditions]]. The preconditions are written in exactly the same way as for production rules. Note that a partial specialization can be restricted by preconditions as well. |
| ? ''object_specialization'' object_name''::''spec_name ''{'' \\ ... \\ ''}'' | ? ''object_specialization'' object_name''::''spec_name ''{'' \\ ... \\ ''}'' |
| :: Reopens the definition scope of a named partial/restricted specialization of the given "big" object type. | :: Reopens the definition scope of a named partial/restricted specialization of the given "big" object type. |
| :: specifies a prerequisite property of the owning object (or one of its subobjects) needed for proper construction of the property value. The value of the prerequisite property is passed to the ''construct'' method of the property type together with the value being assigned to this property. For example, values of type NodeMap or EdgeMap need a Graph object to be attached to, therefore such properties of "big" objects graph::Graph or graph::FaceLattice usually have an attribute ''construct(ADJACENCY)''. | :: specifies a prerequisite property of the owning object (or one of its subobjects) needed for proper construction of the property value. The value of the prerequisite property is passed to the ''construct'' method of the property type together with the value being assigned to this property. For example, values of type NodeMap or EdgeMap need a Graph object to be attached to, therefore such properties of "big" objects graph::Graph or graph::FaceLattice usually have an attribute ''construct(ADJACENCY)''. |
| ? ''property NAME = override INHERITED_NAME;'' | ? ''property NAME = override INHERITED_NAME;'' |
| :: introduces an alias for an inherited property. The alias name will appear everywhere you ask for properties, e.g. in XML data files and in lists produced by ''list_properties'' method; but the value of the property stays accessible over both alias name and inherited original name. The inherited production rules for this property are in effect as well; if you want to disable them, see the [[reference:rules#overrides|override option for rules]]. | :: introduces an alias for an inherited property. The alias name will appear everywhere you ask for properties, e.g. in XML data files and in lists produced by ''list_properties'' method; but the value of the property stays accessible over both alias name and inherited original name. The inherited production rules for this property are in effect as well; if you want to disable them, see the [[user_guide:extend:rules#overrides|override option for rules]]. |
| .. For obvious reasons, a property can't be overridden in the same object type where it has been defined, nor within a partial or conditional specialization of an object type. | .. For obvious reasons, a property can't be overridden in the same object type where it has been defined, nor within a partial or conditional specialization of an object type. |
| ? ''property NAME = override ''['' INHERITED_NAME '']'' : Type;'' | ? ''property NAME = override ''['' INHERITED_NAME '']'' : Type;'' |
| |
| ==== Rules ==== | ==== Rules ==== |
| The syntax of rules is so manifold that it deserves a description [[reference:rules|on a separate page]]. | The syntax of rules is so manifold that it deserves a description [[user_guide:extend:rules|on a separate page]]. |
| |
| ==== User methods ==== | ==== User methods ==== |
| ? ''user_method'' [labels :] name ''('' [[user_guide:extend:polymorphic|signature]] '') {'' \\ ... \\ ''}'' | ? ''user_method'' [labels :] name ''('' [[user_guide:extend:polymorphic|signature]] '') {'' \\ ... \\ ''}'' |
| :: defines a method to be called from scripts and interactive shell. It should be accompanied by a properly formatted comment block. The syntax rules for the signature and overload resolution rules are the same as for user_functions, apart from the fact that the leading argument, a reference to an object of the current type, may not appear in the signature. As the name //method// says, it is inherited by all derived object types. Methods defined in derived classes completely override inherited methods of the same name only if they possess compatible signatures (that is, accept the same or broader sets of arguments than the inherited instance). | :: defines a method to be called from scripts and interactive shell. It should be accompanied by a properly formatted comment block. The syntax rules for the signature and overload resolution rules are the same as for user_functions, apart from the fact that the leading argument, a reference to an object of the current type, may not appear in the signature. As the name //method// says, it is inherited by all derived object types. Methods defined in derived classes completely override inherited methods of the same name only if they possess compatible signatures (that is, accept the same or broader sets of arguments than the inherited instance). |
| .. //labels// can be used in [[:general#preferences|preference]] settings controlling the favorites among several overloaded instances with equivalent signatures. The first limb of each label must be defined earlier in this application, or in a //used// or //imported// one. | .. //labels// can be used in [[:user_guide:howto:shell_custom#preferences|preference]] settings controlling the favorites among several overloaded instances with equivalent signatures. The first limb of each label must be defined earlier in this application, or in a //used// or //imported// one. |
| .. If the routine is declared as ''method'' instead of ''user_method'', it does not appear in the interactive help, TAB completion, or auto-generated documentation, but in all other aspects both flavors behave identically. | .. If the routine is declared as ''method'' instead of ''user_method'', it does not appear in the interactive help, TAB completion, or auto-generated documentation, but in all other aspects both flavors behave identically. |
| ? ''user_method'' [labels :] name ''('' [[user_guide:extend:polymorphic|signature]] '') : '' property, ... '' {'' \\ ... \\ ''}'' | ? ''user_method'' [labels :] name ''('' [[user_guide:extend:polymorphic|signature]] '') : '' property, ... '' {'' \\ ... \\ ''}'' |
| :: defines a rule-like method. This is a hybrid creature between a polymorphic method and a [[reference:rules|rule]]. Like a normal production rule, it specifies a list of required input properties and, optionally, preconditions, which must follow the main code block. | :: defines a rule-like method. This is a hybrid creature between a polymorphic method and a [[user_guide:extend:rules|rule]]. Like a normal production rule, it specifies a list of required input properties and, optionally, preconditions, which must follow the main code block. |
| .. When such a method is called, suitable candidates are first chosen depending on the argument list. Then they are handled much like production rules: the input property lists and preconditions are evaluated and the cheapest feasible candidate is executed. However, unlike for real production rules, if the chosen method instance throws an exception, no alternative candidates are tried any more. | .. When such a method is called, suitable candidates are first chosen depending on the argument list. Then they are handled much like production rules: the input property lists and preconditions are evaluated and the cheapest feasible candidate is executed. However, unlike for real production rules, if the chosen method instance throws an exception, no alternative candidates are tried any more. |
| .. Rule-like methods can also be defined without signatures. In this case the choice of a suitable instance is performed solely by analyzing input properties and preconditions. | .. Rule-like methods can also be defined without signatures. In this case the choice of a suitable instance is performed solely by analyzing input properties and preconditions. |
| |
| There is also one sort of definition elements which is specific for packages not belonging to the "big" object hierarchy: so called //global methods//. They are defined exactly the same way as polymorphic user_methods, just using the keyword ''global_method''. The main difference lies in the [[user_guide:extend:polymorphic#labels|overload resolution]]: it usually takes place before the object of the class is created. The global methods from different classes having an identical signature are bundled together by preference lists and the current favorite is used to determine the class to create the object which is then passed to the chosen method. This is how all the visualization methods work. If, for example, you are going to draw a graph, all known global methods having signatures compatible to ''draw(Visual::Graph)'' are ordered according to the active preference settings, then the definition package of the method in the "pole position" determines which visualization back-end object is to be created, and finally the ''draw'' method is called with this object and the graph. | There is also one sort of definition elements which is specific for packages not belonging to the "big" object hierarchy: so called //global methods//. They are defined exactly the same way as polymorphic user_methods, just using the keyword ''global_method''. The main difference lies in the [[user_guide:extend:polymorphic#labels|overload resolution]]: it usually takes place before the object of the class is created. The global methods from different classes having an identical signature are bundled together by preference lists and the current favorite is used to determine the class to create the object which is then passed to the chosen method. This is how all the visualization methods work. If, for example, you are going to draw a graph, all known global methods having signatures compatible to ''draw(Visual::Graph)'' are ordered according to the active preference settings, then the definition package of the method in the "pole position" determines which visualization back-end object is to be created, and finally the ''draw'' method is called with this object and the graph. |
| | |