From a14c9600d3838595fafe7f3fb3b99fef8492a012 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Mon, 2 Oct 2023 19:28:13 +0200 Subject: Documentation work. --- doc/ref/calp.texi | 1 + doc/ref/general.texi | 2 +- doc/ref/general/io.texi | 2 + doc/ref/general/lens.texi | 2 + doc/ref/general/util-object.texi | 86 -------------------------------- doc/ref/general/util.texi | 7 +++ doc/ref/object.texi | 4 ++ doc/ref/object/object.texi | 104 +++++++++++++++++++++++++++++++++++++++ 8 files changed, 121 insertions(+), 87 deletions(-) delete mode 100644 doc/ref/general/util-object.texi create mode 100644 doc/ref/object.texi create mode 100644 doc/ref/object/object.texi (limited to 'doc') diff --git a/doc/ref/calp.texi b/doc/ref/calp.texi index d54bce22..b122fdfd 100644 --- a/doc/ref/calp.texi +++ b/doc/ref/calp.texi @@ -73,6 +73,7 @@ text @footnote{Improvements welcome} @include text.texi @include vulgar.texi @include introspection.texi +@include object.texi @node Index @unnumbered Index diff --git a/doc/ref/general.texi b/doc/ref/general.texi index a2fc2ca3..1810a29b 100644 --- a/doc/ref/general.texi +++ b/doc/ref/general.texi @@ -22,8 +22,8 @@ of these should be generally useful in any project. @include general/graph.texi @include general/options.texi +@c TODO document (hnh util coverage) @include general/util-type.texi -@include general/util-object.texi @include general/lens.texi @include general/sxml.texi diff --git a/doc/ref/general/io.texi b/doc/ref/general/io.texi index 178df749..e7ff51fa 100644 --- a/doc/ref/general/io.texi +++ b/doc/ref/general/io.texi @@ -10,6 +10,8 @@ Like @code{open-*-file}, but ``-'' gives @code{standard-@{input,output@}}. @defun read-lines port Return a list of all lines read from port. + +The trailing newlines are @emph{not} part of the string. @end defun @defun with-atomic-output-to-file filename thunk diff --git a/doc/ref/general/lens.texi b/doc/ref/general/lens.texi index e59b5d72..a07dd7c9 100644 --- a/doc/ref/general/lens.texi +++ b/doc/ref/general/lens.texi @@ -3,6 +3,8 @@ Provided by the module @code{(hnh util lens)} +@c TODO write an actuall introduction here + @defun modify object lens f args ... @end defun diff --git a/doc/ref/general/util-object.texi b/doc/ref/general/util-object.texi deleted file mode 100644 index ceac2f2a..00000000 --- a/doc/ref/general/util-object.texi +++ /dev/null @@ -1,86 +0,0 @@ -@node define-type -@section Yet Another Object System - -@defmac define-type (name type-parameters ...) fields ... -Introduce a new type. - -Each field is either a symbol, or a list where the first element is a -symbol, and the remaining elements are alternating keywords and -values, as per @ref{Field Parameters}. All fields are optional by -default, but can be made non-optional through its type parameter. - -The example below creates a new type called @var{type}, with a custom -printer which always displays the string ``TYPE''. It has two fields, -@var{x}, which must be an integer, and @var{y}, which can have any -type, but gets the value ``Hello'' in none is given. -@example -(define-type (type #:printer (lambda (r p) (display "TYPE" p))) - (x #:type integer?) - (y #:default "Hello")) -@end example -@end defmac - -@subsection Type Parameters - -@deffn {Type Parameter} constructor (λ (primitive-constructor type-validator)) -Use a custom constructor for the type. The given procedure is called -with two values: -@itemize -@item the types primitive (and usually hidden) constructor, -which takes as many arguments as there are fields, in the order given -in define-type, and -@item the type validator procedure, which also takes all arguments, -but instead either returns an undefined value if everything is fine, -or throws @code{'wrong-type-arg} otherwise. -@end itemize -The procedure should then return a new procedure, which will be bound -as the constructor for the type. Note that default values are current -disregarded with custom constructors. - -A custom constructor for the type above might look like -@example -(lambda (primitive-constructor type-check) - (lambda* (#:key x y) - (type-check x y) - (primitive-constructor x y))) -@end example -@end deffn - -@deffn {Type Parameter} printer (λ (record port)) -Use a custom printer for the type. -@end deffn - -@subsection Field Parameters -@anchor{Field Parameters} - -@deffn {Field Parameter} default value -Value the field should get if not given. -@end deffn - -@deffn {Field Parameter} type type-clause -A type predicate that the field must obey. See @ref{type-clause} for details. -@end deffn - -@subsection Introduced Bindings - -Define type introduces a number procedures. (@var{} should be -replaced with whatever was given as @var{name} to define-type. - -@defun @var{} [kv-args ...] -Type constructor. Takes key-value arguments. Where the keys are the -names of the fields. -@end defun - -@defun @var{}? x -Type predicate. -@end defun - -And for each field @var{}: - -@defun @var{} object [value] -Accessor for the given filed. -Returns the current value if called with only an object, and returns a -new object with @var{field} set to @var{value} if called with two values. - -The updating version checks the type if #:type was given on creation. -@end defun diff --git a/doc/ref/general/util.texi b/doc/ref/general/util.texi index 1d6a4e7a..ced5c27a 100644 --- a/doc/ref/general/util.texi +++ b/doc/ref/general/util.texi @@ -341,6 +341,13 @@ A variable can also be removed from the environment, by setting its value to @code{#f}. @end defmac +@defmac with-working-directory directory thunk +Run @var{thunk} with the working directory set to @var{directory}. + +Note that this probably isn't thread safe. See source for more +inforamtion. +@end defmac + @defmac with-locale1 category locale thunk Run @var{thunk} with the locale @var{category} temporarily set to @var{locale}. diff --git a/doc/ref/object.texi b/doc/ref/object.texi new file mode 100644 index 00000000..8fa2e1e9 --- /dev/null +++ b/doc/ref/object.texi @@ -0,0 +1,4 @@ +@node Yet Another Object System +@chapter Yet Another Object System + +@include object/object.texi diff --git a/doc/ref/object/object.texi b/doc/ref/object/object.texi new file mode 100644 index 00000000..7eff8ec2 --- /dev/null +++ b/doc/ref/object/object.texi @@ -0,0 +1,104 @@ +@node YAOS Primitives +@section Primitives + +What Scheme lacks is a proper object system. This library solves that +problem @emph{once and for all}! + +The records created through this library are all immutale, where each +field becomes a multiple dispatch procedure, whence called with a +single argument returns the value of that field, and when called with +two values (first one being the object, second being the new value) +returns a new instance of the object, with the field in question +replaced. + +@defmac define-type (name type-parameters ...) fields ... +Introduce a new type, disjoint from all previously defined types. + +@c Each field is either a symbol, or a list where the first element is a +@c symbol, and the remaining elements are alternating keywords and +@c values, as per @ref{Field Parameters}. All fields are optional by +@c default, but can be made non-optional through its type parameter. + +@c The example below creates a new type called @var{type}, with a custom +@c printer which always displays the string ``TYPE''. It has two fields, +@c @var{x}, which must be an integer, and @var{y}, which can have any +@c type, but gets the value ``Hello'' in none is given. +@c @example +@c (define-type (type #:printer (lambda (r p) (display "TYPE" p))) +@c (x #:type integer?) +@c (y #:default "Hello")) +@c @end example + +@var{type-parameters} is a key-value list, where the valid keys are + +@deffn {Type Parameter} #:constructor (λ (primitive-constructor type-validator)) +The defaulct constructor for these types simply takes a keyword-value +list, validates each argument in regard to the defined types, and +constructs a final object. However; sometimes a more advanced +constructor is needed, which can be added through this parameter. + +The custom constructor is called with two values: + +@itemize +@item the types primitive (and usually hidden) constructor, +which takes as many arguments as there are fields, in the order given +in define-type, and +@item the type validator procedure, which also takes all arguments, +but instead either returns an undefined value if everything is fine, +or throws @code{'wrong-type-arg} otherwise. +@end itemize +The procedure should then return a new procedure, which will be bound +as the constructor for the type. Note that default values are current +disregarded with custom constructors. + +A custom constructor for the type above might look like +@example +(lambda (primitive-constructor type-check) + (lambda* (#:key x y) + (type-check x y) + (primitive-constructor x y))) +@end example +@end deffn + +@deffn {Type Parameter} #:printer (λ (record port)) +Use a custom printer for the type. +@end deffn + +Each field declares a part of the record, along with relevant metadata +about that field. The most basic declaration is a bare symbol, which +adds a field which can hold anything. However, a list with the target +name as its first element can instead be given, with the tail +containing keyword arguments as follows + +@deffn {Field Parameter} default value +Value the field should get if not given. +@end deffn + +@deffn {Field Parameter} type type-clause +A type predicate that the field must obey. See @ref{type-clause} for details. + +Each type introduces a number of bindings, which are@footnote{ +@var{} here refers to the name of the type +}: +@end deffn + +@defun @var{} [kv-args ...] +Type constructor. Takes key-value arguments. Where the keys are the +names of the fields. +@end defun + +@defun @var{}? x +Type predicate. +@end defun + +And for each field @var{}: + +@defun @var{} object [value] +Accessor for the given filed. +Returns the current value if called with only an object, and returns a +new object with @var{field} set to @var{value} if called with two values. + +The updating version checks the type if #:type was given on creation. +@end defun + +@end defmac -- cgit v1.2.3