#  Copyright (c) 1997-2006
#  Ewgenij Gawrilow, Michael Joswig (Technische Universitaet Berlin, Germany)
#  http://www.math.tu-berlin.de/polymake,  mailto:polymake@math.tu-berlin.de
#
#  This program is free software; you can redistribute it and/or modify it
#  under the terms of the GNU General Public License as published by the
#  Free Software Foundation; either version 2, or (at your option) any
#  later version: http://www.gnu.org/licenses/gpl.txt.
#
#  This program is distributed in the hope that it will be useful,
#  but WITHOUT ANY WARRANTY; without even the implied warranty of
#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#  GNU General Public License for more details.
#-----------------------------------------------------------------------------
#  $Project: polymake $$Id: basic_help 7144 2006-03-02 09:42:24Z gawrilow $

# topic: functions/Basic
# These functions are part of the core user interface.
# They are available in both scripting and interactive modes.


# topic: functions/application
# category: Basic
# args: [ "name" | object ]
#
# Set the current application to the one given by @a name (loading its rules if necessary)
# or by an @a object of the type @c Poly::Application.
#
# Called without arguments just returns the current @c Poly::Application object,
# which is also available in the variable @c $application.
# Say @c{ print $application->name } to see its name.


# topic: functions/include
# category: Basic
# args: "rulefile", ...
#
# Read additional rule files, interpret them in the context of the current application.
# If no paths are specified explicitly, the rulefiles are searched in the current directory as well
# as along the path kept in the variable @c @lookup_rules, stored in your preference file @c ~/.polymake/prefer.pl.


# topic: functions/load
# category: Basic
# args: "filename"
#
# Read the data file @a filename and create the object according to the type @see _type{stored there}.
# If the data file does not contain a type declaration, the @see rules.default_type{default type}
# of the current application is assumed.
#
# When called in a void context (that is, the return value is neither explicitly stored in a variable,
# nor passed to another function) the object is stored in the variable @c $this.  The application which has created
# this data file is then made the current application.


# topic: functions/save
# category: Basic
# args: [ object [, "filename" [, overwrite ]]]
#
# Store the given object, or @c $this if omitted, in a data file.
#
# If @a filename is specified, create the file with this name and store the object there.
# The boolean option @a overwrite allows to overwrite existing files.
# If omitted or @c FALSE, and the given file already exists, emit a warning message and do nothing. 
#
# If @a filename is omitted, write the object back to the file it was loaded from.
# If the object was created with a @c new constructor, a new file is created, with the name consisting
# of the object name (specified by the creation) and the application-specific @see rules.file_suffix{suffix}.
# If the object name is empty, an artificial name of the form @c{ObjectType_NNN} is generated, where @c NNN is an ordinal number.
#
# In any case all open transactions on the object are reverted with @see Poly::Object::rollback prior to writing to the file.
# The save operation is not performed if the @see Poly::Object::changed attribute of the object reverts to @c FALSE after the rollback.


# topic: functions/prefer
# category: Basic
# args: "label" | "label.sublevels" | "*.sublevels" "label", ...
#
# Make the production rules, user functions, or methods labeled with given @a label
# be preferred over competing rules (functions, methods).  The label syntax is the same
# as in the @see rules.prefer directive in the rule files, except that the complex label names
# and wildcards must be quoted in order to obey perl syntax.
#
# The new preference list is also saved in your personal file @c ~/.polymake/prefer.pl
# It remains active in all forthcoming sessions until you revoke it with another
# @c prefer or @see reset_preference command.
#
# For the sake of symmetry you can call this function by its alias name @c set_preference.

# topic: functions/prefer_now
# category: Basic
# args: "label" | "label.sublevels" | "*.sublevels" "label", ...
#
# Has the same effect as @see prefer, but the changes are not persistent.  The lifespan of the
# new preference order lasts up to the end of the current user cycle
# (that is, end of user script or interpretation of the current input line in interactive mode).

# topic: functions/reset_preference
# category: Basic
# args: "label" | "label.sublevels" | "*.sublevels" | "*" | "all"
#
# Reset the matching preference lists to the initial state as declared in the rule files.
# This change is permanent, the former settings are wiped out from the user's preference file
# @c ~/.polymake/prefre.pl
#
# The arguments "*" and "all" revert all preference lists in all loaded applications to the initial state.


# Local Variables:
# mode: perl
# c-basic-offset:3
# End: