clj-yaml.core — clj-commons/clj-yaml 1.0.26

Parse and generate YAML.

Please strongly prefer these high-level functions:

• parse-stream
• parse-string
• generate-stream
• generate-string
• marked? - relevant to :mark option when parsing only
• unmark - relevant to :mark option when parsing only

If history were to be rewritten we might have started with the above as our public API.

The clj-commons/clj-yaml team noticed that folks were using other parts of this namespace in the wild and therefore continue to support them.

If you find yourself using something in clj-yaml not listed above, it could be you are doing so to overcome a limitation that we could address in clj-yaml itself. If that's the case, we encourage you to work with us to potentially improve clj-yaml for everybody. You can start by raising an issue and/or reaching out to us on Slack.

General notes:

• We don't do any wrapping/conversion of SnakeYAML exceptions. The SnakeYAML base exception is org.yaml.snakeyaml.error.YAMLException.
• Original YAML elements order is preserved with ordered set and map data structures, currently via org.flatland/ordered lib.

default-dumper-options clj

(default-dumper-options)

⚙️ low level, please consider higher level clj-yaml.core API first

Returns internal default SnakeYAML dumper options.

• preserves clj-yaml backward compat by explicitly setting option to split long lines to false. The current default in SnakeYAML used to be false but has become true.

Consider instead make-dumper-options

default-loader-options clj

(default-loader-options)

⚙️ low level, please consider higher level clj-yaml.core API first

Returns internal default SnakeYAML loader options.

Consider instead make-loader-options

flow-styles clj

⚙️ low level, please consider higher level clj-yaml.core API first

Internal mappings to SnakeYAML's internal flow styles

generate-stream clj

(generate-stream writer data & opts)

Dump Clojure data structure as YAML to writer.

See generate-string for & opts

generate-string clj

(generate-string data & opts)

Return a string of YAML from Clojure data structure.

Relevant & opts (opts are keyword args, see docs):

• :dumper-options map of (see docs for example usage.):
  • :flow-style can be:
    • :auto - let SnakeYAML decide
    • :block - indented syntax
    • :flow - collapsed syntax
    • default: :auto
  • :indent - spaces to block indent
    • default: 2
  • :indicator-indent - spaces to indent after indicator
    • default: 0

make-dumper-options clj

(make-dumper-options {:keys [flow-style indent indicator-indent]})

⚙️ low level, please consider higher level clj-yaml.core API first

Returns internal SnakeYAML dumper options. See generate-string for description of options.

make-loader-options clj

(make-loader-options &
                     {:keys [max-aliases-for-collections allow-recursive-keys
                             allow-duplicate-keys]})

⚙️ low level, please consider higher level clj-yaml.core API first

Returns internal SnakeYAML loader options. See parse-string for description of options.

make-yaml clj

(make-yaml &
           {:keys [unknown-tag-fn dumper-options unsafe mark
                   max-aliases-for-collections allow-recursive-keys
                   allow-duplicate-keys]})

⚙️ low level, please consider higher level clj-yaml.core API first

Returns internal SnakeYAML encoder/decoder.

See parse-string and generate-string for description of options.

mark clj

(mark start end marked)

⚙️ low level, please consider higher level clj-yaml.core API first

Returns internal structure wrapping marked with start and end positional data.

marked? clj

(marked? m)

Returns true if m was marked with positional data.

See docs.

parse-stream clj

(parse-stream reader & opts)

Returns Clojure data structures for stream of YAML read from reader.

See parse-string for & opts

parse-string clj

(parse-string yaml-string & opts)

Returns parsed yaml-string as Clojure data structures.

Valid & opts (opts are keyword args, see docs):

• :key-fn - Single-argument fn, arg is a map with :key; called on YAML keys, return replaces YAML key.
  • default behaviour: see :keywords
  • overrides :keywords, consider using this option instead of :keywords
  • see docs
• :keywords - when true attempts to convert YAML keys to Clojure keywords, else makes no conversion
  • default: true.
  • ignored when :key-fn is specified
  • when clj-yaml detects that a YAML key cannot be converted to a legal Clojure keyword it leaves the key as is.
  • detection is not sophisticated and clj-yaml will produce invalid Clojure keywords, so although our default is true here, false can be a better choice.
  • consider instead using :key-fn
  • see docs
• :load-all - when true loads all YAML documents from yaml-string and returns a vector of parsed docs. Else only first YAML document is loaded, and return is that individual parsed doc.
  • default: false
• :unknown-tag-fn - Single-argument fn, arg is map with keys :tag and :value; return replaces the YAML tag and value.
  • default behaviour: clj-yaml throws on unknown tags.
  • see docs for example usage.
• :max-aliases-for-collections the maximum number of YAML aliases for collections (sequences and mappings).
  • Default: 50
  • throws when value is exceeded.
• :allow-recursive-keys - when true allows recursive keys for mappings. Only checks the case where the key is the direct value.
  • Default: false
• :allow-duplicate-keys - when false throws on duplicate keys.
  • Default: true - last duplicate key wins.
• :unsafe - when true attempt to load tagged elements to Java objects, else prohibits via throw.
  • default: false
  • WARNING: be very wary of parsing unsafe YAML. See docs
• :mark - when true position of YAML input is tracked and returned in alternate structure.
  • default: false
  • see docs

Note: clj-yaml will only recognize the first of :unsafe, :mark or :unknown-tag-fn

unmark clj

(unmark m)

Returns m without positional data wrapper, else m if not wrapped.

See docs.

YAMLCodec clj protocol

⚙️ low level, please consider higher level clj-yaml.core API first

A protocol to translate to/from Clojure and SnakeYAML data structures

decode clj

(decode data opts)

Decode SnakeYAML -> Clojure

encode clj

(encode data)

Encode Clojure -> SnakeYAML