+++ /dev/null
-= lsp-dbus.a(8)
-:doctype: manpage
-:revdate: {sys:date "+%Y-%m-%d %H:%M:%S"}
-:BC: *:*
-
-== 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_ that implements the connection/authorization
-level and a context _Dbus_ that implements the "object
-modelling"/messaging level.
-
-The source software is divided into a couple of different source files
-that are packed together into an _ar_ archive.
-
-Note that *lsp-dbus.a* depends on _FOOP_ and _prog1_ from *lsp-misc.a*.
-
-=== lsp-dbus API
-
-(*load* "lsp-dbus.lsp")::
-
-The main file, *lsp-dbus.lsp*, includes connection setup (see
-*:initialize* below) and client registration (i.e. issuing the dbus
-"Hello():s" message 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").
-
-==== The Dbus Context
-
-(*Dbus* _PATH_ [_DESTINATION_])::
-
-The _Dbus_ context is used for identifying remote "objects" with the
-given _PATH_ and _DESTINATION_ (aka bus name). The resulting _FOOP_
-object provides a proxying channel for invoking methods targeting the
-given path on the given bus-name application. When omitted, the
-_DESTINATION_ string is obtained from the _PATH_ string following the
-convention of chopping the initial "/" and replacing remaining "/"
-with ".".
-+
-====
-Note that a term like _(Dbus "/org/freedesktop/DBus")_ defines an
-identifer for, or pointer to, a remote "dbus object", and it is here
-referred to as _PROXY_. The _PATH_ part serves as the object
-identifier for dbus while the _DESTINATION_ part is an identfier for
-the application that we expect holds the actual "dbus object" for the
-given _PATH_. This particular term identifies object path
-"/org/freedesktop/DBus" held by the application named
-"org.freedesktop.DBus", which belongs to the dbus framewok.
-
-There is however no central arbitration for paths in dbus. It all
-relies on application developers documenting which paths their
-applications service and access, and then client applications rely on
-using the destination tags for directing their messages to the
-intended applications.
-====
-
-(*:new-path* _PROXY_ _PATH_)::
-
-The _:new-path_ method clones the FOOP object to dentify the given
-_PATH_ for the same destination.
-
-(*:invoke* _PROXY_ _METHOD_ _ARGUMENTS_ _FLAGS_)::
-
-The _:invoke_ method performs a Dbus _METHOD_CALL_ handshake for the
-gven _PROXY_ using the given _METHOD_, _ARGUMENTS_ and message
-_FLAGS_. The function sends a dbus message and then polls for debus
-messages until the reply message has arrived. any and all other
-messages recevied meanwhile are added to the _pending_ list.
-+
-The _METHOD_ is given as a string composed as path, interface, name
-and signature
-+
-====
-_path:interface.name(signature)_
-====
-+
-The _path:_ component including the colon is optional and taken from
-the _PROXY_ by default. The _interface._ component incuding the period
-is also optional as per dbus documentation: a method call without
-explicit interface results in that the method name is looked up across
-all interfaces of the destination path.
-+
-The _SIGNATURE_ is the dbus style signature as a character sequence,
-where y, b, n, q, i, u, x, t, d and h indicate the basic types BYTE,
-BOOLEAN, INT16, UINT16, INT32, UINT32, INT64, UINT64, DOUBLE and FD
-respectivly (both BOOLEAN and FD are also UINT32); a indicates
-"array"; s, o and g indicate strings of various restrictions;
-parentheses and curly braces wrap "struct" signatures, and v indicates
-a pair of a data item preceded by its signature. Refer to dbus
-documentation for further details.
-+
-The given _ARGUMENTS_ is a list structure that must correspond to the
-given signature. All number and string values are mapped naturally
-into the indicated signatures while arrays, struct and variant
-elements should occur as lists: an array is formed from the list of
-elements, as is a struct. A variant typed element must occur as the
-list of signature and data. See also the MARSHALLING section below.
-+
-The optional _FLAGS_ argument is given either a bit mask (number) or a
-list of the _Dbus_ context symbols _NO_REPLY_EXPECTED_,
-_NO_AUTO_START_ and _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 documentation for further details.
-+
-.Some :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 "GetManagedObjects()")
-(Dbus:process-pending)
-----
-+
-Note "org.bluez" here provides the "GetManagedObjects()" method of
-interface "org.freedesktop.ObjectManager" unambiguously on the root
-path, "/", rather than its bus name 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.
-+
-.Return value:
-[caption=""]
-====
-The return value of *:invoke* is the METHOD_REPLY message reduced into
-an association list of the headers (with the _Dbus_ header symbols as
-keys) extended with the method return value as a list wrapped into a
-final association that is keyed by the empty string.
-
-In other words, the template for using *:invoke* may look like the
-following:
-----
-(if (:invoke ...) ($it -1 -1 -1))
-----
-====
-
-(*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
-combined _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.
-
-(*:handler* _OBJ_ _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.
-
-==== The DbusConnection Context
-
-(*DbusConnection* _PATH)::
-
-The _DbusConnection_ context is a FOOP implementation intended for the
-dbus socket connection. Each _(DbusConnection PATH)_ is intended to be
-like a real object that contains state, namely the opened socket file
-descriptor, the connection name given to it by DBus on connection and
-and the messaging serial.
-
-(*:serial++* _OBJECT_)::
-
-This method increments the serial of the given object.
-
-(*:open-socket* _OBJECT_)::
-
-This method opens the path and assignes the socket file descriptor of
-the given object. Before that though, if the socket file descriptor is
-non-negative then that file descriptor is closed before opening the
-object's path.
-
-(*:read-message* _OBJECT_)::
-
-This method reads the next message by reading data from the socket
-successively while there's something to read within a millisecond.
-
-(*:handshake* _OBJECT_ _MESSAGE_ [_PATTERN_])::
-
-This method performs a "raw" text-based handshake on the connection,
-which means to send the given message and then read and return the
-response message. If a _PATTERN_ is given, then the response must
-match the pattern (assigning the automatic variables $1 etc according
-to the pattern). The method returns nil if the given pattern is not
-matched. Note that this method is used only during connection setup
-and dbus communication uses its own marshalling subsequently.
-
-(*:initialize* _OBJECT_ [_USER_])::
-
-This method performs the connection set up including the very first
-newline and the subsequent AUTH handshake. It ends with the connection
-in "BEGIN" mode and returns the received connection name.
-
-=== 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.
-
-
-== SEE ALSO
-
-*newlisp*, *packnl*, *incore.lsp*
-
-== AUTHOR
-
-Ralph Ronnquist <ralph.ronnquist@gmail.com>
--- /dev/null
+= lsp-dbus.a(8)
+:doctype: manpage
+:revdate: {sys:date "+%Y-%m-%d %H:%M:%S"}
+:BC: *:*
+
+== 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_ that implements the connection/authorization
+level and a context _Dbus_ that implements the "object
+modelling"/messaging level.
+
+The source software is divided into a couple of different source files
+that are packed together into an _ar_ archive.
+
+Note that *lsp-dbus.a* depends on _FOOP_ and _prog1_ from *lsp-misc.a*.
+
+=== lsp-dbus API
+
+(*load* "lsp-dbus.lsp")::
+
+The main file, *lsp-dbus.lsp*, includes connection setup (see
+*:initialize* below) and client registration (i.e. issuing the dbus
+"Hello():s" message 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").
+
+==== The Dbus Context
+
+(*Dbus* _PATH_ [_DESTINATION_])::
+
+The _Dbus_ context is used for identifying remote "objects" with the
+given _PATH_ and _DESTINATION_ (aka bus name). The resulting _FOOP_
+object provides a proxying channel for invoking methods targeting the
+given path on the given bus-name application. When omitted, the
+_DESTINATION_ string is obtained from the _PATH_ string following the
+convention of chopping the initial "/" and replacing remaining "/"
+with ".".
++
+====
+Note that a term like _(Dbus "/org/freedesktop/DBus")_ defines an
+identifer for, or pointer to, a remote "dbus object", and it is here
+referred to as _PROXY_. The _PATH_ part serves as the object
+identifier for dbus while the _DESTINATION_ part is an identfier for
+the application that we expect holds the actual "dbus object" for the
+given _PATH_. This particular term identifies object path
+"/org/freedesktop/DBus" held by the application named
+"org.freedesktop.DBus", which belongs to the dbus framewok.
+
+There is however no central arbitration for paths in dbus. It all
+relies on application developers documenting which paths their
+applications service and access, and then client applications rely on
+using the destination tags for directing their messages to the
+intended applications.
+====
+
+(*:new-path* _PROXY_ _PATH_)::
+
+The _:new-path_ method clones the FOOP object to dentify the given
+_PATH_ for the same destination.
+
+(*:invoke* _PROXY_ _METHOD_ _ARGUMENTS_ _FLAGS_)::
+
+The _:invoke_ method performs a Dbus _METHOD_CALL_ handshake for the
+gven _PROXY_ using the given _METHOD_, _ARGUMENTS_ and message
+_FLAGS_. The function sends a dbus message and then polls for debus
+messages until the reply message has arrived. any and all other
+messages recevied meanwhile are added to the _pending_ list.
++
+The _METHOD_ is given as a string composed as path, interface, name
+and signature
++
+====
+_path:interface.name(signature)_
+====
++
+The _path:_ component including the colon is optional and taken from
+the _PROXY_ by default. The _interface._ component incuding the period
+is also optional as per dbus documentation: a method call without
+explicit interface results in that the method name is looked up across
+all interfaces of the destination path.
++
+The _SIGNATURE_ is the dbus style signature as a character sequence,
+where y, b, n, q, i, u, x, t, d and h indicate the basic types BYTE,
+BOOLEAN, INT16, UINT16, INT32, UINT32, INT64, UINT64, DOUBLE and FD
+respectivly (both BOOLEAN and FD are also UINT32); a indicates
+"array"; s, o and g indicate strings of various restrictions;
+parentheses and curly braces wrap "struct" signatures, and v indicates
+a pair of a data item preceded by its signature. Refer to dbus
+documentation for further details.
++
+The given _ARGUMENTS_ is a list structure that must correspond to the
+given signature. All number and string values are mapped naturally
+into the indicated signatures while arrays, struct and variant
+elements should occur as lists: an array is formed from the list of
+elements, as is a struct. A variant typed element must occur as the
+list of signature and data. See also the MARSHALLING section below.
++
+The optional _FLAGS_ argument is given either a bit mask (number) or a
+list of the _Dbus_ context symbols _NO_REPLY_EXPECTED_,
+_NO_AUTO_START_ and _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 documentation for further details.
++
+.Some :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 "GetManagedObjects()")
+(Dbus:process-pending)
+----
++
+Note "org.bluez" here provides the "GetManagedObjects()" method of
+interface "org.freedesktop.ObjectManager" unambiguously on the root
+path, "/", rather than its bus name 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.
++
+.Return value:
+[caption=""]
+====
+The return value of *:invoke* is the METHOD_REPLY message reduced into
+an association list of the headers (with the _Dbus_ header symbols as
+keys) extended with the method return value as a list wrapped into a
+final association that is keyed by the empty string.
+
+In other words, the template for using *:invoke* may look like the
+following:
+----
+(if (:invoke ...) ($it -1 -1 -1))
+----
+====
+
+(*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
+combined _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.
+
+(*:handler* _OBJ_ _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.
+
+==== The DbusConnection Context
+
+(*DbusConnection* _PATH)::
+
+The _DbusConnection_ context is a FOOP implementation intended for the
+dbus socket connection. Each _(DbusConnection PATH)_ is intended to be
+like a real object that contains state, namely the opened socket file
+descriptor, the connection name given to it by DBus on connection and
+and the messaging serial.
+
+(*:serial++* _OBJECT_)::
+
+This method increments the serial of the given object.
+
+(*:open-socket* _OBJECT_)::
+
+This method opens the path and assignes the socket file descriptor of
+the given object. Before that though, if the socket file descriptor is
+non-negative then that file descriptor is closed before opening the
+object's path.
+
+(*:read-message* _OBJECT_)::
+
+This method reads the next message by reading data from the socket
+successively while there's something to read within a millisecond.
+
+(*:handshake* _OBJECT_ _MESSAGE_ [_PATTERN_])::
+
+This method performs a "raw" text-based handshake on the connection,
+which means to send the given message and then read and return the
+response message. If a _PATTERN_ is given, then the response must
+match the pattern (assigning the automatic variables $1 etc according
+to the pattern). The method returns nil if the given pattern is not
+matched. Note that this method is used only during connection setup
+and dbus communication uses its own marshalling subsequently.
+
+(*:initialize* _OBJECT_ [_USER_])::
+
+This method performs the connection set up including the very first
+newline and the subsequent AUTH handshake. It ends with the connection
+in "BEGIN" mode and returns the received connection name.
+
+=== 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.
+
+
+== SEE ALSO
+
+*newlisp*, *packnl*, *incore.lsp*
+
+== AUTHOR
+
+Ralph Ronnquist <ralph.ronnquist@gmail.com>
+++ /dev/null
-= 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)
-----
-
-=== mmap.lsp API
-
-This newlisp module implements a small FOOP model based memory mapping
-API that links in the _libc6_ functions _mmap_, _munmap_, _msync_ and
-_lseek_.
-
-(*MMap* _FD_ _LENGTH_ [_OFFSET_ [_PROT_]])::
-
-This function creates a FOOP object that represents the memory mapping
-of the given file descriptor. _FD_ may be the pathname string of a
-file to memory map or an already opened file descriptor. The MMap
-object represents the memory block starting at (:%base) and (%len)
-bytes in length where the file is memory mapped.
-+
-.Access example (from test.lsp)
-[caption=""]
-----
-(println (setf X (MMap "mmap.lsp")))
-(println (get-string (:%base X)))
-----
-+
-Note that only a plain text file would be accessed with _get-string_.
-A binary file would rather be accessed with _unpack_. The memory
-mapping provides read-only "random access" to the file content.
-+
-To set up read-write acces requires an _OFFSET_ and the _PROT_
-argument 0x3, and writing should be accompanied by _MMap:msync_ calls
-so as to synchronize with the backing file.
-+
-The FOOP object includes get and set methods for the fields (in
-order): _base_, _len_, _prot_, _flags_, _fd_ and _offset_.
-
-=== test.lsp
-
-This file is a small test of the MMap memory mapping.
-
-== SEE ALSO
-
-*newlisp*
-
-== AUTHOR
-
-Ralph Ronnquist <ralph.ronnquist@gmail.com>
--- /dev/null
+= 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)
+----
+
+=== mmap.lsp API
+
+This newlisp module implements a small FOOP model based memory mapping
+API that links in the _libc6_ functions _mmap_, _munmap_, _msync_ and
+_lseek_.
+
+(*MMap* _FD_ _LENGTH_ [_OFFSET_ [_PROT_]])::
+
+This function creates a FOOP object that represents the memory mapping
+of the given file descriptor. _FD_ may be the pathname string of a
+file to memory map or an already opened file descriptor. The MMap
+object represents the memory block starting at (:%base) and (%len)
+bytes in length where the file is memory mapped.
++
+.Access example (from test.lsp)
+[caption=""]
+----
+(println (setf X (MMap "mmap.lsp")))
+(println (get-string (:%base X)))
+----
++
+Note that only a plain text file would be accessed with _get-string_.
+A binary file would rather be accessed with _unpack_. The memory
+mapping provides read-only "random access" to the file content.
++
+To set up read-write acces requires an _OFFSET_ and the _PROT_
+argument 0x3, and writing should be accompanied by _MMap:msync_ calls
+so as to synchronize with the backing file.
++
+The FOOP object includes get and set methods for the fields (in
+order): _base_, _len_, _prot_, _flags_, _fd_ and _offset_.
+
+=== test.lsp
+
+This file is a small test of the MMap memory mapping.
+
+== SEE ALSO
+
+*newlisp*
+
+== AUTHOR
+
+Ralph Ronnquist <ralph.ronnquist@gmail.com>
projects / rrq / lsp-utils.git / commitdiff