Use polymake's JSON format, require polymake 4

CHANGES.md

@@ -1,5 +1,28 @@
 0.9.0 (unreleased)
 
+- polymake 4.0 or newer is now required, and the GAP package json is a new
+  dependency; json needs GAP 4.12, so that is now polymaking's minimum too. polymaking now writes and reads polymake's own JSON data format
+  instead of the pre-4 plain format, which means polymake no longer converts
+  the files and no longer says so (issue #22)
+- nested polymake properties can be named directly, e.g.
+  `Polymake(poly, "HASSE_DIAGRAM.FACES")`
+- `Polymake(poly, "GRAPH")` works again; it used to fail with
+  `POSITION_SUBSTRING: <string> must be a string`
+- when several keywords are given, they are now evaluated independently, so one
+  failing no longer discards the others
+- `MINIMAL_VERTEX_ANGLE` and other floating point properties now return a
+  proper GAP float instead of a rational approximation
+- values decoded from polymake are chosen by polymake's own type rather than by
+  a per-keyword table, so properties polymaking has never heard of are decoded
+  correctly too. `ObjectConverters` and the `ConvertPolymake...` functions are
+  gone, as is `ConvertMatrixToPolymakeString`
+- `AppendToPolymakeObject(poly, name, value)` now takes a GAP value; it used to
+  take a string to append to the file verbatim. The two argument form and
+  `ConvertMatrixToPolymakeString` still work together as before and are
+  deprecated: the latter now hands the section to the former as a record rather
+  than as a string, so code composing the two is unaffected
+- polymaking will not write to a file it did not create
+
 - polymaking is now configured via the GAP user preferences `PolymakeCommand`
   and `PolymakeDataDirectory` (issues #16, #19)
 - the data directory is determined lazily and re-created when it has vanished,
@@ -22,8 +45,9 @@
   and no longer rewrites `tst/pplane.poly` in place while running (issue #18).
   Set `POLYMAKING_CHULL` to test a specific backend, e.g.
   `POLYMAKING_CHULL=cdd gap tst/testall.g`.
-- the globals `POLYMAKE_COMMAND` and `POLYMAKE_DATA_DIR` are no longer set by
-  the package; if you set them yourself they are still honoured
+- the globals `POLYMAKE_COMMAND` and `POLYMAKE_DATA_DIR` are deprecated. They
+  are still set, and still honoured if you set them before loading polymaking,
+  but the preferences above are the ones to use
 
 ------------------
 0.8.9 (2026-04-08)

PackageInfo.g

@@ -50,8 +50,8 @@ PackageDoc := rec(
 ),
 
 Dependencies := rec(
-  GAP := ">=4.8",
-  NeededOtherPackages := [],
+  GAP := ">= 4.12",   # this is what the json package requires
+  NeededOtherPackages := [ [ "json", ">= 2.0.0" ] ],
   SuggestedOtherPackages := [],
   NeededSystemPackages := rec( Ubuntu := [["polymake"]] ),
   ExternalConditions := [["polymake must be installed", "https://www.polymake.org"]]

README.md

@@ -21,12 +21,10 @@ National University of Ireland, Galway
 Requirements
 ------------
 
-polymaking requires GAP version 4.8. It also needs polymake to be
-installed.  The GAPDoc package is needed to display the documentation.
-polymaking was written for the "first generation" polymake which was
-called as a command-line tool. Using it with a current ("next generation")
-version of polymake will result in longer runtimes and fewer supported
-keywords/features.
+polymaking requires GAP version 4.12, the GAP package json, and polymake 4.0
+or newer. The GAPDoc package is needed to display the documentation.
+
+Use polymaking 0.8.9 if you need to work with polymake 3 or older.
 
 
 Installation

doc/environment.xml

@@ -9,26 +9,25 @@
  But it should be as platform independent as ⪆ and polymake.
  <P/>
  The interaction with polymake is restricted to writing files and
- carrying out simple operations. These looked like 
+ carrying out simple operations. polymaking writes a data file in polymake's
+ own JSON format and then asks polymake to evaluate properties of it, using
+ the script <C>lib/pm.pl</C>:
 
  <Br/>
-<C>polymake file KEYWORD1 KEYWORD2 KEYWORD3</C>
-<Br/>
-
- on the command line for polymake versions before 4. The keywords are polymake methods without arguments. 
- Since polymake no longer supports this interface the polymaking package 
- provides the script <C>lib/pm_script_arg.pl</C> to emulate this. 
-
- <Br/>
- <C>polymake &ndash;&ndash;script lib/pm_script_arg.pl KEYWORD1 KEYWORD2 KEYWORD3</C>
+ <C>polymake &ndash;&ndash;script lib/pm.pl RESULTFILE OBJECTFILE KEYWORD1 KEYWORD2</C>
  <Br/>
 
+ The keywords are polymake properties or methods without arguments. The script
+ writes the results as JSON to <C>RESULTFILE</C>, which &GAP; reads back with
+ the <Package>json</Package> package; going through a file rather than through
+ standard output keeps the results clear of anything polymake prints.
+
  Using custom scripts is not supported.<Br/>
 Every call to polymake will re-start the program anew. This causes considerable overhead.
 The number of calls to polymake is reduced by caching the results in the so-called 
 <K>PolymakeObject</K> in GAP.
-As of polymaking version 0.8.0, old versions of polymake (i.e. versions before 2.7.9) are not 
-supported anymore.
+As of polymaking version 0.9.0, polymake 4.0 or newer is required. Use
+polymaking 0.8.9 with older versions of polymake.
 
 
 <Section Label="chap:polymakeinstall">

doc/input.xml

@@ -3,14 +3,14 @@
    The interaction with the polymake program is done via files. A 
    <K>PolymakeObject</K> is mainly a pointer to a file and a list of
    known properties of the object. These properties need not be stored
-   in the file. Whenever polymake is called, the returned value is
-   read from standard output and stored in the <K>PolymakeObject</K>
-   corresponding to the file for which polymake is called.
+   in the file. Whenever polymake is called, the returned values are
+   read back and stored in the <K>PolymakeObject</K> corresponding to the
+   file for which polymake was called.
 
-   The files for polymake are written in the old (non-xml) format.
-   The first run of polymake converts them into the new (xml) format. This
-   means that changes to the file by means of the methods outlined below 
-   after the first run of polymake will probably lead to corrupted files.
+   The files are written in polymake's own JSON format. Writing to a
+   <K>PolymakeObject</K> rewrites the whole file from the properties given so
+   far, which means a file may be extended at any point, also after polymake
+   has been called for it.
 
    <ManSection>
     <Meth Name="CreateEmptyFile" Arg="filename" />
@@ -39,11 +39,12 @@
       "poly1340.1"). If <A>prefix</A> is given, the filename starts
       with this prefix. 
 
-      Optionally, the file can be generated with a header specifying
-      application, version and type of the object. This is done by passing the
-      triple of strings <A>appvertyp</A> to 
-      <Ref Meth="CreatePolymakeObject"/>. A valid triple is 
-      <C>["polytope","2.3","RationalPolytope"]</C>. Validity is checked by 
+      Objects are of polymake type <C>polytope::Polytope&lt;Rational&gt;</C>
+      unless another type is given. A type may be passed either as a qualified
+      polymake 4 type name, or as the triple of strings <A>appvertyp</A> the
+      pre-0.9 interface used, for example
+      <C>["polytope","2.3","RationalPolytope"]</C>; in the latter case the
+      version is ignored and the application and type are joined, see 
       <Ref Meth="CheckAppVerTypList"/>.
     </Description>
    </ManSection>
@@ -70,15 +71,17 @@
 
      This method generates a <K>PolymakeObject</K> corresponding to
      the file <A>filename</A> in the directory <A>dir</A>. If
-     <A>dir</A> is not given, the <K>POLYMAKE&uscore;DATA&uscore;DIR</K> is
-     used.If no file with name <A>filename</A> exists in <A>dir</A> (or
-     <K>POLYMAKE&uscore;DATA&uscore;DIR</K>, respectively), an empty file is created.
+     <A>dir</A> is not given, <Ref Func="PolymakeDataDirectory"/> is used. If
+     no file of that name exists there, a new one is created.
 
-     Note that the contents of the file do not matter for the
+     Note that the contents of an existing file do not matter for the
      generation of the object. In particular, the object does not know
      any of the properties that might be encoded in the file. The only
      way to transfer information from files to <K>PolymakeObject</K>s
-     is via <Ref Meth="Polymake"/>.
+     is via <Ref Meth="Polymake"/>. polymaking will not write to a file it
+     did not create, so the methods of Section 
+     <Ref Sect="WritingToObjects"/> raise an error for such an object; polymake
+     may read files in any format it understands.
 
     </Description>
    </ManSection>
@@ -211,15 +214,15 @@ rec(
    resulting polymake file is still consistent.
 
    <ManSection>
-    <Meth Name="AppendToPolymakeObject" Arg="poly string"/>
+    <Meth Name="AppendToPolymakeObject" Arg="poly name value"/>
     <Returns>nothing</Returns>
     <Description>
-     This appends the string <A>string</A> to the file associated to
-     the <K>PolymakeObject</K>
-     <A>poly</A>. It is not tested if the string is syntactically
-     correct as a part of a polymake file. It is also not tested if
-     the string is compatible with the data already contained in the
-     file.
+     Sets the polymake property <A>name</A> of <A>poly</A> to <A>value</A> and
+     rewrites the file. Rational numbers are written the way polymake spells
+     them; no check is made that <A>value</A> is meaningful for <A>name</A>, or
+     consistent with the properties set so far.
+     <P/>
+     Before version 0.9 this took a string to append verbatim to the file.
     </Description>    
    </ManSection>
 
@@ -230,12 +233,9 @@ rec(
    <Meth Name="AppendPointlistToPolymakeObject" Arg="poly pointlist"/>
    <Returns>nothing</Returns>
    <Description>
-      Takes a list <A>pointlist</A> of vectors and converts it into a
-      string which represents a polymake block labeled "POINTS". This
-      string is then added to the file associated with <A>poly</A>.
-      The "POINTS" block of the file associated with <A>poly</A> then
-      contains points with leading ones, as polymake uses affine
-      notation.
+      Sets the "POINTS" property of <A>poly</A> to the list
+      <A>pointlist</A> of vectors. The points are written with leading ones, as
+      polymake uses affine notation.
    </Description>
    </ManSection>
 
@@ -252,38 +252,22 @@ rec(
    <Meth Name="AppendInequalitiesToPolymakeObject" Arg="poly ineqlist"/>
    <Returns>nothing</Returns>
    <Description>
-     Just appends the inequalities given in <A>ineqlist</A> to  the polymake
-     object <A> poly</A> (with caption "INEQUALITIES"). Note that this does 
-     not check if an "INEQUALITIES" section does already exist in the file 
-     associated with <A>poly</A>.
+     Sets the "INEQUALITIES" property of the polymake object <A>poly</A> to
+     <A>ineqlist</A>. Unlike points and vertices, inequalities are written as
+     given.
    </Description>
    </ManSection>
 
 
-  <ManSection>
-   <Meth  Name="ConvertMatrixToPolymakeString" Arg="name matrix"/>
-   <Returns>String</Returns>
-   <Description>
-    This function takes a matrix <A>matrix</A> and converts it to a
-    string. This string can then be appended to a polymake file via
-    <Ref Meth="AppendToPolymakeObject"/> to form a block of data labeled
-    <A>name</A>.
-
-    This may be used to write blocks like INEQUALITIES or FACETS.
-   </Description>
-   </ManSection>
-
    <ManSection>
     <Meth Name="ClearPolymakeObject" Arg="poly[, appvertyp]"/>
     <Returns>nothing</Returns>
     <Description>
      Deletes all known properties of the <K>PolymakeObject</K>
-     <A>poly</A> and replaces its file with an empty one.
+     <A>poly</A> and replaces its file with an empty object of the same type.
      <Br/>
-     If the triple of strings <A>appvertyp</A> specifying application, version
-     and type (see <Ref Meth="CheckAppVerTypList"/>) is given, the file is
-     replaced with a file that contains only a header specifying application,
-     version and type of the polymake object.
+     If <A>appvertyp</A> is given, the object is given that polymake type
+     instead, see <Ref Meth="CreatePolymakeObject"/>.
     </Description>
    </ManSection>