### Start New Process (start)

Source: https://github.com/candid82/joker/blob/master/docs/joker.os.html

Starts a new process with the specified program and options, without waiting for it to finish. Returns the PID of the newly started process.

```APIDOC
`(start name opts)`

Starts a new process with the program specified by name.
opts is a map with the same keys as in exec.
Doesn't wait for the process to finish.
Returns the process's PID.
```

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

### Joker Linter Output Format Example

Source: https://github.com/candid82/joker/blob/master/README.md

Demonstrates the standard output format of the Joker linter, showing a parse warning for the provided Clojure code example.

```shell
test.clj:1:1: Parse warning: let form with empty body
```

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

### Building and Installing Joker from Source

Source: https://github.com/candid82/joker/blob/master/README.md

To build Joker, Go version 1.13 or later is required. These commands fetch the source code, navigate to the project directory, and then build and install the Joker executable.

```Go/Shell
go get -d github.com/candid82/joker
cd $GOPATH/src/github.com/candid82/joker
./run.sh --version && go install
```

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

### HTTP Server: Start File Server

Source: https://github.com/candid82/joker/blob/master/docs/joker.http.html

Starts an HTTP server on a specified TCP network address that serves HTTP requests by providing content from a file system rooted at a given directory.

```APIDOC
(start-file-server addr root)
  Starts HTTP server on the TCP network address 'addr' that
  serves HTTP requests with the contents of the file system rooted at 'root'.
  
  Parameters:
    addr (string): The TCP network address to bind the server to.
    root (string): The root directory for serving files.
```

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

### Get Executable Path API (executable)

Source: https://github.com/candid82/joker/blob/master/docs/joker.os.html

Returns the path name for the executable that started the current process.

```APIDOC
executable
Function v1.0
(executable)
```

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

### Joker Bolt Database Basic Operations Example

Source: https://github.com/candid82/joker/blob/master/docs/joker.bolt.html

Demonstrates how to open a Bolt database, create a bucket, generate a sequence ID, store a JSON object, and retrieve it using the joker.bolt namespace functions. This example illustrates a typical workflow for interacting with the embedded database.

```Joker
user=> (def db (joker.bolt/open "bolt.db" 0600))
#'user/db
user=> (joker.bolt/create-bucket db "users")
nil
user=> (def id (joker.bolt/next-sequence db "users"))
#'user/id
user=> id
1
user=> (joker.bolt/put db "users" (str id) (joker.json/write-string {:id id :name "Joe Black"}))
nil
user=> (joker.json/read-string (joker.bolt/get db "users" (str id)))
{"id" 1, "name" "Joe Black"}
```

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

### Install Joker via Homebrew

Source: https://github.com/candid82/joker/blob/master/README.md

This command installs the Joker interpreter, linter, and formatter on macOS and Linux systems using the Homebrew package manager. Ensure Homebrew or Linuxbrew is installed before running.

```Shell
brew install candid82/brew/joker
```

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

### Install Joker via Nix

Source: https://github.com/candid82/joker/blob/master/README.md

This command installs the Joker interpreter using the Nix package manager. This method is suitable for users on NixOS or those who prefer managing packages with Nix.

```Shell
nix-env -i joker
```

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

### HTTP Server: Start Custom Handler Server

Source: https://github.com/candid82/joker/blob/master/docs/joker.http.html

Starts an HTTP server on a specified TCP network address, utilizing a provided handler function to process incoming HTTP requests.

```APIDOC
(start-server addr handler)
  Starts HTTP server on the TCP network address 'addr'.
  
  Parameters:
    addr (string): The TCP network address to bind the server to.
    handler (function): The function to handle incoming HTTP requests.
```

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

### defmethod

Source: https://github.com/candid82/joker/blob/master/docs/joker.core.html

Creates and installs a new method of multimethod associated with dispatch-value.

```APIDOC
(defmethod multifn dispatch-val & fn-tail)
```

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

### Get Environment Variables API (env)

Source: https://github.com/candid82/joker/blob/master/docs/joker.os.html

Returns a map representing the environment.

```APIDOC
env
Function v1.0
(env)
```

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

### Execute Program API (exec)

Source: https://github.com/candid82/joker/blob/master/docs/joker.os.html

Executes the named program with the given arguments. opts is a map with the following keys (all optional): :args - vector of arguments (all arguments must be strings), :dir - if specified, working directory will be set to this value before executing the program, :stdin - if specified, provides stdin for the program. Can be either a string or an IOReader. If it's a string, the string's content will serve as stdin for the program. IOReader can be, for example, *in* (in which case Joker's stdin will be redirected to the program's stdin) or the value returned by (joker.os/open). :stdout - if specified, must be an IOWriter. It can be, for example, *out* (in which case the program's stdout will be redirected to Joker's stdout) or the value returned by (joker.os/create). :stderr - the same as :stdout, but for stderr. Returns a map with the following keys: :success - whether or not the execution was successful, :err-msg (present iff :success if false) - string capturing error object returned by Go runtime :exit - exit code of program (or attempt to execute it), :out - string capturing stdout of the program (unless :stdout option was passed) :err - string capturing stderr of the program (unless :stderr option was passed).

```APIDOC
exec
Function v1.0
(exec name opts)
Parameters:
  name: Program name (string)
  opts: Map of optional arguments
    :args (vector of strings): Arguments for the program
    :dir (string): Working directory
    :stdin (string|IOReader): Standard input
    :stdout (IOWriter): Standard output
    :stderr (IOWriter): Standard error
Returns: Map
  :success (boolean): Execution status
  :err-msg (string, optional): Error message if not successful
  :exit (int): Exit code
  :out (string): Standard output content
  :err (string): Standard error content
```

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

