X-Git-Url: https://git.rrq.au/?a=blobdiff_plain;f=lsp-misc%2Flsp-misc.a.8.adoc;h=670af48400e1540c8f2659e01cad0d1ca3beab41;hb=12b8b31df1918875f91a1830743a23004f373466;hp=7f8a5d05c4257a1db4d02a671f56ebdfb4a5c646;hpb=d7e334fda533e0de8cf5bd9f585e7125cb33eb92;p=rrq%2Flsp-utils.git diff --git a/lsp-misc/lsp-misc.a.8.adoc b/lsp-misc/lsp-misc.a.8.adoc index 7f8a5d0..670af48 100644 --- a/lsp-misc/lsp-misc.a.8.adoc +++ b/lsp-misc/lsp-misc.a.8.adoc @@ -1,138 +1 @@ -= 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 +== lsp-misc.a(8)