branch: externals/yaml
commit 091521769e518513b4db03045404fd8faf7ea8d0
Author: Zachary Romero <zacrom...@posteo.net>
Commit: Zachary Romero <zacrom...@posteo.net>
Add readme file
---
README.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
grammargen.bb | 7 +++++++
2 files changed, 72 insertions(+)
diff --git a/README.md b/README.md
new file mode 100644
index 0000000000..25a298c908
--- /dev/null
+++ b/README.md
@@ -0,0 +1,65 @@
+# yaml.el
+
+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 function provided is as follows:
+
+``` emacs-lisp
+(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`
+- `: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`.
+
+## 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
+
+``` emacs-lisp
+(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 ...)))
+```
+
+
+
+## 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](https://github.com/syohex/emacs-libyaml).
+
+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.
diff --git a/grammargen.bb b/grammargen.bb
index 3a5921fb6c..f494ffb7a9 100755
--- a/grammargen.bb
+++ b/grammargen.bb
@@ -1,5 +1,12 @@
#!/usr/bin/env bb
+;; This file is the Babashka script used to initially generate the YAML
grammer Elisp code.
+;; The program expects to find a yaml-spec-1.2.json file in the same directory
and will
+;; generate the elisp code that should go in the main grammer parsing cond.
Due to certain
+;; hand optimizations made in the Elisp code, the output of this program has
fell out of sync
+;; with what is currently in yaml.el (though I don't find this a big problem
as the YAML spec
+;; should never change).
+
(def package-prefix "yaml")
(def fn-name "yaml--parse-from-grammar")