### Clojure: Loading Libraries with `require` and Aliases

Source: https://github.com/candid82/joker/blob/master/docs/joker.core.html

Demonstrates how to load Clojure libraries using the `require` special form, including the use of prefix lists to reduce repetition and aliasing a library for brevity. The example loads `clojure.zip` and `clojure.set`, aliasing `clojure.set` as 's'.

```Clojure
(require '(clojure zip [set :as s]))
```

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

### Clojure: Defining Test Fixtures

Source: https://github.com/candid82/joker/blob/master/docs/joker.test.html

Fixtures are functions that encapsulate setup and teardown logic for tests. They take another function as an argument, perform necessary setup (e.g., establish bindings), call the passed function (which represents the test execution), and can then perform teardown.

```Clojure
(defn my-fixture [f]
Perform setup, establish bindings, whatever.
(f) Then call the function we were passed.)
```

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

### Joker Namespace and File System Mapping Example

Source: https://github.com/candid82/joker/blob/master/docs/misc/lib-loader.md

This Clojure code snippet demonstrates how Joker's library loader maps namespace names to file paths within a project structure. It shows three interconnected files (`core.joke`, `utils/a.joke`, `utils/b.joke`) that define namespaces `ttt.core`, `ttt.utils.a`, and `ttt.utils.b` respectively, illustrating how `require` statements resolve dependencies based on the file system layout.

```Clojure
;; 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"))
```

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

### Get Go Runtime Version String

Source: https://github.com/candid82/joker/blob/master/docs/joker.runtime.html

This function provides the version string of the Go runtime currently in use. The returned value is identical to that provided by Go's runtime/Version() function.

```APIDOC
(go-version)
Returns the Go version string (as returned by runtime/Version()).
```

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

### Get File Information (stat)

Source: https://github.com/candid82/joker/blob/master/docs/joker.os.html

Returns a map containing detailed information about the named file, including its name, size, mode, modification time, and whether it's a directory.

```APIDOC
`(stat filename)`

Returns a map describing the named file. The info map has the following attributes:
:name - base name of the file
:size - length in bytes for regular files; system-dependent for others
:mode - file mode bits
:modtime - modification time
:dir? - true if file is a directory
```

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

### Get Next of First Item (Joker)

Source: https://github.com/candid82/joker/blob/master/docs/joker.core.html

Equivalent to calling `(next (first x))`.

```APIDOC
(nfirst x)
Same as (next (first x))
```

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

### Attach 'each' Fixtures to Namespace (Clojure)

Source: https://github.com/candid82/joker/blob/master/docs/joker.test.html

Demonstrates how to attach 'each' fixtures to the current namespace. These fixtures run repeatedly, once for each test function, ensuring a consistent before/after state for individual tests. Examples include using named functions and anonymous functions.

```Clojure
(use-fixtures :each fixture1 fixture2 ...)
```

```Clojure
(use-fixtures :each (fn [f] setup... (f) cleanup...))
```

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

### Retrieve Go Root Directory Path

Source: https://github.com/candid82/joker/blob/master/docs/joker.runtime.html

This function returns the GOROOT string, which indicates the root directory of the Go installation. It directly reflects the value returned by Go's runtime/GOROOT() function.

```APIDOC
(go-root)
Returns the GOROOT string (as returned by runtime/GOROOT()).
```

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

### Joker HTTP Source Path Resolution and Retrieval Example

Source: https://github.com/candid82/joker/blob/master/LIBRARIES.md

Illustrates how Joker constructs the local cache path for an HTTP-sourced namespace and the corresponding remote URL that is retrieved. The local path is derived by appending the domain and path segments of the URL to `$HOME/.jokerd/deps/`, followed by the namespace's subpath. The remote URL is formed by appending the namespace's subpath to the base `:url`.

```Text
$HOME/.jokerd/deps/example.com/joker/libs/a/b/c.joke
```

```Text
https://example.com/joker/libs/a/b/c.joke
```

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

### Setting BigFloat Precision with `joker.math/set-precision`

Source: https://github.com/candid82/joker/blob/master/docs/misc/bigfloat.md

This example illustrates the use of `joker.math/set-precision` to create a new `BigFloat` instance with a specific precision. It shows how to truncate a high-precision `BigFloat` to a lower precision, similar to Go's `math/big.(*Float).SetPrec()` method, and verifies the resulting precision against `joker.math/e`.

```Clojure
user=> (def big-e 2.71828182845904523536028747135266249775724709369995957496696763M)
#'user/big-e
user=> (joker.math/precision big-e)
208N
user=> (def truncated-e (joker.math/set-precision 53 big-e))
#'user/truncated-e
user=> truncated-e
2.718281828459045M
user=> (joker.math/precision truncated-e)
53N
user=> (joker.math/precision joker.math/e)
53N
user=>
```

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

### Attach 'once' Fixtures to Namespace (Clojure)

Source: https://github.com/candid82/joker/blob/master/docs/joker.test.html

Shows how to attach 'once' fixtures to the current namespace. These fixtures run only once around all tests in the namespace, suitable for tasks like establishing database connections or other time-consuming setups.

```Clojure
(use-fixtures :once fixture1 fixture2 ...)
```

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

### Demonstrating Joker Namespace Loading and Initialization

Source: https://github.com/candid82/joker/blob/master/DEVELOPER.md

This console output demonstrates the lifecycle of Joker namespaces. It shows how namespaces are lazily initialized (e.g., `joker.string`, `joker.repl`), explicitly loaded using `the-ns` and `use`, and how a custom namespace (`a.b.c`) is loaded. It also illustrates checking the set of all loaded namespaces and their initialization status using `joker.core/ns-initialized?`.

