| Both sides previous revision Previous revision Next revision | Previous revision Next revisionBoth sides next revision |
| user_guide:howto:scripting [2019/03/13 15:09] – [Namespaces] gawrilow | user_guide:howto:scripting [2019/03/28 10:53] – put $ into '' '' benmuell |
|---|
| $c=cast<LatticePolytope>(cube(3)); | $c=cast<LatticePolytope>(cube(3)); |
| </code> | </code> |
| |
| This syntax is resembling the C++ language as close as possible; unfortunately, this comfort was achieved at the price of severe mistreatment of perl parser. The consequence is that it can't always correctly recognize the end of the argument list. If you are going to put several expressions | |
| involving templates into a single list (for example, when calling a function), you must enclose each expression in an extra pair of parentheses: | |
| $p=intersection( (new Polytope<Rational>(POINTS=>$p1)), (new Polytope<Rational>(POINTS=>$p2)) ); | |
| |
| ==== Advanced techniques ==== | ==== Advanced techniques ==== |
| === Localizations === | === Localizations === |
| |
| 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 several 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 additional keywords ''scalar'' and ''ref'', you can temporarily modify lexical variables, scalars returned by lvalue functions, and any data items passed by reference: |
| .. 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 | ? ''local scalar $a=2;'' \\ ''local scalar $obj->member=3;'' |
| -- 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: | : Temporarily modify a lexical variable or a data member returned as lvalue |
| .. <code> | ? ''local scalar $b;'' |
| sub func { | : Save the current value of a scalar so that it's automatically restored when the localization scope is left |
| my $guard=shift; | ? ''local scalar ++$c;'' \\ ''local scalar --$d;'' |
| $guard->begin_locals; | : Save the current value and increment/decrement temporarily |
| local $xyz=123; | ? ''local ref $e=[3,4];'' \\ ''local ref $f={value => 5};'' |
| $guard->end_locals; | :: Temporarily replace an array or hash passed by reference. |
| } | .. Note: it's really the array resp. hash which is modified here, the change will be visible through all references pointing to it. |
| declare $xyz=0; | ? ''local ref $s=sub { ... }'' |
| { | : Temporarily replace the implementation of a subroutine passed by reference |
| my $guard=new Scope; | ? ''local bless $obj;'' \\ ''%%local bless $obj, "Package";%%'' |
| func($guard); | : Temporarily change the type of an object passed by reference |
| # $xyz is still 123 | -- Some basic array modifications can be made temporarily, they are automatically undone when the localization scope is left. Arrays can reside in package or local variables or be passed by reference: |
| } | ? ''local unshift @a, ...;'' \\ ''local push @$b, ...;'' |
| # $xyz reverted to 0 now</code> | : Temporarily add elements at the beginning resp. at the end of an array |
| .. All ''local_XXX'' functions described above can be used in the block ''begin_locals'' .. ''end_locals'' too. | ? ''local shift @a;'' \\ ''local pop @$b;'' |
| .. 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. | : Return and temporarily hide the first resp. last element |
| | ? ''local splice @a, 0, N;'' |
| | : Return and temporarily hide the first N elements |
| | ? ''local splice @a, N;'' |
| | : Return and temporarily hide trailing elements starting with position N (can be negative) |
| | ? ''local swap @a, i1, i2;'' |
| | : Temporarily exchange two elements with given indices |
| | -- Localization scope can be extended to the outer enclosing block or bound to the lifetime of a certain scalar: |
| | ? ''local if (...) { local $x=1; } else { local ref $y=[ 2 ]; }'' |
| | :: Changes made in then/else branches will be reverted when the block enclosing the entire ''if'' is left |
| | ? ''local with ($scope) { local $x=1; }'' |
| | :: Changes made within the block will be reverted when the ''$scope'' scalar is destroyed; this can happen at any later point in time, far away from the block or subroutine enclosing this place. The same scalar can be used repeatedly in the same or different ''with'' blocks; all reverting actions will be accumulated and applied in reverse order. It must have an undefined value before first use. |
| | .. There is one session-scope guard ''%%$Scope->locals%%'' used, among others, by [[:general#preferences|prefer_now]] commands and for removing temporary properties from big objects. |
| | .. If you want to introduce temporary changes lasting until the next interactive shell input or the completion of a script started in [[#calling|batch mode]], \\ use ''%%local with($Scope->locals) { ... }%%'' |
| | .. If you want to introduce a nested localization scope with shorter lifetime within your script, create a temporary Scope object: ''local $Scope=new Scope();'' |
| |
| ===== Most important interfaces ===== | ===== Most important interfaces ===== |
| :: like above, but adding (or replacing) properties | :: like above, but adding (or replacing) properties |
| ? ''%%$p->copy_permuted(VERTICES => $v)%%'' | ? ''%%$p->copy_permuted(VERTICES => $v)%%'' |
| :: first finds a permutation mapping the listed properties of the source object $p to the given values (here: ''%%$p->VERTICES%%'' => ''$v''), then applies it to all source properties and stores the results in the new object. Invariant properties are copied verbatim. If no suitable permutation can be found, an exception is raised. | :: first finds a permutation mapping the listed properties of the source object ''$p'' to the given values (here: ''%%$p->VERTICES%%'' => ''$v''), then applies it to all source properties and stores the results in the new object. Invariant properties are copied verbatim. If no suitable permutation can be found, an exception is raised. |
| |
| === Name and Description === | === Name and Description === |