;;; -*-scheme-*-
(use-modules (ice-9 readline))
(activate-readline)

See the DESIGN document for an overview of the
implementation, and detailed information about Guile is available in
the Guile Reference Manual
which should also be available via info guile if installed.

General comparison with Clojure/JVM

• The implementation should be properly tail-recursive.

• Argument evaluation order is (currently) unspecified.

• Clojure namespaces may be implemented in either Clojure or Scheme,
  and Clojure namespaces are Guile modules
  with the entire Clojure namespace tree situated under (lokke ns)
  in the Guile module tree.

• Lokke vars are Guile variables, and unlike JVM vars, they
  include no information about their origin (JVM vars include a
  namespace). As a result Lokke vars cannot be printed as a reader
  macro (e.g. #'clojure.core).

• Lokke’s reader conditional identifier is :cljl, for example,
  #?(:cljl x), and at the moment reader conditionals are always
  supported by the reader functions; they are not restricted to
  .cljc files.

• Symbols, like keywords, are unique and compare very efficiently (via
  pointer comparison). On the JVM, this is only promised for
  keywords.
  Symbols do not currently support metadata.

• There are no agents or refs yet.

• At the moment, format strings are
  Guile format
  strings.

• The default regular expressions are
  PCRE2
  regular expressions, and right now, reader literal patterns #"x"
  just translate to an equivalent (re-pattern ...) at read time.
  That is, they are not compiled at read time, and so are
  re-evaluated.

• lokke.io is analogous to clojure.java.io, and lokke.shell is
  analogous to clojure.java.shell. At the moment, paths are
  generally only handled as (Unicode) strings. We’ll fix that once
  Guile does. As a workaround, you may be able to set the LC_CTYPE
  to a locale that passes arbitrary bytes transparently,
  e.g.(guile/setlocale LC_CTYPE "en_US.iso88591"), but note that
  setlocale acts globally, not just with respect to the current
  thread.

• Arrays (byte-array, aref, aset, etc.) are implemented using
  Guile’s SRFI-4 homogeneous vectors,
  and so should behave fairly similarly to JVM arrays (constant time
  access, compact storage, etc.). The support is imcomplete,
  currently omitting object arrays, support for multidimensional
  arrays (including make-array), and casts like bytes, for
  example.

  Boolean arrays are implemented as
  Guile bit vectors,
  and so are “packed”, but consider the type subject to change.

• There is some experimental, rudimentary
  compatibility with Clojure/JVM exception handling.

• Currently, future and future-call always create a new thread,
  i.e. they do not cache/pool threads.

• Metadata support is limited: vectors, hash-sets, and hash-maps,
  vars, namespaces, and atoms are supported, lists and symbols are
  not. Often metadata will just be discarded when it’s unsupported.

• Persistent lists are currently not counted?, so count must
  traverse the list.

• Dynamic variables and binding
  behave a bit differently, and they must be defined via defdyn.

• The numeric tower is
  Guile’s,
  backed by GMP, and there is currently no
  distinction between functions like +' and +, or *' and *,
  etc.

• Currently ratio? tests whether the value is a number that’s
  actually represented as a fraction, more specifically, that the
  value is an exact rational, but not an integer.

• There are no explicit bigints or BigDecimal (bigint, decimal?,
  bigdec, 7N, 4.2M, etc.), but of course arbitrarily large integers
  are supported.

• The reader currently reads invalid integer syntaxes like 2rff as
  symbols.

• abs returns the absolute value for all integers, i.e. it does not
  return the minimum 64-bit integer unchanged.

• parse-long will return a value for integers of arbitrary
  magnitude while the JVM returns nil for anything outside the range
  of a 64-bit signed integer.

• parse-double does not yet handle JVM Double/valueOf hex format
  doubles, and at the moment, the floating point syntax is the same as
  the reader’s.

• Rather than throwing an exception, the Clojure and edn reader
  functions, read, read-string, etc. return the rnrs end-of-file
  object,
  which can be identified with guile/eof-object?.

• There are some differences and limitations with respect to the
  handling of comparisons, hashes, and equality.

• fn condition maps (i.e. :pre :post, etc.) are currently ignored.

• deftest is little more than a do, i.e. it executes immediately,
  there’s no support for *load-tests*, and it doesn’t create a test
  function to run later.

• For now, types are implemented via
  GOOPS
  which means that you can actually modify them via slot-set!. We
  may eventually pursue immutable GOOPS classes in Guile, but of
  course you can modify anything on the JVM too, if you really set
  your mind to it.

• References like x.y.z (that are class references on the JVM) are
  not supported, and there is no import or :import.

• defrecord and defprotocol define a normal bindings in the
  current namespace, which must be required, not imported (as with
  records in ClojureScript).

• deftype is not yet supported.

• For now, *assert* (which is not documented in clojure.core) is
  not supported.

On the Scheme side

• #nil is nil

• There is no do, only begin.

• Lists are Guile lists.

• Strings are Guile strings.

• As with Clojure and :refer, explicit symbol imports are
  recommended, e.g. #:use-module ((foo) #:select (x)) rather than
  just #:use-module (foo), and Lokke modules assume this is the norm.

• Currently equal? is only augmented to handle new types like
  hash-map, hash-set, etc.

• Currently Clojure = is only available as an export from (lokke core), and for now, it is implemented via clj=.

• Bindings starting with /lokke/ are reserved (but they’re illegal
  in Clojure anyway). We use them for internal
  compiler-communication, among other things. See the DESIGN document
  for more information.

• In the (lokke scm) apis, Scheme vectors are referred to as vector,
  Clojure’s as lokke-vector.

• The num method can be used to convert characters or any
  to a number. Characters are converted via Guile’s char->integer.

• The integer method is effectively (truncate (num x)), using
  Guile’s truncate.

• For now, bit-test treats negative values as twos-complement.

• We prefer to follow the Clojure convention of explicitly #:selecting
  symbols for import most of the time.

• We prefer to format module declarations along the same lines
  suggested here: https://stuartsierra.com/2016/clojure-how-to-ns.html

Clojure namespaces and Guile modules

Clojure namespaces are Guile modules (which have very comparable
semantics), and the entire Clojure namespace tree is situated under
(lokke ns) in the Guile module tree, i.e. clojure.string is
implemented by the (lokke ns clojure string) module, and
clojure.string/join is exactly equivalent to a Guile reference to
the join function in the (lokke ns clojure string) module.

All clojure namspaces starting with guile represent direct
references to the root of the guile module tree, e.g.
(guile.srfi.srfi-19/current-date) calls the current-date function
in the guile (srfi srfi-19) module. These provide a convenient way
to refer to modules that are not under a (lokke ns ...) prefix, and
of course you can use them in forms like ns and require. As a
special case, the guile namespace refers to the (guile) module,
not (guile guile). For example (guile/current-time) or
(guile/delete-file ...).

In many cases, you may have lokke or lok handle the Guile
%load-path for you via deps.edn :paths, but manual arrangements
like this will also work fine:

$ GUILE_LOAD_PATH=$(pwd)/mod lok -e "(require '[something.core ...])" ...