```console
$ joker --verbose
Lazily running fast version of string.InternsOrThunks().
NamespaceFor: Lazily initialized joker.string for joker.repl
NamespaceFor: Lazily initialized joker.repl for FindNameSpace
Welcome to joker v0.14.2. Use EOF (Ctrl-D) or SIGINT (Ctrl-C) to exit.
user=> (all-ns)
(joker.walk joker.template joker.io joker.json joker.base64 joker.csv joker.filepath joker.url joker.html user joker.core joker.hiccup joker.strconv joker.better-cond joker.bolt joker.crypto joker.math joker.os joker.uuid joker.yaml joker.string joker.test joker.pprint joker.hex joker.http joker.repl joker.set joker.tools.cli joker.time)
user=> joker.core/*core-namespaces*
#{joker.tools.cli joker.test user joker.template joker.core joker.walk joker.set joker.repl joker.hiccup joker.pprint joker.better-cond}
user=> (the-ns 'joker.hiccup)
Lazily running fast version of html.InternsOrThunks().
NamespaceFor: Lazily initialized joker.html for joker.hiccup
NamespaceFor: Lazily initialized joker.hiccup for FindNameSpace
#object[Namespace "joker.hiccup"]
user=> (use 'joker.hiccup)
nil
user=> (use 'joker.template)
NamespaceFor: Lazily initialized joker.walk for joker.template
NamespaceFor: Lazily initialized joker.template for FindNameSpace
nil
user=> (the-ns 'joker.hiccup)
#object[Namespace "joker.hiccup"]
user=> (the-ns 'a.b.c)
<repl>:7:10: Exception: No namespace: a.b.c found
Stacktrace:
  global <repl>:7:1
  core/the-ns <joker.core>:2316:18
user=> (use 'a.b.c)
here i am!
nil
user=> (all-ns)
(joker.string joker.test joker.pprint joker.hex joker.http joker.uuid joker.yaml joker.repl joker.set joker.tools.cli joker.time joker.walk joker.template joker.io joker.json joker.base64 joker.csv joker.filepath joker.url joker.html user joker.core joker.hiccup joker.better-cond joker.bolt joker.crypto joker.math joker.os joker.strconv a.b.c)
user=> (defn all-ns-as-set-of-strings [] (set (map str (all-ns))))
#'user/all-ns-as-set-of-strings
user=> (all-ns-as-set-of-strings)
#{"joker.crypto" "joker.strconv" "joker.pprint" "joker.csv" "joker.io" "joker.string" "joker.url" "joker.template" "joker.core" "joker.tools.cli" "joker.uuid" "joker.html" "joker.set" "joker.hex" "joker.time" "joker.json" "joker.bolt" "joker.hiccup" "user" "joker.yaml" "joker.filepath" "joker.repl" "joker.os" "joker.base64" "joker.better-cond" "joker.math" "joker.test" "joker.http" "joker.walk" "a.b.c"}
user=> ((all-ns-as-set-of-strings) "a.b.c")
"a.b.c"
user=> ((all-ns-as-set-of-strings) "joker.foo")
nil
user=> (joker.core/ns-initialized? 'joker.os)
false
user=> (joker.core/ns-initialized? 'joker.hiccup)
true
user=> (joker.core/ns-initialized? 'joker.html)
true
user=> (joker.core/ns-initialized? 'a.b.c)
true
user=>
```

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

### range

Source: https://github.com/candid82/joker/blob/master/docs/joker.core.html

Returns a lazy seq of numbers from start (inclusive) to end (exclusive), by step, where start defaults to 0, step to 1, and end to infinity. When step is equal to 0, returns an infinite sequence of start. When start is equal to end, returns empty list.

```APIDOC
(range)
^Seq (range)

(range end)
^Seq (range ^Number end)

(range start end)
^Seq (range ^Number start ^Number end)

(range start end step)
^Seq (range ^Number start ^Number end ^Number step)
```

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

### Check if String Starts With Substring (joker.string/starts-with?)

Source: https://github.com/candid82/joker/blob/master/docs/joker.string.html

True if `s` starts with `substr`.

```APIDOC
(starts-with? s substr)

True if s starts with substr.
```

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

### prewalk-demo Function

Source: https://github.com/candid82/joker/blob/master/docs/joker.walk.html

Demonstrates the behavior of prewalk by printing each form as it is walked. Returns form.

```Clojure
(prewalk-demo form)
```

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

### Clojure Code Example for Joker Linter Warning

Source: https://github.com/candid82/joker/blob/master/README.md

A basic Clojure `let` form with an empty body, designed to trigger a parse warning when analyzed by the Joker linter.

```clojure
(let [a 1])
```

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

### Joker Library Loading Syntax and Procedure

Source: https://github.com/candid82/joker/blob/master/LIBRARIES.md

Outlines the primary syntax used for loading external namespaces in Joker and references the internal procedure responsible for the actual file loading process.

```Joker
(ns ... :require ...)
joker.core/load-lib-from-path__
```

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

### Extract a substring (subs)

Source: https://github.com/candid82/joker/blob/master/docs/joker.core.html

The `subs` function returns a substring of `s` starting at `start` (inclusive) and ending at `end` (exclusive). If `end` is not provided, it defaults to the length of the string.

```Joker
(subs s start)
^String (subs ^String s ^Number start)
(subs s start end)
^String (subs ^String s ^Number start ^Number end)
```

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

### Create Directory and Parents API (mkdir-all)

Source: https://github.com/candid82/joker/blob/master/docs/joker.os.html

Creates a directory named path, along with any necessary parents, and returns nil, or else throws an error. The permission bits perm (before umask) are used for all directories that mkdir-all creates. If path is already a directory, mkdir-all does nothing and returns nil.

