From b7cfbd886e35b227f09bd07db8989115a084b084 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Wed, 13 Sep 2023 00:54:04 +0200 Subject: Move around info nodes. --- doc/ref/calp.texi | 1 + doc/ref/general.texi | 3 - doc/ref/general/data-formats.texi | 26 --- doc/ref/general/data-stores.texi | 36 ----- doc/ref/general/webdav.texi | 301 ----------------------------------- doc/ref/vcomponent.texi | 3 + doc/ref/vcomponent/data-formats.texi | 27 ++++ doc/ref/vcomponent/data-stores.texi | 36 +++++ doc/ref/webdav.texi | 301 +++++++++++++++++++++++++++++++++++ 9 files changed, 368 insertions(+), 366 deletions(-) delete mode 100644 doc/ref/general/data-formats.texi delete mode 100644 doc/ref/general/data-stores.texi delete mode 100644 doc/ref/general/webdav.texi create mode 100644 doc/ref/vcomponent/data-formats.texi create mode 100644 doc/ref/vcomponent/data-stores.texi create mode 100644 doc/ref/webdav.texi (limited to 'doc') diff --git a/doc/ref/calp.texi b/doc/ref/calp.texi index 5815d922..d54bce22 100644 --- a/doc/ref/calp.texi +++ b/doc/ref/calp.texi @@ -67,6 +67,7 @@ text @footnote{Improvements welcome} @include calp-prime.texi @include entry-points.texi @include general.texi +@include webdav.texi @include vcomponent.texi @include web.texi @include text.texi diff --git a/doc/ref/general.texi b/doc/ref/general.texi index a6fce4e7..a2fc2ca3 100644 --- a/doc/ref/general.texi +++ b/doc/ref/general.texi @@ -26,7 +26,4 @@ of these should be generally useful in any project. @include general/util-type.texi @include general/util-object.texi @include general/lens.texi -@include general/data-formats.texi -@include general/data-stores.texi -@include general/webdav.texi @include general/sxml.texi diff --git a/doc/ref/general/data-formats.texi b/doc/ref/general/data-formats.texi deleted file mode 100644 index 592b3085..00000000 --- a/doc/ref/general/data-formats.texi +++ /dev/null @@ -1,26 +0,0 @@ -@node Data Formats -@section Data Formats - -A data format is some way that an individual event may get serialized -to disk. The default is iCalendar (TODO reference RFC 5545), but -others might be available (TODO footnote and reference xcal). - -Each available format should be included as -@code{(vcomponent formats @var{format-name})}. -Which module corresponds to what file type is currently defined out of band. - -Each module should expose the following procedures. - -@defun serialize component port -Write a serialized representation of @var{component} to @var{port}. -@end defun - -@defun deserialize port -Read a serialized representation of a component from @var{port}, and -return the deserialized instance of this object. -@end defun - -@subsection iCalendar -RFC 5545 - -@subsection xCal diff --git a/doc/ref/general/data-stores.texi b/doc/ref/general/data-stores.texi deleted file mode 100644 index ec3962da..00000000 --- a/doc/ref/general/data-stores.texi +++ /dev/null @@ -1,36 +0,0 @@ -@node Data Stores -@section Data Stores -Data stores are persistant stores for events, such as databases or the -file system. Each data store can support any number of data formats, -but which is an implementation detail of that format and shouldn't be -needed information from the high level view. -@footnote{It is however important for interoperability with other programs}. - -@c (make #:path ``hello'') - -@defun path store -@end defun - -@deftp {GOOPS method} get-calendar this -Returns a vcomponent object of type @code{VCALENDAR}. Should contain -all @code{VEVENT} components of this calendar. -@end deftp - -@deftp {GOOPS method} get-by-uid this uid -Return the event object with UID equal to the string @var{uid}. -@end deftp - -@deftp {GOOPS method} queue-save this event -Queue a save event of @var{event} to the store. -@end deftp - -@deftp {GOOPS method} flush this -Force write of all queued actions. -@end deftp - -@subsection VDir -[VDIR]: http://vdirsyncer.pimutils.org/en/latest/vdir.html - -@subsection File - -@subsection SQLite diff --git a/doc/ref/general/webdav.texi b/doc/ref/general/webdav.texi deleted file mode 100644 index a495c945..00000000 --- a/doc/ref/general/webdav.texi +++ /dev/null @@ -1,301 +0,0 @@ -@node WebDAV -@section WebDAV - -For a complete view of WebDAV, please see @cite{RFC4918 (HTTP -Extensions for Web Distributed Authoring and Versioning (WebDAV))}, -but in short, and specifc for this implementation. - -A DAV tree consists of resources, which are analogous to files and -directories. A resource is referenced by its href. - -Each resources is either a collection and have children, or have -content. Parts of this implementation allows a collection to also have -contents, while other does not. The standard doesn't seem to mind -either way. - -Each resource also has a set of properties, modelling metadata and -extra data about the resource. - -@emph{href}'s are internally represented as lists of strings, where the -root element ``/'' is an empty list, and all other cases are mapped -like: -@example -"/a/b" ⇒ '("a" "b") -@end example - -@emph{resources} are GOOPS objects, which the base class -@code{}. - -The user (of the library) is assumed to designate one resource -instance as the root of the resource tree. All other resources are -then added as (grand-)children to that resource. Each resource has a -field @var{name}, which is the normative name used when searching by -name in the tree@footnote{This means that one resource can't easily -exist at multiple points in the tree}. - -@emph{properties} are split into live and dead properties, where live -properties have extra handling by the server, while dead properties -are simply carried along after the end-user put them on a resource. - -Live properties are handled through GOOPS methods. - -Dead properties are (by default) stored directly inside each resource. - -@node WebDAV Properties -@subsection Properties - -@itemize -@item @code{(calp webdav property)} -@item @code{(calp webdav propfind)} -@end itemize - -@subsubsection Default Live Properties - -@deftp {GOOPS method} creationdate -@end deftp - -@deftp {GOOPS method} displayname -@end deftp - -@deftp {GOOPS method} getcontentlanguage -@end deftp - -@deftp {GOOPS method} getcontentlength -@end deftp - -@deftp {GOOPS method} getcontenttype -@end deftp - -@deftp {GOOPS method} getetag -@end deftp - -@deftp {GOOPS method} getlastmodified -@end deftp - -@deftp {GOOPS method} lockdiscovery -@end deftp - -@deftp {GOOPS method} resourcetype -@end deftp - -@deftp {GOOPS method} supportedlock -@end deftp - - -@node WebDAV Resources -@subsection Resources - -@deftp {GOOPS class} -Base type for all WebDAV resources. - -The base class shouldn't be directly instanciated. - - @defun resource? x - Is the given object a , or decendant? - @end defun -@end deftp - -@deftp {GOOPS method} name resource -The name of a resource is the local part of a href. -@end deftp - -@deftp {GOOPS method} children resource -All direct children of a resource, as a list. -@end deftp - -@defun add-child! parent child [#:overwrite?] [#:collection?=(is-collection? child)] -Adds a resource as a child of another resource. - -Before adding the resource to the parents child set, -@code{(setup-new-resource! child parent)} is called. If -@var{collection?} is true, then -@code{(setup-new-collection! child parent)} is also called. - -If @var{overwrite?} is present, then the parent will be checked for a -child which already has that name, and take action accordingly. -It will return one of: @code{'replaced} if a resource already existed -with that name, but it has been replaced, @code{'collision}, if the -old one was kept, and @code{'created} if the new resource was added -without collisions. - -If @var{overwrite?} is absent then the method always returns @var{'created}. -@end defun - -@defun add-resource! resource name content -Creates a new resource with the given name, and make it a child of -@var{self}. Setting its initial content to @var{content}. - -Calls @code{add-resource!}, so the same book-keeping procedures are called. -@c TODO Document throw -@c TODO Document return -@end defun - -@defun add-collection! resource name -Similar to @code{add-resource!} but the created resource is instead a collection. -@end defun - -@deftp {GOOPS method} setup-new-resource! (self ) (parent ) -Book-keeping procedure called by @code{add-resource!} on @emph{all} -added resources. - -Base implementation in a no-op. -@end deftp - -@deftp {GOOPS method} setup-new-collection! (self ) (parent ) -Book-keeping procedure called by @code{add-resource!} if -@var{collection?} is true. - -Base implementation is a no-op. -@end deftp - -@deftp {GOOPS method} is-collection? resource -Is the given resource a collection. - -The base implementation simply checks if the resource has any children. -@end deftp - -@deftp {GOOPS method} content resource -@deftpx {GOOPS method} set-content! resource content -Get and set the content of a given resource. @var{content}s type can -be anything that the given resource type accepts. Overrides of this -procedure should preferably save its contents properly. -@end deftp - -@c - -@defun get-property resource xml-tag -@defunx get-live-property resource xml-tag -@defunx get-dead-property resource xml-tag -@end defun - - -@defun set-property resource xml-el -@defunx set-property! resource xml-el -@defunx set-dead-property resource xml-el -@defunx set-dead-property! resource xml-el -@defunx set-live-property resource xml-el -@defunx set-live-property! resource xml-el -@end defun - - -@defun remove-property resource xml-tag -@defunx remove-property! resource xml-tag -@defunx remove-dead-property resource xml-tag -@defunx remove-dead-property! resource xml-tag -@defunx remove-live-property resource xml-tag -@defunx remove-live-property! resource xml-tag -@end defun - -@c - -@deftp {GOOPS method} copy-resource (resource ) include-children? [name] -Create a new resource which looks as similar as possible to the given -resource. The new resource will have the same (GOOPS) class as the -source, displayname, contentlanguage and all dead properties are -transfered, other live properties are currently not explicitly -transfered (but probably still transfered implicitly). - -The new resources name is @var{name} if given, and the name of the -original resource otherwise. - -If @var{include-children?} is true then a deep copy is performed, -otherwise no children are copied, and the resulting resource will be a -leaf node. - -Content is copied verbatim. - -@b{NOTE} currently no helper method is called, which means that extra -resources held by the resource object can't be copied. -For example, FILE can't create a copy (but it also shouldn't do that -here, but rathen when the element is ``mounted'' into the tree). -@end deftp - -@c - -@defun lookup-resource root-resource path -@end defun - - -@defun all-resources-under resource [prefix='()] -Returns the given resource, and all its children in a flat list. - -Currently depth first, but that might change. -The root resource is however guaranteed to be first. -@end defun - -@c - -@c TODO - make-live-property - live-property? - property-getter - - property-setter-generator - property-remover-generator - - prepare-update-properties - - live-properties - dead-properties - - webdav-properties - - -@node WebDAV Resource Types -@subsection Resource Types - -@subsubsection @code{(calp webdav resource base)} - -Implementation of @code{(calp webdav resource)}. Exists to possibly -avoid dependency loops. - -@subsubsection @code{(calp webdav resource calendar)} -@subsubsection @code{(calp webdav resource file)} - -Resources backed by the file system. - -@defun file-resource? x -@end defun - -@deftp {GOOPS method} children -@end deftp - -@deftp {GOOPS method} is-collection? -@end deftp - -@deftp {GOOPS method} creationdate -Retrived directly from the file through @command{stat -c %W $@{filename@}}. -@end deftp - -@deftp {GOOPS method} content -@deftpx {GOOPS method} set-content! data -Directly interfaced with the file. - -Data can't be retrieved for collections, and will always be -returned as a bytevector for non-collections. - -Data can be set either as a string or a bytevector. When a string is -used Guile's current encoding will be used. -@end deftp - -@subsubsection @code{(calp webdav resource virtual)} - -@node WebDAV Utilities -@subsection Utilities -@defun xml-element-hash-key xml-tag -Given an xml tag object @ref{xml-tag}, return a suitable key for -@code{hash-ref} and family. - -These key objects should preferably not be carried around for -long. Prefer to keep the @emph{real} xml-tag object, and only call -this while directly referencing the hash table. -@end defun - -@defun href->string href -HREF's are represented as lists of strings. The root resource (``/'') -is the empty list. -@end defun - -@defun string->href string -Return a href list back into a string. A leading slash will always be added. -@end defun diff --git a/doc/ref/vcomponent.texi b/doc/ref/vcomponent.texi index 76acf6c3..5823e88e 100644 --- a/doc/ref/vcomponent.texi +++ b/doc/ref/vcomponent.texi @@ -10,3 +10,6 @@ Some of these values are still Calp specific. @include vcomponent/general.texi @include vcomponent/create.texi + +@include vcomponent/data-formats.texi +@include vcomponent/data-stores.texi diff --git a/doc/ref/vcomponent/data-formats.texi b/doc/ref/vcomponent/data-formats.texi new file mode 100644 index 00000000..a871ea1a --- /dev/null +++ b/doc/ref/vcomponent/data-formats.texi @@ -0,0 +1,27 @@ +@node Data Formats +@section Data Formats + +Data formats are the serialization formats for components. +The primary serialization format is iCalendar, but xCalendar and +sxCalendar also exists. + +Each available format should be included as +@code{(vcomponent formats @var{format-name})}. +Which module corresponds to what file type is currently defined out of +band. + +Each module should expose the following procedures. + +@defun serialize component port +Write a serialized representation of @var{component} to @var{port}. +@end defun + +@defun deserialize port +Read a serialized representation of a component from @var{port}, and +return the deserialized instance of this object. +@end defun + +@subsection iCalendar +RFC 5545 + +@subsection xCal diff --git a/doc/ref/vcomponent/data-stores.texi b/doc/ref/vcomponent/data-stores.texi new file mode 100644 index 00000000..ec3962da --- /dev/null +++ b/doc/ref/vcomponent/data-stores.texi @@ -0,0 +1,36 @@ +@node Data Stores +@section Data Stores +Data stores are persistant stores for events, such as databases or the +file system. Each data store can support any number of data formats, +but which is an implementation detail of that format and shouldn't be +needed information from the high level view. +@footnote{It is however important for interoperability with other programs}. + +@c (make #:path ``hello'') + +@defun path store +@end defun + +@deftp {GOOPS method} get-calendar this +Returns a vcomponent object of type @code{VCALENDAR}. Should contain +all @code{VEVENT} components of this calendar. +@end deftp + +@deftp {GOOPS method} get-by-uid this uid +Return the event object with UID equal to the string @var{uid}. +@end deftp + +@deftp {GOOPS method} queue-save this event +Queue a save event of @var{event} to the store. +@end deftp + +@deftp {GOOPS method} flush this +Force write of all queued actions. +@end deftp + +@subsection VDir +[VDIR]: http://vdirsyncer.pimutils.org/en/latest/vdir.html + +@subsection File + +@subsection SQLite diff --git a/doc/ref/webdav.texi b/doc/ref/webdav.texi new file mode 100644 index 00000000..cc361e71 --- /dev/null +++ b/doc/ref/webdav.texi @@ -0,0 +1,301 @@ +@node WebDAV +@chapter WebDAV + +For a complete view of WebDAV, please see @cite{RFC4918 (HTTP +Extensions for Web Distributed Authoring and Versioning (WebDAV))}, +but in short, and specifc for this implementation. + +A DAV tree consists of resources, which are analogous to files and +directories. A resource is referenced by its href. + +Each resources is either a collection and have children, or have +content. Parts of this implementation allows a collection to also have +contents, while other does not. The standard doesn't seem to mind +either way. + +Each resource also has a set of properties, modelling metadata and +extra data about the resource. + +@emph{href}'s are internally represented as lists of strings, where the +root element ``/'' is an empty list, and all other cases are mapped +like: +@example +"/a/b" ⇒ '("a" "b") +@end example + +@emph{resources} are GOOPS objects, which the base class +@code{}. + +The user (of the library) is assumed to designate one resource +instance as the root of the resource tree. All other resources are +then added as (grand-)children to that resource. Each resource has a +field @var{name}, which is the normative name used when searching by +name in the tree@footnote{This means that one resource can't easily +exist at multiple points in the tree}. + +@emph{properties} are split into live and dead properties, where live +properties have extra handling by the server, while dead properties +are simply carried along after the end-user put them on a resource. + +Live properties are handled through GOOPS methods. + +Dead properties are (by default) stored directly inside each resource. + +@node WebDAV Properties +@section Properties + +@itemize +@item @code{(calp webdav property)} +@item @code{(calp webdav propfind)} +@end itemize + +@subsection Default Live Properties + +@deftp {GOOPS method} creationdate +@end deftp + +@deftp {GOOPS method} displayname +@end deftp + +@deftp {GOOPS method} getcontentlanguage +@end deftp + +@deftp {GOOPS method} getcontentlength +@end deftp + +@deftp {GOOPS method} getcontenttype +@end deftp + +@deftp {GOOPS method} getetag +@end deftp + +@deftp {GOOPS method} getlastmodified +@end deftp + +@deftp {GOOPS method} lockdiscovery +@end deftp + +@deftp {GOOPS method} resourcetype +@end deftp + +@deftp {GOOPS method} supportedlock +@end deftp + + +@node WebDAV Resources +@section Resources + +@deftp {GOOPS class} +Base type for all WebDAV resources. + +The base class shouldn't be directly instanciated. + + @defun resource? x + Is the given object a , or decendant? + @end defun +@end deftp + +@deftp {GOOPS method} name resource +The name of a resource is the local part of a href. +@end deftp + +@deftp {GOOPS method} children resource +All direct children of a resource, as a list. +@end deftp + +@defun add-child! parent child [#:overwrite?] [#:collection?=(is-collection? child)] +Adds a resource as a child of another resource. + +Before adding the resource to the parents child set, +@code{(setup-new-resource! child parent)} is called. If +@var{collection?} is true, then +@code{(setup-new-collection! child parent)} is also called. + +If @var{overwrite?} is present, then the parent will be checked for a +child which already has that name, and take action accordingly. +It will return one of: @code{'replaced} if a resource already existed +with that name, but it has been replaced, @code{'collision}, if the +old one was kept, and @code{'created} if the new resource was added +without collisions. + +If @var{overwrite?} is absent then the method always returns @var{'created}. +@end defun + +@defun add-resource! resource name content +Creates a new resource with the given name, and make it a child of +@var{self}. Setting its initial content to @var{content}. + +Calls @code{add-resource!}, so the same book-keeping procedures are called. +@c TODO Document throw +@c TODO Document return +@end defun + +@defun add-collection! resource name +Similar to @code{add-resource!} but the created resource is instead a collection. +@end defun + +@deftp {GOOPS method} setup-new-resource! (self ) (parent ) +Book-keeping procedure called by @code{add-resource!} on @emph{all} +added resources. + +Base implementation in a no-op. +@end deftp + +@deftp {GOOPS method} setup-new-collection! (self ) (parent ) +Book-keeping procedure called by @code{add-resource!} if +@var{collection?} is true. + +Base implementation is a no-op. +@end deftp + +@deftp {GOOPS method} is-collection? resource +Is the given resource a collection. + +The base implementation simply checks if the resource has any children. +@end deftp + +@deftp {GOOPS method} content resource +@deftpx {GOOPS method} set-content! resource content +Get and set the content of a given resource. @var{content}s type can +be anything that the given resource type accepts. Overrides of this +procedure should preferably save its contents properly. +@end deftp + +@c + +@defun get-property resource xml-tag +@defunx get-live-property resource xml-tag +@defunx get-dead-property resource xml-tag +@end defun + + +@defun set-property resource xml-el +@defunx set-property! resource xml-el +@defunx set-dead-property resource xml-el +@defunx set-dead-property! resource xml-el +@defunx set-live-property resource xml-el +@defunx set-live-property! resource xml-el +@end defun + + +@defun remove-property resource xml-tag +@defunx remove-property! resource xml-tag +@defunx remove-dead-property resource xml-tag +@defunx remove-dead-property! resource xml-tag +@defunx remove-live-property resource xml-tag +@defunx remove-live-property! resource xml-tag +@end defun + +@c + +@deftp {GOOPS method} copy-resource (resource ) include-children? [name] +Create a new resource which looks as similar as possible to the given +resource. The new resource will have the same (GOOPS) class as the +source, displayname, contentlanguage and all dead properties are +transfered, other live properties are currently not explicitly +transfered (but probably still transfered implicitly). + +The new resources name is @var{name} if given, and the name of the +original resource otherwise. + +If @var{include-children?} is true then a deep copy is performed, +otherwise no children are copied, and the resulting resource will be a +leaf node. + +Content is copied verbatim. + +@b{NOTE} currently no helper method is called, which means that extra +resources held by the resource object can't be copied. +For example, FILE can't create a copy (but it also shouldn't do that +here, but rathen when the element is ``mounted'' into the tree). +@end deftp + +@c + +@defun lookup-resource root-resource path +@end defun + + +@defun all-resources-under resource [prefix='()] +Returns the given resource, and all its children in a flat list. + +Currently depth first, but that might change. +The root resource is however guaranteed to be first. +@end defun + +@c + +@c TODO + make-live-property + live-property? + property-getter + + property-setter-generator + property-remover-generator + + prepare-update-properties + + live-properties + dead-properties + + webdav-properties + + +@node WebDAV Resource Types +@section Resource Types + +@subsection @code{(calp webdav resource base)} + +Implementation of @code{(calp webdav resource)}. Exists to possibly +avoid dependency loops. + +@subsection @code{(calp webdav resource calendar)} +@subsection @code{(calp webdav resource file)} + +Resources backed by the file system. + +@defun file-resource? x +@end defun + +@deftp {GOOPS method} children +@end deftp + +@deftp {GOOPS method} is-collection? +@end deftp + +@deftp {GOOPS method} creationdate +Retrived directly from the file through @command{stat -c %W $@{filename@}}. +@end deftp + +@deftp {GOOPS method} content +@deftpx {GOOPS method} set-content! data +Directly interfaced with the file. + +Data can't be retrieved for collections, and will always be +returned as a bytevector for non-collections. + +Data can be set either as a string or a bytevector. When a string is +used Guile's current encoding will be used. +@end deftp + +@subsection @code{(calp webdav resource virtual)} + +@node WebDAV Utilities +@section Utilities +@defun xml-element-hash-key xml-tag +Given an xml tag object @ref{xml-tag}, return a suitable key for +@code{hash-ref} and family. + +These key objects should preferably not be carried around for +long. Prefer to keep the @emph{real} xml-tag object, and only call +this while directly referencing the hash table. +@end defun + +@defun href->string href +HREF's are represented as lists of strings. The root resource (``/'') +is the empty list. +@end defun + +@defun string->href string +Return a href list back into a string. A leading slash will always be added. +@end defun -- cgit v1.2.3