| Both sides previous revision Previous revision Next revision | Previous revisionLast revisionBoth sides next revision |
| scripting:start [2015/10/18 21:57] – [Object] gawrilow | scripting:start [2019/01/25 09:27] – ↷ Links adapted because of a move operation oroehrig |
|---|
| |
| Special variables residing in the global package such as ''$_'', ''@_'', ''@ARGV'', ''@INC'', ''%ENV'', ''%SIG'', etc. don't need to be declared. The package inheritance list ''@ISA'' and sort placeholders ''$a'' and ''$b'' are also exempt from declaration. | Special variables residing in the global package such as ''$_'', ''@_'', ''@ARGV'', ''@INC'', ''%ENV'', ''%SIG'', etc. don't need to be declared. The package inheritance list ''@ISA'' and sort placeholders ''$a'' and ''$b'' are also exempt from declaration. |
| | |
| | Variables can also be declared temporarily in scripts loaded by operator ''do'': |
| | <code>declare local $bla=123;</code> |
| | After the script has been executed, the variable disappears as if it were never declared, so that this script or other ones reusing the same variable name can safely be loaded again. However, if the variable was already declared persistently beforehand, the effect of such local declaration is equivalent to a standard perl ''local'' operator, that is, its value will be temporarily changed but not the declaration status. Please beware that this is a quite exotic feature introduced primarily for testing purposes. In most cases, one-shot scripts should only create lexical variables and avoid injecting new names in namespaces. |
| |
| === Name lookup === | === Name lookup === |
| The standard ''local'' operator is very useful as it allows to make exception-safe temporary changes. polymake enhances this functionality in two aspects: | The standard ''local'' operator is very useful as it allows to make exception-safe temporary changes. polymake enhances this functionality in two aspects: |
| -- ''local'' works with package variables only. Using new functions ''local_scalar'', ''local_array'', ''local_hash'', and ''local_sub'', you can temporarily modify each data type passed by reference too:\\ ''$a=[1,2];''\\ ''local_array($a, [3,4]);'' | -- ''local'' works with package variables only. Using new functions ''local_scalar'', ''local_array'', ''local_hash'', and ''local_sub'', you can temporarily modify each data type passed by reference too:\\ ''$a=[1,2];''\\ ''local_array($a, [3,4]);'' |
| .. There are further functions doing temporary changes, which are reverted on leaving the block scope:\\ ''local_incr($scalar, number)'' -- add a number\\ ''local_shift(\@array)'' -- hide the first element\\ ''local_pop(\@array)'' -- hide the last element \\ ''local_shorten(\@array, n)'' -- hide abs(n) elements at the front (n>0) or back (n<0) end\\ ''local_unshift(\@array, list)'' -- prepend elements\\ ''local_push(\@array, list)'' -- append elements \\ ''local_swap(\@array, i1, i2)'' -- exchange two elements with given indices | .. There are further functions doing temporary changes, which are reverted on leaving the block scope:\\ ''local_incr($scalar, number)'' -- add a number\\ ''local_shift(\@array)'' -- hide the first element\\ ''local_pop(\@array)'' -- hide the last element \\ ''local_clip_front(\@array, n)'' -- hide elements at the front so that the element [n] becomes the first one\\ ''local_clip_back(\@array, n)'' -- hide elements at the end so that the element [n] becomes the last one\\ ''local_unshift(\@array, list)'' -- prepend elements\\ ''local_push(\@array, list)'' -- append elements \\ ''local_swap(\@array, i1, i2)'' -- exchange two elements with given indices\\ ''%%local_bless($object, "Package" or \%Package::)%%'' -- change the type of an object |
| -- You can postpone the reverting actions to an outer enclosing block scope, even located in a different subroutine. You create a special guard object in the outer scope and pass it to other subroutines. All temporary modifications remain in effect until the guard object is destroyed: | -- You can postpone the reverting actions to an outer enclosing block scope, even located in a different subroutine. You create a special guard object in the outer scope and pass it to other subroutines. All temporary modifications remain in effect until the guard object is destroyed: |
| .. <code> | .. <code> |
| .. All ''local_XXX'' functions described above can be used in the block ''begin_locals'' .. ''end_locals'' too. | .. All ''local_XXX'' functions described above can be used in the block ''begin_locals'' .. ''end_locals'' too. |
| .. There is one session-scope guard dwelling in the variable ''$Polymake::Scope'' (aka ''$Scope'' due to namespace lookup rules). Its lifetime ends with the complete interpretation of the current input line in the interactive shell, or complete execution of the script started in [[#calling|batch mode]]. This guard is used, among others, by [[:general#preferences|prefer_now]] commands, as well as for purging temporary properties from the objects. | .. There is one session-scope guard dwelling in the variable ''$Polymake::Scope'' (aka ''$Scope'' due to namespace lookup rules). Its lifetime ends with the complete interpretation of the current input line in the interactive shell, or complete execution of the script started in [[#calling|batch mode]]. This guard is used, among others, by [[:general#preferences|prefer_now]] commands, as well as for purging temporary properties from the objects. |
| |
| === Classes === | |
| |
| ===== Most important interfaces ===== | ===== Most important interfaces ===== |
| |
| While normal (singular) subobjects are treated much like other properties, multiple subobjects require special methods capable of choosing the desired instance or iterating over them all. Multiple subobject instances must have non-empty, unique names; uniqueness (among all instances of the same property in one parent object) is enforced. | While normal (singular) subobjects are treated much like other properties, multiple subobjects require special methods capable of choosing the desired instance or iterating over them all. Multiple subobject instances must have non-empty, unique names; uniqueness (among all instances of the same property in one parent object) is enforced. |
| | |
| | == Construction of multiple subobjects == |
| |
| The method ''add'' is used for creating and/or attaching multiple subobjects to the parent. It has several flavors, resembling the construction modes of top-level objects: | The method ''add'' is used for creating and/or attaching multiple subobjects to the parent. It has several flavors, resembling the construction modes of top-level objects: |
| In any flavor, you can add an option ''temporary'' directly after the name of the property, specifying that the subobject is to be added temporarily. | In any flavor, you can add an option ''temporary'' directly after the name of the property, specifying that the subobject is to be added temporarily. |
| |
| Having added a subobject, you can retrieve it later using numerous search criteria. Some of the retrieval methods can even create a new subobject on the fly, as described in the corresponding remarks: | **Note:** For the sake of convenience, the very first instance of a multiple subobject may be created in the same manner as singular subobjects, that is, using ''take()'', providing initial property values in the constructor list, or assigning values to property access methods during the initialization phase. |
| | |
| | == Examining multiple subobjects == |
| | |
| | Having added a subobject instance, you can retrieve it later using numerous search criteria. Some of the retrieval methods can even create a new subobject on the fly, as described in the corresponding remarks: |
| |
| | ? ''%%$p->LP%%'' |
| | ? ''%%$p->give("LP.MAXIMAL_VALUE")%%'' |
| | :: access the default subobject instance, that is, a subobject with ordinal number 0. If no subobject of the requested type exists and there are production rules creating new instances, plans the cheapest rule chain and returns a new instance. |
| ? ''%%$p->LP->[$i]%%'' | ? ''%%$p->LP->[$i]%%'' |
| ? ''%%$p->give("LP")->[$i]%%'' | ? ''%%$p->give("LP")->[$i]%%'' |
| :: select the subobject by its ordinal number | :: select the subobject instance by its ordinal number |
| ? ''%%$p->LP("name")%%'' | ? ''%%$p->LP("name")%%'' |
| ? ''%%$p->give("LP", "name")%%'' | ? ''%%$p->give("LP", "name")%%'' |
| :: select the subobject by its name; if no match found, returns ''undef'' | :: select the subobject by its name; if no match found, returns ''undef'' |
| | ? ''%%$p->LP(sub { $_->MAXIMAL_VALUE >= 0 })%%'' |
| ? ''%%$p->give("LP", sub { $_->MAXIMAL_VALUE >= 0 })%%'' | ? ''%%$p->give("LP", sub { $_->MAXIMAL_VALUE >= 0 })%%'' |
| :: select the first subobject satisfying the filter expression; if none satisfies the criteria, returns ''undef''. The subobject under test is passed in the variable ''$_'' . | :: select the first subobject satisfying the filter expression; if none satisfies the criteria, returns ''undef''. The subobject under test is passed in the variable ''$_'' . |
| ? ''%%$p->give("SCHLEGEL_DIAGRAM", FACET => 1, temporary)%%'' | ? ''%%$p->give("SCHLEGEL_DIAGRAM", FACET => 1, temporary)%%'' |
| :: the same as above, but in the non-match case the new subobject will be created temporarily | :: the same as above, but in the non-match case the new subobject will be created temporarily |
| ? ''%%$p->SCHLEGEL_DIAGRAM%%'' | |
| ? ''%%$p->give("SCHLEGEL_DIAGRAM")%%'' | |
| :: if there are many instances, retrieves a random one; if none exists and there are suitable production rules, a new subobject will be created. | |
| ? ''%%foreach $lp (@{$p->LP}) { ... }%%'' | ? ''%%foreach $lp (@{$p->LP}) { ... }%%'' |
| :: iterates over all subobjects | :: iterates over all existing instances |
| | ? ''%%$p->LP->list_names%%'' |
| | :: returns the list of names of all existing instances |
| | ? ''%%$p->LP(...)->select_as_default%%'' |
| | :: permanently makes the selected instance the default one, which simply means moving it at the front of the instance list |
| | ? ''%%$p->LP(...)->select_as_default_now%%'' |
| | :: temporarily makes the selected instance the default one; the change is reverted at the end of the current user cycle |
| | |
| | == Removing multiple subobjects == |
| ? ''%%$p->remove($lp, ...);%%'' | ? ''%%$p->remove($lp, ...);%%'' |
| :: removes the given instance of a multiple subobject. Several instances may be removed at once. | :: removes the given instance of a multiple subobject. Several instances may be removed at once. |
| ? ''%%$p->remove("LP");%%'' | ? ''%%$p->remove("LP");%%'' |
| .. removes //all// subobjects attached as a LP property. | .. removes //all// subobjects attached as a LP property. |
| |
| **Note:** For the sake of convenience, the very first instance of a multiple subobject may be created in the same manner as singular subobjects, that is, using ''take()'', providing initial property values in the constructor list, or assigning values to property access methods during the initialization phase. | |
| |
| === Rule planning === | === Rule planning === |
| ==== Complex objects ==== | ==== Complex objects ==== |
| |
| Some more complex objects like Graphs or Polynomials are also wrapped for directed use from perl code. Please refer to the release documentation and the [[tutorial:start|tutorials]] for more details. | Some more complex objects like Graphs or Polynomials are also wrapped for directed use from perl code. Please refer to the release documentation and the [[user_guide:start|tutorials]] for more details. |
| ===== Debugging ===== | ===== Debugging ===== |
| |