```APIDOC
mkdir-all
Function v1.0
(mkdir-all name perm)
```

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

### Example of File Lookup Error from Namespace Mismatch

Source: https://github.com/candid82/joker/blob/master/docs/misc/lib-loader.md

This log snippet illustrates a 'no such file or directory' error encountered when a namespace's declared name (e.g., `ttt.utils.a.extra`) does not match its expected file path. This mismatch causes the system to incorrectly strip path components (like `mylibs/`) from the file lookup, leading to the reported failure.

```Log
<joker.core>:3536:13: Eval error: open /Users/somebody/ttt/utils/b.joke: no such file or directory
```

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

### drop-while

Source: https://github.com/candid82/joker/blob/master/docs/joker.core.html

Returns a lazy sequence of the items in coll starting from the first item for which (pred item) returns logical false.

```APIDOC
Function v1.0
(drop-while pred coll)
^Seq (drop-while ^Callable pred ^Seqable coll)
```

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

### Create Directory API (mkdir)

Source: https://github.com/candid82/joker/blob/master/docs/joker.os.html

Creates a new directory with the specified name and permission bits.

```APIDOC
mkdir
Function v1.0
(mkdir name perm)
```

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

### postwalk-demo Function

Source: https://github.com/candid82/joker/blob/master/docs/joker.walk.html

Demonstrates the behavior of postwalk by printing each form as it is walked. Returns form.

```Clojure
(postwalk-demo form)
```

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

### APIDOC: by-prefix Function

Source: https://github.com/candid82/joker/blob/master/docs/joker.bolt.html

Retrieves key/value pairs for all keys in a specified bucket that start with a given prefix. Returns a vector of [key value] tuples. Passing an empty prefix will return all key/values in the bucket.

```APIDOC
(by-prefix db bucket prefix)
```

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

### dir Macro Documentation

Source: https://github.com/candid82/joker/blob/master/docs/joker.repl.html

Prints a sorted directory of public variables in a specified namespace.

```APIDOC
dir:
  Signature: (dir nsname)
  Parameters:
    nsname: The name of the namespace.
```

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

### Automating Cross-builds with run.sh and build-arm.sh

Source: https://github.com/candid82/joker/blob/master/README.md

Illustrates a method to perform a cross-build from a Linux amd64 or 386 system to a Linux arm system. This command sequence first verifies the project version using `run.sh` and then executes the `build-arm.sh` script to initiate the ARM-specific build process.

```Shell
./run.sh --version && ./build-arm.sh
```

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

### Create Temporary Directory API (mkdir-temp)

Source: https://github.com/candid82/joker/blob/master/docs/joker.os.html

Creates a new temporary directory.

```APIDOC
mkdir-temp
Function v1.0
```

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

### Get Current Local Time (APIDOC)

Source: https://github.com/candid82/joker/blob/master/docs/joker.time.html

Retrieves the current local time.

```APIDOC
now()
  Returns: The current local time.
```

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

### Get Hostname API (hostname)

Source: https://github.com/candid82/joker/blob/master/docs/joker.os.html

Returns the host name reported by the kernel.

```APIDOC
hostname
Function v1.0
(hostname)
```

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

### Steps to Add a New Standard-library-wrapping Namespace in Joker

Source: https://github.com/candid82/joker/blob/master/DEVELOPER.md

This snippet provides the essential shell commands and procedural steps required to introduce a new standard-library-wrapping namespace into the Joker project. It covers directory creation, Go file generation, and testing procedures.

```Shell
mkdir -p std/foo
```

```Shell
(cd std; ../joker generate-std.joke)
```

```Shell
run.sh
```

```Shell
./all-tests.sh
```

```Shell
./eval-tests.sh
```

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

### Get User Configuration Directory (user-config-dir)

Source: https://github.com/candid82/joker/blob/master/docs/joker.os.html

Returns the default root directory for user-specific configuration data. Users should create application-specific subdirectories within this path. The function determines the path based on the operating system: $XDG_CONFIG_HOME or $HOME/.config on Unix, $HOME/Library/Application Support on Darwin, %AppData% on Windows, and $home/lib on Plan 9. An error is thrown if the location cannot be determined (e.g., $HOME is undefined).

```APIDOC
Function: user-config-dir
Version: v1.0
Signature: (user-config-dir)
Description: Returns the default root directory to use for user-specific configuration data.
OS Specifics:
  Unix: $XDG_CONFIG_HOME (if non-empty) else $HOME/.config
  Darwin: $HOME/Library/Application Support
  Windows: %AppData%
  Plan 9: $home/lib
Errors: Throws an error if the location cannot be determined (e.g., $HOME is not defined).
```

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

### Configuring Joker Namespace Sources with Local Path

Source: https://github.com/candid82/joker/blob/master/LIBRARIES.md

Demonstrates how to configure `*ns-sources*` to map a namespace prefix (e.g., `mylibs.`) to a local file system path. When a namespace like `mylibs.awesome.code` is required, Joker will attempt to load its root file from the specified local directory, appending the namespace's relative path and `.joke` extension.

```Joker
(ns-sources { #"^mylibs[.]" {:url /Users/somebody/mylibs} })
```

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

### Execute Program from Directory (sh-from)

Source: https://github.com/candid82/joker/blob/master/docs/joker.os.html

Executes the specified program with arguments from a given working directory. Returns a map with execution status, error message, exit code, standard output, and standard error.

