newlisp-libmisc.a.8.adoc

   1 = newlisp-libmisc.a(8)
   2 :doctype: manpage
   3 :revdate: {sys:date "+%Y-%m-%d %H:%M:%S"}
   4
   5 == NAME
   6
   7 newlisp-libmisc.a - Newlisp archive comprosing useful functions.
   8
   9 == SYNOPSIS
  10
  11 .With packnl (example)
  12 packnl _main.lsp_ *-A newlisp-libmisc.a*
  13
  14
  15 .With incore.lsp
  16 (load "incore.lsp") +
  17 (archive "newlisp-libmisc.a") +
  18 (load "misc.lsp")
  19
  20 == DESCRIPTION
  21
  22 *newlisp-libmisc.a* is a newlisp archive file that provides loadable
  23 modules with utility functions.
  24
  25 === misc.lsp API
  26
  27 (prog1 [_term_]*)::
  28
  29 The *prog1* function is like a *begin* function except that it returns
  30 the value of the first term rather than the last.
  31
  32 (die _N_ [_term_]*)::
  33
  34 The *die* function printes to stderr the join of term values as
  35 strings with space separation, and if _N_ is a number, then the
  36 function exits the program with that return code.
  37 +
  38 .Example of stderr logging
  39 (die nil 'This "is" 'printed "to stderr")
  40
  41 (octal-byte _B_)::
  42 Print binary byte as octal or as ASCII character [32-126].
  43
  44 (octals-string _S_)::
  45 Print string as a succesion of +octal-byte+.
  46
  47 (human-byte _B_)::
  48 Return byte code as printable (string) or as code (number).
  49
  50 (human-bytes _BL_)::
  51
  52 Return a list of human-byte elements from a list of byte codes but
  53 also joining consecutive string elements to form packed strings.
  54
  55 === foop.lsp API
  56
  57 This newlisp module provides Functional Object-Oriented Programming
  58 (FOOP) modelling support.
  59
  60 FOOP is an abstraction overlay using the newlisp context notion as a
  61 simile to the _class_ notion in genuine object-oriented programming
  62 languages. This is set out in newlisp by means of the representation
  63 principle that an instance of a FOOP "class" (i.e. context) is a list
  64 headed by the context itself, and followed by the "member values".
  65
  66 FOOP further includes by the "method invocation" syntax where a
  67 function is preceded by ':' and then followed by the instance
  68 concerned before actual function arguments. That instance is then
  69 stoved away as implicitly available via the (self) function, and the
  70 member values accessible via index, e.g. the term (self 3) refers to
  71 the third member of the instance. The self references are
  72 destructively assignable with setf.
  73
  74 This modelling support adds member name declaration together with
  75 automatic getter and setter defintions. The (FOOP ...) term is used
  76 for declaring member names in order. For example:
  77
  78 (FOOP [_name_])::
  79
  80 *FOOP* is like a language extension to declare the field names of a
  81 FOOP class, and thereby gain "get" and "set" functions generated with
  82 the respective naming formats (:%name obj) and (:!name obj value).
  83
  84 .illustration
  85 ----
  86 (context 'MAIN:EX)
  87 (FOOP here there more)
  88 (define (EX HERE THERE MORE) (list (context) HERE THERE MORE))
  89
  90 (context MAIN)
  91 (setf A (EX 1 2 3))
  92 --> A = (EX 1 2 3)
  93 (:!there A 4)
  94 --> A = (EX 1 4 3)
  95 ----
  96
  97 === mmap.lsp API
  98
  99 This newlisp module implements a small FOOP model based memory mapping
 100 API that links in the _libc6_ functions _mmap_, _munmap_, _msync_ and
 101 _lseek_.
 102
 103 (*MMap* _FD_ _LENGTH_ [_OFFSET_ [_PROT_]])::
 104
 105 This function creates a FOOP object that represents the memory mapping
 106 of the given file descriptor. _FD_ may be the pathname string of a
 107 file to memory map or an already opened file descriptor. The MMap
 108 object represents the memory block starting at (:%base) and (%len)
 109 bytes in length where the file is memory mapped.
 110 +
 111 .Access example (from test.lsp)
 112 [caption=""]
 113 ----
 114 (println (setf X (MMap "mmap.lsp")))
 115 (println (get-string (:%base X)))
 116 ----
 117 +
 118 Note that only a plain text file would be accessed with _get-string_.
 119 A binary file would rather be accessed with _unpack_. The memory
 120 mapping provides read-only "random access" to the file content.
 121 +
 122 To set up read-write acces requires an _OFFSET_ and the _PROT_
 123 argument 0x3, and writing should be accompanied by _MMap:msync_ calls
 124 so as to synchronize with the backing file.
 125 +
 126 The FOOP object includes get and set methods for the fields (in
 127 order): _base_, _len_, _prot_, _flags_, _fd_ and _offset_.
 128
 129 === test.lsp
 130
 131 This file is a small test of the MMap memory mapping.
 132
 133 == SEE ALSO
 134
 135 *newlisp*
 136
 137 == AUTHOR
 138
 139 Ralph Ronnquist <ralph.ronnquist@gmail.com>