From: Ralph Ronnquist Date: Thu, 27 Apr 2023 09:59:33 +0000 (+1000) Subject: recovered X-Git-Url: https://git.rrq.au/?a=commitdiff_plain;h=HEAD;p=rrq%2Flsp-utils.git recovered --- diff --git a/lsp-misc/lsp-misc.a.8.adoc b/lsp-misc/lsp-misc.a.8.adoc index 670af48..7f8a5d0 100644 --- a/lsp-misc/lsp-misc.a.8.adoc +++ b/lsp-misc/lsp-misc.a.8.adoc @@ -1 +1,138 @@ -== lsp-misc.a(8) += 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