```APIDOC
`(sh-from dir name & arguments)`

Executes the named program with the given arguments and working directory set to dir.
Returns a map with the following keys:
:success - whether or not the execution was successful,
:err-msg (present iff :success if false) - string capturing error object returned by Go runtime
:exit - exit code of program (or attempt to execute it),
:out - string capturing stdout of the program,
:err - string capturing stderr of the program.
```

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

### Get User ID (uid)

Source: https://github.com/candid82/joker/blob/master/docs/joker.os.html

Returns the numeric user ID of the calling process.

```APIDOC
`(uid)`

Returns the numeric user id of the caller.
```

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

### take

Source: https://github.com/candid82/joker/blob/master/docs/joker.core.html

Returns a lazy sequence of the first n items in coll, or all items if
there are fewer than n.

```APIDOC
take: Function v1.0
 (take n coll)
   Parameters:
     n: Number
     coll: Seqable
   Returns: Seq
```

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

### Get Group ID API (gid)

Source: https://github.com/candid82/joker/blob/master/docs/joker.os.html

Returns the numeric group id of the caller.

```APIDOC
gid
Function v1.0
(gid)
```

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

### Configuring Joker Entry Points for Unused Code Reporting

Source: https://github.com/candid82/joker/blob/master/README.md

This Clojure configuration snippet for the `.joker` file specifies namespaces and fully qualified vars that should be considered 'entry points'. These elements will be excluded from global unused code reports, preventing false positives for public APIs or main functions.

```clojure
{:entry-points [my-project.public-api
                my-project.core/-main]}
```

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

### Get Current Process ID (pid)

Source: https://github.com/candid82/joker/blob/master/docs/joker.os.html

Returns the process identifier (PID) of the calling process.

```APIDOC
`(pid)`

Returns the process id of the caller.
```

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

### Get the key of a map entry (key)

Source: https://github.com/candid82/joker/blob/master/docs/joker.core.html

Returns the key of the map entry.

```APIDOC
(key e)
```

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

### Get User Groups API (groups)

Source: https://github.com/candid82/joker/blob/master/docs/joker.os.html

Returns a list of the numeric ids of groups that the caller belongs to.

```APIDOC
groups
Function v1.0
(groups)
```

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

### println-str

Source: https://github.com/candid82/joker/blob/master/docs/joker.core.html

Prints to a string, returning it.

```APIDOC
(println-str & xs)
^String (println-str & xs)
```

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

### Get Effective User ID API (euid)

Source: https://github.com/candid82/joker/blob/master/docs/joker.os.html

Returns the numeric effective user id of the caller.

```APIDOC
euid
Function v1.0
(euid)
```

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

### Search for Go Initialization Code

Source: https://github.com/candid82/joker/blob/master/DEVELOPER.md

This shell command searches for Go `init()` functions and global variable declarations (`var`) across various Go source files within the current directory, parent directory, and `std` subdirectories. It excludes lines containing ' ProcFn = ' to filter out specific assignments.

```Shell
grep --color -nH --null -E -e '^(func init\(|var )' *.go ../*.go ../std/*/*.go | grep -v ' ProcFn = '
```

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

### Execute Program (sh)

Source: https://github.com/candid82/joker/blob/master/docs/joker.os.html

Executes the specified program with the given arguments. Returns a map containing execution status, error message (if any), exit code, standard output, and standard error.

```APIDOC
`(sh name & arguments)`

Executes the named program with the given arguments. Returns a map with the following keys:
:success - whether or not the execution was successful,
:err-msg (present iff :success if false) - string capturing error object returned by Go runtime
:exit - exit code of program (or attempt to execute it),
:out - string capturing stdout of the program,
:err - string capturing stderr of the program.
```

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

### Get Effective Group ID API (egid)

Source: https://github.com/candid82/joker/blob/master/docs/joker.os.html

Returns the numeric effective group id of the caller.

```APIDOC
egid
Function v1.0
(egid)
```

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

### Get Next of Next Item (Joker)

Source: https://github.com/candid82/joker/blob/master/docs/joker.core.html

Equivalent to calling `(next (next x))`.

```APIDOC
(nnext x)
Same as (next (next x))
```

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

### test

Source: https://github.com/candid82/joker/blob/master/docs/joker.core.html

test [v] finds fn at key :test in var metadata and calls it,
presuming failure will throw exception

```APIDOC
test: Function v1.0
 (test v)
   Returns: Keyword
```

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

### Command-Line Option Specification Parameters and parse-opts Return Values

Source: https://github.com/candid82/joker/blob/master/docs/joker.tools.cli.html

This section details the various parameters used when defining command-line options, such as functions for computing default values, parsing arguments, associating values with the option map, and updating values based on multiple occurrences. It also describes the structure of the map returned by `parse-opts` and its configurable behavior.

