module/language/elisp/README

   1 Guile's Emacs Lisp compiler
   2 ===========================
   3
   4 This is more or less a lot of work in progress.  Here are some notes as well
   5 as status information.
   6
   7 Already implemented:
   8   * progn, prog1, prog2
   9   * if, cond, when, unless
  10   * not, and, or
  11   * referencing and setting (setq) variables
  12   * set, symbol-value, makunbound, boundp functions
  13   * fset, symbol-function, fmakunbound, fboundp
  14   * funcall, apply (also with raw lists as arguments and the like!)
  15   * eval
  16   * while, dotimes, dolist
  17   * catch, throw, unwind-protect
  18   * let, let*
  19   * lambda expressions, function calls using list notation
  20   * some built-ins (mainly numbers/arithmetic)
  21   * defconst, defvar, defun
  22   * macros
  23   * quotation and backquotation with unquote/unquote-splicing
  24   * specific elisp reader
  25
  26 Especially still missing:
  27   * more general built-ins
  28   * advice?
  29   * defsubst and inlining
  30   * recursive macros
  31   * anonymous macros
  32
  33 Other ideas and things to think about:
  34   * #nil vs. #f/'() handling in Guile
  35
  36 Compiler options implemented:
  37   * #:disable-void-check ['all / '(sym1 sym2 sym3)] to disable the check
  38     for void value on access either completely or for some symbols
  39   * #:always-lexical (usable same as disable-void-check) to always bind
  40     certain or all symbols lexically (including lambda arguments)
  41
  42 Extensions over original elisp:
  43   * guile-ref, guile-primitive
  44   * flet and flet*
  45   * lexical-let and lexical-let*
  46   * without-void-checks, with-always-lexical
  47
  48
  49 Details to the implemented extensions
  50 =====================================
  51
  52 guile-ref and guile-primitive:
  53 ------------------------------
  54
  55 (guile-ref module sym) is a new special construct to access symbols from the
  56 Guile-world.  Actually, (guile-ref module sym) is the same as (@ module sym)
  57 would be in Scheme.  Both module and sym must be statically given and are not
  58 evaluated.
  59
  60 (guile-primitive sym) does the same to access a Guile primitive directly, which
  61 is slightly faster where applicable.
  62
  63 flet and flet*:
  64 ---------------
  65
  66 These constructs behave exactly like let and let*, except that they bind the
  67 function slots rather than the value slots, and so make dynamic scoping
  68 available for functions, too.
  69
  70 The distinction between flet and flet* is probably less useful than the one
  71 between let and let*, but it was easy to implement both flet and flet*
  72 based on the existing let and let* code, so not having both of them seemed
  73 a little inconsistent.
  74
  75 lexical-let and lexical-let*:
  76 -----------------------------
  77
  78 lexical-let and lexical-let* are constructs provided by the elisp package
  79 'cl originally, but in Guile they are natively implemented because using
  80 lexical instead of dynamic binding gives better performance in this case.
  81
  82 They work just like let and let*, but bind their target symbols lexically.
  83 Some oberservations with the Emacs 'cl implementation that we mimic in Guile
  84 for compatibility:
  85
  86   * Ordinary let's within the lexical scope of a lexical-let still establish new
  87     *lexical* bindings for symbols already lexically bound.  So once lexical,
  88     always lexical (on a per-symbol basis).
  89
  90   * However, lambda constructs within the lexical scope of a lexical-let where
  91     one of their arguments is already lexically bound still bind it dynamically
  92     for their scope.
  93
  94   * On the other hand, symbols lexically bound that are not rebound via the
  95     argument-list build lexical closures just well.
  96
  97   * If symbols are accessed where they are not known at compile-time (like
  98     symbol-value or set primitives), this always refers to the dynamic binding
  99     and never the lexical one.  That's very nice to the implementor...
 100
 101 without-void-checks:
 102 --------------------
 103
 104 Disable void checks in addition to the compiler option for all or some symbols
 105 in the lexical scope of this construct:
 106
 107 (without-void-checks all body...) or
 108 (without-void-checks (sym1 sym2 ...) body...
 109
 110 with-always-lexical:
 111 --------------------
 112
 113 As without-void-checks but adds to list of symbols that should always be bound
 114 lexically.  This lexical binding includes lambda arguments (if the symbols
 115 match up with the list), which can not be bound lexically otherwise.