From a3675c13336afb0b37e0f211c649813f4f291224 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Tue, 12 Sep 2023 10:35:37 +0200 Subject: Further doc work. --- doc/ref/general.texi | 3 ++ doc/ref/general/io.texi | 2 +- doc/ref/general/util-path.texi | 7 +++- doc/ref/general/util.texi | 3 ++ doc/ref/vcomponent.texi | 7 ++++ doc/ref/web.texi | 4 +- doc/ref/web/query.texi | 9 +++++ doc/ref/web/routes.texi | 73 +++++++++++++++++++++++++++++++++ doc/ref/web/uri-query.texi | 7 ++++ doc/ref/web/web.texi | 92 ------------------------------------------ 10 files changed, 112 insertions(+), 95 deletions(-) create mode 100644 doc/ref/web/query.texi create mode 100644 doc/ref/web/routes.texi create mode 100644 doc/ref/web/uri-query.texi delete mode 100644 doc/ref/web/web.texi diff --git a/doc/ref/general.texi b/doc/ref/general.texi index be68fca6..f42b90f3 100644 --- a/doc/ref/general.texi +++ b/doc/ref/general.texi @@ -1,6 +1,9 @@ @node Generally Useful Utilities @chapter Generally Useful Utilities +These are all general utilitios with no direct relation to Calp. Many +of these should be generally useful in any project. + @include general/datetime.texi @include general/zic.texi @include general/srfi-41.texi diff --git a/doc/ref/general/io.texi b/doc/ref/general/io.texi index 8c83ddcf..3f67700b 100644 --- a/doc/ref/general/io.texi +++ b/doc/ref/general/io.texi @@ -1,5 +1,5 @@ @node IO operations -@section IO +@section IO operations Provided by module @code{(hnh util io)}. diff --git a/doc/ref/general/util-path.texi b/doc/ref/general/util-path.texi index 384915ef..9c1da19b 100644 --- a/doc/ref/general/util-path.texi +++ b/doc/ref/general/util-path.texi @@ -1,8 +1,13 @@ @node Path Utilities @section Path Utilities -Provided by the module @code{(hnh util path)}. +An extended path library for Guile. This library builds upon the path +utilities provided by @xref{File System,,,guile}, but adds +manipulation procedures. These procedures should work no matter what +the systems directory delimiter is, even though this documentation +uses ``/'' for its examples. +Provided by the module @code{(hnh util path)}. @defun path-absolute? string Alias of @code{absolute-file-name?} from Guile. diff --git a/doc/ref/general/util.texi b/doc/ref/general/util.texi index bae19987..a85ff661 100644 --- a/doc/ref/general/util.texi +++ b/doc/ref/general/util.texi @@ -1,6 +1,9 @@ @node Miscellaneous utilities @section Miscellaneous utilities +A kitchen sink utility library. Note should be taken that some core +procedures and forms are replaced, but all in compatible ways. + Provided by the module @code{(hnh util)}. @defmac define-syntax [stx] diff --git a/doc/ref/vcomponent.texi b/doc/ref/vcomponent.texi index 983a75e2..dac47348 100644 --- a/doc/ref/vcomponent.texi +++ b/doc/ref/vcomponent.texi @@ -1,6 +1,13 @@ @node VComponents @chapter VComponents +Procedures for manipulating VComponents. +VComponents are the general container type as specified by RFC5545 +(iCalendar). The term VComponent isn't from the standard, but rather +the generialization of VCALENDAR, VEVENT, ... + +Some of these values are still Calp specific. + @defvr {Configuration Variable} calendar-files List of filepaths @end defvr diff --git a/doc/ref/web.texi b/doc/ref/web.texi index e3c73f44..8574e166 100644 --- a/doc/ref/web.texi +++ b/doc/ref/web.texi @@ -1,4 +1,6 @@ @node Webservers and -Clients @chapter Webservers and -Clients -@include web/web.texi +@include web/query.texi +@include web/uri-query.texi +@include web/routes.texi diff --git a/doc/ref/web/query.texi b/doc/ref/web/query.texi new file mode 100644 index 00000000..df3ba953 --- /dev/null +++ b/doc/ref/web/query.texi @@ -0,0 +1,9 @@ +@node Web Query +@section (web query) + +@defun parse-query query-string [encoding=''UTF-8''] +Given a string like ``?key=value&other=something'', returns +@code{(key: "value" other: "something")}. Performs uri-decoding of +both key and value. A key without a value decodes to that key, with +itself as its value +@end defun diff --git a/doc/ref/web/routes.texi b/doc/ref/web/routes.texi new file mode 100644 index 00000000..a2249c7a --- /dev/null +++ b/doc/ref/web/routes.texi @@ -0,0 +1,73 @@ +@node HTTP Routes +@section (web http make-routes) + +@defun parse-endpoint-string str +Only really public for tests. +@end defun + +@defmac make-routes routes ... +Expands a number of endpoint specifiers into a procedure suitable for +use as a handler in @xref{Web Server,run-server,run-server,guile}. + +Each form conists of +@itemize +@item the method (``GET'', ``POST'', ...), +@item the path, possibly with embedded parameters, +@item a list of parameters to capture, and +@item the body. +@end itemize + +@example +(make-routes + (GET "/path/:a" (a b) + (return '((content-type text/plain)) + (format #f "a=~a, b=~a" a b))) + ...) +@end example + +The paths can contain embedded variables, which start with +colon, and their name continues until the next slash or period (or end +of string). Each path-embedded parameter must be present in the +parameter list. + +The parameter list must contain all path-embedded parameters, and can +contain any other parameters, which will be bound from the query +parameters, or stay @code{#f} if not supplied by the browser. + +The body should return one to three values, either directly, or +through an early return by calling the procedure @code{return}. + +@defun return headers [body] [new-state] +@end defun + +Inside the body, the following variables are bound to enable producing +the body: + +@defvar request +@defvarx body +The raw request headers and request body. +@end defvar + +@defvar state +The optional state. +@end defvar + +@defvar r:method +@defvarx r:uri +@defvarx r:version +@defvarx r:headers +@defvarx r:meta +The requests components +@end defvar + +@defvar r:scheme +@defvarx r:userinfo +@defvarx r:host +@defvarx r:port +@defvarx r:path +@defvarx r:query +@defvarx r:fragment +The request uri's components. +@end defvar + +@end defmac diff --git a/doc/ref/web/uri-query.texi b/doc/ref/web/uri-query.texi new file mode 100644 index 00000000..d3df3a70 --- /dev/null +++ b/doc/ref/web/uri-query.texi @@ -0,0 +1,7 @@ +@node URI Query +@section (web uri-query) + +@defun encode-query-parameters parameters +Given the association list @var{parameter}, encode it into a query +string on the form ``key=value&...''. +@end defun diff --git a/doc/ref/web/web.texi b/doc/ref/web/web.texi deleted file mode 100644 index 69ab726f..00000000 --- a/doc/ref/web/web.texi +++ /dev/null @@ -1,92 +0,0 @@ -@node Web Stuff -@section Web Stuff - -@subsection (web query) - -@defun parse-query query-string [encoding=''UTF-8''] -Given a string like ``?key=value&other=something'', returns -@code{(key: "value" other: "something")}. Performs uri-decoding of -both key and value. A key without a value decodes to that key, with -itself as its value -@end defun - - -@subsection (web uri-query) - -@defun encode-query-parameters parameters -Given the association list @var{parameter}, encode it into a query -string on the form ``key=value&...''. -@end defun - -@subsection (web http make-routes) - -@defun parse-endpoint-string str -Only really public for tests. -@end defun - -@defmac make-routes routes ... -Expands a number of endpoint specifiers into a procedure suitable for -use as a handler in @xref{Web Server,run-server,run-server,guile}. - -Each form conists of -@itemize -@item the method (``GET'', ``POST'', ...), -@item the path, possibly with embedded parameters, -@item a list of parameters to capture, and -@item the body. -@end itemize - -@example -(make-routes - (GET "/path/:a" (a b) - (return '((content-type text/plain)) - (format #f "a=~a, b=~a" a b))) - ...) -@end example - -The paths can contain embedded variables, which start with -colon, and their name continues until the next slash or period (or end -of string). Each path-embedded parameter must be present in the -parameter list. - -The parameter list must contain all path-embedded parameters, and can -contain any other parameters, which will be bound from the query -parameters, or stay @code{#f} if not supplied by the browser. - -The body should return one to three values, either directly, or -through an early return by calling the procedure @code{return}. - -@defun return headers [body] [new-state] -@end defun - -Inside the body, the following variables are bound to enable producing -the body: - -@defvar request -@defvarx body -The raw request headers and request body. -@end defvar - -@defvar state -The optional state. -@end defvar - -@defvar r:method -@defvarx r:uri -@defvarx r:version -@defvarx r:headers -@defvarx r:meta -The requests components -@end defvar - -@defvar r:scheme -@defvarx r:userinfo -@defvarx r:host -@defvarx r:port -@defvarx r:path -@defvarx r:query -@defvarx r:fragment -The request uri's components. -@end defvar - -@end defmac -- cgit v1.2.3