user_guide:shell

This is an old revision of the document!


The default running mode of polymake is an interactive shell-like interpreter. To start it, just type polymake in your command line. You will be presented with a command prompt accepting polymake-perl, as described in the ''polymake''-perl intorduction tutorial.

polymake excessively uses the TAB completion feature. It tries to guess the proper context for the partially typed word (as far as the entangled perl syntax allows) and presents the possible continuations.

The online help facility enables a systematic and user-friendly access to a plenty of comments and help texts scattered over polymake source code. There are three ways of getting help.

  1. Hierarchical browsing. All help topics are organized in a tree-like hierarchy. You can just start typing help ' and then use TAB completion to navigate the branch of interest. An example:

    help 'functions/Basic/help';
    help 'functions/Producing from scratch/rand_sphere';
    help 'objects/Polytope/properties/Basic properties/VERTICES';
    help 'custom/$history_size';
  2. Keyword search. You enter help "WORD"; and get a list of all help topics matching the given word. If there are only few topics matching your input, they will be displayed immediately; if there are many of them, you can choose the topic of your interest using the ArrowUp/ArrowDown keys.

  3. Context-sensitive help. Having typed in a part of an expression, you press the F1 key. If the cursor stands within or immediately after a name of a function, method, or property, the corresponding help topic is shown. For functions and methods, only a brief description listing the order of parameters and options is displayed; to get the full explanation, you must press F1 once again.

  4. Partial word search. You enter apropos "SUBSTRING"; and get all matching headlines. Paste one of them with your mouse into a help command. You can use regular expressions in the search string, e.g. .* for an arbitrary substring in the middle of your pattern. The search is case-insensitive and only involves the item names, no full-text search is performed.

Finally, you can just enter a bare help; command and get a very brief summary of the page you are currently reading.

Each command must be concluded with a semicolon. If you hit ENTER without doing so, polymake supposes that your expression is going to be continued on the next line; you will see this on the changed input prompt, which will contain the continuation number in parentheses. This is useful for typing in conditional blocks or loops over several lines or the input of multi-line constants (e.g. for matrices). You can press Ctrl-C to escape from the continuation mode.

A neat trick to conveniently enter a matrix using the continuation mode:

polytope > $m = <<".";
polytope (2)> 1 0 0 0
polytope (3)> 1 1 0 0
polytope (4)> 1 0 1 0
polytope (5)> 1 0 0 1
polytope (6)> .

Polymake shell uses the history facility to store all your input. Besides the standard readline functions for incremental and non-incremental search of single input lines (usually bound to keys Ctrl-S/R and PageUp/PageDown), there are three special commands allowing for manipulate and recall larger input sequences:

history;

starts an editor with complete collected history copied to a temporary file. You can pick an arbitrary sequence of commands, reorder and/or modify them if needed, and paste them at the very beginning of the file. After you exit from the editor, these pasted commands are executed.

replay_history;

rewinds the current history pointer to the very beginning, from where you can re-execute the commands line by line or skip some of them using the usual arrow-key navigation or search functions. During the replay mode the sequential number of the line in the history is displayed in the prompt in square brackets. As soon as you move past the last history line, the replay mode is switched off and the input prompt becomes empty again.

load_commands "file";

appends the commands stored in the given file to the history, rewinds back to the first of them, and turns on the replay mode. This command is especially useful for making live demos with polymake, as you can prepare and test your input in advance and don't have to waste your time for typing during the presentation.

Finally, let's mention two custom variables related to the history handling.

$history_size

specifies a maximal size (in lines) of the file ~/.polymake/history keeping your input history between the sessions. If you want to let it grow unlimitedly, set this variable to undef.

$history_editor

contains the command starting the editor when you call history. The default value is extracted from the environment variables VISUAL or EDITOR.

Precisely speaking, polymake commands are quite normal perl functions, either built-in ones like print or exit, or specially written for polymake. As long as you are not concerned about implementation details, you won't feel any difference. All commands taking arguments may be written in two fashions: with argument list enclosed in parentheses or separated by a blank from the command keyword. For example:

print "dim=", $p->DIM, "\n";
print("dim=", $p->DIM, "\n");

It's completely up to your taste which fashion to use. But never forget the trailing semicolon!

The first command to learn is exit; It gets you out from the interactive shell and ends the session, saving all changed objects (those having associated data files) and settings.

Applications are, roughly speaking, collections of object types, functions, and other stuff related to some distinct mathematical subject. At all times during the interactive session in the polymake shell, there is one current application, while other applications are modestly standing on the backstage. The name of the current application is permanently displayed in the shell prompt.

As a matter of fact, the only difference between the current application and the rest is that you can call the functions and object constructors of the former without having to qualify them with the application name as a prefix; however, this is a quite comfortable feature. When you want to make other application current, you must enter this command: application "NAME";. To perpetuate your choice for future sessions, you can set the custom variable ''$default_application.

  • user_guide/shell.1610466753.txt.gz
  • Last modified: 2021/01/12 15:52
  • by gawrilow