From a86cabca62bd753e6d6eb66fbb1473b8d2099dec Mon Sep 17 00:00:00 2001 From: Ralph Ronnquist Date: Mon, 17 Apr 2023 00:47:15 +1000 Subject: [PATCH] Added man pages for the archives. --- lsp-dbus.a.8.adoc | 130 ++++++++++++++++++++++++++++++++++++++++++++++ lsp-misc.a.8.adoc | 103 ++++++++++++++++++++++++++++++++++++ 2 files changed, 233 insertions(+) create mode 100644 lsp-dbus.a.8.adoc create mode 100644 lsp-misc.a.8.adoc diff --git a/lsp-dbus.a.8.adoc b/lsp-dbus.a.8.adoc new file mode 100644 index 0000000..1fe8729 --- /dev/null +++ b/lsp-dbus.a.8.adoc @@ -0,0 +1,130 @@ += lsp-dbus.a(8) +:doctype: manpage +:revdate: {sys:date "+%Y-%m-%d %H:%M:%S"} + +== NAME + +lsp-dbus.a - Dbus API for newlisp. + +== SYNOPSIS + +.With packnl +packnl _main.lsp_ *-A lsp-misc.a* *-A lsp-dbus.a* + + +.With incore.lsp +(load "incore.lsp") + +(archive "lsp-misc.a") + +(archive "lsp-utils.a") + +(load "lsp-dbus.lsp") + +== DESCRIPTION + +*lsp-dbus.a* implements a newlisp API for Dbus. The module includes a +context *DbusConnection* implementing the connection/authorization +level and a context *Dbus* that implements the "object modelling" +level. The software is divided into a couple of different source files +that are packed together int a _ar_ archive. It also depends on +foop+ +and +prog1+ from +lsp-misc.a+. + +=== Essential API + +On loading:: + +The main file, +lsp-dbus.lsp+, includes connection setup and client +registration as part of its loading. Currently it connects on the +system bus only. It also installs the funcion +main-loop+ as ++prompt-event+ function for processing any unsolicited messages from +dbus (so called "signals"). + +(Dbus _PATH_ [_DESTINATION_]):: + +The context +Dbus+ is used for identifying remote services which by +default have coinsiding path _PATH_ and _DESTINATION_ (aka bus name). +The resulting FOOP object provides a channel for invoking methods. + +(:invoke _OBJECT_ _METHOD_ _ARGUMENTS_ _FLAGS_):: The +:invoke+ method +performs a Dbus +METHOD_CALL+ handshake for the gven _OBJECT_ using +the given _METHOD_, _ARGUMENTS_and message _FLAGS_, while also polling +s.c. signal messages from Dbus. The _METHOD_ is given as a string +composed as "_path_:_interface_._name_(_signature_)", although the +_path_ and _interface_ parts are optional. If without explicit _path_, +the _OBJECT_ path is used. If without explicit interface, the method +will be looked up across all interfaces of the destination path. ++ +The given _ARGUMENTS_ is a list structure that must correspond to the +given signature. See the MARSHALLING below. ++ +The optional _FLAGS_ is either a bit mask or a list of applicable +method call flags as Dbus symbols. See METHOD_CALL flags below. ++ +.invoke usage examples +(:invoke Dbus:ROOT "RequestName(su)" '("my.client" 0)) ++ +(:invoke Dbus:ROOT "GetNameOwner(s)" '("org.bluez" 0)) ++ +(setf BT (Dbus "/org/bluez")) + +(:invoke BT "/:org.freedesktop.ObjectManager.GetManagedObjects()") + +; Note that "org.bluez" here provides the "GetManagedObjects()" + +; method on the root path, "/", rather than its own path + +; "/org/bluez". ++ +While this process is waiting for the +METHOD_CALL+ reply it may +receive signal messsages from +dbus+. These will be added to the list +of "pending callbacks" that is processed via the +process-all-pending+ +function, either via an explicit call following the handshake or +"automagically" as part of the +main-loop+ function that gets +installed as as +prompt-event+ function. + +(Dbus:process-all-pending):: + +The +process-all-pending+ function processes all pending signal +messages by invoking their associated handler functions. + +(prompt-event Dbus:main-loop):: + +The +main-loop+ function is set up as +prompt-event+ function for a ++net-select+ on both stdin and the dbus socket as well as to process +all pending signal messages. Any input from dbus, which are signal +messages, are added to the pending list, which also is processed one +message at a time until empty. ++ +Note that newlisp uses readline for input but that this is not +activated in +main-loop+. Therefore line editing is not available +immediately. However the operator may use ^D to leave the main-loop +and enter the "normal" command line input state for a single line +input (with line editing), or an initial newline for multi-line input +that is "submitted" by means of two newlines. + +(Dbus:handler _KEY_ _HANDLER_):: This function registers a handler +callback for a key that is a string composed as +"path:interface.member(signature)". The handler function takes a +single argument, which is the list of unmarshalled actual call +arguments. + +=== MARSHALLING + +dbus documentation uses the terms "marshalling" and "unmarshalling" +for the translations of data from/to program data to/from dbus message +bytes. The data in newlisp mapped straight-forwardly with the special +note that both "struct" and "array" are held as lists in newlisp. To +that end, the data for the variant type signature must be wrapped into +an extra list of the format _(signature value)_ with explcit dbus +signature string. However, such wrapping does not take place upon +unmarshalling. + +=== METHOD_CALL FLAGS + +As per dbus documentation, there are three +METHOD_call+ flags: ++Dbus:NO_REPLY_EXPECTED+, +Dbus:NO_AUTO_START+ and ++Dbus:ALLOW_INTERACTIVE_AUTHORIZATION. Each of these correspond to a +bit position in the _FLAGS_ mask and they are combined with bit-OR. +Refer to dbus docuemntation for further details. + +== SEE ALSO + +*newlisp*, *packnl*, *incore.lsp* + +== AUTHOR + +Ralph Ronnquist diff --git a/lsp-misc.a.8.adoc b/lsp-misc.a.8.adoc new file mode 100644 index 0000000..5dd0b04 --- /dev/null +++ b/lsp-misc.a.8.adoc @@ -0,0 +1,103 @@ += lsp-misc.a(8) +:doctype: manpage +:revdate: {sys:date "+%Y-%m-%d %H:%M:%S"} + +== NAME + +lsp-misc.a - Misceallaneous useful functions. + +== SYNOPSIS + +.With packnl (example) +packnl _main.lsp_ *-A lsp-misc.a* + + +.With incore.lsp +(load "incore.lsp") + +(archive "lsp-misc.a") + +(load "misc.lsp") + +== DESCRIPTION + +*lsp-misc.a* provides a few global utility functions. + +=== misc.lsp API + +(prog1 [_term_]*):: + +The *prog1* function is like a *begin* function except that it returns +the value of the first term rather than the last. + +(die [_N_ [_term_]]):: + +The *die* function printes to stderr the join of term values as +strings with space separation, and if _N_ is a number, then the +function exits the program with that return code. ++ +.Example of stderr logging +(die nil 'This "is" 'printed "to stderr") + +(octal-byte _B_):: +Print binary byte as octal or as ASCII character [32-126]. + +(octals-string _S_):: +Print string as a succesion of +octal-byte+. + +(human-byte _B_):: +Return byte code as printable (string) or as code (number). + +(human-bytes _BL_):: + +Return a list of human-byte elements from a list of byte codes but +also joining consecutive string elements to form packed strings. + +=== foop.lsp API + +This newlisp module provides Functional Object-Oriented Programming +(FOOP) modelling support. + +FOOP is an abstraction overlay using the newlisp context notion as a +simile to the _class_ notion in genuine object-oriented programming +languages. This is set out in newlisp by means of the representation +principle that an instance of a FOOP "class" (i.e. context) is a list +headed by the context itself, and followed by the "member values". + +FOOP further includes by the "method invocation" syntax where a +function is preceded by ':' and then followed by the instance +concerned before actual function arguments. That instance is then +stoved away as implicitly available via the (self) function, and the +member values accessible via index, e.g. the term (self 3) refers to +the third member of the instance. The self references are +destructively assignable with setf. + +This modelling support adds member name declaration together with +automatic getter and setter defintions. The (FOOP ...) term is used +for declaring member names in order. For example: + +(FOOP [_name_]):: + +*FOOP* is like a language extension to declare the field names of a +FOOP class, and thereby gain "get" and "set" functions generated with +the respective naming formats (:%name obj) and (:!name obj value). + +.illustration +---- +(context 'MAIN:EX) +(FOOP here there more) +(define (EX HERE THERE MORE) (list (context) HERE THERE MORE)) + +(context MAIN) +(setf A (EX 1 2 3)) +--> A = (EX 1 2 3) +(:!there A 4) +--> A = (EX 1 4 3) +---- + + +== SEE ALSO + +*newlisp* + +== AUTHOR + +Ralph Ronnquist -- 2.39.2