user_guide:extend:clients

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
user_guide:extend:clients [2021/01/12 15:38] – external edit 127.0.0.1user_guide:extend:clients [2021/06/17 06:43] (current) – Update from perl::Object to BigObject oberlaender
Line 30: Line 30:
 ==== Object Interface ==== ==== Object Interface ====
  
-Under Objects in this section the "big" polymake objects are meant, like Polytope or SimplicialComplex.  They are represented by C++ class ''perl::Object'', which is automatically defined if you include ''polymake/client.h'' The interface of ''perl::Object'' looks practically identical to that of its perl brother ''[[scripting:start#Object|Object]]'', up to inevitable syntactical deviations.+Under Objects in this section the "big" polymake objects are meant, like Polytope or SimplicialComplex.  They are represented by C++ class ''BigObject'', which is automatically defined if you include ''polymake/client.h'' The interface of ''BigObject'' looks practically identical to that of its perl brother ''[[scripting:start#Object|Object]]'', up to inevitable syntactical deviations.
  
 Wherever a string literal appears as a function argument in the examples below, a ''std::string'' instance may be used as well. Wherever a string literal appears as a function argument in the examples below, a ''std::string'' instance may be used as well.
Line 37: Line 37:
  
   -- Creating an empty object:   -- Creating an empty object:
-    ? ''%%perl::Object p("Polytope<Rational>");%%''+    ? ''%%BigObject p("Polytope<Rational>");%%''
     :: with a type given literally     :: with a type given literally
-    ? ''%%perl::Object p("Polytope", mlist<CoordType>());%%''+    ? ''%%BigObject p("Polytope", mlist<CoordType>());%%''
     :: with a parametrized type depending on template parameters of the enclosing function or class     :: with a parametrized type depending on template parameters of the enclosing function or class
-    ? ''%%perl::Object p(q.type());%%'' +    ? ''%%BigObject p(q.type());%%'' 
-    :: with a same type as of another ''perl::Object'' +    :: with a same type as of another ''BigObject'' 
-    ? ''%%perl::Object p(t);%%''+    ? ''%%BigObject p(t);%%''
     :: with a type given by an [[#ObjectType]] instance     :: with a type given by an [[#ObjectType]] instance
   .. An empty object may be filled with properties one by one, using ''take'' methods described further.  The initialization phase is completed as soon as one of the following happens:   .. An empty object may be filled with properties one by one, using ''take'' methods described further.  The initialization phase is completed as soon as one of the following happens:
Line 50: Line 50:
   .. After this, the object becomes //immutable//, that is, only properties declared as //mutable// may be changed and/or added.   .. After this, the object becomes //immutable//, that is, only properties declared as //mutable// may be changed and/or added.
   -- Creating an object in an //invalid// state:   -- Creating an object in an //invalid// state:
-    ? ''perl::Object p{};'' +    ? ''BigObject p{};'' 
-    :: The default constructor is primarily provided to enable arrays of Objects.  The only allowed operations on an Object in invalid state is an assignment from another ''perl::Object''.+    :: The default constructor is primarily provided to enable arrays of Objects.  The only allowed operations on an Object in invalid state is an assignment from another ''BigObject''.
   -- Creating a copy of another object:   -- Creating a copy of another object:
-    ? ''%%perl::Object p=q.copy();%%''+    ? ''%%BigObject p=q.copy();%%''
     :: as an exact copy less temporary properties     :: as an exact copy less temporary properties
-    ? ''%%perl::Object p("Polytope<Float>", q);%%''+    ? ''%%BigObject p("Polytope<Float>", q);%%''
     :: as a copy of the same or related type specified literally     :: as a copy of the same or related type specified literally
-    ? ''%%perl::Object p(t, q);%%''+    ? ''%%BigObject p(t, q);%%''
     :: ... or given by an [[#ObjectType]] instance     :: ... or given by an [[#ObjectType]] instance
   .. The object created this way is //immutable// from the very beginning.   .. The object created this way is //immutable// from the very beginning.
   .. The source and target types in the converting copy constructor are called //related// if either one of them is derived from another, or both stem from the same parametrized type.  If the target type is the ancestor of the source type, only properties being common to both types are copied, the rest is silently discarded.  The same applies for augmented subobject types: only properties defined for the stand-alone object type are copied.  Copying from one parametrized instance to another implies conversion of all properties whose types are dependent on the parameters being different between the target and the source.   .. The source and target types in the converting copy constructor are called //related// if either one of them is derived from another, or both stem from the same parametrized type.  If the target type is the ancestor of the source type, only properties being common to both types are copied, the rest is silently discarded.  The same applies for augmented subobject types: only properties defined for the stand-alone object type are copied.  Copying from one parametrized instance to another implies conversion of all properties whose types are dependent on the parameters being different between the target and the source.
   .. For example, let ''p'' be a ''Polytope<Rational>'':   .. For example, let ''p'' be a ''Polytope<Rational>'':
-    * ''%%perl::Object q("Polytope<Float>", p)%%'' will convert ''VERTICES'', ''FACETS'', and all other coordinate-related properties from ''Matrix<Rational>'' into ''Matrix<Float>'', ''Vector<Rational>'' into ''Vector<Float>'', etc. +    * ''%%BigObject q("Polytope<Float>", p)%%'' will convert ''VERTICES'', ''FACETS'', and all other coordinate-related properties from ''Matrix<Rational>'' into ''Matrix<Float>'', ''Vector<Rational>'' into ''Vector<Float>'', etc. 
-    * ''%%perl::Object g=p.give("GRAPH");%%''\\ ''%%perl::Object q=g.copy();%%'' won't copy ''EDGE_DIRECTIONS'' because this property is only defined for a graph of a polytope but not for a stand-alone graph object. +    * ''%%BigObject g=p.give("GRAPH");%%''\\ ''%%BigObject q=g.copy();%%'' won't copy ''EDGE_DIRECTIONS'' because this property is only defined for a graph of a polytope but not for a stand-alone graph object. 
-    * ''%%perl::Object q("PointConfiguration", p);%%'' is invalid, because the source and target types are unrelated.+    * ''%%BigObject q("PointConfiguration", p);%%'' is invalid, because the source and target types are unrelated.
  
-**Attention:** the standard copy constructor ''perl::Object::Object(const perl::Object&)'' and assignment operator ''perl::Object::operator=(const perl::Object&)'' are defined, but doesn't do what you would suppose at the first glance.  They don't create any new objects nor change their values.  Instead, they are working with smart references tied to the real perl-side objects (and therefore are very cheap).  As usual in perl, the smart references are counted, so that the real object is destroyed only when the last reference goes out of scope.  Be sure to use the ''copy'' method if you really need an new independent object.+**Attention:** the standard copy constructor ''BigObject::Object(const BigObject&)'' and assignment operator ''BigObject::operator=(const BigObject&)'' are defined, but doesn't do what you would suppose at the first glance.  They don't create any new objects nor change their values.  Instead, they are working with smart references tied to the real perl-side objects (and therefore are very cheap).  As usual in perl, the smart references are counted, so that the real object is destroyed only when the last reference goes out of scope.  Be sure to use the ''copy'' method if you really need an new independent object.
  
 === File operations === === File operations ===
Line 72: Line 72:
 A "big" object can be loaded from a data file and saved in a new data file: A "big" object can be loaded from a data file and saved in a new data file:
  
-  perl::Object p=perl::Object::load("filename"); +  BigObject p=BigObject::load("filename"); 
-  perl::Object q("type");+  BigObject q("type");
   q.save("filename");   q.save("filename");
  
Line 92: Line 92:
  
 When creating an empty object, the name can be specified as an optional trailing argument of any constructor: When creating an empty object, the name can be specified as an optional trailing argument of any constructor:
-  perl::Object p("Polytope<Rational>, "name");+  BigObject p("Polytope<Rational>, "name");
  
 === Type === === Type ===
  
-  ? ''%%perl::ObjectType t=p.type();%%''+  ? ''%%BigObjectType t=p.type();%%''
   :: retrieve the current type of the Object.  The class [[#ObjectType]] is described further   :: retrieve the current type of the Object.  The class [[#ObjectType]] is described further
   ? ''%%p.isa("TightSpan")%%''   ? ''%%p.isa("TightSpan")%%''
Line 117: Line 117:
   ? ''%%Matrix<Rational> V = p.give("VERTICES");%%''   ? ''%%Matrix<Rational> V = p.give("VERTICES");%%''
   ? ''%%p.give("VERTICES") >> V;%%''   ? ''%%p.give("VERTICES") >> V;%%''
-  :: retrieve the property value.  If it does not exist yet, it will be created using production rules; if this is impossible, an exception ''perl::undefined'' will be raised.+  :: retrieve the property value.  If it does not exist yet, it will be created using production rules; if this is impossible, an exception ''undefined'' will be raised.
   ? ''%%p.give("VERTICES | POINTS") >> V;%%''   ? ''%%p.give("VERTICES | POINTS") >> V;%%''
   :: retrieve the value of one of the alternatives, whatever exists or is cheaper to compute   :: retrieve the value of one of the alternatives, whatever exists or is cheaper to compute
Line 124: Line 124:
   ? ''%%p.take("FACETS") << F;%%''   ? ''%%p.take("FACETS") << F;%%''
   :: set the property value.  Unless the property is declared as //mutable//, this operation is only allowed during the initialization phase and in production rules having this property among their declared targets.   :: set the property value.  Unless the property is declared as //mutable//, this operation is only allowed during the initialization phase and in production rules having this property among their declared targets.
-  ? ''%%p.take("FACETS_THRU_VERTICES", perl::temporary) << F;%%''+  ? ''%%p.take("FACETS_THRU_VERTICES", temporary) << F;%%''
   :: create a temporary property.  It will survive until the end of the execution cycle.  In the interactive mode, the cycle ends after the complete evaluation of the last input line; in scripting mode it is the termination of the script.   :: create a temporary property.  It will survive until the end of the execution cycle.  In the interactive mode, the cycle ends after the complete evaluation of the last input line; in scripting mode it is the termination of the script.
   ? ''%%p.remove("POINTS_IN_FACETS");%%''   ? ''%%p.remove("POINTS_IN_FACETS");%%''
Line 131: Line 131:
 === Subobjects === === Subobjects ===
  
-A subobject is an Object attached to another (parent) Object as a property.  The class ''perl::Object'' is used for accessing subobjects as well as top-level Objects.+A subobject is an Object attached to another (parent) Object as a property.  The class ''BigObject'' is used for accessing subobjects as well as top-level Objects.
  
-  ? ''%%perl::Object g=p.give("GRAPH");%%''+  ? ''%%BigObject g=p.give("GRAPH");%%''
   :: retrieve a subobject by property name   :: retrieve a subobject by property name
   ? ''%%p.give("GRAPH.ADJACENCY") >> G;%%''   ? ''%%p.give("GRAPH.ADJACENCY") >> G;%%''
   :: retrieve an atomic property through several layers of hierarchy.  Intermediate subobjects (here: GRAPH) do not need to exist up front, they may be created by production rules.   :: retrieve an atomic property through several layers of hierarchy.  Intermediate subobjects (here: GRAPH) do not need to exist up front, they may be created by production rules.
-  ? ''%%perl::Object p=g.parent();%%''+  ? ''%%BigObject p=g.parent();%%''
   :: navigate to the parent object   :: navigate to the parent object
   ? ''%%if (p.valid()) ...%%''   ? ''%%if (p.valid()) ...%%''
Line 157: Line 157:
  
   -- adding and removing   -- adding and removing
-    ? ''%%perl::Object lp=p.add("LP");%%''+    ? ''%%BigObject lp=p.add("LP");%%''
     :: add a new, empty subobject, to be filled later by calling ''%%lp.take(...)%%''     :: add a new, empty subobject, to be filled later by calling ''%%lp.take(...)%%''
-    ? ''%%perl::Object lp=p.add("LP", perl::temporary);%%''+    ? ''%%BigObject lp=p.add("LP", temporary);%%''
     :: add an empty subobject temporarily     :: add an empty subobject temporarily
     ? ''%%p.add("LP", lp);%%''     ? ''%%p.add("LP", lp);%%''
     :: add a fully initialized subobject     :: add a fully initialized subobject
-    ? ''%%p.add("LP", lp, perl::temporary);%%''+    ? ''%%p.add("LP", lp, temporary);%%''
     :: add it temporarily     :: add it temporarily
     ? ''%%p.remove(lp);%%''     ? ''%%p.remove(lp);%%''
     :: remove the specified instance of a subobject; please note the difference to ''%%remove("LP")%%'' which would remove //all// instances attached under the given property.     :: remove the specified instance of a subobject; please note the difference to ''%%remove("LP")%%'' which would remove //all// instances attached under the given property.
   -- retrieving   -- retrieving
-    ? ''%%polymake::Array<perl::Object> lps = p.give_all("LP");%%''+    ? ''%%polymake::Array<BigObject> lps = p.give_all("LP");%%''
     :: all instances at once.  The result will be empty if the requested property does not exist in the given object.  Note that manipulating the array, for example, deleting some of its elements, would not affect the original objects.  Thanks to smart pointers behind the scene they all will survive.  But you should in general handle such an Array as ''const'', just in order to avoid confusions and surprises about "unexpected" behavior.     :: all instances at once.  The result will be empty if the requested property does not exist in the given object.  Note that manipulating the array, for example, deleting some of its elements, would not affect the original objects.  Thanks to smart pointers behind the scene they all will survive.  But you should in general handle such an Array as ''const'', just in order to avoid confusions and surprises about "unexpected" behavior.
-    ? ''%%perl::Object lp=p.lookup("LP", "name");%%''+    ? ''%%BigObject lp=p.lookup("LP", "name");%%''
     :: retrieve an instance by its name     :: retrieve an instance by its name
-    ? ''%%perl::Object sd=p.lookup("SCHLEGEL_DIAGRAM", PolymakeOptions("FACET", 1));%%''+    ? ''%%BigObject sd=p.lookup("SCHLEGEL_DIAGRAM", PolymakeOptions("FACET", 1));%%''
     :: retrieve an instance with matching values of one or more properties; if nothing matching is found, returns an Object in invalid state.     :: retrieve an instance with matching values of one or more properties; if nothing matching is found, returns an Object in invalid state.
     ? ''%%sd=p.give("SCHLEGEL_DIAGRAM", PolymakeOptions("FACET", 1));%%''     ? ''%%sd=p.give("SCHLEGEL_DIAGRAM", PolymakeOptions("FACET", 1));%%''
     :: retrieve an existing instance or create a new one with the given property values if no matching instance exists yet     :: retrieve an existing instance or create a new one with the given property values if no matching instance exists yet
-    ? ''%%sd=p.give("SCHLEGEL_DIAGRAM", PolymakeOptions("FACET", 1), perl::temporary);%%''+    ? ''%%sd=p.give("SCHLEGEL_DIAGRAM", PolymakeOptions("FACET", 1), temporary);%%''
     :: ... a new instance is created temporarily     :: ... a new instance is created temporarily
     ? ''%%sd=p.give("SCHLEGEL_DIAGRAM");%%''     ? ''%%sd=p.give("SCHLEGEL_DIAGRAM");%%''
Line 184: Line 184:
  
 === Rule Schedules === === Rule Schedules ===
-  ? ''%%perl::Object::Schedule s=p.CallPolymakeMethod("get_schedule", "PROPERTY", ...);%%''+  ? ''%%BigObject::Schedule s=p.CallPolymakeMethod("get_schedule", "PROPERTY", ...);%%''
   :: Determine the optimal sequence of production rules providing the given properties.  Properties of subobjects are specified in the same dotted notations as in the ''give()'' call.  The object created by this method can be used in the following operations:   :: Determine the optimal sequence of production rules providing the given properties.  Properties of subobjects are specified in the same dotted notations as in the ''give()'' call.  The object created by this method can be used in the following operations:
   ? ''s.valid()''   ? ''s.valid()''
Line 190: Line 190:
   ? ''s.apply(q)''   ? ''s.apply(q)''
   :: Executes the production rules on the given Object.  //q// may be the same as //p//, that is, the Object used to determine the sequence, or any other Object of the same type and with the same set of properties as //p// had before the call to ''get_schedule''.   :: Executes the production rules on the given Object.  //q// may be the same as //p//, that is, the Object used to determine the sequence, or any other Object of the same type and with the same set of properties as //p// had before the call to ''get_schedule''.
-  ? ''perl::ListResult props=s.list_new_properties();''+  ? ''ListResult props=s.list_new_properties();''
   :: Returns a list of names of all properties that would be created in the course of executing the rule sequence.  Properties in subobjects are encoded in dotted notation.  The list will be free of duplicates even if some production rules have common target properties.  The order of names in the list is, however, absolutely random.   :: Returns a list of names of all properties that would be created in the course of executing the rule sequence.  Properties in subobjects are encoded in dotted notation.  The list will be free of duplicates even if some production rules have common target properties.  The order of names in the list is, however, absolutely random.
   :: Sometimes, when ''get_schedule'' is called on a subobject, the list might contain rules applicable to the parent object and further ancestors.  In this case, the names of properties created there will be reported with a prefix ''parent.'' repeated as many times as many levels in the hierarchy they are sitting above the given subobject.   :: Sometimes, when ''get_schedule'' is called on a subobject, the list might contain rules applicable to the parent object and further ancestors.  In this case, the names of properties created there will be reported with a prefix ''parent.'' repeated as many times as many levels in the hierarchy they are sitting above the given subobject.
Line 198: Line 198:
  
   ? ''%%p.attach("NAME") << data;%%''   ? ''%%p.attach("NAME") << data;%%''
-  ? ''%%p.take("NAME", perl::attachment) << data;%%''+  ? ''%%p.take("NAME", attachment) << data;%%''
   :: add or replace the named attachment   :: add or replace the named attachment
   ? ''%%if (p.get_attachment("NAME") >> data)%%''   ? ''%%if (p.get_attachment("NAME") >> data)%%''
Line 205: Line 205:
   :: remove the named attachment   :: remove the named attachment
  
-You can store in attachments data items of primitive types like ''int'' or ''std::string'' as well as C++ classes declared on the perl side as admissible property types, like ''Matrix'', ''Set'', or ''std::list'' Instances of ''perl::Object'' are **not** allowed as attachments.+You can store in attachments data items of primitive types like ''int'' or ''std::string'' as well as C++ classes declared on the perl side as admissible property types, like ''Matrix'', ''Set'', or ''std::list'' Instances of ''BigObject'' are **not** allowed as attachments.
  
 Clients called within production rules may not access any attachments.  Allowing to do so would imply the non-deterministic behavior of rules, because attachments do not contribute to the Object's intrinsic state and can be changed by user. Clients called within production rules may not access any attachments.  Allowing to do so would imply the non-deterministic behavior of rules, because attachments do not contribute to the Object's intrinsic state and can be changed by user.
Line 211: Line 211:
 ==== ObjectType ==== ==== ObjectType ====
  
-The class ''perl::ObjectType'' is primarily used as a helper to construct ''perl::Object'' instances, as shown in examples [[#Object_interface|above]].  There is not much what could else be done with this class.+The class ''BigObjectType'' is primarily used as a helper to construct ''BigObject'' instances, as shown in examples [[#Object_interface|above]].  There is not much what could else be done with this class.
  
-  ? ''%%perl::ObjectType t("Polytope<Rational>");%%''+  ? ''%%BigObjectType t("Polytope<Rational>");%%''
   :: construct a type specified literally   :: construct a type specified literally
-  ? ''%%perl::ObjectType t("Polytope", mlist<CoordType>());%%''+  ? ''%%BigObjectType t("Polytope", mlist<CoordType>());%%''
   :: construct a type depending on template parameters of the enclosing function or class   :: construct a type depending on template parameters of the enclosing function or class
-  ? ''%%perl::ObjectType t = p.type();%%'' +  ? ''%%BigObjectType t = p.type();%%'' 
-  :: retrieve the current type of a ''perl::Object''+  :: retrieve the current type of a ''BigObject''
   ? ''t.name()''   ? ''t.name()''
   :: get the type name as a ''std::string'', e.g. ''%%"Polytope<Rational>"%%''   :: get the type name as a ''std::string'', e.g. ''%%"Polytope<Rational>"%%''
Line 240: Line 240:
 === Variable argument lists === === Variable argument lists ===
 Optional (keyword) arguments, ubiquitous in ''VISUAL'' functions, can be either passed in-line: Optional (keyword) arguments, ubiquitous in ''VISUAL'' functions, can be either passed in-line:
-  obj.call_method("VISUAL", perl::OptionSet("FacetColor", "blue", "FacetTransparency", 0.5));+  obj.call_method("VISUAL", OptionSet("FacetColor", "blue", "FacetTransparency", 0.5));
 or prepared up front: or prepared up front:
-  perl::OptionSet opts;+  BigOptionSet opts;
   opts["FacetColor"] << "blue";   opts["FacetColor"] << "blue";
   opts["FacetTransparency"] << 0.5;   opts["FacetTransparency"] << 0.5;
Line 249: Line 249:
  
 Any container object can be passed elementwise to a function using ''unroll'' wrapper: Any container object can be passed elementwise to a function using ''unroll'' wrapper:
-  Array<perl::Object> objects; +  Array<BigObject> objects; 
-  call_function("name", ..., perl::unroll(objects), ...);+  call_function("name", ..., unroll(objects), ...);
      
 Finally, the argument list can be composed dynamically, providing arguments one by one: Finally, the argument list can be composed dynamically, providing arguments one by one:
Line 269: Line 269:
   call_function(...) >> x >> y >> z;   call_function(...) >> x >> y >> z;
   std::vector<std::string> labels;   std::vector<std::string> labels;
-  call_function(...) >> perl::unroll(labels);+  call_function(...) >> unroll(labels);
 The number of values returned by the function does not need to exactly match the number of target variables; excess values are silently dropped, while excess variables stay unchanged.  An unrolled container swallows all return values not consumed so far. The number of values returned by the function does not need to exactly match the number of target variables; excess values are silently dropped, while excess variables stay unchanged.  An unrolled container swallows all return values not consumed so far.
  
Line 298: Line 298:
 Using a cached pointer allows to call function templates without injecting their definition body in the caller source code, so that they can be defined in a different application or bundled extension.  The function may also have several labeled alternative implementations selectable by preference lists.  The cached pointer is automatically following the changes introduced by user commands [[:user_guide:howto:shell_custom#preferences|prefer, prefer_now, and reset_preference]].  Using a cached pointer allows to call function templates without injecting their definition body in the caller source code, so that they can be defined in a different application or bundled extension.  The function may also have several labeled alternative implementations selectable by preference lists.  The cached pointer is automatically following the changes introduced by user commands [[:user_guide:howto:shell_custom#preferences|prefer, prefer_now, and reset_preference]]. 
  
-There is, however, a restriction posed on the eligible functions: they must not have keyword arguments (perl::OptionSet), arguments with default values or explicit type parameters.  The reason for this restriction is that all this is processed in the perl layer which is bypassed when calling over a pointer.+There is, however, a restriction posed on the eligible functions: they must not have keyword arguments (OptionSet), arguments with default values or explicit type parameters.  The reason for this restriction is that all this is processed in the perl layer which is bypassed when calling over a pointer.
  
 An example of use of a cached function pointer for an overloaded function is solve_LP in application polytope. An example of use of a cached function pointer for an overloaded function is solve_LP in application polytope.
 ==== Miscellaneous functions ==== ==== Miscellaneous functions ====
-  ? ''%%var = perl::get_custom("name")%%'' +  ? ''%%var = get_custom("name")%%'' 
-  :: Retrieve the value of a custom variable.  The name must be fully qualified with the package name unless it's defined in the package of the same application as this code belongs to.  If the custom variable is of an array or hash map type, the C++ local variable being assigned to must be of type ''perl::ListResult'' resp. ''perl::OptionSet''+  :: Retrieve the value of a custom variable.  The name must be fully qualified with the package name unless it's defined in the package of the same application as this code belongs to.  If the custom variable is of an array or hash map type, the C++ local variable being assigned to must be of type ''ListResult'' resp. ''OptionSet''
-  ? ''%%var = perl::get_custom("name", "key")%%''+  ? ''%%var = get_custom("name", "key")%%''
   :: Retrieve the value of an element of a custom hash map variable.   :: Retrieve the value of an element of a custom hash map variable.
-  ? ''%%perl::save_data("filename", var, "description");%%''+  ? ''%%save_data("filename", var, "description");%%''
   :: Store an item of a data type known as a [[user_guide:extend:rulefiles#type_definitions|property type]] (not a "big" object!) in an XML file.  The description string is optional.   :: Store an item of a data type known as a [[user_guide:extend:rulefiles#type_definitions|property type]] (not a "big" object!) in an XML file.  The description string is optional.
-  ? ''%%var = perl::load_data("filename");%%''+  ? ''%%var = load_data("filename");%%''
   :: Retrieve the data stored in an XML file created with ''save_data''.   :: Retrieve the data stored in an XML file created with ''save_data''.
  
-All retrieval functions, similar to ''Object::give()'', can also be used with an "input" ''%%operator >>%%'' : \\ ''%%perl::get_custom("name") >> var;%%''+All retrieval functions, similar to ''Object::give()'', can also be used with an "input" ''%%operator >>%%'' : \\ ''%%get_custom("name") >> var;%%''
  
-  ? ''%%int d = perl::get_debug_level();%%''+  ? ''%%int d = get_debug_level();%%''
   :: Get the current value of the global variable ''$DebugLevel'', which is initially set according to the occurrence of ''-d'' command-line options of ''polymake'' main script.  A C++ client may decide to produce additional debugging output depending on this value.   :: Get the current value of the global variable ''$DebugLevel'', which is initially set according to the occurrence of ''-d'' command-line options of ''polymake'' main script.  A C++ client may decide to produce additional debugging output depending on this value.
 ==== Connection to perl ==== ==== Connection to perl ====
Line 356: Line 356:
   .. For example, the signature ''func(Matrix)'' matches any of the following C++ functions (return types do not matter here): \\ ''template <typename X> int func(X);'' \\ ''template <typename X> int func(const Matrix<X>&);'' \\ ''template <typename M, typename X> int func(const GenericMatrix<M,X>&);''   .. For example, the signature ''func(Matrix)'' matches any of the following C++ functions (return types do not matter here): \\ ''template <typename X> int func(X);'' \\ ''template <typename X> int func(const Matrix<X>&);'' \\ ''template <typename M, typename X> int func(const GenericMatrix<M,X>&);''
   ? ObjectType   ? ObjectType
-  :: A `big' polymake object is always kept in a C++ object of class ''perl::Object'' Both concrete types and parametrized types can be used: +  :: A `big' polymake object is always kept in a C++ object of class ''BigObject'' Both concrete types and parametrized types can be used: 
-    * ''int func(perl::Object o);'' \\ ''%%Function4perl(func, "func(Polytope)");%%'' \\ any Polytope would match +    * ''int func(BigObject o);'' \\ ''%%Function4perl(func, "func(Polytope)");%%'' \\ any Polytope would match 
-    * ''int func(perl::Object o);'' \\ ''%%Function4perl(func, "func(Polytope<Rational>)");%%'' \\ only Polytope with Rational coordinates would match +    * ''int func(BigObject o);'' \\ ''%%Function4perl(func, "func(Polytope<Rational>)");%%'' \\ only Polytope with Rational coordinates would match 
-    * ''template <typename Coord> int func(perl::Object o);'' \\ ''%%FunctionTemplate4perl("func<Coord>(Polytope<Coord>)");%%'' \\ any Polytope would match; the coordinate type will be included into the generated wrapper code as an explicit type parameter.+    * ''template <typename Coord> int func(BigObject o);'' \\ ''%%FunctionTemplate4perl("func<Coord>(Polytope<Coord>)");%%'' \\ any Polytope would match; the coordinate type will be included into the generated wrapper code as an explicit type parameter.
   ? ''&''   ? ''&''
   :: A signature element with this modifier must correspond to a parameter of the C++ function passed by a non-const reference.  Trying to pass a write-protected object property to such a function will cause an exception.   :: A signature element with this modifier must correspond to a parameter of the C++ function passed by a non-const reference.  Trying to pass a write-protected object property to such a function will cause an exception.
Line 370: Line 370:
   :: Optional arguments must have default values, otherwise an exception will be raised by an attempt to initialize the C++ parameter with an ''undef'' value.  The corresponding parameters of the C++ function themselves do not need to be declared with default values, because the C++ function will always be called with a full list of arguments.   :: Optional arguments must have default values, otherwise an exception will be raised by an attempt to initialize the C++ parameter with an ''undef'' value.  The corresponding parameters of the C++ function themselves do not need to be declared with default values, because the C++ function will always be called with a full list of arguments.
   ? ''+''   ? ''+''
-  :: An element with this modifier swallows a list of arbitrarily many objects of matching type.  The corresponding argument of the C++ function must be an appropriate container like ''Set'', ''Array'', or ''std::vector'' \\ For "big" objects like ''Polytope'' the container type must be ''%%Array<perl::Object>%%'' An attempt to use any other container will fail miserably.+  :: An element with this modifier swallows a list of arbitrarily many objects of matching type.  The corresponding argument of the C++ function must be an appropriate container like ''Set'', ''Array'', or ''std::vector'' \\ For "big" objects like ''Polytope'' the container type must be ''%%Array<BigObject>%%'' An attempt to use any other container will fail miserably.
   ? ''@''   ? ''@''
   :: This element swallows all trailing arguments of any //elementary// types, even of different ones.  The corresponding argument of the C++ function must be a container.  If the type of any of the trailing argument does not match the element type of this container (and can't be converted to it), an exception is raised.  Don't define the C++ function with ellipsis parameter ''%%...%%'' !   :: This element swallows all trailing arguments of any //elementary// types, even of different ones.  The corresponding argument of the C++ function must be a container.  If the type of any of the trailing argument does not match the element type of this container (and can't be converted to it), an exception is raised.  Don't define the C++ function with ellipsis parameter ''%%...%%'' !
   ? ''%%{ option_key => default_value, ... }%%''   ? ''%%{ option_key => default_value, ... }%%''
-  :: The keyword-value pairs are gathered in a hash map before the C++ function is called, the corresponding parameter must be of type ''perl::OptionSet'' Options with ''undef'' default values are not stored in the OptionSet unless explicitly specified by the caller.  Options with other default values are always be passed to the C++ function.+  :: The keyword-value pairs are gathered in a hash map before the C++ function is called, the corresponding parameter must be of type ''BigOptionSet'' Options with ''undef'' default values are not stored in the OptionSet unless explicitly specified by the caller.  Options with other default values are always be passed to the C++ function.
  
  
  • user_guide/extend/clients.txt
  • Last modified: 2021/06/17 06:43
  • by oberlaender