Skip to content

YS Internals Library

This library serves 2 purposes. It provides functions for working with YS code from within a YS program/file.

It also provides functions that are wrappers around common Clojure functions so that they can be used in places where functions are not allowed; like in dot chaining operations.

Load the library before using its full name or an alias:

use: ys

YS Functions🔗

  • compile — Compile a YS string to a Clojure string

  • eval — Evaluate a YS string

  • load-file — Load a YS file path

  • load-pod — Load a Babashka Pod

  • unload-pods — Unload all loaded pods

  • use — Use a YS or Clojure library found in YSPATH. Normally called as use, not ys/use.

Using Modules🔗

The use form loads a module and optionally aliases or refers its names. Without a source option, YAMLScript searches the directories in YSPATH. The :path option searches one directory, and :file loads one exact .ys, .clj, or .cljc file. The :url option loads an actual HTTP or HTTPS source-file URL.

Prefer one grouped mapping when loading multiple modules:

use:
  fs:
  str:

Bare short names that identify bundled modules expand into ys:: module names and receive matching aliases. The scalar form use: http fs ipc ys loads four such aliases. A bundled short name with options does not imply an alias, so use http: :all means use ys::http: :all. Other short and fully qualified module names retain their existing behavior.

use foo::bar: :path './lib'
use foo::bar: :file './lib/foo/bar.ys'
use foo::bar: :url 'https://example.com/foo/bar.ys'

The :from option accepts one coordinate supported by Grenadine's clojurestar.deps library. Maven coordinates use normal dotted group names. Gist coordinates may name a file and full commit SHA. GitHub coordinates name one source file at a branch, tag, or commit.

use clojure::math::combinatorics:
  :from 'mvn:org.clojure/math.combinatorics@0.3.0/clojure.math.combinatorics'
use medley:
  :from 'mvn:dev.weavejester/medley@1.10.0/medley.core'
use mathy:
  :from 'gist:ingydotnet/f70409675d234aa4f2fe379cd975a4f5/mathy.clj'
use grenadine::require-deps:
  :from 'github:clojurestar/grenadine/v0.1.12/src/grenadine/require_deps.cljc'

When the name on the left is a short name, it becomes an alias for the namespace provided by :from. An explicit :as option overrides that implicit alias. A qualified name on the left must match the namespace provided by :from. Generic Git repositories and dependency coordinate maps are not accepted.

Use :as to add an alias, :get to refer selected names, :all to refer all names, :none to refer none, and :not to refer all except selected names. A slash in a :get name renames it, as in old-name/new-name. With no selection option, use loads the module for qualified access without referring any names. The :none option remains as an explicit spelling of the same behavior.

use foo::bar: :as bar :get one two/second
use foo::baz: :all :not internal
use foo::quux: :as quux :none

Selection options on ys::std replace the automatically referred standard set for the current namespace. For example, use std: :not read write keeps all standard names except file input and output, while preserving user definitions with those names. Bare use: std only creates the std alias.

The former require function is retired and reports an error directing callers to use.

Macro Wrapper Functions🔗

  • for — An eager version of Clojure's lazy for macro
  • if — Wrapper around the Clojure if special form
  • when — Wrapper around the Clojure when macro