From f653a01328be3b8be6af35c0c96867623765ca5b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Tue, 5 Sep 2023 11:41:46 +0200 Subject: Move JS documentation into the JS-code. Texinfo was a bad match for how TypeScript is structured. This also allows generation of jsdoc pages, which can be nice. Another large win is that this opens up for the texinfo pages to replace the Guile heading with different subheadings, including - external library - internal library - C library - ... --- doc/ref/calp.texi | 4 - doc/ref/guile/util-exceptions.texi | 22 +++ doc/ref/javascript.texi | 48 ------- doc/ref/javascript/clock.texi | 78 ----------- doc/ref/javascript/components/changelog.texi | 10 -- doc/ref/javascript/components/date_time_input.texi | 34 ----- doc/ref/javascript/components/edit_rrule.texi | 10 -- doc/ref/javascript/components/input_list.texi | 16 --- doc/ref/javascript/components/popup_element.texi | 40 ------ .../javascript/components/tab_group_element.texi | 46 ------- doc/ref/javascript/components/vevent.texi | 23 ---- doc/ref/javascript/components/vevent_block.texi | 10 -- .../javascript/components/vevent_description.texi | 16 --- doc/ref/javascript/components/vevent_dl.texi | 11 -- doc/ref/javascript/components/vevent_edit.texi | 9 -- doc/ref/javascript/eventCreator.texi | 15 --- doc/ref/javascript/formatters.texi | 23 ---- doc/ref/javascript/globals.texi | 41 ------ doc/ref/javascript/jcal.texi | 7 - doc/ref/javascript/lib.texi | 148 --------------------- doc/ref/javascript/server_connect.texi | 22 --- doc/ref/javascript/types.texi | 95 ------------- doc/ref/javascript/user-additions.texi | 18 --- doc/ref/javascript/vevent.texi | 113 ---------------- 24 files changed, 22 insertions(+), 837 deletions(-) create mode 100644 doc/ref/guile/util-exceptions.texi delete mode 100644 doc/ref/javascript.texi delete mode 100644 doc/ref/javascript/clock.texi delete mode 100644 doc/ref/javascript/components/changelog.texi delete mode 100644 doc/ref/javascript/components/date_time_input.texi delete mode 100644 doc/ref/javascript/components/edit_rrule.texi delete mode 100644 doc/ref/javascript/components/input_list.texi delete mode 100644 doc/ref/javascript/components/popup_element.texi delete mode 100644 doc/ref/javascript/components/tab_group_element.texi delete mode 100644 doc/ref/javascript/components/vevent.texi delete mode 100644 doc/ref/javascript/components/vevent_block.texi delete mode 100644 doc/ref/javascript/components/vevent_description.texi delete mode 100644 doc/ref/javascript/components/vevent_dl.texi delete mode 100644 doc/ref/javascript/components/vevent_edit.texi delete mode 100644 doc/ref/javascript/eventCreator.texi delete mode 100644 doc/ref/javascript/formatters.texi delete mode 100644 doc/ref/javascript/globals.texi delete mode 100644 doc/ref/javascript/jcal.texi delete mode 100644 doc/ref/javascript/lib.texi delete mode 100644 doc/ref/javascript/server_connect.texi delete mode 100644 doc/ref/javascript/types.texi delete mode 100644 doc/ref/javascript/user-additions.texi delete mode 100644 doc/ref/javascript/vevent.texi (limited to 'doc/ref') diff --git a/doc/ref/calp.texi b/doc/ref/calp.texi index 92c30242..4dac681b 100644 --- a/doc/ref/calp.texi +++ b/doc/ref/calp.texi @@ -64,7 +64,6 @@ text @footnote{Improvements welcome} @c @end menu @include guile.texi -@include javascript.texi @node Index @unnumbered Index @@ -75,7 +74,4 @@ text @footnote{Improvements welcome} @printindex tp @printindex vr -@unnumbered Web Components -@printindex wc - @bye diff --git a/doc/ref/guile/util-exceptions.texi b/doc/ref/guile/util-exceptions.texi new file mode 100644 index 00000000..4e84d8c4 --- /dev/null +++ b/doc/ref/guile/util-exceptions.texi @@ -0,0 +1,22 @@ +@node Exception Utilities +@section Exception Utilities + +@defun warning fmt args ... + +@end defun + +@deftp {parameter} warning-handler +Procedure, which htnaoe htn oeu htn oeu +@end deftp + +@deftp {parameter} warnings-are-errors +Boolean parameter +@end deftp + +@defun fatal fmt args ... +Display the message in fmt, populated with args, then raises the UNIX +signal 2, which kills the program. +@end defun + +@defun filter-stack pred? stack +@end defun diff --git a/doc/ref/javascript.texi b/doc/ref/javascript.texi deleted file mode 100644 index bbe1cb25..00000000 --- a/doc/ref/javascript.texi +++ /dev/null @@ -1,48 +0,0 @@ -@node Javascript -@chapter Javascript - -@c web components -@defindex wc - -@c done -@node General Stuff -@section General stuff -The frontend code has its entry-point in @code{script.ts} - -All elements are initialized in elements.ts - -@include javascript/clock.texi -@include javascript/lib.texi -@include javascript/eventCreator.texi -@include javascript/types.texi -@include javascript/vevent.texi -@include javascript/globals.texi -@include javascript/server_connect.texi -@include javascript/formatters.texi -@include javascript/user-additions.texi - -@node General Components -@section General Components -@include javascript/components/date_time_input.texi -@include javascript/components/input_list.texi - -@node VEvent Components -@section VEvent Components -@include javascript/components/vevent.texi -@include javascript/components/changelog.texi -@include javascript/components/edit_rrule.texi -@include javascript/components/popup_element.texi -@include javascript/components/tab_group_element.texi -@include javascript/components/vevent_block.texi -@include javascript/components/vevent_description.texi -@include javascript/components/vevent_dl.texi -@include javascript/components/vevent_edit.texi - -@section About our buildsystem -Currently (almost) everything is written in Typescript, and bundled -through browserify. Ideally we would, for debug builds, export the -single transplied Javascript files, but Chromium Chromium lacks -support for modules on XHTML documents -@url{https://bugs.chromium.org/p/chromium/issues/detail?id=717643}. -However, seeing as the issue still gets frequent updates as of 2021 I -believe that this might one day get resolved. diff --git a/doc/ref/javascript/clock.texi b/doc/ref/javascript/clock.texi deleted file mode 100644 index 10ab7d4e..00000000 --- a/doc/ref/javascript/clock.texi +++ /dev/null @@ -1,78 +0,0 @@ -@node clock -@subsection clock.js - -@deftp {abstract class} Clock -Interface for ``things'' which wants to get updated on a human timescale. - -@defmethod Clock update now -@c abstract method -Called every now and then, with @var{now} being the current time. -@end defmethod -@end deftp - -@deftp {class} Timebar @extends{Clock} -The (blue) vertical line which show the current time in the current day. - -@c @defmethod Timebar constructor ∅ -@c @end defmethod -@c -@c @defmethod Timebar update now -@c @end defmethod -@end deftp - -@deftp {class} SmallcalCellHighlight @extends{Clock} -Highlights the current date in the small calendar to the side. -Currently directly sets a border -@TODO{but should preferably set a class instead}. - -@defmethod SmallcalCellHighlight constructor small_cal -@var{small_cal} is the DOM-node of the calendar. -(it should support querySelector). -@end defmethod - -@c @defmethod SmallcalCellHighlight update now -@c @end defmethod -@end deftp - -@deftp {class} ButtonUpdater @extends{Clock} -Updates the ``Today'' link in the side panel to point directly to the -correct web-address. The link works without JavaScript, but then -requires a redirect from the server. - -All actual updating logic is already abstracted away. It would be -desirable if something more was done with this. - -@defmethod ButtonUpdater el proc -Takes the element @var{el} to be updated, and the procedure @var{proc} -which will be called with the element, and the current time. -@end defmethod -@end deftp - - -As of commit -@githash{c9719ce7937f0f0f2aa371ced1d585f67af22457,static/script.js,231} -all objects required manual setup. See static/script.js: - -@verbatim - 231 let start_time = document.querySelector("meta[name='start-time']").content; - 232 let end_time = document.querySelector("meta[name='end-time']").content; - 233 - 234 const button_updater = new ButtonUpdater( - 235 document.getElementById("today-button"), - 236 (e, d) => e.href = d.format('~Y-~m-~d') + ".html" - 237 ); - 238 - 239 const sch = new SmallcalCellHighlight( - 240 document.querySelector('.small-calendar')) - 241 - 242 const timebar = new Timebar(start_time, end_time); - 243 - 244 timebar.update(new Date); - 245 window.setInterval(() => { - 246 let d = new Date; - 247 timebar.update(d); - 248 button_updater.update(d); - 249 sch.update(d); - 250 }, 1000 * 60); - 251 -@end verbatim diff --git a/doc/ref/javascript/components/changelog.texi b/doc/ref/javascript/components/changelog.texi deleted file mode 100644 index d14fb84e..00000000 --- a/doc/ref/javascript/components/changelog.texi +++ /dev/null @@ -1,10 +0,0 @@ -@subsection Changelog - -@deftp {Web Component for VEvent} VEventChangelog -@wcindex -@wcindex vevent-changelog -@anchor{VEventChangelog} -@code{} - -Display of a VEvents changelog. @ref{ChangeLogEntry} -@end deftp diff --git a/doc/ref/javascript/components/date_time_input.texi b/doc/ref/javascript/components/date_time_input.texi deleted file mode 100644 index f26627d2..00000000 --- a/doc/ref/javascript/components/date_time_input.texi +++ /dev/null @@ -1,34 +0,0 @@ -@subsection date-time-input - -@deftp {Web Component} DateTimeInput -@wcindex -@wcindex date-time-input -@code {} - -An element for input for date-times. Similar to -@example - - -@end example -But as a single unit. - -@deftypeivar DateTimeInput boolean dateonly -Setting this to true disabled the time part of the input, and makes -any output only have date components (alternativly, the time component -set to zero). -@end deftypeivar - -@defcv {Attribute} DateTimeInput dateonly -Same data as the field dateonly, but as an attribute. Present means -true, absent means false. -@end defcv - -@deftypeivar DateTimeInput Date value -Returns current value as a Date object. -@end deftypeivar - -@deftypeivar DateTimeInput string stringValue -Returns current value as an ISO-8601 formatted string. -@end deftypeivar - -@end deftp diff --git a/doc/ref/javascript/components/edit_rrule.texi b/doc/ref/javascript/components/edit_rrule.texi deleted file mode 100644 index 21437863..00000000 --- a/doc/ref/javascript/components/edit_rrule.texi +++ /dev/null @@ -1,10 +0,0 @@ -@subsection Edit RRule - -@deftp {Web Component for VEvent} EditRRule -@wcindex -@wcindex vevent-edit-rrule -@code{} - -An edit form for a recurrence rule. Searches its template for elements -with @code{[name="<>"]}, and binds to those. -@end deftp diff --git a/doc/ref/javascript/components/input_list.texi b/doc/ref/javascript/components/input_list.texi deleted file mode 100644 index bdc00ecb..00000000 --- a/doc/ref/javascript/components/input_list.texi +++ /dev/null @@ -1,16 +0,0 @@ -@subsection input_list.js - -@deftp {Web Component} InputList -@wcindex -@wcindex input-list -@code{} - -A list of identical input fields, which forms a group. For example -useful to handle keywords. - -@deftypeivar DateTimeInput {any[]} value -The value from each element, except the last which should always be empty. -Has an unspecified type, since children:s value field might give non-strings. -@end deftypeivar - -@end deftp diff --git a/doc/ref/javascript/components/popup_element.texi b/doc/ref/javascript/components/popup_element.texi deleted file mode 100644 index 2b76b347..00000000 --- a/doc/ref/javascript/components/popup_element.texi +++ /dev/null @@ -1,40 +0,0 @@ -@subsection Popup - -@deftp {Web Component for VEvent} PopupElement -@wcindex -@wcindex popup-element -@code{} - -A (small) floating window containing information, which can be dragged -arround. Consists of a navigation bar with a few buttons for -controlling the window, which also works as a drag handle, along with -an area for contents, which can be resized by the user. - -Currently tightly coupled to VEvent's, since their color -profile is derived from their owning events calendar, and they have -action buttons for the event in their navigation bar. - -@deftypecv {Static Member} PopupElement {PopupElement?} activePopup -The popup which was most recently interacted with by the user. Used to -move it on top of all others, as well as sending relevant key events there. -@end deftypecv - -@defcv {Attribute} PopupElement visible -Present is the popup is currently visible, absent otherwise. -@end defcv - -@deftypeivar PopupElement boolean visible -See the attribute of the same name. -@end deftypeivar - -@defmethod PopupElement maximize -Resize the popup window to fill the current viewport (mostly). Is -probably bonud to the maximize button in the navigation bar. -@end defmethod -@end deftp - -@deftypefun PopupElement setup_popup_element VEvent -Create a new popup element for the given VEvent, and ready it for -editing the event. Used when creating event (through the frontend). -The return value can safely be ignored. -@end deftypefun diff --git a/doc/ref/javascript/components/tab_group_element.texi b/doc/ref/javascript/components/tab_group_element.texi deleted file mode 100644 index 7e0b190a..00000000 --- a/doc/ref/javascript/components/tab_group_element.texi +++ /dev/null @@ -1,46 +0,0 @@ -@subsection Tab Group Element - -@deftp {Web Component for VEvent} TabGroupElement -@wcindex -@wcindex tab-group -@code{} - -A group of tabs, where only one can be visible at a time. - -@c TODO which form does the HTML document have? For CSS purposes - -Each tab consists of two parts, a label which is used for selecting -it, and a tab-element, which contains the actual content. These two -should refer to each other as follows: - -@example -+---------------+ +-----------------+ -| TabLabel | | Tab | -+---------------+ +-----------------+ -| id |<----| aria-labelledby | -| aria-controls |---->| id | -+---------------+ +-----------------+ -@end example - -Further information about tabs in HTML can be found here: -@url{https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/Tab_Role} - -@defvr {CSS Variable} {--tabcount} -Each tab element has the style property @code{--tabcount} set to how -many tabs it has. This is mostly useful to make sure the tab context -is large enough to fit all tab labels without overflowing. -@end defvr - -@deftypemethod TabGroupElement void addTab {HTMLElement} {label: string?} {title: string?} -Adds a new tab to the group. The first parameter will make up the body -of the tab. The label is whath should be shown in the tab selector, -but defaults to the first letter of the text content of the body node. -Title is the hoover text of the label. -@end deftypemethod - -@deftypemethod TabGroupElement void removeTab {HTMLElement} -HTMLElement must be one of the tab bodies in this group. This method -removes it, along with its TabLabel. -@end deftypemethod - -@end deftp diff --git a/doc/ref/javascript/components/vevent.texi b/doc/ref/javascript/components/vevent.texi deleted file mode 100644 index be53a46e..00000000 --- a/doc/ref/javascript/components/vevent.texi +++ /dev/null @@ -1,23 +0,0 @@ -@subsection vevent - -@deftp {Abstract Web Component} ComponentVEvent {uid: string?} - -@c TODO what is done in the default constructor, -@c and the default connectedCallback - -This registeres itself, but doesn't redraw -We do however redraw in connectedCallback - -@deftypeivar ComponentVEvent uid uid -@end deftypeivar - -@deftypeivar ComponentVEvent {HTMLTemplateElement?} template -@end deftypeivar - -@deftypemethod ComponentVEvent void redraw (data: VEvent) -While abstract for this, @emph{must} be overridden for everyone else -@end deftypemethod -@end deftp - -Note that many of these assume that their initial children are -configured specifically, that is however not completely documented. diff --git a/doc/ref/javascript/components/vevent_block.texi b/doc/ref/javascript/components/vevent_block.texi deleted file mode 100644 index 1a0ef160..00000000 --- a/doc/ref/javascript/components/vevent_block.texi +++ /dev/null @@ -1,10 +0,0 @@ -@subsection VEvent Block - -@deftp {Web Component for VEvent} ComponentBlock -@wcindex -@wcindex vevent-block -@code{} -A block in our graphical view. - -Unique in that it works quite differently between the week and month view. -@end deftp diff --git a/doc/ref/javascript/components/vevent_description.texi b/doc/ref/javascript/components/vevent_description.texi deleted file mode 100644 index 54dda7e3..00000000 --- a/doc/ref/javascript/components/vevent_description.texi +++ /dev/null @@ -1,16 +0,0 @@ -@subsection VEvent Description - -@deftp {Web Component for VEvent} ComponentDescription -@wcindex -@wcindex vevent-description -@code{} - -A text representation of a VEvent. Used as the summary tab of our -popup windows, and in the sidebar. - -When redrawn, it looks for an HTML-tag inside its template having the -attribute @code{data-property} matching the properties name. If one is -found, it looks in the @code{formatters} table -(@ref{formatters-proc}), for a field matching the property value, and -defaults to the key @code{default}. -@end deftp diff --git a/doc/ref/javascript/components/vevent_dl.texi b/doc/ref/javascript/components/vevent_dl.texi deleted file mode 100644 index 26bc8fd4..00000000 --- a/doc/ref/javascript/components/vevent_dl.texi +++ /dev/null @@ -1,11 +0,0 @@ -@subsection VEvent Description List - -@deftp {Web Component for VEvent} VEventDL -@wcindex -@wcindex vevent-dl -@code{} -A description list of a vevent, used for debugging. - -No guarantees are given about the contents of the data fields, more -than that they are related to the value in question. -@end deftp diff --git a/doc/ref/javascript/components/vevent_edit.texi b/doc/ref/javascript/components/vevent_edit.texi deleted file mode 100644 index 67e9f6b3..00000000 --- a/doc/ref/javascript/components/vevent_edit.texi +++ /dev/null @@ -1,9 +0,0 @@ -@subsection VEvent Edit - -@deftp {Web Component for VEvent} ComponentEdit -@wcindex -@wcindex vevent-edit -@code{} -Edit form for a vevent, designed for useful human interaction (and -thereby not being all-encompassing). -@end deftp diff --git a/doc/ref/javascript/eventCreator.texi b/doc/ref/javascript/eventCreator.texi deleted file mode 100644 index 164d1335..00000000 --- a/doc/ref/javascript/eventCreator.texi +++ /dev/null @@ -1,15 +0,0 @@ -@deftp {class} EventCreator - -@defmethod EventCreator create_empty_event -@end defmethod - -@defmethod EventCreator create_event_down intended_target -@end defmethod - -@defmethod EventCreator create_event_move pos_in [round=1] [wide_element=false] -@end defmethod - -@defmethod EventCreator create_event_finisher callback -@end defmethod - -@end deftp diff --git a/doc/ref/javascript/formatters.texi b/doc/ref/javascript/formatters.texi deleted file mode 100644 index a3086aa9..00000000 --- a/doc/ref/javascript/formatters.texi +++ /dev/null @@ -1,23 +0,0 @@ -@node formatters -@subsection formatters - -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 void>} formatters -@anchor{formatters-proc} - -Each procedure takes three arguments. The HTML-element which contents -should be replaced, the VEvent containing all data, and the target -value, as returned by @ref{VEvent.getProperty}. -@end deftypevar - -@deftypevr {Window Value} {Map void>} formatters -Same object as @xref{formatters-proc}. Provided for @xref{user-additions.js}. -@end deftypevr diff --git a/doc/ref/javascript/globals.texi b/doc/ref/javascript/globals.texi deleted file mode 100644 index 5ef7a43b..00000000 --- a/doc/ref/javascript/globals.texi +++ /dev/null @@ -1,41 +0,0 @@ -@node globals -@subsection globals.ts - -Different variables and values which for different reasons needs to be -global. Window Value's are those that are bound to the @code{window} -context in JavaScript, so is really always available, no opt out. - -@deftypevar {Map} vcal_objects -All VEvent objects on current page, indexed by their unique identifiers. - -A global object store. -@end deftypevar - -@deftypevar {Map} event_calendar_mapping -Mapping from VEvent unique identifier, to name of its calendar. Should -probably not be global, so refrain from using it. -@end deftypevar - -@deftypevr {Window Value} {Map} vcal_objects -The exact same object store as the regular variable of the same -name. Mostly here for human debugability. -@end deftypevr - -@deftypevr {Window Value} {@code{'month'} | @code{'string'}} VIEW -How the calendar is currently formatted. Should be set by the backend -through a simple @code{script}-tag. -@end deftypevr - -@deftypevr {Window Value} {boolean} EDIT_MODE -However editing of events is enabled or not. -Should be set by the backend through a simple @code{script}-tag. -@end deftypevr - -@deftypevr {Window Value} {string} default_calendar -Name of the calendar to assume when creating new events. -Should be set by the backend through a simple @code{script}-tag. -@end deftypevr - -@c TODO addNewEvent -@c @deftypevr {Window Value} {string} default_calendar -@c @end deftypevr diff --git a/doc/ref/javascript/jcal.texi b/doc/ref/javascript/jcal.texi deleted file mode 100644 index 997b4d59..00000000 --- a/doc/ref/javascript/jcal.texi +++ /dev/null @@ -1,7 +0,0 @@ -@node jcal -@subsection jcal.js - -@deftypefun Document jcal_to_xcal {JCal ...} -A document with the xcal namespace, and @code{icalendar} as its root -element. Each child is a valid xcal representation of our JCal object. -@end deftypefun diff --git a/doc/ref/javascript/lib.texi b/doc/ref/javascript/lib.texi deleted file mode 100644 index a3fb0697..00000000 --- a/doc/ref/javascript/lib.texi +++ /dev/null @@ -1,148 +0,0 @@ - -@node lib -@subsection lib.js - -General procedures which in theory could be used anywhere. - - -@node Default prototype extensions -@subsubsection Default prototype extensions - -HTMLElement extensions - -@defmethod HTMLElement addEventListener name proc -Replace the default @code{addEventListener} with a version that stores -all listeners in the dictionary @var{listeners}. -@end defmethod - -@defivar HTMLElement listeners -Dictionary of all registered listeners to this element. -Keys are taken from @code{addEventListener}. -@end defivar - -@defmethod DOMTokenList find regexp -Finds the first element of the DOMTokenList whichs value matches -the supplied regexp. Returns a pair of the index and the value. -@end defmethod - -@defmethod Object format args ... -Returns a string representation of the given object. -Allows extending for custom types, -@ref{date-format} -@end defmethod - -@node General -@subsubsection General - -@defun zip args ... -Takes a list of lists, and returns a single list of tuples. -@example -» zip([1,2,3,4,5], "Hello") -← [[1,'H'],[2,'e'],[3,'l'],[4,'l'],[5,'o']] -@end example -@end defun - -@defun makeElement name [attr=@{@}] -Creates a new DOM element of type @var{name}, with all keys in -@var{attr} transfered to it. For example, the equivalent of -@example - -@end example -would be -@verbatim -values.push(makeElement('input', { - type: 'number', -})); -@end verbatim -. -@end defun - -@defun round_time time fraction -TODO -@end defun - -@defun date_to_percent date -Retuns how far along the date specified by @var{date} is, between 0 -and 100, where 00:00 maps to 0, and 23:59 to ~100. -@end defun - -@defun gensym [pxrefix='gensym'] -Generates a new string which is (hopefully) globally unique. -Compare with @code{gensym} from Lisp. -@end defun - -@defun asList thing -Ensures that @var{thing} is a list. Returning it outright if it -already is one, otherwise wrapping it in a list. -@end defun - -@node Date -@subsubsection Date - -Some extensions to the builtin class ``Date'' is made. - -@defivar Date utc -Boolean indicating if the given timestamp is in UTC or local time. -true means UTC. -@end defivar - -@defivar Date dateonly -Boolean indicating if the time component of the Date object should be disregarded. -@end defivar - -@defun parseDate str -Takes a string @var{str}, which should be in ISO-8601 date-format, and -returns a javascript Date object. -Handles date-times, with and without seconds, trailing `Z' for -time-zones, and dates without times. -If no time is given the @code{dateonly} attribute is set to yes. -@end defun - -@defun copyDate date -Creates a new instance of the given Date @var{date}, also transfers my -custom fields. -@end defun - -@defun to_local date -@anchor{to_local} -Returns a Date object (which may be new) which is guaranteed in local -time. -This means that the @var{utc} field is @code{false}, and that -@code{to_local(current_time())} should show what your wall-clock shows. -@end defun - -@defmethod Date format str args ... -@anchor{date-format} -Formats a Date object according to the format specification @var{str}. -Keeping with Guile each format specifier starts with a ~. - -@table @samp -@item ~~ -literal ~ -@c Almost all fields are left padded. How do I signify this -@c with a single footnote? -@item ~Y -year, left-padding with zeroes. -@item ~m -month number, left padded with zeroes. -@item ~d -day of month. -@item ~H -hour -@item ~M -minute -@item ~S -second -@item ~Z -'Z' if Date is UTC, otherwise nothing -@item ~L -Converts the date to local time -(@pxref{to_local}) (doesn't modify source object). Outputs nothing -@end table -@end defmethod - -@defun format_date date str -Equivalent to @code{(@var{date}).format(@var{str})}. -@c TODO link -@end defun - diff --git a/doc/ref/javascript/server_connect.texi b/doc/ref/javascript/server_connect.texi deleted file mode 100644 index c67f47ff..00000000 --- a/doc/ref/javascript/server_connect.texi +++ /dev/null @@ -1,22 +0,0 @@ -@node server_connect -@subsection server_connect.js - -Procedures for interfacing with the backend server. - -@deftypefn {Async Function} void create_event {event: VEvent} -Packs up the given event and sends it to the server to either be -created, or simply be updated in the persistant database. - -Also does some minor updates registered components, to show that the -event is actually created. -@end deftypefn - -@deftypefn {Async Function} void remove_event {uid: uid} -Requests that the server permanently remove the event with the given -unique id from its persistant storage. - -If the server responds with a success also delete it from our local -store (@code{vcal_objects}). - -@c TODO link to our backend flow here -@end deftypefn diff --git a/doc/ref/javascript/types.texi b/doc/ref/javascript/types.texi deleted file mode 100644 index 6f518f53..00000000 --- a/doc/ref/javascript/types.texi +++ /dev/null @@ -1,95 +0,0 @@ -@node types -@subsection types.js - -Collection of type information for calendar data. - -@defvar all_types -Name of all valid icalendar types. - - text, uri, binary, float, integer, date-time, date, duration, - period, utc-offset, cal-address, recur, boolean, -@end defvar - -@deftp {Data Type} ical_type -The union of all elements in @var{all_types}. -@end deftp - -@defvar property_names -All known names properties (top level keys) can have. -Such as ``calscale'', ``dtstart'', ... -@end defvar - -@deftypevar {Map} valid_fields -Which property fields each component can hold. - -@verbatim -{ 'VCALENDAR': ['PRODID', 'VERSION', 'CALSCALE', 'METHOD'], - ... -} -@end verbatim -@end deftypevar - -@deftypevar {Map>} valid_input_types -Which types are valid to store under each property. -If multiple values are an option for that property, then -the list of possibilities will contain a sub-list (see example). - -@verbatim -{ 'DTSTART': ['date', 'date-time'], - 'CATEGORIES': [['text']], - ... -} -@end verbatim -@end deftypevar - -@deftp {Data Type} tagname -Alias of (@code{'vevent'} | @code{'string'}). -@end deftp - -@deftp {Data Type} uid -Alias of @code{'string'}. -@end deftp - -@c TODO link to the RFC -@c - RFC 7265 (jCal) - -@deftp {Data Type} JCalProperty -Alias for a record consisting of -@itemize @bullet -@item the name of the type, as a string -@item All parameters of the object, as a @code{Record} -@footnote{Which is simply a regular javascript object, mapping strings to anything}. -@item An @code{ical_type} value, noting the type of the final field(s) -@item And one or more values of the type specified by the third field. -@end itemize -@end deftp - -@deftp {Data Type} JCal -A record consisting of a @code{tagname}, a list of -@code{JCalProperties}, and a list of other @code{JCal} objects. -@end deftp - -@defvar xcal -The xml namespace name for xcalendar, which is -``urn:ietf:params:xml:ns:icalendar-2.0''. -@end defvar - - -@deftp {Interface} ChangeLogEntry -@anchor{ChangeLogEntry} - -@ref{VEventChangelog} - -@deftypecv {Interface Field} ChangeLogEntry {(@code{'calendar'} | @code{'property'})} type -@end deftypecv - -@deftypecv {Interface Field} ChangeLogEntry {string} name -@end deftypecv - -@deftypecv {Interface Field} ChangeLogEntry {string?} from -@end deftypecv - -@deftypecv {Interface Field} ChangeLogEntry {string?} to -@end deftypecv - -@end deftp diff --git a/doc/ref/javascript/user-additions.texi b/doc/ref/javascript/user-additions.texi deleted file mode 100644 index 706b1dd4..00000000 --- a/doc/ref/javascript/user-additions.texi +++ /dev/null @@ -1,18 +0,0 @@ -@node user-additions.js -@section user-additions.js - -Some things in the JavaScript code is built to be user-extendable. -The HTML-page attempts to load @code{/static/user/user-additions.js}. - - -Currently; this only entails @ref{formatters}, where you could, for -example, parse all HTTP-links in a description. - -@example -window.formatters.set('description', (el, d) => @{ - el.innerHTML = d.replaceAll(/https?:\/\/\S+/g, '$&'); -@}) -@end example - -Remember that the documents are X-HTML, so be @emph{extremely} careful -with innerHTML. diff --git a/doc/ref/javascript/vevent.texi b/doc/ref/javascript/vevent.texi deleted file mode 100644 index 97d15f2a..00000000 --- a/doc/ref/javascript/vevent.texi +++ /dev/null @@ -1,113 +0,0 @@ -@node vevent -@subsection vevent.js - -@deftp {Interface} Redrawable -@deftypeop {Interface Field} Redrawable void redraw VEvent -@end deftypeop -@end deftp - -@deffn {Type Predicate} isRedrawable element -Checks if the given element is an instance of Redrawable. -@end deffn - - -@deftp {class} VEventValue {type: ical_type} {value: any} {parameters: Map} - -@deftypemethod VEventValue {[Record, ical_type, any]} @ - to_jcal {} -The return value is @emph{almost} a @code{JCalProperty}, just without -the field name. -@end deftypemethod - -@end deftp - -@deftp VEvent {properties: Map} @ - {components: VEvent[]} - -Component for a single instance of a calendar event. Almost all data -access should go through @code{getProperty} and @code{setProperty}, -with the exception of the current calendar (which is accessed directly -through @code{calendar}). Almost all changes through these interfaces -are logged, and can be viewed through @var{changelog}. - -@deftypemethod VEvent {any?} getProperty {key: string} -@anchor{VEvent.getProperty} -Returns the value of the given property if set, or undefined otherwise. - -For the keys -@itemize -@item @code{'CATEGORIES'}, -@item @code{'RESOURCES'}, -@item @code{'FREEBUSY'}, -@item @code{'EXDATE'}, and -@item @code{'RDATE'} -@end itemize -instead returns a list list of values. -@end deftypemethod - - -@deftypemethod VEvent void setProperty {key: string} {value: any} {type: ical_type?} -Sets the given property to the given value. If type is given it's -stored alongside the value, possibly updating what is already -there. Do however note that no validation between the given type and -the type of the value is done. - -@var{value} may also be a list, but should only be so for the keys -mentioned in @var{getProperty}. - -After the value is set, @var{redraw} is called on all registered -objects, notifying them of the change. -@end deftypemethod - -@deftypemethod VEvent void setProperties {[string, any, ical_type?][]} -Equivalent to running @var{setProperty} for each element in the input -list, but only calls @var{redraw} once at the end. -@end deftypemethod - -@deftypemethod VEvent {IteratableIterator} boundProperties -Returns an iterator of all our properties. -@end deftypemethod - -@deftypeivar VEvent {ChangeLogEntry[]} {#changelog} -Every write through getProperty gets logged here, and can be -consumed. Hopefully this will one day turn into an undo system. -@ref{ChangeLogEntry}. -@end deftypeivar - -@deftypeivar VEvent {IterableIterator<[number, ChangeLogEntry]>} changelog -Public (read only) interface to changelog. -@end deftypeivar - -@deftypeivar VEvent {string?} calendar -The name of the calendar which this event belongs to. -@end deftypeivar - -@deftypemethod VEvent void register {htmlNode: Redrawable} -Register something redrawable, which will be notified whenever this -VEvents data is updated. -@end deftypemethod - -@deftypemethod VEvent void unregister {htmlNode: Redrawable} -Stop recieving redraw events on the given component. -@end deftypemethod - -@deftypemethod VEvent JCal to_jcal -Converts the object to JCal data. -@end deftypemethod - -@end deftp - - -@deftp {class} RecurrenceRule -@deftypemethod RecurrenceRule {Record} to_jcal -Converts ourselves to JCal data. -@end deftypemethod -@end deftp - -@deftypefun RecurrencRule xml_to_recurrence_rule {Element} -Parse a XCAL recurrence rule into a RecurrenceRule object. -@end deftypefun - -@deftypefun VEvent xml_to_vcal {Element} -Parse a complete XCAL object into a JS VEvent object. -@end deftypefun -- cgit v1.2.3 From 517aa9c28f6b321af712aed04f42859061f96780 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Thu, 7 Sep 2023 15:34:55 +0200 Subject: Fix info declaration of `extract`. --- doc/ref/calp.texi | 1 + doc/ref/guile/vcomponent.texi | 6 +++--- 2 files changed, 4 insertions(+), 3 deletions(-) (limited to 'doc/ref') diff --git a/doc/ref/calp.texi b/doc/ref/calp.texi index 4dac681b..e8464edf 100644 --- a/doc/ref/calp.texi +++ b/doc/ref/calp.texi @@ -1,4 +1,5 @@ \input texinfo +@setfilename calp.info @settitle Calp @copying diff --git a/doc/ref/guile/vcomponent.texi b/doc/ref/guile/vcomponent.texi index 299ae1da..a0f3438e 100644 --- a/doc/ref/guile/vcomponent.texi +++ b/doc/ref/guile/vcomponent.texi @@ -89,10 +89,10 @@ have parent in its parent slot @end lisp @end deffn -@deffn (extract field) vcomponent -@deffnx (extract* field) vcomponent +@defun {(extract field)} vcomponent +@defunx {(extract* field)} vcomponent Curried version of @var{prop}. -@end deffn +@end defun @defun delete-property! component key @end defun -- cgit v1.2.3 From 01987c093e2cfbd46115cc58e4ff9f789efb9d0d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Thu, 7 Sep 2023 18:03:40 +0200 Subject: Enable let-env to unset variables. --- doc/ref/guile/util.texi | 3 +++ 1 file changed, 3 insertions(+) (limited to 'doc/ref') diff --git a/doc/ref/guile/util.texi b/doc/ref/guile/util.texi index 72463407..7536a9bc 100644 --- a/doc/ref/guile/util.texi +++ b/doc/ref/guile/util.texi @@ -315,6 +315,9 @@ Converts @var{any} to a string, as per @var{display}. @defmac let-env bindings body ... Similar to @var{let}, but sets environment variables for the code in body. Restores the old values once we leave. + +A variable can also be removed from the environment, by setting its +value to @code{#f}. @end defmac @defmac catch* thunk (symbol proc) ... -- cgit v1.2.3 From a2c3802be5301048fb899bc51b8935943daf73fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Thu, 7 Sep 2023 18:04:27 +0200 Subject: Add documentation and tests for xdg basedir. --- doc/ref/guile.texi | 1 + doc/ref/guile/xdg-basedir.texi | 62 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 63 insertions(+) create mode 100644 doc/ref/guile/xdg-basedir.texi (limited to 'doc/ref') diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi index a6c5ebe4..f32dca65 100644 --- a/doc/ref/guile.texi +++ b/doc/ref/guile.texi @@ -8,6 +8,7 @@ @include guile/util-path.texi @include guile/util-config.texi @include guile/base64.texi +@include guile/xdg-basedir.texi @include guile/web.texi @include guile/vcomponent.texi diff --git a/doc/ref/guile/xdg-basedir.texi b/doc/ref/guile/xdg-basedir.texi new file mode 100644 index 00000000..cdcf179b --- /dev/null +++ b/doc/ref/guile/xdg-basedir.texi @@ -0,0 +1,62 @@ +@node XDG Base Directory +@section XDG Base Directory + +Implementation of the XDG Base Directory Specification +@url{https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html}, v0.8. + +It's recommended to include this module with a symbol prefix: + +@example +(use-modules ((xdg basedir) :prefix xdg-) + +(xdg-data-dirs) +⇒ ("/usr/local/share" "/usr/share") +@end example + +The users home directory is fetched from the environment variable @env{HOME}. + + +@defun data-home +@findex XDG_DATA_HOME +@env{XDG_DATA_HOME}, usually @file{~/.local/share}. +@end defun + +@defun config-home +@findex XDG_CONFIG_HOME +@env{XDG_CONFIG_HOME}, usually @file{~/.config}. +@end defun + +@defun state-home +@findex XDG_STATE_HOME +@env{XDG_STATE_HOME}, usually @file{~/.local/state}. +@end defun + +@defun data-dirs +@findex XDG_DATA_DIRS +@env{XDG_DATA_DIRS}, split into a list. + +Defaults to @code{("/usr/local/share" "/usr/share")}. +@end defun + +@defun config-dirs +@findex XDG_CONFIG_DIRS +@env{XDG_CONFIG_DIRS} as a list, usually @code{("/etc/xdg")}. + +Defaults to @file{/etc/xdg}. +@end defun + +@defun cache-home +@findex XDG_CACHE_HOME +@env{XDG_CACHE_HOME}, usually @file{~/.cache}. +@end defun + +@defun runtime_dir +@findex XDG_RUNTIME_DIR +If @env{XDG_RUNTIME_DIR} is set, than that is used. Otherwise a +warning message is printed to stderr and @file{/tmp} is returned. + +The standard also stipulates a few things about permissons for this +directory. These are currently not checked. + +Systemd usually sets this value to @file{/run/user/$(id -u)}. +@end defun -- cgit v1.2.3 From 5672d44892c4010cdfbdc46f5fb29259fa51e076 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Sun, 10 Sep 2023 17:07:56 +0200 Subject: Add `break` and `continue` support in `for`. --- doc/ref/guile/util.texi | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) (limited to 'doc/ref') diff --git a/doc/ref/guile/util.texi b/doc/ref/guile/util.texi index 7536a9bc..95af9038 100644 --- a/doc/ref/guile/util.texi +++ b/doc/ref/guile/util.texi @@ -34,8 +34,8 @@ our extra specialized @var{when}}, but binds the return of @defmacx for (key ...) in collection body ... Syntactic sugar over @code{map}. @example -for x in collection - body ... +(for x in collection + body ...) @end example expands into @example @@ -44,6 +44,17 @@ expands into If keys are a list, an match-lambda is used instead. @xref{Pattern Matching,,,guile} + +@defun break args ... +Abandon the entire loop. Returing what was given to @code{break}. +@end defun + +@defun continue [arg] +Abandon the current iteration of the loop. If an argument is given, +it's used as the result in the resulting list, otherwise @code{#f} is +used. +@end defun + @end defmac -- cgit v1.2.3 From c809c81a7b9bffa1b65fdb09df0e49614f5e054f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Sun, 10 Sep 2023 17:09:37 +0200 Subject: Fix spelling of stream-remove in documentation. --- doc/ref/guile/srfi-41.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/ref') diff --git a/doc/ref/guile/srfi-41.texi b/doc/ref/guile/srfi-41.texi index 8c65b6eb..310751ec 100644 --- a/doc/ref/guile/srfi-41.texi +++ b/doc/ref/guile/srfi-41.texi @@ -39,7 +39,7 @@ was found. @end defun -@defun stream-remave pred stream +@defun stream-remove pred stream Stream-filter, but with predicate negated. @end defun -- cgit v1.2.3 From 72361e8c3aa8a33e1ea71e2fe081362670940fb7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Sun, 10 Sep 2023 17:16:46 +0200 Subject: Require component for path append. Changed the signature of `path-append` to require at least one argument. The alternative would have been that no components expands into '.'. --- doc/ref/guile/util-path.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/ref') diff --git a/doc/ref/guile/util-path.texi b/doc/ref/guile/util-path.texi index cf99a170..384915ef 100644 --- a/doc/ref/guile/util-path.texi +++ b/doc/ref/guile/util-path.texi @@ -8,7 +8,7 @@ Provided by the module @code{(hnh util path)}. Alias of @code{absolute-file-name?} from Guile. @end defun -@defun path-append strings ... +@defun path-append path paths ... Joins all strings into a path, squeezing duplicated delimiters, but ensuring that all delimiters that are needed are there. -- cgit v1.2.3 From c26324e29043423387c3041e86d8cbe5cd4102b2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Tue, 21 Feb 2023 03:21:43 +0100 Subject: Change `kvlist->assq` and `group-by` to return pairs. Each value in the return of group-by must have exactly two values, so cons pairs (instead of lists) is much better. --- doc/ref/guile/util.texi | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/ref') diff --git a/doc/ref/guile/util.texi b/doc/ref/guile/util.texi index 95af9038..d61bd0ed 100644 --- a/doc/ref/guile/util.texi +++ b/doc/ref/guile/util.texi @@ -186,8 +186,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 -- cgit v1.2.3 From 723502e4642b1861b902dd87de59973b3f10eca7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Sun, 10 Sep 2023 21:08:50 +0200 Subject: Clean up and include exception utility documentation. --- doc/ref/guile.texi | 3 +++ doc/ref/guile/util-exceptions.texi | 28 +++++++++++++++++++++++----- 2 files changed, 26 insertions(+), 5 deletions(-) (limited to 'doc/ref') diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi index f32dca65..1fc0065a 100644 --- a/doc/ref/guile.texi +++ b/doc/ref/guile.texi @@ -7,6 +7,7 @@ @include guile/util.texi @include guile/util-path.texi @include guile/util-config.texi +@include guile/util-exceptions.texi @include guile/base64.texi @include guile/xdg-basedir.texi @include guile/web.texi @@ -24,6 +25,8 @@ Should possibly be replaced by an explicit return-continuation. @deftp{Error type} warning fmt args Thrown when @code{warnings-are-errors} is true. + +@ref{warning} for more information. @end deftp @deftp{Error type} max-page page-number diff --git a/doc/ref/guile/util-exceptions.texi b/doc/ref/guile/util-exceptions.texi index 4e84d8c4..34ba33f9 100644 --- a/doc/ref/guile/util-exceptions.texi +++ b/doc/ref/guile/util-exceptions.texi @@ -1,22 +1,40 @@ -@node Exception Utilities -@section Exception Utilities +@node Exception & Warning Utilities +@section Exception & Warning Utilities +@anchor{warning} + +Warnings are like exceptions, but only fatal when wanted. + +@code{(hnh util exceptions)} @defun warning fmt args ... +Emit a warning. +If the parameter @var{warnings-are-errors} is true, then an exception +of type @code{'warning} will be raised, with @var{fmt} and @var{args} +as arguments. + +If that parameter is false, then the procedure in +@var{warning-handler} will instead be called. @end defun @deftp {parameter} warning-handler -Procedure, which htnaoe htn oeu htn oeu +Parameter containing proceudre which will be called for non-throwing +warnings. This procedure is assumed by the program to log the warning +in some way, and continue program flow. But anything goes. + +The procedure is given a format specifier (as per Scheme's basic +@code{format}), along with the correct number of arguments. @end deftp @deftp {parameter} warnings-are-errors -Boolean parameter +Boolean parameter, which if set causes warnings to be thrown as exceptions. @end deftp @defun fatal fmt args ... Display the message in fmt, populated with args, then raises the UNIX -signal 2, which kills the program. +signal SIGINT, which kills the program. @end defun @defun filter-stack pred? stack +@c TODO document me @end defun -- cgit v1.2.3 From fabddcf27bce94651ae1f0eea868d6747431e6d3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Sun, 10 Sep 2023 21:10:38 +0200 Subject: Add documentation for translation procedures. --- doc/ref/guile.texi | 1 + doc/ref/guile/translation.texi | 31 +++++++++++++++++++++++++++++++ 2 files changed, 32 insertions(+) create mode 100644 doc/ref/guile/translation.texi (limited to 'doc/ref') diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi index 1fc0065a..131d435c 100644 --- a/doc/ref/guile.texi +++ b/doc/ref/guile.texi @@ -12,6 +12,7 @@ @include guile/xdg-basedir.texi @include guile/web.texi @include guile/vcomponent.texi +@include guile/translation.texi @node Errors and Conditions @section Errors and Conditions diff --git a/doc/ref/guile/translation.texi b/doc/ref/guile/translation.texi new file mode 100644 index 00000000..0e710c47 --- /dev/null +++ b/doc/ref/guile/translation.texi @@ -0,0 +1,31 @@ +@node Translation +@section Translation + +Base for string translation in the application. Calp uses Guile's +built in gettext bindings. The text domain used is ``calp''. + +@defun translate str +@anchor{translate} +Translate a string from english into an (through enviroment) specified +target language. All newlines in the source string will be changed to +spaces. + +This procedure is both used as the ``backend'' for @ref{G_}, but also +for non-literal strings which should be translated. +@end defun + +@defun G_ msg ... +@anchor{G_} +The ``global'' binding indicating a string to be translated. + +All arguments must be strings, and will be concatenated before being +passed to @ref{translate} (meaning newlines will be ignored). +@end defun + +@defun yes-no-check string [locale=%global-locale] +Checks @var{string} if it's a yes or no response in the given +@var{locale}. + +Returns @code{'yes} or @code{'no}, or @code{#f} if the string couldn't +be parsed as a yes/no predicate in the current locale. +@end defun -- cgit v1.2.3 From 634502e7246f8850ad6c649b79ae9f072f45baf4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Mon, 11 Sep 2023 17:54:35 +0200 Subject: Introduce stream-split-by. This procedure isn't currently used, but as noted is really useful for grouping a character stream into a word stream, which is a later commit will use for it for justifying posibly infinite streams of text. --- doc/ref/guile/srfi-41.texi | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) (limited to 'doc/ref') diff --git a/doc/ref/guile/srfi-41.texi b/doc/ref/guile/srfi-41.texi index 310751ec..d8020ecc 100644 --- a/doc/ref/guile/srfi-41.texi +++ b/doc/ref/guile/srfi-41.texi @@ -73,6 +73,26 @@ times. stream cons, but eval arguments beforehand. @end defun +@defun stream-split-by pred strm +Chunks the content of @var{strm} into lists, breaking on @var{pred}. +If the end of the stream is reached, the remaining objects +are put into a final chunk. + +Can for example be used to split a stream of characters into a stream +of words. + +@lisp +(stream-split-by (lambda (c) (char=? c #\space)) + (-> "This is a short test" + string->list list->stream)) +⇒ # +@end lisp +@end defun + @defun stream-timeslice-limit stream timeslice Wrap a stream in time limits. Each element has at most @var{timeslice} seconds to produce a value, otherwise the stream ends. Useful for finding the -- cgit v1.2.3 From e9d6798e9cf79d54f64171eda6fa9102fffe1f30 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Mon, 11 Sep 2023 20:45:45 +0200 Subject: Document text modules. --- doc/ref/calp.texi | 1 + doc/ref/text.texi | 9 ++++++ doc/ref/text/flow.texi | 23 +++++++++++++++ doc/ref/text/markup.texi | 71 +++++++++++++++++++++++++++++++++++++++++++++ doc/ref/text/numbers.texi | 42 +++++++++++++++++++++++++++ doc/ref/text/utilities.texi | 67 ++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 213 insertions(+) create mode 100644 doc/ref/text.texi create mode 100644 doc/ref/text/flow.texi create mode 100644 doc/ref/text/markup.texi create mode 100644 doc/ref/text/numbers.texi create mode 100644 doc/ref/text/utilities.texi (limited to 'doc/ref') diff --git a/doc/ref/calp.texi b/doc/ref/calp.texi index e8464edf..d9cad0af 100644 --- a/doc/ref/calp.texi +++ b/doc/ref/calp.texi @@ -65,6 +65,7 @@ text @footnote{Improvements welcome} @c @end menu @include guile.texi +@include text.texi @node Index @unnumbered Index diff --git a/doc/ref/text.texi b/doc/ref/text.texi new file mode 100644 index 00000000..ec7074ae --- /dev/null +++ b/doc/ref/text.texi @@ -0,0 +1,9 @@ +@node Text Procedures +@chapter Text Procedures + +Various utilities for formatting text in various ways. + +@include text/utilities.texi +@include text/flow.texi +@include text/markup.texi +@include text/numbers.texi diff --git a/doc/ref/text/flow.texi b/doc/ref/text/flow.texi new file mode 100644 index 00000000..0613d78f --- /dev/null +++ b/doc/ref/text/flow.texi @@ -0,0 +1,23 @@ +@node Reflowing Text +@section Reflowing Text + +@code{(text flow)} + +@defun flow-text str [width=70] +Reflow and justify @var{str} to @var{width} columns. + +Each newline is as a newline, so each paragraph needs to be on its own +line. The output will look something like the following: + +@example +muck calendar's Hobart's Kendall's lighthouse wooziest knot's swanky +Ghats's witless heftiness's hailstorm's ladybugs abridgment's +whispered Willemstad's ludo stewardess photostatic potshot ninety +perfected Potsdam asinine swings Valiums Adrenalin's contralto +emigration's besmears finessing resorption's literariness's +verbalize maximums Bjork diverticulitis cascaras implacably +overeager deepen funeral's Edwardian Calvinistic seawards microlight +palatial Shaun fungus's unmounted armrests Culbertson's lineage +@end example + +@end defun diff --git a/doc/ref/text/markup.texi b/doc/ref/text/markup.texi new file mode 100644 index 00000000..bec33557 --- /dev/null +++ b/doc/ref/text/markup.texi @@ -0,0 +1,71 @@ +@node Markup +@section Markup + +@defun sxml->ansi-text tree +Takes an HTML-like document in SXML format, and produces a formatted +string with embedded ANSI-escapes suitable to print to a terminal. + +Supported tags are: + +@table @samp +@item group +@item block +Groups elements, concatenating their format. Mainly here for helper +procedres and the like. Also used for the root node. + +@item header +Centers and bolds its content. Attributes will be sent along to the +inner @code{
} tag. + +@item center +Center its contents on the line. The output is undefined if the body +serializes to a multiline string. + +@item p +A text paragraph. Justifies the content inside. + +Ends with a double newline, unless the parameter @code{inline} is set. + +@item b +Make content bold. + +@item i +@item em +Make content italics. + +@item code +Format content as code. + +(currently does nothing since we only support output to terminal) + +@item blockquote +Justifies content, and sets it slightly indented. + +@item ws +Forces horizontal whitespace. Use the parameter @code{minwidth} to +specify how many spaces should be inserted. + +@item br +Forces a linebreak. + +@item hr +Generates a horrizontal line. + +@item dl +Declares a description list. + +@item dt +A key in a description list, only valid inside @code{dl}. + +@item dd +A value of a description list, only valid inside @code{dl}. + +@item scheme +Set content as Scheme code. The content will be passed through Guile's +pretty-print. +@end table + + +Almost all of the block environments accept the attribute @var{width}, +which specifies the desired output width. +@end defun diff --git a/doc/ref/text/numbers.texi b/doc/ref/text/numbers.texi new file mode 100644 index 00000000..fce5c9fa --- /dev/null +++ b/doc/ref/text/numbers.texi @@ -0,0 +1,42 @@ +@node Spelled out Numbers +@section Spelled out Numbers + +Numbers writtens as word. The usual interface is through +@code{(text numbers)} which uses the current locale for translations. +However, @code{(text numbers @var{})} can also be imported +directly with the exact same interface. Language codes should be two +letter ISO language codes (e.g. ``se'', ``en'', ...) + +When resolving the current language, first the environment variable +@env{LC_MESSAGES} is checked, followed by @env{LC_ALL}, and finaly +falls back to ``en''. + +English is also chosen if no implementation for the chosen language +exists. + +Note that English uses the term cardinal and ordinal @emph{numeral}, +rather than @emph{number}. + + +@defun number->string-ordinal n [language=(resolve-language)] +Convert a string into an ordinal number. These are the ``ranking'' +numbers, e.g. ``first'', ``second'', ... +@end defun + +@defun number->string-cardinal n [language=(resolve-language)] +Convert a string into a cardinal number. These are the ``ordinary'' +counting numbers, e.g. ``one'', ``two'', ... +@end defun + +@defun resolve-language +Return the current language. +@end defun + +@defun each-string count args ... +Return a (locale dependant) string indicating which elements of a set +are targeted, such as ``each'', ``every other'', ... + +@var{args} is reserved for locale specific extensions, such as in +Swedish where both ``var tredje'' and ``vart tredje'' (meaning ``every +third'') exists, and is chosen depending on the following noun. +@end defun diff --git a/doc/ref/text/utilities.texi b/doc/ref/text/utilities.texi new file mode 100644 index 00000000..175b8f60 --- /dev/null +++ b/doc/ref/text/utilities.texi @@ -0,0 +1,67 @@ +@node Text Utilities +@section Text Utilities + +@code{(text util)} + +Various general utilities for basic text manipulation. + +Some of these procedures claim to use ``true'' text width. These +calculate text width in unicode code-points, but with (some) ANSI +escape sequences omitted. In a perfect world, these would show exactly +how many characters wide the outputed string is when printed to a +(sufficiently advanced) terminal. + +@defun words str +Split string on spaces. No space merging is done. +@end defun + +@defun unwords list +Join list with spaces. +@end defun + +@defun lines str +Split string on newlines. +@end defun + +@defun unlines list +Join string with newlines. +@end defun + +@defun true-string-length word +@anchor{true-string-length} +Alternative string-length whith counts ANSI escapes as 0-length. +@end defun + +@defun true-string-pad str len [chr=#\space] +Works like the regular @code{string-pad}, but uses the ``true'' +length. @ref{true-string-length} +@end defun + +@defun trim-to-width str len +Forces @var{str} to be exactly @var{len} characters long. + +This is done by either right padding the string, or by drop +characters from the right until the string is one shorter than length, +then an ellipsis character is added. + +@example +(trim-to-width "Hello, World!" 6) +⇒ "Hello…" + +(trim-to-width "Hello" 10) +⇒ "Hello " +@end example +@end defun + +@defun add-enumeration-punctuation list [final-delim=``&''] +Intersperse punctuation into @var{list}, preparing it to be formatted +as a inline list in the body of the document. The sequence ``, '' +inserted between each element, except the last which will use +@var{final-delim}. An oxford comma is not used. + +@example +(string-concatenate (add-enumeration-punctuation + '("Pasta" "Hamburgers" "Hotdog and Mash"))) +⇒ "Pasta, Hamburgers & Hotdog and Mash" +@end example +@end defun -- cgit v1.2.3 From 1d147d7420cc4c14326fa273e9163a7dc807f94a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Mon, 11 Sep 2023 21:03:47 +0200 Subject: Add basic documentation of entry points. --- doc/ref/calp.texi | 1 + doc/ref/entry-points.texi | 62 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 63 insertions(+) create mode 100644 doc/ref/entry-points.texi (limited to 'doc/ref') diff --git a/doc/ref/calp.texi b/doc/ref/calp.texi index d9cad0af..a3ab4bf6 100644 --- a/doc/ref/calp.texi +++ b/doc/ref/calp.texi @@ -65,6 +65,7 @@ text @footnote{Improvements welcome} @c @end menu @include guile.texi +@include entry-points.texi @include text.texi @node Index diff --git a/doc/ref/entry-points.texi b/doc/ref/entry-points.texi new file mode 100644 index 00000000..4c4ec90f --- /dev/null +++ b/doc/ref/entry-points.texi @@ -0,0 +1,62 @@ +@node Entry Points +@chapter Entry Points + +Calp has many different entry points. Each is implemented in a module +residing under @code{calp entry-points}. Each such module @emph{must} +export a @code{main} procedure, which should take a list of command +line arguments (as a single parameter). + +When starting Calp from the command line, the @code{main} procedure +located in @code{(calp main)} is called. That procedure parse it's own +command line flags, up until the first non-flag argument. That word +will be used to chose the actual entry point, which is then +responsible for parsing the remaining command line flags. + +Information about global command line arguments can be accessed by +running @command{calp --help}, and subcommands arguments through +@command{calp @var{} --help}. + +@deftp {Entry Point} benchmark module +Run @code{(@ (calp benchmark @var{module}) run-benchmark)} with +profiling enabled, and prints the collected data. +@end deftp + +@deftp {Entry Point} convert +Convert calendar files between filetypes. +@end deftp + +@deftp {Entry Point} html +Generates static HTML files. +@end deftp + +@deftp {Entry Point} ical +Generates static iCal files. +@end deftp + +@deftp {Entry Point} import +Import entry into database. +@end deftp + +@deftp {Entry Point} server +Start the web server. +@end deftp + +@deftp {Entry Point} terminal +Start the terminal interface. +@end deftp + +@deftp {Entry Point} text +Format text, completely ignoring calendars. +@end deftp + +@deftp {Entry Point} tidsrapport +Generate an FDF (PDF Form submission file) for some very specific time +reporting sheets. + +TODO this should be removed from this project, and moved to a +``private'' repo of hugo. +@end deftp + +@deftp {Entry Point} update-zoneinfo +Downloads zoneinfo files and places them in the correct location. +@end deftp -- cgit v1.2.3 From 475307bc9926898e769c7ad6fa3a844853b07f52 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Tue, 12 Sep 2023 10:04:04 +0200 Subject: Add a bunch of documentation. --- doc/ref/calp.texi | 1 + doc/ref/guile.texi | 3 + doc/ref/guile/crypto.texi | 17 +++ doc/ref/guile/glob.texi | 37 ++++++ doc/ref/guile/graphviz.texi | 10 ++ doc/ref/guile/util.texi | 66 +++++++++++ doc/ref/guile/xdg-basedir.texi | 2 +- doc/ref/vulgar.texi | 261 +++++++++++++++++++++++++++++++++++++++++ 8 files changed, 396 insertions(+), 1 deletion(-) create mode 100644 doc/ref/guile/crypto.texi create mode 100644 doc/ref/guile/glob.texi create mode 100644 doc/ref/guile/graphviz.texi create mode 100644 doc/ref/vulgar.texi (limited to 'doc/ref') diff --git a/doc/ref/calp.texi b/doc/ref/calp.texi index a3ab4bf6..b9e8723d 100644 --- a/doc/ref/calp.texi +++ b/doc/ref/calp.texi @@ -67,6 +67,7 @@ text @footnote{Improvements welcome} @include guile.texi @include entry-points.texi @include text.texi +@include vulgar.texi @node Index @unnumbered Index diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi index 131d435c..1e8d44fd 100644 --- a/doc/ref/guile.texi +++ b/doc/ref/guile.texi @@ -13,6 +13,9 @@ @include guile/web.texi @include guile/vcomponent.texi @include guile/translation.texi +@include guile/glob.texi +@include guile/graphviz.texi +@include guile/crypto.texi @node Errors and Conditions @section Errors and Conditions diff --git a/doc/ref/guile/crypto.texi b/doc/ref/guile/crypto.texi new file mode 100644 index 00000000..b9e362d3 --- /dev/null +++ b/doc/ref/guile/crypto.texi @@ -0,0 +1,17 @@ +@node Cryptographic and Hash Procedures +@section Cryptographic and Hash Procedures + +This module links libcrypto, exposing some hash procedures. + +@defun sha256 message +Calculate the sha256-sum of @var{message}. The message can either be a +bytevector or a string (in which case it will de encoded as UTF-8). + +Returns the checksum as a bytevector. +@end defun + +@defun checksum->string message-digest [port] +Generates a hex digest string from a checksum (generated by +@code{sha256}). The checksum is written to @var{port} if given, or +returned as a string otherwise. +@end defun diff --git a/doc/ref/guile/glob.texi b/doc/ref/guile/glob.texi new file mode 100644 index 00000000..400eb1f7 --- /dev/null +++ b/doc/ref/guile/glob.texi @@ -0,0 +1,37 @@ +@node Glob +@section Glob + +@defun glob str +Globs (glob(7)) on @var{str}, returing a list of files, which will be +on the same form of the glob. E.g. @code{(glob "../*")} will return +strings all starting with ``../'' + +If no matches are found, a misc error is thrown. +@end defun + + + +@defvar GLOB_NOMAGIC +@defvarx GLOB_NOCHECK +@defvarx unix +@defvarx GLOB_NOSPACE +@defvarx GLOB_TILDE_CHECK +@defvarx GLOB_ALTDIRFUNC +@defvarx GLOB_NOSORT +@defvarx GLOB_NOMATCH +@defvarx GLOB_TILDE +@defvarx GLOB_ERR +@defvarx GLOB_MAGCHAR +@defvarx GLOB_BRACE +@defvarx GLOB_APPEND +@defvarx GLOB_NOSYS +@defvarx GLOB_DOOFFS +@defvarx GLOB_NOESCAPE +@defvarx GLOB_MARK +@defvarx GLOB_PERIOD +@defvarx linux +@defvarx GLOB_ABORTED +@defvarx _POSIX_VDISABLE +@defvarx GLOB_ONLYDIR +``Symbols'' imported from the C header ``glob.h''. See that documentation. +@end defvar diff --git a/doc/ref/guile/graphviz.texi b/doc/ref/guile/graphviz.texi new file mode 100644 index 00000000..72817ea8 --- /dev/null +++ b/doc/ref/guile/graphviz.texi @@ -0,0 +1,10 @@ +@node Graphviz +@section Graphviz + +The graphviz library comes bundled with Guile bindings, but without a +corresponding .scm file exporting the symbols. The module @code{(guile)} does +exactly that. + +This ``header'' is borrowed from +@url{https://github.com/roelj/graphviz-guile/blob/master/graphviz.scm}, +under GPL 3.0. diff --git a/doc/ref/guile/util.texi b/doc/ref/guile/util.texi index d61bd0ed..e7accf90 100644 --- a/doc/ref/guile/util.texi +++ b/doc/ref/guile/util.texi @@ -1,6 +1,9 @@ @node General Utilities @section General Utilities +@node Miscellaneous utilities +@subsection Miscellaneous utilities + Provided by the module @code{(hnh util)}. @defmac define-syntax [stx] @@ -340,6 +343,25 @@ innermost. then @code{with-throw-handler} is used instead of @code{catch}. @end defmac +@defun uniq lst +@defunx univ lst +@defunx unique lst +@defunx uniqx comp lst +Squash repeated equivalent elements in a list into single instances, +similar to the POSIX command uniq(1). The three variants uses +@code{eq?}, @code{eqv?}, and @code{equal?} respectively. + +@code{uniqx} also takes @var{comp}, which is sholud be a binary +procedure returning if the elements are equal. +@end defun + +@defmac begin1 forms ... +Port of Common Lisp's @code{begin1} form. Like @code{begin} runs each +form in its body in order, but returns the first result instead of the +last. +@end defmac + +@node UUIDs @subsection UUID generation Provided by module @code{(hnh util uuid)}. @@ -352,6 +374,12 @@ Generates a UUID-v4 string. Generates an implementation defined (but guaranteed valid) UUID. @end defun +@deftp {parameter} seed +Guile parameter containing the seed used when generating UUID's in +this module. Only set this when you want non-random randomness. +@end deftp + +@node IO operations @subsection IO Provided by module @code{(hnh util io)}. @@ -382,3 +410,41 @@ the file, and @code{#f} otherwise. @defun read-file path Open file at path, and return its content as a string. @end defun + +@node Binary Search Tree +@subsection Binary Search Tree + +A simple ``read only'' binary search tree. + +@defun make-tree pred? lst +Constructs a new tree. @var{pred?} should be a procedure taking the +first element of @var{lst}, along with each element, and should return +a boolean value indicating if the specific element should go in the +left or right subtree. (left subtree is ``truthy'' values). + +This operation is done recursively. +@end defun + +@defun tree-node tree +Return the value of a tree node. +@end defun + +@defun left-subtree tree +Return all ``truthy'' children of tree node. +@end defun + +@defun right-subtree tree +Return all ``falsy children of tree node. +@end defun + +@defun length-of-longest-branch tree +Get the depth of a tree. +@end defun + +@defun tree-map proc tree +Apply proc onto the value of every node in tree, keeping the structure +of the tree. + +@b{Note:} this can cause the tree to no longer be a binary search +tree, but simply a ``formless'' binary tree. +@end defun diff --git a/doc/ref/guile/xdg-basedir.texi b/doc/ref/guile/xdg-basedir.texi index cdcf179b..2d3b2972 100644 --- a/doc/ref/guile/xdg-basedir.texi +++ b/doc/ref/guile/xdg-basedir.texi @@ -50,7 +50,7 @@ Defaults to @file{/etc/xdg}. @env{XDG_CACHE_HOME}, usually @file{~/.cache}. @end defun -@defun runtime_dir +@defun runtime-dir @findex XDG_RUNTIME_DIR If @env{XDG_RUNTIME_DIR} is set, than that is used. Otherwise a warning message is printed to stderr and @file{/tmp} is returned. diff --git a/doc/ref/vulgar.texi b/doc/ref/vulgar.texi new file mode 100644 index 00000000..e98daaa0 --- /dev/null +++ b/doc/ref/vulgar.texi @@ -0,0 +1,261 @@ +@node Vulgar Terminal Interface +@chapter Vulgar Terminal Interface + +The Vulgar@footnote{Since it's not Curses} +Terminal Interface aims to be a simple way to semi advanced terminal +interfaces. + +@defun cls +Clear the screen, and move the cursor to the ``home''. +@end defun + +@defun set-cursor-pos x y +Move the cursor to the specified position on the screen. +@end defun + +@defun with-vulgar [bits] thunk +Runs @var{thunk} with +@code{iattr.lflag &= @var{bits}} and +@code{oattr.lflag &= @var{bite}}, along with +@command{tput civis} being run on entrance, and +@command{tput cnorm} being run on exit. + +The thunk is properly prepared on non-local entrances and exits. +@end defun + +@node Color +@section Color + +@defvar STR-RESET +ANSI escape sequence for removing all current formatting, as a string. +@end defvar + +@defmac color-if predicate color body ... +@code{(begin body ...)} is run, coloring it's return value using the +ANSI escape sequence @var{color}, if @var{predicate} is true, and +uncolored otherwise. +@end defmac + +@defun color-escape n +Generates an RGB color escape code. @var{n} can either be @code{#f}, +in which case the empty string is returned, or a a 24 bit color code +encoded hexadecimaly as @samp{#RRGGBB}. +@end defun + +@node Termios +@section Termios + +Interface to termios procedures. See termios(3) and @code{termios.h} +for general information. + +@code{(vulgar termios)} + +Refer to termios(3) for deeper information about all these fields. + +@deftp {Record Type} +See ``The termios structure'' in termios(3). +@defun make-termios +Create a new (empty) termios structure. +@end defun + +@defun cc termios +@defunx cflag termios +@defunx iflag termios +@defunx ispeed termios +@defunx lflag termios +@defunx line termios +@defunx oflag termios +@defunx ospeed termios +Accessors to termios each field. +@end defun +@end deftp + +@defun copy-termios termios +Create a copy of the given termios structure. +@end defun + +@defun tcsetattr! termios [port] [when=TCSANOW] +Updates @var{port} with flags from @var{termios}. +@end defun + +@defun tcgetattr! termios [port=(current-input-port)] +Gets termios information about @var{port}, and stores it in @var{termios}. +@end defun + +@defun cfmakeraw! termios +Calls the termios function @code{cfmakeraw} on @var{termios}, updating +the structure. +@end defun + + +@defvar TOSTOP +@defvarx NLDLY +@defvarx CREAD +@defvarx VSTOP +@defvarx B1500000 +@defvarx B4000000 +@defvarx B150 +@defvarx VEOL +@defvarx VQUIT +@defvarx CSTART +@defvarx CBAUD +@defvarx CR0 +@defvarx OLCUC +@defvarx CSTATUS +@defvarx VSTART +@defvarx IXANY +@defvarx ONOCR +@defvarx VERASE +@defvarx TTYDEF_IFLAG +@defvarx B1000000 +@defvarx NL0 +@defvarx FLUSHO +@defvarx TABDLY +@defvarx CDSUSP +@defvarx CEOL +@defvarx CIBAUD +@defvarx TAB3 +@defvarx CR2 +@defvarx NL1 +@defvarx CS8 +@defvarx CERASE +@defvarx OPOST +@defvarx TTYDEF_SPEED +@defvarx TAB1 +@defvarx EXTA +@defvarx B1200 +@defvarx TAB0 +@defvarx B75 +@defvarx EXTB +@defvarx FF1 +@defvarx CR1 +@defvarx CS5 +@defvarx INPCK +@defvarx B576000 +@defvarx B3000000 +@defvarx OCRNL +@defvarx TCOON +@defvarx CBAUDEX +@defvarx CCEQ +@defvarx IXOFF +@defvarx CREPRINT +@defvarx FF0 +@defvarx ECHONL +@defvarx IXON +@defvarx ISTRIP +@defvarx CSTOP +@defvarx PENDIN +@defvarx BRKINT +@defvarx IEXTEN +@defvarx TCIFLUSH +@defvarx VSUSP +@defvarx B38400 +@defvarx TCION +@defvarx B921600 +@defvarx ECHOPRT +@defvarx CQUIT +@defvarx IMAXBEL +@defvarx CRTSCTS +@defvarx ECHOCTL +@defvarx CEOT +@defvarx VMIN +@defvarx ICANON +@defvarx ONLRET +@defvarx VINTR +@defvarx CSTOPB +@defvarx B3500000 +@defvarx B230400 +@defvarx CS7 +@defvarx TCOFLUSH +@defvarx TIOCSER_TEMT +@defvarx B200 +@defvarx CSUSP +@defvarx BS1 +@defvarx XTABS +@defvarx CLNEXT +@defvarx VT0 +@defvarx NCCS +@defvarx BSDLY +@defvarx B9600 +@defvarx ECHOKE +@defvarx VEOF +@defvarx TTYDEF_OFLAG +@defvarx VTDLY +@defvarx VT1 +@defvarx CTRL +@defvarx NOFLSH +@defvarx VREPRINT +@defvarx ICRNL +@defvarx CINTR +@defvarx ADDRB +@defvarx B2500000 +@defvarx EXTPROC +@defvarx B110 +@defvarx XCASE +@defvarx ECHOE +@defvarx IUTF8 +@defvarx CS6 +@defvarx CFLUSH +@defvarx B500000 +@defvarx CKILL +@defvarx CDISCARD +@defvarx VDISCARD +@defvarx B2400 +@defvarx TTYDEF_CFLAG +@defvarx VWERASE +@defvarx INLCR +@defvarx ONLCR +@defvarx OFDEL +@defvarx B1800 +@defvarx ISIG +@defvarx IGNPAR +@defvarx TAB2 +@defvarx CTIME +@defvarx B1152000 +@defvarx ECHO +@defvarx CR3 +@defvarx CMSPAR +@defvarx PARENB +@defvarx B2000000 +@defvarx VKILL +@defvarx B4800 +@defvarx CLOCAL +@defvarx IGNBRK +@defvarx BS0 +@defvarx TCSAFLUSH +@defvarx B19200 +@defvarx TCSANOW +@defvarx VTIME +@defvarx B0 +@defvarx TCOOFF +@defvarx CEOF +@defvarx B460800 +@defvarx PARMRK +@defvarx VEOL2 +@defvarx FFDLY +@defvarx TCSADRAIN +@defvarx IGNCR +@defvarx CRDLY +@defvarx VLNEXT +@defvarx PARODD +@defvarx CRPRNT +@defvarx B600 +@defvarx VSWTC +@defvarx IUCLC +@defvarx HUPCL +@defvarx B50 +@defvarx TCIOFF +@defvarx TTYDEF_LFLAG +@defvarx CBRK +@defvarx ECHOK +@defvarx B115200 +@defvarx CSIZE +@defvarx B300 +@defvarx OFILL +@defvarx CWERASE +@defvarx B134 +@defvarx B57600 +@defvarx TCIOFLUSH +@defvarx CMIN +Imported from the ``termios.h'' header file. +@end defvar -- cgit v1.2.3 From 4d5d13b5e86dce1db72649204021882fbab668a4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Tue, 12 Sep 2023 10:10:57 +0200 Subject: Change overarching structure of info document. --- doc/ref/calp-prime.texi | 179 ++++++++++++++++++++++++++++++++++++++++++++ doc/ref/calp.texi | 5 +- doc/ref/general.texi | 15 ++++ doc/ref/guile.texi | 193 ------------------------------------------------ doc/ref/guile/util.texi | 11 +-- doc/ref/vcomponent.texi | 4 + doc/ref/web.texi | 4 + 7 files changed, 210 insertions(+), 201 deletions(-) create mode 100644 doc/ref/calp-prime.texi create mode 100644 doc/ref/general.texi delete mode 100644 doc/ref/guile.texi create mode 100644 doc/ref/vcomponent.texi create mode 100644 doc/ref/web.texi (limited to 'doc/ref') diff --git a/doc/ref/calp-prime.texi b/doc/ref/calp-prime.texi new file mode 100644 index 00000000..89decb1b --- /dev/null +++ b/doc/ref/calp-prime.texi @@ -0,0 +1,179 @@ +@node Calp as a Program +@chapter Calp as a Program + +@include guile/translation.texi + +@node Errors and Conditions +@section Errors and Conditions + +@subsection ``Special'' Errors + +@deftp{Error type} return +Thrown in some sub-mains to quickly return from the sub-function. +Should possibly be replaced by an explicit return-continuation. +@end deftp + +@deftp{Error type} warning fmt args +Thrown when @code{warnings-are-errors} is true. + +@ref{warning} for more information. +@end deftp + +@deftp{Error type} max-page page-number +@end deftp + +@subsection ``Regular'' Errors +All below mentioned error types behave as expected, e.g., they are +produced through @code{scm-error}. + +@deftp{Error Type} configuration-error +Thrown by (calp util config), in some scenarios. +@TODO{Better documentation} +@end deftp + +@deftp{Error Type} c-parse-error +Errors thrown by our make-shift C parser. +@end deftp + +@deftp{Error Type} decoding-error +thrown by base64 in some cases +@end deftp + +@deftp{Error Type} parse-error +Thrown by some things related to parsing, but not all. +@TODO{normalize parsing errors further} +@end deftp + +@deftp{Error Type} graph-error +The first element of data is guaranteed to be the graph which caused +the error. +@end deftp + +@deftp{Error Type} missing-helper +A helper program we wanted was missing, could be resolved by somehow +downloading it into one of the searched locations. + +@example +data : (program-name : string) + , (searched-locations : (list string)) +@end example +@end deftp + + + +@node Other +@section Other + +@defun get-parser type +@example +get-parser ∷ type-name → hash-table x string → any +type = 'BINARY | 'BOOLEAN | 'CAL-ADDRES | 'DATE | 'DATE-TIME + | 'DURATION | 'FLOAT | 'INTEGER | 'PERIOD | 'RECUR + | 'TEXT | 'TIME | 'URI | 'UTC-OFFSET +@end example + +@ref{ical-get-writer} +@end defun + +@subsection formats ical +@subsubsection output + +@defun component->ical-string component +@end defun + +@defun print-components-with-fake-parent events +@end defun + +@defun print-all-events +@end defun + +@defun print-events-in-interval start end +@end defun + +@subsubsection parse + +@defun parse-calendar port +@end defun + +@subsubsection types + +@defun escape-chars str +Escape @code{,}, @code{;} and @code{\} with a +backslash, and encode newlines as @code{\n}. +@end defun + +@defun get-writer type +@anchor{ical-get-writer} +@example +get-writer ∷ type-name → hash-table x value → string +type = 'BINARY | 'BOOLEAN | 'CAL-ADDRES | 'DATE | 'DATE-TIME + | 'DURATION | 'FLOAT | 'INTEGER | 'PERIOD | 'RECUR + | 'TEXT | 'TIME | 'URI | 'UTC-OFFSET +@end example +@end defun + +@subsection formats vdir +@subsubsection parse + +@defun parse-vdir path +@end defun + +@subsubsection save-delete + +@defun save-event event +@end defun + +@defun remove-event event +@end defun + +@subsection formats xcal +@subsubsection output + +@defun vcomponent->sxcal component +@end defun + +@defun ns-wrap +@lisp +(define (ns-wrap sxml) + `(icalendar (@@ (xmlns "urn:ietf:params:xml:ns:icalendar-2.0")) + ,sxml)) +@end lisp +Where @var{sxml} is expected to be the output of @var{vcomponent->sxcal}. +@end defun + +@subsubsection parse +@defun sxcal->vcomponent sxcal +Parses a vcomponent in sxcal format. Requires that the vcomponent is +the root of the document (fragment), so wrapping icalendar-tags or +similar @emph{must} be removed. + +@example +(vcalendar + (properties ...) + (components ...)) +@end example +@end defun + +@subsubsection types +@defun get-writer type +@ref{ical-get-writer} +@end defun + + +@c -------------------------------------------------- + +@c TODO +This chapter will probably in the future be replaced by a proper +system overview in the future. + +@c module (vcomponent control) + +@defmac with-replaced-properties (component (key value) ...) body ... +Through the extent of @var{body} each @var{key}'s value in +@var{component} is replaced by its repspective @var{value}. + +Note that @var{body} is guarded through a dynamic-wind, meaning that +even non-local exits will restore @var{component} to its initial +state. +@end defmac + diff --git a/doc/ref/calp.texi b/doc/ref/calp.texi index b9e8723d..c0a7f3cd 100644 --- a/doc/ref/calp.texi +++ b/doc/ref/calp.texi @@ -64,8 +64,11 @@ text @footnote{Improvements welcome} @c * Index:: @c @end menu -@include guile.texi +@include calp-prime.texi @include entry-points.texi +@include general.texi +@include vcomponent.texi +@include web.texi @include text.texi @include vulgar.texi diff --git a/doc/ref/general.texi b/doc/ref/general.texi new file mode 100644 index 00000000..0b54205a --- /dev/null +++ b/doc/ref/general.texi @@ -0,0 +1,15 @@ +@node Generally Useful Utilities +@chapter Generally Useful Utilities + +@include guile/datetime.texi +@include guile/zic.texi +@include guile/srfi-41.texi +@include guile/util.texi +@include guile/util-path.texi +@include guile/util-config.texi +@include guile/util-exceptions.texi +@include guile/base64.texi +@include guile/xdg-basedir.texi +@include guile/glob.texi +@include guile/graphviz.texi +@include guile/crypto.texi diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi deleted file mode 100644 index 1e8d44fd..00000000 --- a/doc/ref/guile.texi +++ /dev/null @@ -1,193 +0,0 @@ -@node Guile -@chapter Guile - -@include guile/datetime.texi -@include guile/zic.texi -@include guile/srfi-41.texi -@include guile/util.texi -@include guile/util-path.texi -@include guile/util-config.texi -@include guile/util-exceptions.texi -@include guile/base64.texi -@include guile/xdg-basedir.texi -@include guile/web.texi -@include guile/vcomponent.texi -@include guile/translation.texi -@include guile/glob.texi -@include guile/graphviz.texi -@include guile/crypto.texi - -@node Errors and Conditions -@section Errors and Conditions - -@subsection ``Special'' Errors - -@deftp{Error type} return -Thrown in some sub-mains to quickly return from the sub-function. -Should possibly be replaced by an explicit return-continuation. -@end deftp - -@deftp{Error type} warning fmt args -Thrown when @code{warnings-are-errors} is true. - -@ref{warning} for more information. -@end deftp - -@deftp{Error type} max-page page-number -@end deftp - -@subsection ``Regular'' Errors -All below mentioned error types behave as expected, e.g., they are -produced through @code{scm-error}. - -@deftp{Error Type} configuration-error -Thrown by (calp util config), in some scenarios. -@TODO{Better documentation} -@end deftp - -@deftp{Error Type} c-parse-error -Errors thrown by our make-shift C parser. -@end deftp - -@deftp{Error Type} decoding-error -thrown by base64 in some cases -@end deftp - -@deftp{Error Type} parse-error -Thrown by some things related to parsing, but not all. -@TODO{normalize parsing errors further} -@end deftp - -@deftp{Error Type} graph-error -The first element of data is guaranteed to be the graph which caused -the error. -@end deftp - -@deftp{Error Type} missing-helper -A helper program we wanted was missing, could be resolved by somehow -downloading it into one of the searched locations. - -@example -data : (program-name : string) - , (searched-locations : (list string)) -@end example -@end deftp - - - -@node Other -@section Other - -@defun get-parser type -@example -get-parser ∷ type-name → hash-table x string → any -type = 'BINARY | 'BOOLEAN | 'CAL-ADDRES | 'DATE | 'DATE-TIME - | 'DURATION | 'FLOAT | 'INTEGER | 'PERIOD | 'RECUR - | 'TEXT | 'TIME | 'URI | 'UTC-OFFSET -@end example - -@ref{ical-get-writer} -@end defun - -@subsection formats ical -@subsubsection output - -@defun component->ical-string component -@end defun - -@defun print-components-with-fake-parent events -@end defun - -@defun print-all-events -@end defun - -@defun print-events-in-interval start end -@end defun - -@subsubsection parse - -@defun parse-calendar port -@end defun - -@subsubsection types - -@defun escape-chars str -Escape @code{,}, @code{;} and @code{\} with a -backslash, and encode newlines as @code{\n}. -@end defun - -@defun get-writer type -@anchor{ical-get-writer} -@example -get-writer ∷ type-name → hash-table x value → string -type = 'BINARY | 'BOOLEAN | 'CAL-ADDRES | 'DATE | 'DATE-TIME - | 'DURATION | 'FLOAT | 'INTEGER | 'PERIOD | 'RECUR - | 'TEXT | 'TIME | 'URI | 'UTC-OFFSET -@end example -@end defun - -@subsection formats vdir -@subsubsection parse - -@defun parse-vdir path -@end defun - -@subsubsection save-delete - -@defun save-event event -@end defun - -@defun remove-event event -@end defun - -@subsection formats xcal -@subsubsection output - -@defun vcomponent->sxcal component -@end defun - -@defun ns-wrap -@lisp -(define (ns-wrap sxml) - `(icalendar (@@ (xmlns "urn:ietf:params:xml:ns:icalendar-2.0")) - ,sxml)) -@end lisp -Where @var{sxml} is expected to be the output of @var{vcomponent->sxcal}. -@end defun - -@subsubsection parse -@defun sxcal->vcomponent sxcal -Parses a vcomponent in sxcal format. Requires that the vcomponent is -the root of the document (fragment), so wrapping icalendar-tags or -similar @emph{must} be removed. - -@example -(vcalendar - (properties ...) - (components ...)) -@end example -@end defun - -@subsubsection types -@defun get-writer type -@ref{ical-get-writer} -@end defun - - -@c -------------------------------------------------- - -@c TODO -This chapter will probably in the future be replaced by a proper -system overview in the future. - -@c module (vcomponent control) - -@defmac with-replaced-properties (component (key value) ...) body ... -Through the extent of @var{body} each @var{key}'s value in -@var{component} is replaced by its repspective @var{value}. - -Note that @var{body} is guarded through a dynamic-wind, meaning that -even non-local exits will restore @var{component} to its initial -state. -@end defmac - diff --git a/doc/ref/guile/util.texi b/doc/ref/guile/util.texi index e7accf90..d4dce3a6 100644 --- a/doc/ref/guile/util.texi +++ b/doc/ref/guile/util.texi @@ -1,8 +1,5 @@ -@node General Utilities -@section General Utilities - @node Miscellaneous utilities -@subsection Miscellaneous utilities +@section Miscellaneous utilities Provided by the module @code{(hnh util)}. @@ -362,7 +359,7 @@ last. @end defmac @node UUIDs -@subsection UUID generation +@section UUID generation Provided by module @code{(hnh util uuid)}. @@ -380,7 +377,7 @@ this module. Only set this when you want non-random randomness. @end deftp @node IO operations -@subsection IO +@section IO Provided by module @code{(hnh util io)}. @@ -412,7 +409,7 @@ Open file at path, and return its content as a string. @end defun @node Binary Search Tree -@subsection Binary Search Tree +@section Binary Search Tree A simple ``read only'' binary search tree. diff --git a/doc/ref/vcomponent.texi b/doc/ref/vcomponent.texi new file mode 100644 index 00000000..0aa7806c --- /dev/null +++ b/doc/ref/vcomponent.texi @@ -0,0 +1,4 @@ +@node VComponents +@chapter VComponents + +@include guile/vcomponent.texi diff --git a/doc/ref/web.texi b/doc/ref/web.texi new file mode 100644 index 00000000..342b6852 --- /dev/null +++ b/doc/ref/web.texi @@ -0,0 +1,4 @@ +@node Webservers and -Clients +@chapter Webservers and -Clients + +@include guile/web.texi -- cgit v1.2.3 From 108a0454d05c744c4a05e298cfc8cbf157952414 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Tue, 12 Sep 2023 10:23:59 +0200 Subject: Rework file tree structure for info files. --- doc/ref/calp-prime.texi | 177 +-------- doc/ref/general.texi | 27 +- doc/ref/general/base64.texi | 22 ++ doc/ref/general/bst.texi | 37 ++ doc/ref/general/crypto.texi | 17 + doc/ref/general/datetime.texi | 670 +++++++++++++++++++++++++++++++++++ doc/ref/general/glob.texi | 37 ++ doc/ref/general/graphviz.texi | 10 + doc/ref/general/io.texi | 31 ++ doc/ref/general/srfi-41.texi | 100 ++++++ doc/ref/general/util-config.texi | 93 +++++ doc/ref/general/util-exceptions.texi | 40 +++ doc/ref/general/util-path.texi | 62 ++++ doc/ref/general/util.texi | 359 +++++++++++++++++++ doc/ref/general/uuid.texi | 17 + doc/ref/general/xdg-basedir.texi | 62 ++++ doc/ref/general/zic.texi | 135 +++++++ doc/ref/guile/base64.texi | 22 -- doc/ref/guile/crypto.texi | 17 - doc/ref/guile/datetime.texi | 670 ----------------------------------- doc/ref/guile/glob.texi | 37 -- doc/ref/guile/graphviz.texi | 10 - doc/ref/guile/srfi-41.texi | 100 ------ doc/ref/guile/translation.texi | 31 -- doc/ref/guile/util-config.texi | 93 ----- doc/ref/guile/util-exceptions.texi | 40 --- doc/ref/guile/util-path.texi | 62 ---- doc/ref/guile/util.texi | 447 ----------------------- doc/ref/guile/vcomponent.texi | 117 ------ doc/ref/guile/web.texi | 92 ----- doc/ref/guile/xdg-basedir.texi | 62 ---- doc/ref/guile/zic.texi | 135 ------- doc/ref/vcomponent.texi | 115 +++++- doc/ref/vulgar.texi | 238 +------------ doc/ref/vulgar/color.texi | 18 + doc/ref/vulgar/termios.texi | 217 ++++++++++++ doc/ref/web.texi | 2 +- doc/ref/web/web.texi | 92 +++++ 38 files changed, 2154 insertions(+), 2359 deletions(-) create mode 100644 doc/ref/general/base64.texi create mode 100644 doc/ref/general/bst.texi create mode 100644 doc/ref/general/crypto.texi create mode 100644 doc/ref/general/datetime.texi create mode 100644 doc/ref/general/glob.texi create mode 100644 doc/ref/general/graphviz.texi create mode 100644 doc/ref/general/io.texi create mode 100644 doc/ref/general/srfi-41.texi create mode 100644 doc/ref/general/util-config.texi create mode 100644 doc/ref/general/util-exceptions.texi create mode 100644 doc/ref/general/util-path.texi create mode 100644 doc/ref/general/util.texi create mode 100644 doc/ref/general/uuid.texi create mode 100644 doc/ref/general/xdg-basedir.texi create mode 100644 doc/ref/general/zic.texi delete mode 100644 doc/ref/guile/base64.texi delete mode 100644 doc/ref/guile/crypto.texi delete mode 100644 doc/ref/guile/datetime.texi delete mode 100644 doc/ref/guile/glob.texi delete mode 100644 doc/ref/guile/graphviz.texi delete mode 100644 doc/ref/guile/srfi-41.texi delete mode 100644 doc/ref/guile/translation.texi delete mode 100644 doc/ref/guile/util-config.texi delete mode 100644 doc/ref/guile/util-exceptions.texi delete mode 100644 doc/ref/guile/util-path.texi delete mode 100644 doc/ref/guile/util.texi delete mode 100644 doc/ref/guile/vcomponent.texi delete mode 100644 doc/ref/guile/web.texi delete mode 100644 doc/ref/guile/xdg-basedir.texi delete mode 100644 doc/ref/guile/zic.texi create mode 100644 doc/ref/vulgar/color.texi create mode 100644 doc/ref/vulgar/termios.texi create mode 100644 doc/ref/web/web.texi (limited to 'doc/ref') diff --git a/doc/ref/calp-prime.texi b/doc/ref/calp-prime.texi index 89decb1b..a13cbd0b 100644 --- a/doc/ref/calp-prime.texi +++ b/doc/ref/calp-prime.texi @@ -1,179 +1,8 @@ @node Calp as a Program @chapter Calp as a Program -@include guile/translation.texi +@include calp/translation.texi +@include calp/error.texi +@include calp/other.texi -@node Errors and Conditions -@section Errors and Conditions - -@subsection ``Special'' Errors - -@deftp{Error type} return -Thrown in some sub-mains to quickly return from the sub-function. -Should possibly be replaced by an explicit return-continuation. -@end deftp - -@deftp{Error type} warning fmt args -Thrown when @code{warnings-are-errors} is true. - -@ref{warning} for more information. -@end deftp - -@deftp{Error type} max-page page-number -@end deftp - -@subsection ``Regular'' Errors -All below mentioned error types behave as expected, e.g., they are -produced through @code{scm-error}. - -@deftp{Error Type} configuration-error -Thrown by (calp util config), in some scenarios. -@TODO{Better documentation} -@end deftp - -@deftp{Error Type} c-parse-error -Errors thrown by our make-shift C parser. -@end deftp - -@deftp{Error Type} decoding-error -thrown by base64 in some cases -@end deftp - -@deftp{Error Type} parse-error -Thrown by some things related to parsing, but not all. -@TODO{normalize parsing errors further} -@end deftp - -@deftp{Error Type} graph-error -The first element of data is guaranteed to be the graph which caused -the error. -@end deftp - -@deftp{Error Type} missing-helper -A helper program we wanted was missing, could be resolved by somehow -downloading it into one of the searched locations. - -@example -data : (program-name : string) - , (searched-locations : (list string)) -@end example -@end deftp - - - -@node Other -@section Other - -@defun get-parser type -@example -get-parser ∷ type-name → hash-table x string → any -type = 'BINARY | 'BOOLEAN | 'CAL-ADDRES | 'DATE | 'DATE-TIME - | 'DURATION | 'FLOAT | 'INTEGER | 'PERIOD | 'RECUR - | 'TEXT | 'TIME | 'URI | 'UTC-OFFSET -@end example - -@ref{ical-get-writer} -@end defun - -@subsection formats ical -@subsubsection output - -@defun component->ical-string component -@end defun - -@defun print-components-with-fake-parent events -@end defun - -@defun print-all-events -@end defun - -@defun print-events-in-interval start end -@end defun - -@subsubsection parse - -@defun parse-calendar port -@end defun - -@subsubsection types - -@defun escape-chars str -Escape @code{,}, @code{;} and @code{\} with a -backslash, and encode newlines as @code{\n}. -@end defun - -@defun get-writer type -@anchor{ical-get-writer} -@example -get-writer ∷ type-name → hash-table x value → string -type = 'BINARY | 'BOOLEAN | 'CAL-ADDRES | 'DATE | 'DATE-TIME - | 'DURATION | 'FLOAT | 'INTEGER | 'PERIOD | 'RECUR - | 'TEXT | 'TIME | 'URI | 'UTC-OFFSET -@end example -@end defun - -@subsection formats vdir -@subsubsection parse - -@defun parse-vdir path -@end defun - -@subsubsection save-delete - -@defun save-event event -@end defun - -@defun remove-event event -@end defun - -@subsection formats xcal -@subsubsection output - -@defun vcomponent->sxcal component -@end defun - -@defun ns-wrap -@lisp -(define (ns-wrap sxml) - `(icalendar (@@ (xmlns "urn:ietf:params:xml:ns:icalendar-2.0")) - ,sxml)) -@end lisp -Where @var{sxml} is expected to be the output of @var{vcomponent->sxcal}. -@end defun - -@subsubsection parse -@defun sxcal->vcomponent sxcal -Parses a vcomponent in sxcal format. Requires that the vcomponent is -the root of the document (fragment), so wrapping icalendar-tags or -similar @emph{must} be removed. - -@example -(vcalendar - (properties ...) - (components ...)) -@end example -@end defun - -@subsubsection types -@defun get-writer type -@ref{ical-get-writer} -@end defun - - -@c -------------------------------------------------- - -@c TODO -This chapter will probably in the future be replaced by a proper -system overview in the future. - -@c module (vcomponent control) - -@defmac with-replaced-properties (component (key value) ...) body ... -Through the extent of @var{body} each @var{key}'s value in -@var{component} is replaced by its repspective @var{value}. - -Note that @var{body} is guarded through a dynamic-wind, meaning that -even non-local exits will restore @var{component} to its initial -state. -@end defmac diff --git a/doc/ref/general.texi b/doc/ref/general.texi index 0b54205a..be68fca6 100644 --- a/doc/ref/general.texi +++ b/doc/ref/general.texi @@ -1,15 +1,18 @@ @node Generally Useful Utilities @chapter Generally Useful Utilities -@include guile/datetime.texi -@include guile/zic.texi -@include guile/srfi-41.texi -@include guile/util.texi -@include guile/util-path.texi -@include guile/util-config.texi -@include guile/util-exceptions.texi -@include guile/base64.texi -@include guile/xdg-basedir.texi -@include guile/glob.texi -@include guile/graphviz.texi -@include guile/crypto.texi +@include general/datetime.texi +@include general/zic.texi +@include general/srfi-41.texi +@include general/util.texi +@include general/uuid.texi +@include general/io.texi +@include general/bst.texi +@include general/util-path.texi +@include general/util-config.texi +@include general/util-exceptions.texi +@include general/base64.texi +@include general/xdg-basedir.texi +@include general/glob.texi +@include general/graphviz.texi +@include general/crypto.texi diff --git a/doc/ref/general/base64.texi b/doc/ref/general/base64.texi new file mode 100644 index 00000000..ab6bba81 --- /dev/null +++ b/doc/ref/general/base64.texi @@ -0,0 +1,22 @@ +@node Base64 +@section Base64 + +@defun base64->bytevector bv +@defunx bytevector->base64 bv +Base procedure for all Base64 operations. +Takes and returns bytevectors. + +Throws @code{decoding-error} on invalid input. +@end defun + +@defun base64-string->bytevector string +@defunx bytevector->base64-string bv +Base64 side is strings, while data is bytevectors. +@end defun + + +@defun base64encode string [transcoder=(native-transcoder)] +@defunx base64decode string [transcoder=(native-transcoder)] +Highest level Base64 procedures. Both encoded and decoded data is +strings. +@end defun diff --git a/doc/ref/general/bst.texi b/doc/ref/general/bst.texi new file mode 100644 index 00000000..d2bba0ff --- /dev/null +++ b/doc/ref/general/bst.texi @@ -0,0 +1,37 @@ +@node Binary Search Tree +@section Binary Search Tree + +A simple ``read only'' binary search tree. + +@defun make-tree pred? lst +Constructs a new tree. @var{pred?} should be a procedure taking the +first element of @var{lst}, along with each element, and should return +a boolean value indicating if the specific element should go in the +left or right subtree. (left subtree is ``truthy'' values). + +This operation is done recursively. +@end defun + +@defun tree-node tree +Return the value of a tree node. +@end defun + +@defun left-subtree tree +Return all ``truthy'' children of tree node. +@end defun + +@defun right-subtree tree +Return all ``falsy children of tree node. +@end defun + +@defun length-of-longest-branch tree +Get the depth of a tree. +@end defun + +@defun tree-map proc tree +Apply proc onto the value of every node in tree, keeping the structure +of the tree. + +@b{Note:} this can cause the tree to no longer be a binary search +tree, but simply a ``formless'' binary tree. +@end defun diff --git a/doc/ref/general/crypto.texi b/doc/ref/general/crypto.texi new file mode 100644 index 00000000..b9e362d3 --- /dev/null +++ b/doc/ref/general/crypto.texi @@ -0,0 +1,17 @@ +@node Cryptographic and Hash Procedures +@section Cryptographic and Hash Procedures + +This module links libcrypto, exposing some hash procedures. + +@defun sha256 message +Calculate the sha256-sum of @var{message}. The message can either be a +bytevector or a string (in which case it will de encoded as UTF-8). + +Returns the checksum as a bytevector. +@end defun + +@defun checksum->string message-digest [port] +Generates a hex digest string from a checksum (generated by +@code{sha256}). The checksum is written to @var{port} if given, or +returned as a string otherwise. +@end defun diff --git a/doc/ref/general/datetime.texi b/doc/ref/general/datetime.texi new file mode 100644 index 00000000..037ac8d5 --- /dev/null +++ b/doc/ref/general/datetime.texi @@ -0,0 +1,670 @@ +@node Datetime +@section Datetime + +My datetime library, with focus on date manipulation in ways sensible +for humans. So that a date-time plus one day always keep the time of +day. +For example, 26 mars 2022 10:00 plus 1 day would give 27 mars 2022 +10:00, even though 25 hours have passed due to summer time starting +(in Sweden). + +Note that while some of these procedures mentions timezones, almost +nothing is actually done with it. + +@subsection Constants + +@defvar jan +@defvarx january +@defvarx feb +@defvarx february +@defvarx mar +@defvarx mars +@defvarx apr +@defvarx april +@defvarx may +@defvarx jun +@defvarx june +@defvarx jul +@defvarx july +@defvarx aug +@defvarx august +@defvarx sep +@defvarx september +@defvarx oct +@defvarx october +@defvarx nov +@defvarx november +@defvarx dec +@defvarx december +Numeric constants for all months. +@code{@var{jan} = 1}, @code{@var{dec} = 12}. +@end defvar + +@defvar sun +@defvarx sunday +@defvarx mon +@defvarx monday +@defvarx tue +@defvarx tuesday +@defvarx wed +@defvarx wednesday +@defvarx thu +@defvarx thursday +@defvarx fri +@defvarx friday +@defvarx sat +@defvarx saturday +@anchor{sunday} +Numeric constants for all weekdays. +@code{@var{sunday} = 0}, @code{@var{saturday} = 6}. +@end defvar + +@subsection Parameters and Configuration + +@deftp {parameter} week-start +@anchor{week-start} +Which weekday should be considered the first. Used for calculating +week numbers, the start dates of week, and is available for UI-code +and the like which wants it. +@end deftp + +@deftp {config} week-start +Configuration item, updates @xref{week-start}. +@end deftp + + +@subsection Datatypes + +@deftp {Immutable Record} year month day +Object representing a date, without any timezone information. +Given the date 2040-03-23 (in ISO-8601 format), @var{year} = 2020, +@var{month} = 3 and @var{day} = 23. + +Values higher than those usually used are possible, but not recommended. + +@defun date? x +Is @var{x} a date object? +@end defun + +@defun date [#:year=0] [#:month=0] [#:day=0] +Create a new date object. +@end defun + +@defun year +@defunx month +@defunx day +Fetch corresponding field from the date object. +@end defun +@end deftp + +@deftp {Immutable Record}