All `polymake` objects are derived from the Poly::Object class. The public interface of this class is described here.

### Construction

$p=new QUALIFIED::NAME( "object_name", "PROPERTY_NAME" => value, ... );
The qualified name must include the application (or module) package the object is declared in, for example Apps::polytope::RationalPolytope.
object_name is an individual object's name used, for example, in the visualization. It can be omitted.
property - value pairs build up the object's initial set of properties. Each value must match the declared property type. Properties can be also added later via explicit Poly::Object::take calls. The property values stay tentative until the Poly::Object::commit method is called.
Naturally, the object name and the property names may be not only string literals, but also arbitrary expressions. They are shown here as literals just to point out that they must evaluate to string values.

### Property access

$p->give("PROPERTY_NAME", ...);
Return the value of the requested property, or a list of values when more than one argument are passed. Lacking properties are created by applying production rules. Failure to create some of them leads to an exception.
The kind of returned value (scalar or array reference) depends on the declared property type. In any case it will be a write-protected value. Trying to change it will cause an exception; always make a copy if you really need to transform the value.
For alternative properties you can use the same syntax as in the rule header: "PROPERTY_1 | PROPERTY_2 ... " .
$p->lookup("PROPERTY_NAME");
Return the value of the given property or undef if it is not currently present in the object. Be aware that this method does not distinguish between a non-existing property and one with undefined value; see the next method if this issue is important for you. No production rules are applied.
$p->exists("PROPERTY_NAME");
Just check the presence of a property; return a boolean.
$p->take("PROPERTY_NAME", value);
Add or overwrite a property. The value must match the declared property type. The new property value stays tentative until the Poly::Object::commit method is called on the object.
$p->remove("PROPERTY_NAME");
Completely remove the specified property from the object. It can get resurrected, however, if requested later.
$v=$p->PROPERTY_NAME; $v=$p->PROPERTY_1 | PROPERTY_2; $p->PROPERTY_NAME=$v;
This is a direct access method which is automatically defined for each declared property. It is a comfortable replacement for both Poly::Object::give and Poly::Object::take, and is executed a little bit faster than those. As shown in the example, it supports alternative requests too.

### Transactions and persistency handling

Transaction is a well-known concept from the database world, serving to provide data consistency. A transaction is a sequence of change operations distributed over a time period, which should be either adopted as a whole or rejected completely. The change operations for a `polymake` object are Poly::Object::take and Poly::Object::remove methods. The following methods are used to control the transaction management:

$p->begin_transaction;
Open a new transaction on the object. Without opening a transaction the use of any changing methods is prohibited.
Transactions can be nested, therefore two subsequent calls to this method will open two transaction levels. The current transaction level can be queried as scalar @{$p->transactions} .
Note that the constructor new described above opens a transaction automatically. A production rule is always executed in an own transaction level, which is committed if the rule succesfully finishes.
$p->commit;
Adopt the changes made in the current transaction and decrease the transaction level. If it was the outermost transaction, the object $p now has exactly the state that will be eventually stored in the data file.
$p->rollback;
Discard the changes made in the current transaction and decrease the transaction level. If it was the outermost transaction, the object $p now has exactly the same set of properties as in the data file it was loaded from, or as committed by the last successful outermost transaction.
$p->changed;
is a boolean attribute telling whether the consistent state of the object is different from the data file contents it was loaded from. An object becomes changed not before the first successful top-level Poly::Object::commit.

See also the user functions load and save.

### Verification

$p->verify("PROPERTY_NAME" | "label", ...);
This is a very useful tool for debugging new production rules. It temporarily hides the specified properties, finds a rule chain to recompute them, and runs it. As the rules produce the new values of the properties, they are compared to the saved values. If everything matches each other, this function quietly returns. Otherwise it rises an exception with a descriptive message. In any case the original properties of the object are restored and the Poly::Object::changed attribute is not set.
If there are some labels among the arguments, only the corresponding labeled production rules are taken into consideration (plus, possibly, some rules supplying their input properties). If the labeled rules fail (e.g. due to unsatisfied preconditions), the rule scheduler does not try the competing rules; rather the verification is considered as failed.
Please remember to quote the arguments, otherwise the property names will be (mis)interperted as methods of direct access to the $this object properties.