Skip to content

zkry/yaml.el

Repository files navigation

yaml.el

MELPA

yaml.el is a YAML parser written in Emacs List without any external dependencies. It provides an interface similar to the Emacs JSON parsing utility. The functions provided are as follows:

(yaml-parse-string string &rest args)

The following keyword args are accepted:

  • :object-type specifies the Lisp data structure to store parsed objects data in. It takes the following symbols:
    • hash-table (default)
    • alist
    • plist
  • :object-key-type specifies how map keys should be handled. It takes the following symbols:
    • string
    • symbol (default) Use symbols as keys. If :object-type is plist, this becomes the same as keyword.
    • keyword Always use keywords as keys.
  • :sequence-type specifies the Lisp data structure to store the parsed sequences in. It takes the following symbols:
    • array (default)
    • list
  • :null-object specifies the lisp object to use for nulls. Defaults to the symbol :null.
  • :false-object specifies the lisp object to use for false. Defaults to the symbol :false.
(yaml-encode object)

The function yaml-encode will encode a Lisp object to a YAML string.

Installation

Until this is published to MELPA you will need to use the code from this repo directly. You can put yaml.el in you load path directly or use a tool like use-package or straight.el.

Examples

(require 'yaml)

(yaml-parse-string "
recipe:
  ingredients:
  - milk
  - eggs
  - oil
  - flour
  duration: 10
  steps: null" :object-type 'alist
               :sequence-type 'array
               :null-object :empty)

;; => (("recipe" ("ingredients" . ["milk" "eggs" "oil" "flour"]) ("duration" . 10) ("steps" . :empty)))

(yaml-parse-string "
translations:
  one: бір
  two: екі
  three: үш")

;; => #s(hash-table ... data ("translations" #s(hash-table ...)))


(yaml-encode '("omitted" ((count . 3) (value . 10) (items ("ruby" "diamond"))) "omitted"))

;; => "
- omitted
- count: 3
  value: 10
  items:
    ruby: [diamond]
- omitted"

Caveats

Since this is implemented in Emacs Lisp performance is probably not the best. An alternative implementation using libyaml exists and can be found here.

If you have a very deeply nested YAML file and your max-lisp-eval-depth variable is set too low, these is a chance that you might hit the maximum Lisp eval depth limit. In the future I may work on changing the parsing algorithm to avoid this problem but in the meantime you can bump up the max-lisp-eval-depth variable in your config.

Development

You can run the tests by executing

$ ~/path/to/git-repo/yaml.el
$ emacs -batch -l ert -l yaml.el -l yaml-tests.el -f ert-run-tests-batch-and-exit