| Both sides previous revision Previous revision Next revision | Previous revision |
| user_guide:howto:scripting [2019/03/15 16:08] – [Advanced techniques] gawrilow | user_guide:howto:scripting [2021/01/12 15:49] (current) – [Location] gawrilow |
|---|
| ===== Structure ===== | ===== Structure ===== |
| |
| A script can contain pretty anything allowed by perl syntax rules. However, to get access to polymake classes and functions, it needs a preamble: <code>use application "NAME";</code> It sets a default application for the rest of the enclosing lexical context (that is, normally, up to the next ''use application'' statement or the end of the script file, but may also be just the enclosing block). The notion of the default application has exactly the same meaning as the [[:general#switching_applications|current application]] for the interactive shell: Functions and class names defined in or imported into the default application may be used without qualification, while names from other applications must be prefixed by the application name. | A script can contain pretty anything allowed by perl syntax rules. However, to get access to polymake classes and functions, it needs a preamble: <code>use application "NAME";</code> It sets a default application for the rest of the enclosing lexical context (that is, normally, up to the next ''use application'' statement or the end of the script file, but may also be just the enclosing block). The notion of the default application has exactly the same meaning as the [[:shell#switching_applications|current application]] for the interactive shell: Functions and class names defined in or imported into the default application may be used without qualification, while names from other applications must be prefixed by the application name. |
| |
| The script code is compiled in the package ''Polymake::User'', the same as the interactive shell expressions are evaluated in. Thus the scripts can access non-local variables introduced in the shell and vice versa, having run the script once, you can use the variables and subroutines defined in the script. If you want to define additional packages, please define them as subpackages of ''Polymake::User'' or completely outside ''Polymake::'', to prevent accidental clashes with polymake internal classes. | The script code is compiled in the package ''Polymake::User'', the same as the interactive shell expressions are evaluated in. Thus the scripts can access non-local variables introduced in the shell and vice versa, having run the script once, you can use the variables and subroutines defined in the script. If you want to define additional packages, please define them as subpackages of ''Polymake::User'' or completely outside ''Polymake::'', to prevent accidental clashes with polymake internal classes. |
| |
| * ''$InstallTop/scripts'' -- standard neutral scripts shipped with polymake | * ''$InstallTop/scripts'' -- standard neutral scripts shipped with polymake |
| * ''@lookup_scripts'' -- additional directories of your choice containing your private scripts. This list is a [[:general#custom_variables|custom variable]] stored in ''~/.polymake/prefer.pl''. | * ''@lookup_scripts'' -- additional directories of your choice containing your private scripts. This list is a [[shell_custom#custom_variables|custom variable]]. |
| * ''$Extension/scripts'' -- neutral scripts coming from an [[user_guide:extend:extensions|extension]] | * ''$Extension/scripts'' -- neutral scripts coming from an [[user_guide:extend:extensions|extension]] |
| |
| These scripts don't need the preamble ''use application'', it is automatically imposed. An application-specific script can be executed with the ''script'' command if its application is the current one or is imported by the current application. | These scripts don't need the preamble ''use application'', it is automatically imposed. An application-specific script can be executed with the ''script'' command if its application is the current one or is imported by the current application. |
| |
| Your collection of scripts will probably grow over the time, some scripts sharing common code parts. The common code is usually extracted in separate ''.pl'' or ''.pm'' files included with ''require'' statement. The lookup rules for these files is a bit different: the directories to be searched have to be inserted into the global array ''@INC''. The appropriate ''push'' or ''unshift'' statements can be placed in ''~/.polymake/prefer.pl'' somewhere in the ''package Polymake::User'' section. We recommend, however, to create a private extension and store the scripts and the included files in subdirectories ''scripts'' and ''perllib'' respectively. In this setting you don't have to manipulate any lookup list. | Your collection of scripts will probably grow over the time, some scripts sharing common code parts. The common code is usually extracted in separate ''.pl'' or ''.pm'' files included with ''require'' statement. The lookup rules for these files is a bit different: the directories to be searched have to be inserted into the global array ''@INC''. The appropriate ''push'' or ''unshift'' statements can be placed in your personal startup script ''~/.polymake/init.pl''. We recommend, however, to create a private extension and store the scripts and the included files in subdirectories ''scripts'' and ''perllib'' respectively. In this setting you don't have to manipulate any lookup list. |
| |
| ===== Extended syntax ===== | ===== Extended syntax ===== |
| ? ''local with ($scope) { local $x=1; }'' | ? ''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. | :: 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. | .. There is one session-scope guard ''%%$Scope->locals%%'' used, among others, by [[shell_custom#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 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();'' | .. If you want to introduce a nested localization scope with shorter lifetime within your script, create a temporary Scope object: ''local $Scope=new Scope();'' |
| :: 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 === |
| |
| Running polymake in debugger has one inconvenience you ought to be warned about: the debugger and the interactive shell share the same instance of the ''readline'' input line editor, so that the history buffer is filled by polymake commands only. You have to retype the debugger commands completely each time you want to repeat them; fortunately, most of them are just one letter short. And you may not try TAB completion entering debugger commands - you would land in polymake shell routines! | Running polymake in debugger has one inconvenience you ought to be warned about: the debugger and the interactive shell share the same instance of the ''readline'' input line editor, so that the history buffer is filled by polymake commands only. You have to retype the debugger commands completely each time you want to repeat them; fortunately, most of them are just one letter short. And you may not try TAB completion entering debugger commands - you would land in polymake shell routines! |
| | |