```APIDOC
Option Parameters:

:default-fn
  Description: A function to compute the default value of this option, given the whole, parsed option map as its one argument. If no function is specified, the resulting option map will not contain an entry for this option unless set on the command line. Also see :default.
  Interaction: If both :default and :default-fn are provided, if the argument is not provided on the command-line, :default-fn will still be called (and can override :default).

:parse-fn
  Description: A function that receives the required option argument and returns the option value.
  Boolean Option: If this is a boolean option, parse-fn will receive the value true. This may be used to invert the logic of this option.
  Example:
    ["-q" "--quiet"
     :id :verbose
     :default true
     :parse-fn not]

:assoc-fn
  Description: A function that receives the current option map, the current option :id, and the current parsed option value, and returns a new option map. The default is 'assoc'.
  Usage: For non-idempotent options, where you need to compute an option value based on the current value and a new value from the command line. If you only need the current value, consider :update-fn (below).
  Constraint: You cannot specify both :assoc-fn and :update-fn for an option.

:update-fn
  Description: A function that receives the current parsed option value, and returns a new option value, for each option :id present. The default is 'identity'.
  Usage: May be used to create non-idempotent options where you only need the current value, like setting a verbosity level by specifying an option multiple times. ("-vvv" -> 3)
  Example 1 (verbosity):
    ["-v" "--verbose"
     :default 0
     :update-fn inc]
  Example 2 (fnil with default):
    :default is applied first. If you wish to omit the :default option value, use fnil in your :update-fn as follows:
    ["-v" "--verbose"
     :update-fn (fnil inc 0)]
  Constraint: You cannot specify both :assoc-fn and :update-fn for an option.

:validate
  Description: A vector of [validate-fn validate-msg ...]. Multiple pairs of validation functions and error messages may be provided.

:validate-fn
  Description: A vector of functions that receives the parsed option value and returns a falsy value or throws an exception when the value is invalid. The validations are tried in the given order.

:validate-msg
  Description: A vector of error messages corresponding to :validate-fn that will be added to the :errors vector on validation failure.

parse-opts Return Map:
  :options: The options map, keyed by :id, mapped to the parsed value
  :arguments: A vector of unprocessed arguments
  :summary: A string containing a minimal options summary
  :errors: A possible vector of error message strings generated during parsing; nil when no errors exist

parse-opts Function Options:

:in-order
  Description: Stop option processing at the first unknown argument. Useful for building programs with subcommands that have their own option specs.

:no-defaults
  Description: Only include option values specified in arguments and do not include any default values in the resulting options map. Useful for parsing options from multiple sources; i.e. from a config file and from the command line.

:strict
  Description: Parse required arguments strictly: if a required argument value matches any other option, it is considered to be missing (and you have a parse error).

:summary-fn
  Description: A function that receives the sequence of compiled option specs (documented at #'clojure.tools.cli/compile-option-specs), and returns a custom option summary string.
```

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

### Get the Joker version string (joker-version)

Source: https://github.com/candid82/joker/blob/master/docs/joker.core.html

Returns joker version as a printable string.

```APIDOC
(joker-version)^String (joker-version)
```

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

### Get Denominator of Ratio (denominator)

Source: https://github.com/candid82/joker/blob/master/docs/joker.core.html

Function that returns the denominator part of a Ratio number.

```APIDOC
denominator:
  Function v1.0
  (denominator r) ^Number (denominator ^Ratio r)
```

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

### apropos Function Documentation

Source: https://github.com/candid82/joker/blob/master/docs/joker.repl.html

Given a regular expression or stringable thing, return a sequence of all public definitions in all currently-loaded namespaces that match the provided pattern.

```APIDOC
apropos:
  Signature: (apropos str-or-pattern)
  Parameters:
    str-or-pattern: A regular expression or stringable thing.
```

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

### prewalk Function

Source: https://github.com/candid82/joker/blob/master/docs/joker.walk.html

Like postwalk, but does pre-order traversal.

```Clojure
(prewalk f form)
```

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

### APIDOC: get Function

Source: https://github.com/candid82/joker/blob/master/docs/joker.bolt.html

Retrieves the value for a key in the specified bucket. Returns nil if the key does not exist.

```APIDOC
(get db bucket key)
```

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

### binding

Source: https://github.com/candid82/joker/blob/master/docs/joker.core.html

Creates new bindings for the (already-existing) vars, with the supplied initial values, executes the exprs in an implicit do, then re-establishes the bindings that existed before. The new bindings are made in parallel (unlike let); all init-exprs are evaluated before the vars are bound to their new values.

```APIDOC
binding (Macro):
  (binding bindings & body)
  Parameters:
    bindings: var-symbol init-expr (new bindings for existing vars)
    body: Expressions to execute.
  Effect: Re-establishes previous bindings after execution.
```

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

### Get Parent Process ID (ppid)

Source: https://github.com/candid82/joker/blob/master/docs/joker.os.html

Returns the process identifier (PID) of the calling process's parent.

```APIDOC
`(ppid)`

Returns the process id of the caller's parent.
```

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

### Get System Memory Page Size (pagesize)

Source: https://github.com/candid82/joker/blob/master/docs/joker.os.html

Returns the memory page size of the underlying operating system.

```APIDOC
`(pagesize)`

Returns the underlying system's memory page size.
```

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

### Clojure Joker Configuration: Known Macros with Introduced Symbols

Source: https://github.com/candid82/joker/blob/master/README.md

Demonstrates how to specify symbols introduced by a macro within the `:known-macros` configuration. This allows Joker to avoid symbol resolution warnings for implicitly interned symbols.

```Clojure
{:known-macros [[riemann.streams/where [service event]]]}
```

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

### Joker API: var-get function to retrieve var value

Source: https://github.com/candid82/joker/blob/master/docs/joker.core.html

Gets the value in the var object

```Joker
(var-get x)
(var-get ^Var x)
```

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

### Get the name of a Joker namespace

Source: https://github.com/candid82/joker/blob/master/docs/joker.core.html

The `ns-name` function returns the symbolic name of the specified namespace.

```APIDOC
(ns-name ns)^Symbol (ns-name ns)
```

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

### Clojure Symbol Resolution: Using Namespace Aliases

Source: https://github.com/candid82/joker/blob/master/README.md

Provides an alternative to using `:refer :all` by demonstrating how to use namespace aliases and qualified symbols. This approach helps Joker properly resolve symbols and is generally preferred for clarity and linting accuracy.

```Clojure
(:require [clojure.test :as t])
(t/deftest ...)
```

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

### Create Hard Link API (link)

Source: https://github.com/candid82/joker/blob/master/docs/joker.os.html

Creates newname as a hard link to the oldname file.

