diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/ref/Makefile | 2 | ||||
| -rw-r--r-- | doc/ref/guile.texi | 4 | ||||
| -rw-r--r-- | doc/ref/guile/data-formats.texi | 25 | ||||
| -rw-r--r-- | doc/ref/guile/data-stores.texi | 36 | ||||
| -rw-r--r-- | doc/ref/guile/sxml.texi | 100 | ||||
| -rw-r--r-- | doc/ref/guile/util-path.texi | 30 | ||||
| -rw-r--r-- | doc/ref/guile/util.texi | 62 | ||||
| -rw-r--r-- | doc/ref/guile/vcomponent.texi | 41 | ||||
| -rw-r--r-- | doc/ref/guile/webdav.texi | 301 | ||||
| -rw-r--r-- | doc/ref/javascript/formatters.texi | 6 |
10 files changed, 600 insertions, 7 deletions
diff --git a/doc/ref/Makefile b/doc/ref/Makefile index 79486a46..64b3dda3 100644 --- a/doc/ref/Makefile +++ b/doc/ref/Makefile @@ -6,7 +6,7 @@ INFOFLAGS := --no-split all: calp.info calp.info: $(TEXI_FILES) - makeinfo -o $@ $(INFOFLAGS) calp.texi + $(MAKEINFO) -o $@ $(INFOFLAGS) calp.texi install: all install -m644 -D -t $(DESTDIR)/usr/share/info/ calp.info diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi index 58c162e1..78fe2293 100644 --- a/doc/ref/guile.texi +++ b/doc/ref/guile.texi @@ -1,6 +1,8 @@ @node Guile @chapter Guile +@include guile/data-formats.texi +@include guile/data-stores.texi @include guile/datetime.texi @include guile/zic.texi @include guile/srfi-41.texi @@ -12,6 +14,8 @@ @include guile/base64.texi @include guile/web.texi @include guile/vcomponent.texi +@include guile/sxml.texi +@include guile/webdav.texi @node Errors and Conditions @section Errors and Conditions diff --git a/doc/ref/guile/data-formats.texi b/doc/ref/guile/data-formats.texi new file mode 100644 index 00000000..037d3ae7 --- /dev/null +++ b/doc/ref/guile/data-formats.texi @@ -0,0 +1,25 @@ +@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/guile/data-stores.texi b/doc/ref/guile/data-stores.texi new file mode 100644 index 00000000..ec3962da --- /dev/null +++ b/doc/ref/guile/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 <calendar-store> #: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/guile/sxml.texi b/doc/ref/guile/sxml.texi new file mode 100644 index 00000000..dd635b4c --- /dev/null +++ b/doc/ref/guile/sxml.texi @@ -0,0 +1,100 @@ +@node sxml namespaced +@section Namespaced SXML + +Namespaces is a variant to ``regular'' SXML. Difference being that +instead of representing XML-tags as symbols, they are instead actual +objects. + +For example +@example +`(a (b "Content")) +@end example + +Would be represented as +@example +`(,(xml 'a) + (,(xml 'b) + "Content")) +@end example + +@defun namespaced-sxml->sxml tree [namespace-prefixes='()] +Takes a tree of namespaced-sxml, and optionally an assoc list from +namespace symbols, to prefered prefix. + +Returns a sxml tree, with xmlns:<prefix>=namespace attributes +@end defun + +@defun namespaced-sxml->xml tree [namespaces='()] [port='(current-output-port)] +Serializes the namespaced sxml tree to port. @var{namespaces} should +be an association list from namespace symbols, to prefered prefixes. +@end defun + +@defun namespaced-sxml->sxml/namespaces tree [namespace-prefixes='()] +Returns two values: +@itemize +@item An SXML tree (which doesn't have namespace attributes) +@item an association list from namespace symbols, to used prefixes. +@end itemize +@end defun + +@c xml->namespcaed-sxml and sxml->namespaced-sxml don't share +@c implementation, despite doing almost the same thing. This is since +@c xml->namespaced-sxml directly uses the ssax parser, giving us great +@c controll, while sxml->namespaced-sxml attempt to look at symbols. + +@defun xml->namespaced-sxml port-or-string +Reads xml from port, and return a namespaced SXML tree. +@end defun + +@defun sxml->namespaced-sxml tree namespaces +Converts a ``regular'' SXML tree into a namespaced sxml tree. +@var{namespaces} must be an association list which maps each prefix +used in @var{tree} onto a full XML namespace. + +The key @code{#f} can be used to map non-namespaced elements into a +namespace. +@end defun + +@defun xml tag +@defunx xml ns tag [attrs] +@anchor{xml-tag} + A single XML element, suitable to go as the car of a list to + create a full object. + + @var{xml} is a shorthand to @code{make-xml-element}, which + either takes just a tag (for non-namespaced elements), or a + namespace, a tag, and a list of attributes. + + @itemize + @item @var{tag} should be a symbol. + @item @var{ns} should be a symbol. + @item @var{attrs} should be a hash table. + @end itemize + + @defun make-xml-element tagname namespace attributes + @end defun + + @defun xml-element? x + @end defun + + @defun xml-element-tagname el + @end defun + + @defun xml-element-namespace el + @end defun + + @defun xml-element-attributes el + @end defun +@end defun + + +@defun make-pi-element tag body + @defun pi-element? x + @end defun + + @defun pi-tag pi + @end defun + + @defun pi-body pi + @end defun +@end defun diff --git a/doc/ref/guile/util-path.texi b/doc/ref/guile/util-path.texi index 322c50ec..9cf41b40 100644 --- a/doc/ref/guile/util-path.texi +++ b/doc/ref/guile/util-path.texi @@ -3,7 +3,10 @@ Provided by the module @code{(hnh util path)}. -See also @code{absolute-file-name?} from Guile. + +@defun path-absolute? string +Alias of @code{absolute-file-name?} from Guile. +@end defun @defun path-append strings ... Joins all strings into a path, squeezing duplicated delimiters, but @@ -33,10 +36,33 @@ The first component will be @code{""} if path is absolute. @defun filename-extension filename -Returns the extension of the filename, or the empty string if none exists. +Returns the extension of the filename without a leading period, or the +empty string if none exists. + +@example +(filename-extension "file.tar.gz") +⇒ "gz" +@end example @end defun @defun realpath path Equivalent of realpath(3). Absolute file names are returned as is, while relative filenames gets expanded to absolute filenames. @end defun + +@defun relative-to base path +Returns @var{path} as a relative path relative to @var{base}. + +base must be non-empty +@example +(relative-to "/some" "/some/path") +;; ⇒ "path" + +(relative-to "/some" "/other/path/") +;; ⇒ "../path" + +(relative-to "/a/b/c" "/a/b") +;; ⇒ "/a/b" +@end example + +@end defun diff --git a/doc/ref/guile/util.texi b/doc/ref/guile/util.texi index 32df5fce..1d35e0bf 100644 --- a/doc/ref/guile/util.texi +++ b/doc/ref/guile/util.texi @@ -113,6 +113,11 @@ See @var{find-extreme} @end lisp @end defun +@defun init+last list +Returns two values: everything except the last element of @var{list}, +and the last element of @var{list}. +@end defun + @defun take-to lst n Equivalent to @var{take}, but return everything (instead of crash) if n > (length lst). @@ -175,8 +180,8 @@ pairs of symbols and values. @lisp (kvlist->assq '(#:a 1 #:b "Hello")) -⇒ ((a 1) - (b "Hello")) +⇒ ((a . 1) + (b . "Hello")) @end lisp @end defun @@ -188,6 +193,8 @@ pairs of symbols and values. Calls @var{proc} on each element in @var{lst}, and return a association list which @code{(proc e)} as its keys, and all elements which mapped to that value. + +The values returned by @var{proc} are compared as per @code{equal?}. @end defun @defun split-by lst element @@ -219,7 +226,9 @@ list, whose indices matches the order of the inputs @end defun @defun string-flatten tree -@c TODO document me +Given an arbitary tree, do a pre-order traversal, appending all strings. + +Non-strings are converted to strings, and also appended. @end defun @defun intersperse item list @@ -227,7 +236,7 @@ Inserts @var{item} between each element in @var{list}. @end defun -@defun insert-ordered item collection [<=<] +@defun insert-ordered item collection [<] Inserts @var{item} into @var{collection}, such that collection remainins sorted if it was sorted beforehand. @end defun @@ -315,10 +324,18 @@ Similar to @var{let}, but sets environment variables for the code in body. Restores the old values once we leave. @end defmac +@defmac with-locale1 category locale thunk +Run @var{thunk} with the locale @var{category} temporarily set to +@var{locale}. +@end defmac + @defmac catch* thunk (symbol proc) ... Macro allowing multiple exception types to be caught. Each (symbol proc) pair expands to a regular @code{catch}, with the leftmost being innermost. + +@var{Symbol} can also be on the form @code{(pre-unwind @var{symbol})}, +then @code{with-throw-handler} is used instead of @code{catch}. @end defmac @subsection UUID generation @@ -332,3 +349,40 @@ Generates a UUID-v4 string. @defun uuid Generates an implementation defined (but guaranteed valid) UUID. @end defun + +@subsection IO + +Provided by module @code{(hnh util io)}. + +@defun open-input-port path +@defunx open-output-port path +Like @code{open-*-file}, but ``-'' gives @code{standard-@{input,output@}}. +@end defun + +@defun read-lines port +Return a list of all lines read from port. +@end defun + +@defun with-atomic-output-to-file filename thunk +Same functionality as the regular @var{with-output-to-file}, but +with the difference that either everything is written, or nothing +is written, and if anything is written it's all written atomicaly at +once (the original file will never contain an intermidiate state). +Does NOT handle race conditions between threads. + +propagates the return value of @var{thunk} upon successfully writing +the file, and @code{#f} otherwise. +@end defun + +@defun call-with-tmpfile proc [#:tmpl ``/tmp/file-XXXXXXX''] +@end defun + +@defun ->port port-or-strings +If @var{port-or-string} is a port, return it directly. If it's a +string, instead return an input string containing the strings content. +@end defun + +@c Is this even a procedure? +@defun read-file path +Open file at path, and return its content as a string. +@end defun diff --git a/doc/ref/guile/vcomponent.texi b/doc/ref/guile/vcomponent.texi index 299ae1da..2560bdde 100644 --- a/doc/ref/guile/vcomponent.texi +++ b/doc/ref/guile/vcomponent.texi @@ -106,6 +106,8 @@ Curried version of @var{prop}. @end deftp @defun copy-vcomponent vcomponent +Creates a shallow copy of @var{vcomponent}. If the source object has a +parent, then than parent adopts the new event also. @end defun @@ -115,3 +117,42 @@ Does symbol start with ``X-''? @defun internal-field? symb [prefix="-"] @end defun + +@node VComponent Create +@section (vcomponent create) + +Procedures for declarativly creating components (instead of the +primitive procedural API). + +@defun vcomponent type [key: prop] ... children +Creates a new vcomponent of @var{type}. Each kv-pair should contain a +keyword @var{key}, and a value which is either a direct value, or the +return value of @code{with-parameters} or +@code{as-list}. @var{children} should be a list of other vcomponent's. +@end defun + +@defun vcalendar +@defunx vevent +@defunx vtimezone +@defunx standard +@defunx daylight +Calls @code{vcomponent}, with type set to the procedure name (but +up-cased). +@end defun + +@defun with-parameters [key: param] ... value +Allows setting parameters for a property as created by @code{vcomponent}. + +@var{value} follows the same rules as in @code{vcomponent}. Multiple +@var{key}, @var{value} pairs can be given, where each key must be a keyword. +@end defun + +@defun as-list lst +Allows setting list values when using @code{vcomponent}. + +Without this a list value would be stored as a single value, while +with this a list of values is instead stored (as, for example, in EXDATE). + +A list of list types could be hard-coded, but even then this procedure +is needed since custom types might need it. +@end defun diff --git a/doc/ref/guile/webdav.texi b/doc/ref/guile/webdav.texi new file mode 100644 index 00000000..a495c945 --- /dev/null +++ b/doc/ref/guile/webdav.texi @@ -0,0 +1,301 @@ +@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{<resource>}. + +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} <resource> +Base type for all WebDAV resources. + +The base class shouldn't be directly instanciated. + + @defun resource? x + Is the given object a <resource>, 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 <resource>) (parent <resource>) +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 <resource>) (parent <resource>) +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 <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 <file-resource> +@end deftp + +@deftp {GOOPS method} is-collection? <file-resource> +@end deftp + +@deftp {GOOPS method} creationdate <file-resource> +Retrived directly from the file through @command{stat -c %W $@{filename@}}. +@end deftp + +@deftp {GOOPS method} content <file-resource> +@deftpx {GOOPS method} set-content! <file-resource> 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/javascript/formatters.texi b/doc/ref/javascript/formatters.texi index 71394b39..a3086aa9 100644 --- a/doc/ref/javascript/formatters.texi +++ b/doc/ref/javascript/formatters.texi @@ -4,6 +4,12 @@ Formatting procedures used by some components. @c TODO can we have a backref of every node containing @ref{formatters-proc}? +@deftypefun void format(targetElement:HTMLElement, data:VEvent, key:string) +Checks if a specific formatter exists for the given key, and executes +it. +Defaults to 'default', and also runs that if the regular formatter throws. +@end deftypefun + @deftypevar {Map<string, (e:HTMLElement, d:VEvent, s:any) => void>} formatters @anchor{formatters-proc} |