Define an XML-loadable meta-class

1 files changed, 43 insertions, 31 deletions

diff --git a/doc/disfluid.texi b/doc/disfluid.texi
index a73a5c7..06af9e4 100644
--- a/doc/disfluid.texi
+++ b/doc/disfluid.texi
@@ -69,6 +69,7 @@ is tracked in the Guix channel
 * Running an Identity Provider::
 * Running a Resource Server::
 * Running a client::
+* Serialization to (S)XML::
 * Exceptional conditions::
 * GNU Free Documentation License::
 * Index::
@@ -440,26 +441,6 @@ Return an alist with known parameter names for JSON.
 Parse @var{jwk} as a key or a key pair.
 @end deffn
 
-It is also possible to serialize and deserialize the key to and from
-SXML.
-
-@deftypefn {Generic method} <list> ->sxml (@var{key} @code{<public-key>})
-@deftypefnx {Generic method} <list> ->sxml (@var{key} @code{<private-key>})
-@deftypefnx {Generic method} <list> ->sxml (@var{key} @code{<key-pair>})
-Convert @var{key} to an SXML representation that can be parsed back
-with @code{sxml->key}.
-@end deftypefn
-
-@deffn function sxml->key @var{sxml}
-Parse the @var{sxml} fragment back to a key or a key pair. For this to
-work, you need to not touch the
-@url{https://disfluid.planete-kraus.eu/Public_002dkey-cryptography.html#Public_002dkey-cryptography}
-prefix. So, if you pass a @code{jwk} element, it should be
-@code{https://disfluid.planete-kraus.eu/Public_002dkey-cryptography.html#Public_002dkey-cryptography:jwk},
-or @code{jwk} with an explicit @code{xmlns} attribute containing
-@url{https://disfluid.planete-kraus.eu/Public_002dkey-cryptography.html#Public_002dkey-cryptography}.
-@end deffn
-
 @deftypefn {Generic method} <symbol> kty (@var{key} @code{<rsa-key-pair>})
 @deftypefnx {Generic method} <symbol> kty (@var{key} @code{<rsa-public-key>})
 @deftypefnx {Generic method} <symbol> kty (@var{key} @code{<rsa-private-key>})
@@ -635,17 +616,6 @@ Return two alists, following the JSON representation from srfi-180:
 one for the header, and then one for the payload.
 @end deffn
 
-A token can also be serialized as SXML.
-
-@deffn {Generic} ->sxml @var{token}
-Convert @var{token} to an SXML representation.
-@end deffn
-
-@deffn {function} sxml->token @var{token-class} @var{sxml}
-Construct and return a token of class @var{token-class} from
-@var{sxml}.
-@end deffn
-
 @deffn {Generic} lookup-keys @var{token} @var{args}
 Return the set of keys that could be used to sign @var{token}, as a
 public key, a list of keys, or a JWKS. @var{args} is a list of keyword
@@ -1858,6 +1828,48 @@ the @var{client-name} to your application name and @var{client-uri} to
 point to where to a presentation of your application.
 @end deffn
 
+@node Serialization to (S)XML
+@chapter Serialization to (S)XML
+
+The @emph{(webid-oidc serializable)} module provides tools to have
+serialization to SXML and deserialization from XML.
+
+@deftp {Class} <plugin-class> (<class>) @var{module-name} @var{direct-name}
+This metaclass permits to register plugins. @var{module-name} is the
+name of a module that defines the class, and @var{direct-name} is the
+class name without the surrounding angle brackets. Please note that
+all plugin classes should be surrounded by angle brackets.
+
+Most GOOPS classes defined in this program are actually plugin classes.
+
+Serialization works for each slot by serializing other plugin classes
+the normal way, and other values are simply represented as strings
+with @code{display}.
+
+Deserialization works by loading the module containing the target
+class, collecting a value for each slot (a string for
+non-plugin-class-valued slots), and making an instance of that class
+with all collected values. The initialization function should accept
+strings values, for objects that are not of a plugin class.
+
+Since most scheme data types written by @code{display} cannot be read
+in a meaningful way, you may add a @code{#:->sxml} slot option with a
+function taking the slot value and either returning a string that the
+initialization function can parse, or an SXML fragment. For instance,
+if a slot should contain an URI value, you would pass @code{#:->sxml
+uri->string} as options to the slot definition, and accept a string
+value in the initialization function, that you would convert to an URI
+with @code{string->uri}.
+@end deftp
+
+@deffn {function} read/xml @var{port}
+Read the XML document at @var{port} and deserialize it.
+@end deffn
+
+@deffn {function} ->sxml @var{object}
+Convert @var{object} to an SXML fragment.
+@end deffn
+
 @node Exceptional conditions
 @chapter Exceptional conditions