```APIDOC
link
Function v1.0
(link oldname newname)
```

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

### Get Metadata of Object (Joker)

Source: https://github.com/candid82/joker/blob/master/docs/joker.core.html

Returns the metadata of an object. If no metadata is present, it returns nil.

```APIDOC
(meta obj)
Returns the metadata of obj, returns nil if there is no metadata.
```

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

### Get the Last Item of a Collection (Joker Function)

Source: https://github.com/candid82/joker/blob/master/docs/joker.core.html

Returns the last item in coll, in linear time.

```Joker
(last coll)
```

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

### Get keys of a map (keys)

Source: https://github.com/candid82/joker/blob/master/docs/joker.core.html

Returns a sequence of the map's keys, in the same order as (seq map).

```APIDOC
(keys map)^Seq (keys ^Map map)
```

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

### Joker OS Function: args

Source: https://github.com/candid82/joker/blob/master/docs/joker.os.html

Retrieves the command-line arguments passed to the Joker program, with the first element typically being the program's name.

```Joker
(args)
```

```APIDOC
Returns a sequence of the command line arguments, starting with the program name (normally, joker).
```

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

### Get Distinct Elements (distinct)

Source: https://github.com/candid82/joker/blob/master/docs/joker.core.html

Function that returns a lazy sequence of the elements from a collection with duplicates removed.

```APIDOC
distinct:
  Function v1.0
  (distinct coll) ^Seq (distinct ^Seqable coll)
```

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

### Go `Init` Function for Library Initialization

Source: https://github.com/candid82/joker/blob/master/DEVELOPER.md

Presents the `Init` function generated for Joker libraries. This function is responsible for performing non-function runtime initializations and calling `InternsOrThunks()` to register variables and functions within the namespace.

```Go
func Init() {
{non-fn-inits}
        InternsOrThunks()
}
```

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

### Configuring Library Search Paths with `joker.core/*classpath*`

Source: https://github.com/candid82/joker/blob/master/LIBRARIES.md

Details the usage of the `joker.core/*classpath*` variable to define a list of directories where Joker searches for library source files. It shows how a classpath component is combined with the namespace's converted path to form the full file path.

```Joker
Variable: `joker.core/*classpath*`
Example Component: `/usr/lib/joker`
Target Namespace: `biz.logic`
Resulting Path: `/usr/lib/joker/biz/logic.joke`

Default Behavior (empty *classpath* component):
Uses `lib-path__` pathname (e.g., `./biz/logic.joke` if current directory is `.`)
```

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

### Unescape HTML Entities

Source: https://github.com/candid82/joker/blob/master/docs/joker.html.html

This function converts HTML entities back into their original special characters. For example, it transforms &lt; back into <.

```APIDOC
unescape:
  Signature: (unescape s)
  Description: Unescapes entities like &lt; to become <.
  Parameters:
    s: The string containing HTML entities to be unescaped.
  Returns: The string with HTML entities converted back to special characters.
```

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

### Create Formatted Option Summary Part (Clojure)

Source: https://github.com/candid82/joker/blob/master/docs/joker.tools.cli.html

Transforms a single compiled option specification into a formatted string. It can optionally include its default values if `show-defaults?` is true.

```Clojure
(make-summary-part show-defaults? spec)
```

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

### Get Symbolic Link Status API (lstat)

Source: https://github.com/candid82/joker/blob/master/docs/joker.os.html

Like stat, but if the file is a symbolic link, the result describes the symbolic link.

```APIDOC
lstat
Function v1.0
(lstat filename)
```

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

### Adding Core Namespaces to Joker Executable

Source: https://github.com/candid82/joker/blob/master/DEVELOPER.md

Describes the steps to integrate a new core namespace directly into the Joker executable. This involves placing Joker source code, updating Go configuration files, handling dependencies, and running tests. Core namespaces are automatically available upon Joker startup.

```Joker
1. Code new namespace (Joker or Go) in `core/data/*.joke`.
2. Add to `core/gen_code/gen_code.go` `CoreSourceFiles` array.
3. If dependent on std-lib wrappers:
   a. Edit `core/gen_code/gen_code.go` `import` statement.
   b. Ensure `std/*/a_*.go` files are generated.
4. Create tests in `tests/eval/`.
5. Build Joker: `./run.sh`.
6. Run tests: `./eval-tests.sh` or `./all-tests.sh`.

Namespace availability:
- Automatically added to `*core-namespaces*`.
- Added to `*loaded-libs*` upon loading (or at startup for fast-init Joker).
- In `slow_init` Joker, core libraries (except `joker.core`, `joker.repl`) appear in `loaded-libs` only after `:require`.
```

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

### Get Namespace String (Joker)

Source: https://github.com/candid82/joker/blob/master/docs/joker.core.html

Returns the namespace String of a symbol or keyword. Returns nil if no namespace is present.

```APIDOC
(namespace x)
^String (namespace ^Named x)
Returns the namespace String of a symbol or keyword, or nil if not present.
```

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

### Joker Core Library and System API References

Source: https://github.com/candid82/joker/blob/master/LIBRARIES.md

References to key Joker functions and special variables related to library loading, file handling, and namespace source configuration. These entries indicate which API elements can be queried for documentation using the `(doc)` function within the Joker environment.

```APIDOC
require: Function for loading namespaces
*file*: Special variable for current file path
ns-sources: Function to configure namespace sources
joker.core/*ns-sources*: Vector of namespace source mappings
joker.core/*classpath*: Vector of classpath entries
```

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

### Kill Process by PID API (kill)

Source: https://github.com/candid82/joker/blob/master/docs/joker.os.html

Causes the process with the given PID to exit immediately. Only kills the process itself, not any other processes it may have started.

