====== BigObject Core::Object ======
//from application [[..:core|core]]//\\
\\
 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.

===== Methods =====

==== no category ====
{{anchor:apply_rule:}}
  ?  **''apply_rule([[..:common#String |String]] pattern)''**
  :: Executes the specified production rule. If the object does not possess enough initial properties to provide all required rule sources, or any of its preconditions are not satisfied, an exception is raised.
    ? Parameters:
    :: ''[[..:common#String |String]]'' ''pattern'': either a label (see ''[[..:core#prefer |prefer]]'') or a rule header.        The rule header must exactly match the definition in the rulefile,        up to white spaces around property names.        If the given pattern matches headers of several rules, or the given label        is associated with several rules, the rule chain with smallest total weight        (including the rules supplying the source properties) is chosen.


----
{{anchor:attach:}}
  ?  **''attach([[..:common#String |String]] name, Any data, [[..:common#String |String]] constructor_args)''**
  :: Attach an arbitrary data item to a `big' object. Attachments are saved in the same data file as the `big' object itself. They can be retrieved by calling ''[[..:core:Core_Object#get_attachment |get_attachment]]''.
    ? Parameters:
    :: ''[[..:common#String |String]]'' ''name'': attachment name, can be an arbitrary string.                      If an attachment with the given name already exists,                      it is silently replaced with new data.
    :: ''Any'' ''data'': attachment data, can be a simple numeric scalar, a string,                   or a complex data type, e.g. a ''[[..:common#Matrix |Matrix]]'' or ''[[..:common#Polynomial |Polynomial]]''.                   `Big' objects, anonymous arrays or hashes are not allowed.
    :: ''[[..:common#String |String]]'' ''constructor_args'': optional list of property names of the owning `big' object               which should be passed to the attached data constructor when it will be               restored from a data file.  Properties of subobjects are specified               in dotted path notation.  For example, for an attachment of type ''[[..:common#NodeMap |NodeMap]]''               you must specify the "ADJACENCY" property containing the graph               the map is referring to.


----
{{anchor:disable_rules:}}
  ?  **''disable_rules([[..:common#String |String]] pattern)''**
  :: Temporarily disable production rules matching given pattern for an object. Rules are re-enabled after the complete execution of the current script or input expression in interactive mode. Works much like the user function ''[[..:core:Core_Object#disable_rules |disable_rules]]'' but only affecting the given object.
    ? Parameters:
    :: ''[[..:common#String |String]]'' ''pattern'': either a label (see ''[[..:core#prefer |prefer]]'') or a rule header.        The rule header must exactly match the definition in the rulefile,        up to white spaces around property names.        If the given pattern matches headers of several rules, or the given label        is associated with several rules, they all will be disabled regardless        their precoditions, weights, or other attributes.


----
{{anchor:dont_save:}}
  ?  **''dont_save''**
  :: Clears the `changed' flag in the object, so that it won't be saved in the XML file it stems from. This method is primarily designed for unit tests, but could be also useful in interactive mode if you want to revert all recent changes and reload the object from the data file.


----
{{anchor:get_attachment:}}
  ?  **''get_attachment([[..:common#String |String]] name)''**
  :: Retrieve data stored in the given attachment.
    ? Parameters:
    :: ''[[..:common#String |String]]'' ''name'': attachment name


----
{{anchor:get_schedule:}}
  ?  **''get_schedule([[..:common#String |String]] request)''**
  :: Compose an optimal chain of production rules providing all requested properties. The returned RuleChain object can be applied to the original object as well as to any other object with the same initial set of properties.  If no feasible rule chain exists, `undef' is returned. To watch the rule scheduler at work, e.g. to see announcements about tried preconditions, you may temporarily increase the verbosity levels ''$Verbose::rules'' and ''$Verbose::scheduler''.
    ? Parameters:
    :: ''[[..:common#String |String]]'' ''request'': name of a property with optional alternatives or a property path in dotted notation.                         Several requests may be listed.
    ? Returns:
    :''[[..:core:Core_RuleChain |Core::RuleChain]]''
    ? Example:
    :: generate an optimal rule chain for a parameterized family of polytopes:
    :: <code perl> > @p=map { new Polytope("POINTS" => my_matrix($_) ) } 1..10;
 > $s=$p[0]->get_schedule("FACETS", "TRIANGULATION.FACETS");
 > $s->apply($_) for @p;
</code>


----
{{anchor:list_attachments:}}
  ?  **''list_attachments''**
  :: Return names of all attachments as a list of strings.


----
{{anchor:list_names:}}
  ?  **''list_names''**
  :: Returns the list of names of multiple subobject instances. This method can be applied to any instance of a multiple subobject. For a normal (non-multiple) subobject or a top-level object just returns its name.
    ? Example:
    :: List all names of linear programs associated with a polytope:
    :: <code perl> > print join(" ", $p->LP->list_names);
</code>


----
{{anchor:list_properties:}}
  ?  **''list_properties([[..:common#Bool |Bool]] deep)''**
  :: Returns the list of names of all properties kept in the object.
    ? Parameters:
    :: ''[[..:common#Bool |Bool]]'' ''deep'': recursively descend in all subobjects                    and list their properties in dotted notation.


----
{{anchor:properties:}}
  ?  **''properties()''**
  :: Returns or prints a string with all properties (names and values) and subobjects.
    ? Options:
    : 
    :: ''[[..:common#Int |Int]]'' ''maxdepth'': descend into subobjects up to given depth, default 0


----
{{anchor:remove:}}
  ?  **''remove([[..:common#String |String]] prop)''**
  :: Remove the property //prop// from the object. The property must be //mutable//, //multiple//, or unambiguously reconstructible from the remaining properties.
    ? Parameters:
    :: ''[[..:common#String |String]]'' ''prop'': property name or a path to a property in a subobject in dotted notation,                      Several properties may be removed at once.
  ?  **''remove([[..:core:Core_Object |Core::Object]] subobj)''**
  :: Remove the multiple subobject instance(s) from the object.
    ? Parameters:
    :: ''[[..:core:Core_Object |Core::Object]]'' ''subobj'': multiple subobject instance.                     Several subobjects may be removed at once.


----
{{anchor:remove_attachment:}}
  ?  **''remove_attachment([[..:common#String |String]] name)''**
  :: Remove the given attachment from the `big' object.
    ? Parameters:
    :: ''[[..:common#String |String]]'' ''name'': attachment name
    ? Returns:
    :''Any''


----
{{anchor:set_as_default:}}
  ?  **''set_as_default''**
  :: Makes the multiple subobject instance the default one. Physically this means moving it at the 0-th position in the instance list. The instance can be selected by give() or PROPERTY_NAME access method.
    ? Example:
    :: by current position:
    :: <code perl> > $p->TRIANGULATION->[$i]->set_as_default;
</code>
    ? Example:
    :: by subobject name:
    :: <code perl> > $p->TRIANGULATION("placing")->set_as_default;
</code>
    ? Example:
    :: by checking for a specific property:
    :: <code perl> > $p->TRIANGULATION(sub { defined($_->lookup("WEIGHTS")) })->set_as_default;
</code>
    ? Example:
    :: by analyzing all instances and picking the best one:
    :: <code perl> > for (@{$p->TRIANGULATION}) { assign_min($min_facets, $_->N_FACETS) and $t=$_ } $t->set_as_default;
</code>


----
{{anchor:set_as_default_now:}}
  ?  **''set_as_default_now''**
  :: Temporarily make the multiple subobject instance the default one. The change is automatically reverted at the end of the current user cycle. Usage as ''[[..:core:Core_Object#set_as_default |set_as_default]]''.


----