README

Changes
=======

All bugs introduced are mine.

This picoLisp fork can be built in 32bit/64bit mode and pil32 has all the
documented features of pil64: namespaces, native C calls, coroutines,
destructuring bind in let, list target in put and =: The external symbols
and the database format follows the pil32 tradition.

So where you see in the documentation "64bit-only", you can try out the
examples. They should work.

Implemented the documented pil21 functions.

How to run Mike Pechkin's (https://git.envs.net/mpech/pil21-tests) ?
Execute 'select_pil pil21' in the lib directory of the distribution. This
selects the pil21 versions of frac.l,simul.l and svg.l.

Note, to call a C function with variable number of arguments, the number of
fixed arguments must be marked with ..., eg:

     (native "@" "printf" "abc%d%s^J" ... 7 "XYZ")

The arguments before ... are the fixed arguments, the number of arguments
after the ... are variable. This change is due to the native C call
implementation which uses libffi.

To skip call, just assign handle and pointer, use:

     (native "@" "cos" . T)



What is included?

From Pil21:
   %~
   (tty . prg) -> any
   (enum 'var 'cnt ['cnt ..]) -> lst
   (enum 'var) -> lst
   (enum? 'lst 'cnt ['cnt ..]) -> lst | NIL
   (fish 'fun 'any ['any2]) -> lst
   (rev 'cnt1 'cnt2) -> cnt
   (shift 'var) -> any
   *Term
   (co ['sym [.prg]]) -> any
   (stack ['cnt] ['cnt]) -> cnt | (.. (sym . cnt) . cnt)
   (buf sym 'cnt . prg) -> any
   (history ['lst]) -> lst
   (intern 'sym ['nsp]) -> sym
   (plio 'num) -> any
   (plio 'num 'cnt 'any) -> cnt
   (with 'var . prg) -> any
   (%@ 'cnt|sym 'any 'any ..) -> any

From Pil64:
   Coroutines
      (co 'sym [. prg]) -> any
      (stack ['cnt]) -> cnt | (.. sym . cnt)
      (yield 'any ['sym]) -> any

   Database
      (blk fd cnt siz [fd2]) -> lst
      (blk fd 0) -> (cnt . siz)
      (pool2 'sym . prg) -> any

   Debug
      (bt ['flg]) -> flg
      (trail ['flg]) -> lst
      (up [cnt] sym ['val]) -> any

   Misc
      *CPU
      (byte 'num ['cnt]) -> cnt
      (errno) -> cnt
      (gc ['cnt [cnt2]) -> cnt | NIL
      *Tstp1, *Tstp2
      (let (lst 'any ...) . prg) -> any
         destructuring bind
      (put ..)
      (=: ...)
         final destination as list

   Namespaces
      (nsp 'sym) -> sym
      pico
      (symbols) -> lst
      (symbols 'lst) -> lst
      (symbols 'lst . prg) -> any
      (symbols 'sym1 'sym2 ..) -> lst
      (intern 'sym ['flg]) -> sym
      (all ['T | '0 | 'sym]) -> lst

   Native C Call
      (native 'cnt1|sym1 'cnt2|sym2 'any 'any ..) -> any
      (lisp 'sym ['fun]) -> num
      (struct 'num 'any 'any ..) -> any
      long lisp(char*,long,long,long,long,long);


* '~' reader macro splice atoms too, '^' in fill modified as well
* added 'tty', '%~' reader macro
* replaced (model) in rcsim.l with the pil21 version by Alexander Burger
  misc/rcsim.l works as expected
* added 'enum' and 'enum?', pil21-tests: passed sym.l and turing.l
* fixed 32bit 'struct'
* unwind restores tgt coroutine env
* clear *Bye and *Run in children
* added 'shift','rev' functions, optional skip item to 'fish'
* '*Term' to handle SIGTERM, 'plio' preserves Ptr and End, (co) returns tag
  of current coroutine
* pil21-tests: 'enum' not supported (yet), fixed 'native'/'struct' bugs,
  fixed nested 'co'/'yield' calls, advent2015 requires '(gc 256)',
  fixed interned msg send
* Android: dummy ucontext functions, 'co'/'stack'/'yield' not available
* enabled 'tzo' on macOS
* on CentOS 7 coroStkFree() returns 0
* fixed symToNum(), misc/bigtest passed
* macOS only SHA1 test in struct.l
* bin/pil script changed to reference /usr/local/bin instead of /usr/bin
* (stack) return coroutine tags and unused space (Pil21)
* map functions accept atomic arguments
* 'select_pil' script in lib/ to select either Pil21 versions of
  frac.l and simul.l
* 'prove' fails if using checked arithmetic
  (tankf33der's pil21-tests pilog-rosettacode.l)
* bignum subtract fixed
  (tankf33der's pil21-tests fern.l test)
* lists of symbols as function parameters (destructuring, one-dimensional)
* 'native' (T . any) direct Lisp argument
* 'native'/'struct' result specifications: 'W', 'P', and 'T'
* changed native to call vararg fns
* 'plio' function
* 'buf' function
* 'intern' accepts namespace argument
* 'history' function for lib/(e)led.l
* 'file' returns NIL instead of "./"
* 'with' accepts 'var' instead of 'sym'
* '%@' function for the common case (native "@" ...)
* 'W' and 'P' result specs for 'native' and 'struct'
* 'adr' returns a pointer usable by 'native' and 'struct'
* 'info' returns the file argument in '@@'
* path names expand "~" for the HOME directory
* '*Winch' global SIGWINCH handler
* 'mix' accepts also negative arguments

* automatically translate shared lib names from Linux ".so" to macOS ".dylib"
  eg. when (native) references "libcrypto.so" on macOS it is translated to
  "libcrypto.dylib"
* modified (bench) to return the number of garbage collections and pairs consed
* added (gcccount): returns the number of garbage collections since last called
* added (consed): returns the number of pairs consed since last called
* applied 20.6 changes
* fixed coroutine issues, all tankf33der tests passed
* tankf33der ping-pong.l works, pil64 core dumps ;)
* added lst target in put and =:
* fixed coroutine issues, tankf33der tests are running, except advent2019
* added coroutines co,yield,stack
* fixed float/double scaling in native calls
* fixed float/double result/argument type decoding, both 32bit/64bit target uses
  lib/math64.l (ie. native calls)
* fixed 32bit libffi native C calls
* native C calls thru libffi float/double return values/arguments supported
* added native, struct, lisp (callbacks), and external lisp() call
  float/double return values/arguments in native calls not supported (yet)
* reduced overhead of nested Apply and exe tracking in bindFrame
* can be used to regenerate pil21 sources
* fixed up to return any call, load to preserve namespace, nested Apply
* fixed 64bit seed/rand to match pil64
* added destructuring bind in let, fixed trail, modified gc
* added trail, modified up, bt now works
* fixed namespace deallocation in 32bit target
* added nsp, pico, symbols, %CPU, modified all, intern
* added pool2
* added byte, *Tstp1, *Tstp2
* added errno, blk, lib/dbgc.l runs
* passed misc/bigtest
* pil 64bit target uses the same short/bigNum fmt as pil64, the 32bit target 
  supports shortNums
* added gcc -O3 target, run with pilx
* fixed SIGSEGV on UTF-8 character tables
* added build scripts m and m32 in src/ dir
* pil supports short numbers in 32bit/64bit versions
* pil default target is 64bit, build the 32bit version with "make target=pil32"
  seed and rand is not compatible with 32bit build.
  The 64bit version passes the picoLisp tests except the seed and rand tests,
  and passes tankf33der's huge.l
* set the stack size to the allowed maximum, when cannot be set to unlimited
* the 64bit emu version could be compiled on macOS
* the 32bit version could be compiled with clang on macOS

pahihu 5 / 15 / 2020




02nov17abu
(c) Software Lab. Alexander Burger

                                                          Perfection is attained
                                           not when there is nothing left to add
                                     but when there is nothing left to take away
                                                     (Antoine de Saint-Exupery)
         The PicoLisp System
         ===================

     _PI_co Lisp is not _CO_mmon Lisp

PicoLisp can be viewed from two different aspects: As a general purpose
programming language, and a dedicated application server framework.


(1) As a programming language, PicoLisp provides a 1-to-1 mapping of a clean
and powerful Lisp derivate, to a simple and efficient virtual machine. It
supports persistent objects as a first class data type, resulting in a database
system of Entity/Relation classes and a Prolog-like query language tightly
integrated into the system.

The virtual machine was designed to be
   Simple
      The internal data structure should be as simple as possible. Only one
      single data structure is used to build all higher level constructs.
   Unlimited
      There are no limits imposed upon the language due to limitations of the
      virtual machine architecture. That is, there is no upper bound in symbol
      name length, number digit counts, or data structure and buffer sizes,
      except for the total memory size of the host machine.
   Dynamic
      Behavior should be as dynamic as possible ("run"-time vs. "compile"-time).
      All decisions are delayed till runtime where possible. This involves
      matters like memory management, dynamic symbol binding, and late method
      binding.
   Practical
      PicoLisp is not just a toy of theoretical value. PicoLisp is used since
      1988 in actual application development, research and production.

The language inherits the major advantages of classical Lisp systems like
   - Dynamic data types and structures
   - Formal equivalence of code and data
   - Functional programming style
   - An interactive environment

PicoLisp is very different from any other Lisp dialect. This is partly due to
the above design principles, and partly due to its long development history
since 1984.

You can download the latest release version at http://software-lab.de/down.html


(2) As an application server framework, PicoLisp provides for
   NoSQL Database Management
      Index trees
      Object local indexes
      Entity/Relation classes
      Pilog (PicoLisp Prolog) queries
      Multi-user synchronization
      DB Garbage collection
      Journaling, Replication
   User Interface
      Browser GUI
      (X)HTML/CSS
      XMLHttpRequest/JavaScript
   Application Server
      Process management
      Process family communication
      XML I/O
      Import/export
      User administration
      Internationalization
      Security
      Object linkage
      Postscript/Printing

PicoLisp is not an IDE. All program development in Software Lab. is done using
the console, bash, vim and the Lisp interpreter.

The only type of GUI supported for applications is through a browser via HTML.
This makes the client side completely platform independent. The GUI is created
dynamically. Though it uses JavaScript and XMLHttpRequest for speed
improvements, it is fully functional also without JavaScript or CSS.

The GUI is deeply integrated with - and generated dynamically from - the
application's data model. Because the application logic runs on the server,
multiple users can view and modify the same database object without conflicts,
everyone seeing changes done by other users on her screen immediately due to the
internal process and database synchronization.

PicoLisp is free software, and you are welcome to use and redistribute it under
the conditions of the MIT/X11 License (see "COPYING").

It compiles and runs on current 32-bit GNU/Linux, FreeBSD, NetBSD, OpenBSD,
SunOS (illumos), HP-UX, AIX, IRIX64, Cygwin/Win32 (and possibly other) systems.
A native 64-bit version is available for arm64/Linux, x86-64/Linux, ppc64/Linux,
x86-64/FreeBSD, x86-64/OpenBSD and x86-64/SunOS (illumos).

--------------------------------------------------------------------------------

   Alexander Burger
   Software Lab. / 7fach GmbH
   Bahnhofstr. 24a, D-86462 Langweid
   abu@software-lab.de, http://www.software-lab.de, +49 8230 5060