```APIDOC
kill
Function v1.0.1
(kill pid)
```

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

### doc Macro Documentation

Source: https://github.com/candid82/joker/blob/master/docs/joker.repl.html

Prints documentation for a variable, type, or special form given its name, or for a spec if given a keyword.

```APIDOC
doc:
  Signature: (doc name)
  Parameters:
    name: The name of the var, type, special form, or a keyword for a spec.
```

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

### Get Environment Variable Value API (get-env)

Source: https://github.com/candid82/joker/blob/master/docs/joker.os.html

Returns the value of the environment variable named by the key or nil if the variable is not present in the environment.

```APIDOC
get-env
Function v1.0
(get-env key)
```

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

### Get Name String (Joker)

Source: https://github.com/candid82/joker/blob/master/docs/joker.core.html

Returns the name String of a string, symbol, keyword, or any Named object (e.g., File).

```APIDOC
(name x)
^String (name x)
Returns the name String of a string, symbol, keyword or any Named object (e.g. File).
```

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

### Get Currently Loaded Libraries (Joker Function)

Source: https://github.com/candid82/joker/blob/master/docs/joker.core.html

Returns an UNSORTED set of symbols naming the currently loaded libs.

```Joker
(loaded-libs)
^MapSet (loaded-libs)
```

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

### Go `init` Function for Lazy Namespace Loading

Source: https://github.com/candid82/joker/blob/master/DEVELOPER.md

Demonstrates the Go `init` function's role in Joker's lazy namespace loading mechanism. Upon Joker startup, this `init` function registers the `Init` function as the lazy-initialization callback for the corresponding namespace, ensuring resources are loaded only when needed.

```Go
func init() {
        fooNamespace.Lazy = Init
}
```

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

### Joker OS Function: create

Source: https://github.com/candid82/joker/blob/master/docs/joker.os.html

Creates a new file with default permissions (0666 before umask). If the file already exists, it is truncated.

```Joker
(create name)
```

```APIDOC
Creates the named file with mode 0666 (before umask), truncating it if it already exists.

Parameters:
  name: The path to the file to create.
```

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

### Get Multimethod Dispatch Map (Joker)

Source: https://github.com/candid82/joker/blob/master/docs/joker.core.html

Given a multimethod, returns a map where keys are dispatch values and values are dispatch functions.

```APIDOC
(methods multifn)
^Map (methods multifn)
Given a multimethod, returns a map of dispatch values -> dispatch fns
```

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

### Create Temporary Directory (mkdir-temp)

Source: https://github.com/candid82/joker/blob/master/docs/joker.os.html

Creates a new temporary directory with a unique name based on a pattern. It handles concurrent calls and uses a default temp directory if none is specified. The caller is responsible for cleanup.

```APIDOC
`(mkdir-temp dir pattern)`

Creates a new temporary directory in the directory dir.
The directory name is generated by taking pattern and applying a random string to the end.
If pattern includes a "*", the random string replaces the last "*".
Returns the name of the new directory. If dir is the empty string,
uses the default directory for temporary files (see joker.os/temp-dir).
Multiple programs calling joker.os/mkdir-temp simultaneously will not choose the same directory.
It is the caller's responsibility to remove the directory when no longer needed.
```

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

### get

Source: https://github.com/candid82/joker/blob/master/docs/joker.core.html

Returns the value mapped to key in the given map. If the key is not present, it returns the not-found value if supplied, otherwise nil.

```Joker
(get map key)
(get map key not-found)
```

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

### Get Default Temporary Directory (temp-dir)

Source: https://github.com/candid82/joker/blob/master/docs/joker.os.html

Returns the system's default directory for temporary files. This varies by OS and is not guaranteed to exist or have accessible permissions.

```APIDOC
`(temp-dir)`

Returns the default directory to use for temporary files.
On Unix systems, it returns $TMPDIR if non-empty, else /tmp.
On Windows, it uses GetTempPath, returning the first non-empty
value from %TMP%, %TEMP%, %USERPROFILE%, or the Windows directory.
The directory is neither guaranteed to exist nor have accessible permissions.
```

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

### Clojure Joker Configuration: Known Namespaces

Source: https://github.com/candid82/joker/blob/master/README.md

Shows how to add namespaces to the `:known-namespaces` list in the `.joker` file. This helps resolve 'No namespace found' or 'Unable to resolve symbol' warnings for namespaces that are referred to but not explicitly required in the current file.

```Clojure
{:known-namespaces [clojure.spec.gen.test]}
```

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

### Get Sequence from Collection (Joker)

Source: https://github.com/candid82/joker/blob/master/docs/joker.core.html

Returns a sequence on the collection. If the collection is empty, returns nil. (seq nil) also returns nil.

```APIDOC
seq coll
  coll: The collection to convert to a sequence.
  Returns: A sequence on the collection, or nil if the collection is empty.
```

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

### Create Symbolic Link (symlink)

Source: https://github.com/candid82/joker/blob/master/docs/joker.os.html

Creates a new symbolic link (newname) pointing to an existing file or directory (oldname).

```APIDOC
`(symlink oldname newname)`

Creates newname as a symbolic link to oldname.
```

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

### xml-seq Function for XML Tree Traversal

Source: https://github.com/candid82/joker/blob/master/docs/joker.core.html

Performs a tree sequence traversal on XML elements, as parsed by `xml/parse`, starting from a given root element.

```APIDOC
Function: xml-seq
  Version: v1.0
  Signatures:
    (xml-seq root)
    ^Seq (xml-seq root)
  Parameters:
    root: The root XML element to start the traversal from.
  Returns: A sequence (`^Seq`) of XML elements.
```