====== application core ======
Core functionality available in all applications.


===== Objects =====
  ** ''[[.:core:Core_BigObject |Core::BigObject]]'':\\  This is the common base class of all `big' objects in polymake. It does not have any properties, but provides several useful methods for scripting and interactive use.
  ** ''[[.:core:Core_RuleChain |Core::RuleChain]]'':\\  A rule chain to compute properties of a `big' object. It can be obtained by calling the method ''[[.:core:Core_BigObject#get_schedule |get_schedule]]''.
  ** ''[[.:core:Schema |Schema]]'':\\  JSON schema used for validation and filtering, see ''[[.:core#save |save]]''. See also functions for most common manipulations of restricted schemas, ''[[.:core:Schema#prescribe_property_types |prescribe_property_types]]''

===== Functions =====

==== Basic ====
 These functions are part of the core user interface. They are available in both scripting and interactive modes.
----
{{anchor:application:}}
  ?  **''application([[.:common#String |String]] name)''**
  :: Called in void context sets the current application to the one given by //name// loading its rules if necessary. Called in non-void context loads the application if necessary and returns the ''Application'' object representing it, but does not make it the current application. Finally, if called without arguments, just returns the current ''Application'' object, which is also always available in the variable ''$application''. Type ''print $application->name;'' to see its name. To obtain the introductory help topic on an application, type ''help "APPLICATION_NAME";''
    ? Parameters:
    :: ''[[.:common#String |String]]'' ''name''
    ? Example:
    :: To set the graph application as the current one, type this:
    :: <code perl> > application "graph";
</code>


----
{{anchor:disable_rules:}}
  ?  **''disable_rules([[.:common#String |String]] pattern)''**
  :: Temporarily disable production rules matching a given pattern. All rules defined in the current application are affected. For a more fine-granular control on object type level or even for individual objects, please refer to the corresponding methods of the same name:  ''$obj->type->disable_rules(...)''  ''$obj->disable_rules(...)'' Rules are re-enabled after the completion of the current user cycle, that is, end of user script or complete execution of the current shell input. or input expression in interactive mode.
    ? Parameters:
    :: ''[[.:common#String |String]]'' ''pattern'': either a label (see ''[[.:core#prefer |prefer]]'') or a rule header.  If it's a label, selected rules are those having this label or any of its sublabels.  If the label is preceded with an explamation mark '!', not the selected rules are disabled  but all others competing with them.  If it's a rule header, it must exactly match the definition in the rulefile,  up to white spaces around property names.
    ? Example:
    :: disable all rules labelled with 'lrs.convex_hull.primal', 'lrs.convex_hull.dual',  'lrs.simplex', etc.
    :: <code perl> > disable_rules('lrs');
</code>
    ? Example:
    :: disable all rules labelled with 'lrs.convex_hull.primal' and 'lrs.convex_hull.dual'
    :: <code perl> > disable_rules('lrs.convex_hull');
</code>
    ? Example:
    :: disable all rules labelled with 'cdd.convex_hull.primal', 'cdd.convex_hull.dual',  'ppl.convex_hull.primal', 'ppl.convex_hull.dual', etc.
    :: <code perl> > disable_rules('!lrs.convex_hull');
</code>
    ? Example:
    :: disable a single rule with the given header
    :: <code perl> > disable_rules('POINTED : LINEALITY_DIM');
</code>


----
{{anchor:include:}}
  ?  **''include([[.:common#String |String]] rulefile)''**
  :: Read additional rule files, interpret them in the context of the current application. The rule files may reside in the application's standard subdirectory ''rules'' or in any of the known extensions.
    ? Parameters:
    :: ''[[.:common#String |String]]'' ''rulefile'': name of a rule file


----
{{anchor:load:}}
  ?  **''load([[.:common#String |String]] filename)''**
  :: Read a //big object// from a file created earlier by ''[[.:core#save |save]]''. The object will be associated with the data file, so that any changes made to the object later will be saved in the same file automatically. If the data file has been created by an earlier polymake release, all necessary transformations making the object match the current data model will be applied immediately. Backward transformations to older versions are not supported. For old plain ASCII data files lacking type declaration, the default type of the current application is assumed.
    ? Parameters:
    :: ''[[.:common#String |String]]'' ''filename''
    ? Returns:
    :''[[.:core:Core_BigObject |Core::BigObject]]''


----
{{anchor:load_data:}}
  ?  **''load_data([[.:common#String |String]] filename)''**
  :: Read data from a file created earlier by ''[[.:core#save_data |save_data]]''.
    ? Parameters:
    :: ''[[.:common#String |String]]'' ''filename''
    ? Returns:
    :''Any''


----
{{anchor:prefer:}}
  ?  **''prefer([[.:common#String |String]] label_expression)''**
  :: Make the production rules, user functions, or methods (further called //items//) matching the given //label_expression// be preferred over competing rules (functions, methods). The new preference list is also saved in your personal file ''~/.polymake/settings'' It remains active in all forthcoming sessions until you revoke it with another //prefer// or ''[[.:core#reset_preference |reset_preference]]'' command. For the sake of symmetry you can call this function by its alias name //set_preference//.
    ? Parameters:
    :: ''[[.:common#String |String]]'' ''label_expression'': may have one of the following forms:   "top_label" or "top_label.sublevels"      selects all items whose labels start with the given path,      e.g. "javaview" or "cdd.convex_hull".   "*.sublevels top_label_1, top_label_2 ... "      selects all items with matching labels and establishes a ranking between them.      For example, "*.convex_hull cdd,lrs" makes rules labeled with cdd.convex_hull      and lrs.convex_hull preferred over all other convex hull rules,      with cdd rules having the topmost rank.


----
{{anchor:prefer_now:}}
  ?  **''prefer_now([[.:common#String |String]] label_expression)''**
  :: Same as ''[[.:core#prefer |prefer]]'', but does not store the changes persistently.  The lifespan of the new preference order lasts up to the end of the current user cycle, that is, end of user script or complete execution of the current shell input.
    ? Parameters:
    :: ''[[.:common#String |String]]'' ''label_expression''


----
{{anchor:reset_custom:}}
  ?  **''reset_custom(Any variable)''**
  :: Reset the custom variable, array, hash, or hash element to the default value(s) as defined in the rule base and store it perpetually in your personal settings file ''~/.polymake/settings''
    ? Parameters:
    :: ''Any'' ''variable'': following expressions are allowed:  ''$var;''  ''@array;''  ''%hash;''  ''$hash{key};''


----
{{anchor:reset_preference:}}
  ?  **''reset_preference([[.:common#String |String]] label_expression)''**
  :: Reset the matching preference lists to the default state. If there are matching preference lists declared in the rule files, they come back into effect; otherwise the preferences are neutralized, i.e. all competing items (rules/methods/etc.) get equal ranks. This change is permanent, the former settings are wiped out from your preference file ''~/.polymake/settings''
    ? Parameters:
    :: ''[[.:common#String |String]]'' ''label_expression'': "label" or "label.sublevels" or "*.sublevels" or "*" or "all"  Two last forms match all preference lists visible from the current application.


----
{{anchor:save:}}
  ?  **''save([[.:core:Core_BigObject |Core::BigObject]] object, [[.:common#String |String]] filename)''**
  :: Store the given //big object// in a data file. If //filename// is specified, create the file with this name (or overwrite an existing one) and store the object there.  The filename may have the suffix ".gz" in which case the contents are compressed with gzip. If //filename// is omitted, write the object back to the file it was loaded from, but only if has been changed since then and not saved before (this fact is reflected in the boolean attribute ''object->changed''). If the object is not yet associated with a file (e.g. it was created with a ''new'' constructor) a new file is created, with the name consisting of the object name and the application-specific suffix. If the object name is empty, you will be asked for it.  In non-interactive mode an artificial name of the form ''ObjectType_NNN'' will be generated, where ''NNN'' is an ordinal number.
    ? Parameters:
    :: ''[[.:core:Core_BigObject |Core::BigObject]]'' ''object''
    :: ''[[.:common#String |String]]'' ''filename''
    ? Options:
    : 
    :: ''[[.:common#Bool |Bool]]'' ''canonical'': store JSON with pretty indentation and all properties ordered alphabetically  (automatically enforced for all data files stored in the testsuite)
    :: ''[[.:core:Schema |Schema]]'' ''schema'': JSON schema which the saved object should validate against.  A schema can be used for filtering out uninteresting properties and attachments,  for enforcing certain properties or user methods to be computed before storing,  and/or for coercion of certain properties to desired data types, e.g. choosing between dense and  sparse representations of matrices.  When this option is specified, the object will not be associated with this datafile,  so that later changes made to the object will be saved in the original datafile the object comes from, if any.


----
{{anchor:save_data:}}
  ?  **''save_data(Any data, [[.:common#String |String]] filename)''**
  :: Store given data in a JSON file. The filename may have the suffix ".gz" in which case the contents are compressed with gzip.
    ? Parameters:
    :: ''Any'' ''data'': big object, anonymous array or hash map of big objects, or a single property value
    :: ''[[.:common#String |String]]'' ''filename''
    ? Options:
    : 
    :: ''[[.:common#Bool |Bool]]'' ''canonical'': store JSON with pretty indentation and all properties ordered alphabetically  (automatically enforced for all data files stored in the testsuite)


----
{{anchor:script:}}
  ?  **''script([[.:common#String |String]] filename, Any Arguments)''**
  :: Run the polymake script, passing the arguments in localized ''@ARGV''. The scripts specified without path are first looked for in the current application's ''scripts'' subdirectory, then in the user's script directories (custom array ''@lookup_scripts''), and finally in the top-level ''scripts'' subdirectory.
    ? Parameters:
    :: ''[[.:common#String |String]]'' ''filename'': script file
    :: ''Any'' ''Arguments'': arbitrary many arguments passed to the script
    ? Returns:
    :''Any''


----
{{anchor:set_custom:}}
  ?  **''set_custom(Any assignment)''**
  :: Set the custom variable, array, hash, or hash element to a new value and store it perpetually in your personal settings file ''~/.polymake/settings''
    ? Parameters:
    :: ''Any'' ''assignment'': following expressions are allowed:  ''$var=value;''  ''@array=(values);''  ''%hash=( key => value, ... );''  ''$hash{key}=value;''


----
{{anchor:set_preference:}}
  ?  **''set_preference([[.:common#String |String]] label_expression)''**
  :: Alternative name of command ''[[.:core#prefer |prefer]]''.
    ? Parameters:
    :: ''[[.:common#String |String]]'' ''label_expression''


----

==== Interactive ====
 These functions are available in the interactive shell only.
----
{{anchor:apropos:}}
  ?  **''apropos([[.:common#String |String]] pattern)''**
  :: List all help topics matching the given pattern.
    ? Parameters:
    :: ''[[.:common#String |String]]'' ''pattern'': (part of) an item name to be looked for, may contain regular expression elements.
    ? Example:
    :: To get all help topics that include the word "simplicial", type this:
    :: <code perl> > apropos("simplicial");
 /objects/Visual::SimplicialComplexLattice
 /objects/Visual::SimplicialComplex
 /objects/GeometricSimplicialComplex
 /objects/SimplicialComplex
 /functions/Producing a new simplicial complex from others/simplicial_product
</code>
    ::  Then display the desired help topic:
    :: <code perl> > help("/functions/Producing a new simplicial complex from others/simplicial_product");
</code>


----
{{anchor:exit:}}
  ?  **''exit''**
  :: Use this command only if you want to restart polymake.


----
{{anchor:export_configured:}}
  ?  **''export_configured([[.:common#String |String]] filename)''**
  :: Saves all custom variables having non-defalt values in a file. This includes all results of successful automatic or manual rule configuration. The obtained file can be edited manually, if needed, and used as a global configuration source (see also [[:howto/configure|How to configure polymake for a group of users]]).
    ? Parameters:
    :: ''[[.:common#String |String]]'' ''filename'': where to store the settings
    ? Options:
    : 
    :: ''[[.:common#Bool |Bool]]'' ''include_imported'': include settings imported from *your* global configuration;  by default, only your private settings will be exported.
    :: ''[[.:common#String |String]]'' ''suppress'': regular expression matching fully qualified names of custom variables  that should not be exported


----
{{anchor:extend_application:}}
  ?  **''extend_application([[.:common#String |String]] extension, [[.:common#String |String]] app_name)''**
  :: Create a directory tree for rules, scripts, clients, etc. in the given //extension// pertaining to the given application.
    ? Parameters:
    :: ''[[.:common#String |String]]'' ''extension'': URI or top-level directory of a registered extension.
    :: ''[[.:common#String |String]]'' ''app_name'': name of the application to be extended; by default, the current application is assumed.


----
{{anchor:found_application:}}
  ?  **''found_application([[.:common#String |String]] extension, [[.:common#String |String]] app_name)''**
  :: Create a directory tree for a new application, rooted at the given extension. The new application is neither loaded at this moment (just because it's quite empty at its birth), nor it is inserted in the ''@start_applications'' list. Both must be done manually at the appropriate time. A new core application can be created by entering the string "core" instead of the //extension// argument. This action is only allowed in developer's mode, i.e. when polymake is invoked from the git copy of the source tree.
    ? Parameters:
    :: ''[[.:common#String |String]]'' ''extension'': URI or top-level directory of a registered extension, or literal ''"core"''.
    :: ''[[.:common#String |String]]'' ''app_name'': name of the new application


----
{{anchor:found_extension:}}
  ?  **''found_extension([[.:common#String |String]] dirname)''**
  :: Found a new extension in the directory //dirname//.  The specified directory may be absent, then it will be created; if it already exists, it should be empty or at least not contain any files and subdirectories with names having special meaning for polymake, like polymake.ext or apps. A new bundled extension can be created by entering a name of the form ''"bundled:NAME"'' intead of //dirname//. This action is only allowed in developer's mode, i.e. when polymake is invoked from the git worktree. Please note that this command only creates an empty skeleton of top-level directories.  In order to be able to populate the extension with new rules, scripts, clients, etc. you must execute the command ''[[.:core#extend_application |extend_application]]'' for every application you want to to extend.
    ? Parameters:
    :: ''[[.:common#String |String]]'' ''dirname'': top-level directory of the extension, or ''"bundled:NAME"'' for a bundled extension.


----
{{anchor:help:}}
  ?  **''help([[.:common#String |String]] item)''**
  :: Display the help information or comments associated with a given item. If a single word without path separators ''/'' is given, it is looked for in the entire help hierarchy. If there are more than 5 matches, the corresponding help commands with full paths are generated and placed into the shell history buffer, so you can choose the themes of interest using the standard history navigation (arrow up/down keys). You may use TAB completion to navigate through the category tree. Start with '/' to see the description of the current application. Descend via 'functions', 'objects', 'types', or 'preferences' to the topics of interest.  If you stop in an intermediate category level, both the comment specific to this category and the list of subtopics will be displayed.
    ? Parameters:
    :: ''[[.:common#String |String]]'' ''item'': "word" | "category/subcategory/.../item"


----
{{anchor:history:}}
  ?  **''history''**
  :: Let you choose and edit the commands typed earlier in the interactive shell. The complete history list is written in a temporary file, which is opened with a text editor. Until you store your favorite editor in the custom variable ''$history_editor'', the values of environment variables ''VISUAL'' and ''EDITOR'' are consulted.


----
{{anchor:import_extension:}}
  ?  **''import_extension([[.:common#String |String]] dirname, [[.:common#String |String]] options)''**
  :: Load the extension installed in the directory //dirname//. The directory will be included in the custom list ''@extensions'' in order to load the extension automatically in future sessions. If the extension requires some third-party libraries, which can't automatically be found by its configuration script, you can pass options to it as trailing arguments of this command.  Usually, the error message displayed after the failed attempt to configure the extension will tell you which options you should specify. To obtain the complete list of configuration options supported by the extension, you can pass a single option ''"--help"'', examine its script configure.pl, or just make use of the TAB completion when typing this command.
    ? Parameters:
    :: ''[[.:common#String |String]]'' ''dirname'': top-level directory of the extension
    :: ''[[.:common#String |String]]'' ''options'': options passed to the extension script configure.pl


----
{{anchor:load_commands:}}
  ?  **''load_commands([[.:common#String |String]] filename)''**
  :: Read the lines from the given file, filter out comments and empty lines, append them to the history list of the interactive shell, and enter the replay mode (see ''[[.:core#replay_history |replay_history]]'') starting at the first inserted line.
    ? Parameters:
    :: ''[[.:common#String |String]]'' ''filename''


----
{{anchor:obliterate_extension:}}
  ?  **''obliterate_extension([[.:common#String |String]] extension)''**
  :: Removes all references to the specified extension from your settings, so that the //following// polymake session won't load anything from it. Beware that in the //current// session all the rules and functions defined in the extension remain active! Therefore it's strongly recommended to quit the current session right after executing this command. The files comprising the extension itself are not deleted, however, so that you can re-import the extension later once you need it again.
    ? Parameters:
    :: ''[[.:common#String |String]]'' ''extension'': URI or top-level directory of the extension.


----
{{anchor:reconfigure:}}
  ?  **''reconfigure([[.:common#String |String]] rulename)''**
  :: Repeats the auto-configuration routines stored in the given rulefiles, possibly asking for program paths, options, etc. If the configuration succeeds, and the rulefiles haven't been configured until now, they will be loaded, as well as all other known rulefiles depending on them.
    ? Parameters:
    :: ''[[.:common#String |String]]'' ''rulename'': name of the rulefile with optional prefix and suffix: "[APPNAME::]rulefile[@URI]".  APPNAME should be specified when the rulefile does not belong to the current application;  URI specifies an extension the rulefile comes from.


----
{{anchor:reconfigure_extension:}}
  ?  **''reconfigure_extension([[.:common#String |String]] extension, [[.:common#String |String]] options)''**
  :: Re-run the configuration script of the extension, passing some options to it.  The extension must already have been imported; if not, please use the command ''[[.:core#import_extension |import_extension]]'', which supports passing configuration options too.
    ? Parameters:
    :: ''[[.:common#String |String]]'' ''extension'': URI or top-level directory of the extension.
    :: ''[[.:common#String |String]]'' ''options'': options passed to the extension script configure.pl


----
{{anchor:replay_history:}}
  ?  **''replay_history''**
  :: Bring the interactive shell in the replay mode.  In this mode you can revisit, edit and execute the commands stored in the history. Simply press RETURN if you want to execute the command as is; alternatively you can edit it or jump over it using the usual history navigation keystrokes.  The replay mode is switched off when the last history line has been executed or navigated over. You can leave it prematurely by entering Control-C as well. The replay mode is visually signaled by the history line number in square brackets displayed in the shell prompt.


----
{{anchor:save_history:}}
  ?  **''save_history([[.:common#String |String]] filename)''**
  :: Saves the commands entered in the current and recent sessions in the file. Polymake does it automatically at the end of each interactive session; this command is provided for the case that you might want to store the commands in an alternative file and/or don't want to exit the session. Commands can be loaded using ''[[.:core#load_commands |load_commands]]''.
    ? Parameters:
    :: ''[[.:common#String |String]]'' ''filename'': defaults to ~/.polymake/history


----
{{anchor:show_credits:}}
  ?  **''show_credits''**
  :: Prints the short descriptions of third-party software packages available from within polymake, including the copyright holders and project site URLs. Please note that here you will see only packages for which the polymake interface has been successfully configured; try ''[[.:core#show_unconfigured |show_unconfigured]]'' command to see what's you currently missing.


----
{{anchor:show_extensions:}}
  ?  **''show_extensions''**
  :: Prints the list of active extensions including their URIs and credit notes.


----
{{anchor:show_preferences:}}
  ?  **''show_preferences''**
  :: Prints the currently active preference lists. Please be aware that the output only reflects the persistent preferences; temporary changes made by ''[[.:core#prefer_now |prefer_now]]'' are not displayed even if they might be in effect when this command is executed.


----
{{anchor:show_unconfigured:}}
  ?  **''show_unconfigured''**
  :: Prints the names of all rulefiles visible from the current application, which could not be loaded because of configuration failures (in most cases, due to some lacking external software). You may use the command ''[[.:core#reconfigure |reconfigure]]'' to load some of them if you have installed the required software and/or cleared out other configuration troubles.


----
{{anchor:unconfigure:}}
  ?  **''unconfigure([[.:common#String |String]] rulename)''**
  :: Forgets the configuration made for the given rulefiles and disables them for the //following// polymake sessions.
    ? Parameters:
    :: ''[[.:common#String |String]]'' ''rulename'': name of the rulefile with optional prefix and suffix: "[APPNAME::]rulefile[@URI]".  APPNAME should be specified when the rulefile does not belong to the current application;  URI specifies an extension the rulefile comes from.


----

==== Schemas ====
 Functions for creating and manipulating JSON schemas describing serialized polymake objects.
----
{{anchor:create_permissive_schema:}}
  ?  **''create_permissive_schema(Any object ...)''**
  :: Generate a JSON schema for one or more `big' object types The resulting schema will prescribe the representation of all known properties of the given big object types and allow arbitrary additional properties.
    ? Parameters:
    :: ''Any'' ''object ...'': a big object or a type expression
    ? Returns:
    :''[[.:core:Schema |Schema]]''
    ? Example:
    :: create a schema for Polytope<Rational> and use it for validation of JSON input
    :: <code perl> > $schema = create_permissive_schema(typeof Polytope<Rational>);
 > $schema->validate(decode_json($json_input_string));
</code>
    ? Example:
    :: create a schema for a representative big data object
    :: <code perl> > $g = graph::complete(4);
 > $schema = create_permissive_schema($g);
</code>


----
{{anchor:create_restrictive_schema:}}
  ?  **''create_restrictive_schema(Any object)''**
  :: Generate a JSON schema from a given `big' object instance The resulting schema will exactly match the given object: it will declare all present properties as mandatory and not allow any other properties even if they are defined for the object type in general. Such a schema can be used for manipulating properties of other objects when they are serialized before storing in a file or a database.
    ? Parameters:
    :: ''Any'' ''object''
    ? Returns:
    :''[[.:core:Schema |Schema]]''
    ? Example:
    :: create a schema exactly describing a cross polytope
    :: <code perl> > $c = polytope::cross(3);
 > $schema = create_restrictive_schema($c);
</code>


----
{{anchor:load_schema:}}
  ?  **''load_schema([[.:common#String |String]] filename)''**
  :: Load a JSON schema from a file.
    ? Parameters:
    :: ''[[.:common#String |String]]'' ''filename''
    ? Returns:
    :''[[.:core:Schema |Schema]]''


----
{{anchor:save_schema:}}
  ?  **''save_schema([[.:core:Schema |Schema]] schema, [[.:common#String |String]] filename)''**
  :: Save a JSON schema in a file.
    ? Parameters:
    :: ''[[.:core:Schema |Schema]]'' ''schema'': , e.g. created by ''[[.:core#create_permissive_schema |create_permissive_schema]]'' or ''[[.:core#create_restrictive_schema |create_restrictive_schema]]''
    :: ''[[.:common#String |String]]'' ''filename'': file to store the JSON representation of the schema
    ? Options:
    : 
    :: ''[[.:common#Bool |Bool]]'' ''canonical'': store JSON with pretty indentation and all properties ordered alphabetically.   This is particularly useful if you are going to modify the schema in a text editor.


----