joker

Joker's library loader (joker.core/load), which powers (ns ... :require ...) and related macros, assumes that namespace names correspond to their filesystem location.

Specifically:

• The last part of the namespace (after the last dot) must match the filename (excluding the .joke extension).
• The preceding parts of the namespace must correspond to the directory path, with dots separating directories.

Example structure:

├── core.joke
└── utils
    ├── a.joke
    └── b.joke

Corresponding namespaces:

• core.joke $\rightarrow$ ttt.core (if in directory ttt)
• utils/a.joke $\rightarrow$ ttt.utils.a (if in directory ttt/utils)
• utils/b.joke $\rightarrow$ ttt.utils.b (if in directory ttt/utils)

Note: Joker resolves paths relative to the file currently being executed, not the current working directory. You can override this using joker.core/*classpath* and joker.core/*ns-sources* variables.

;; core.joke
(ns ttt.core
  (:require [ttt.utils.a :refer [a]]))

(a)

;; utils/a.joke
(ns ttt.utils.a
  (:require [ttt.utils.b :refer [b]]))

(defn a []
  (println "I am A")
  (b))

;; utils/b.joke
(ns ttt.utils.b)

(defn b []
  (println "I am B"))

Joker is a lightweight interpreter designed for scripting. Users should be aware of the following constraints compared to standard Clojure:

• Single-threaded: No support for parallelism (no refs, agents, futures, promises, locks, etc.). It does support core.async style concurrency via the go macro.
• Reduced Data Structures: The set of persistent data structures is smaller (includes ArrayMap, MapSet, HashMap, List, Vector).
• Limited Interop: Joker does not have the same level of host (Go) interoperability as Clojure/Java. Dot notation for calling methods is not supported.
• Missing Features: Protocols, records, structmaps, transients, transducers, and several clojure.core functions (like subseq, iterator-seq, etc.) are not implemented.
• Namespace Prefixing: Built-in namespaces use the joker prefix (e.g., joker.core, joker.string, joker.json).
• Execution Model: Joker reads and executes s-expressions sequentially. It does not support AOT compilation. To run code only when a file is the main entry point, use the (when (= *main-file* *file*) ...) idiom.

Joker organizes code into namespaces that transition through three distinct states:

1. Available: The namespace's source code is either compiled into the Joker executable (built-in) or exists as a Joker source file that the executable can locate on disk. An available but unmapped namespace cannot be found via (the-ns 'name) until it is first referenced.
2. Mapped: The namespace is registered in the current global environment and will appear in the output of (all-ns). A mapped namespace is known to the system but may not yet be initialized.
3. Loaded: The namespace's internal code and data structures are fully initialized. This happens lazily when the namespace is first required via (ns ... :require [...]), via (require 'name), or when a symbol is qualified by that namespace (e.g., namespace/symbol).

While Joker manages these transitions automatically for most users, understanding them is useful for debugging namespace resolution or managing large library deployments.

The :url value in an *ns-sources* map can be an HTTP URL (starting with http:// or https://). This allows Joker to fetch libraries from the web and cache them locally.

How HTTP caching works:

1. Joker calculates the subpath for the namespace (e.g., a.b.c $\rightarrow$ a/b/c.joke).
2. It attempts to find the file in the local cache directory: $HOME/.jokerd/deps/<url_domain_and_path>/<subpath>.joke.
3. If the file is missing, Joker performs an HTTP GET request to retrieve the file.
   • If the :url ends in .joke, it is used directly.
   • Otherwise, the subpath is appended to the URL.
4. The retrieved file is saved to the $HOME/.jokerd cache for future use.

Example: If :url is https://example.com/joker/libs and the namespace is a.b.c:

• Retrieved URL: https://example.com/joker/libs/a/b/c.joke
• Cached Path: $HOME/.jokerd/deps/example.com/joker/libs/a/b/c.joke