branch: elpa/parseclj
commit b79b3a54385dc2fb84680078dce929c6bc58b595
Author: Daniel Barreto <[email protected]>
Commit: Daniel Barreto <[email protected]>
Add documentation to `parseclj-ast.el`
---
parseclj-ast.el | 38 ++++++++++++++++++++++++++++++++++----
parseclj.el | 11 +++++++----
2 files changed, 41 insertions(+), 8 deletions(-)
diff --git a/parseclj-ast.el b/parseclj-ast.el
index 95958a662d..873bb49648 100644
--- a/parseclj-ast.el
+++ b/parseclj-ast.el
@@ -33,12 +33,11 @@
(defun parseclj-ast-node (type position &rest attributes)
"Create an AST node with given TYPE and POSITION.
-
-Other ATTRIBUTES can be given as a flat list of key-value pairs. "
+Other ATTRIBUTES can be given as a flat list of key-value pairs."
(apply 'a-list :node-type type :position position attributes))
(defun parseclj-ast-node? (node)
- "Return `t' if the given NODE is a Clojure AST node."
+ "Return t if the given NODE is a Clojure AST node."
(and (consp node)
(consp (car node))
(eq :node-type (caar node))))
@@ -48,12 +47,17 @@ Other ATTRIBUTES can be given as a flat list of key-value
pairs. "
(a-get node :node-type))
(defun parseclj-ast-leaf-node? (node)
- "Return `t' if the given ast NODE is a leaf node."
+ "Return t if the given ast NODE is a leaf node."
(member (parseclj-ast-node-type node) parseclj--leaf-tokens))
;; Parse/reduce strategy functions
(defun parseclj-ast--reduce-leaf (stack token options)
+ "Put into the STACK an AST leaf node based on TOKEN.
+Ignores white spaces and comments.
+
+OPTIONS is an association list. See `parseclj-parse' for more information
+on available options."
(if (member (parseclj-lex-token-type token) '(:whitespace :comment))
stack
(cons
@@ -64,6 +68,13 @@ Other ATTRIBUTES can be given as a flat list of key-value
pairs. "
stack)))
(defun parseclj-ast--reduce-leaf-with-lexical-preservation (stack token
options)
+ "Put into STACK an AST leaf node based on TOKEN.
+This function is very similar to `parseclj-ast--reduce-leaf', but unlike
+it, takes into account tokens representing white space or comments, and
+saves them into the STACK.
+
+OPTIONS is an association list. See `parseclj-parse' for more information
+on available options."
(let ((token-type (parseclj-lex-token-type token))
(top (car stack)))
(if (member token-type '(:whitespace :comment))
@@ -78,6 +89,14 @@ Other ATTRIBUTES can be given as a flat list of key-value
pairs. "
(parseclj-ast--reduce-leaf stack token options))))
(defun parseclj-ast--reduce-branch (stack opening-token children options)
+ "Reduce STACK with an AST branch node representing a collection of tokens.
+Ignores discard tokens.
+
+OPENING-TOKEN is a lex token representing an opening paren, bracket or
+brace.
+CHILDREN is the collection of nodes to be reduced into the AST branch node.
+OPTIONS is an association list. See `parseclj-parse' for more information
+on available options."
(let* ((pos (a-get opening-token :pos))
(type (parseclj-lex-token-type opening-token))
(type (cl-case type
@@ -97,6 +116,17 @@ Other ATTRIBUTES can be given as a flat list of key-value
pairs. "
stack)))))
(defun parseclj-ast--reduce-branch-with-lexical-preservation (stack
opening-token children options)
+ "Reduce STACK with an AST branch node representing a collection of tokens.
+Similar to `parseclj-ast--reduce-branch', but reduces discard tokens as
+well. Nodes produced by this function have a `:lexical-preservation'
+key set to t.
+
+OPENING-TOKEN is a lex token representing an opening paren, bracket or
+brace.
+CHILDREN is the collection of tokens to be reduced into the AST branch
+node.
+OPTIONS is an association list. See `parseclj-parse' for more information
+on available options."
(if (eq :discard (parseclj-lex-token-type opening-token))
(cons (parseclj-ast-node :discard (a-get opening-token :pos) :children
children) stack)
(let* ((stack (funcall #'parseclj-ast--reduce-branch stack opening-token
children options))
diff --git a/parseclj.el b/parseclj.el
index 8d5698300a..ef59a4153b 100644
--- a/parseclj.el
+++ b/parseclj.el
@@ -33,7 +33,6 @@
(require 'cl-lib)
(require 'subr-x)
(require 'a)
-
(require 'parseclj-lex)
(require 'parseedn)
(require 'parseclj-ast)
@@ -191,17 +190,21 @@ errors.
OPTIONS is an association list which is passed on to the reducing
functions. Additionally the following options are recognized
-- :fail-fast
+- `:fail-fast'
Raise an error when a parse error is encountered, rather than continuing
with a partial result.
-- :value-p
+- `:value-p'
A predicate function to differentiate values from tokens and
whitespace. This is needed when scanning the stack to see if any
reductions can be performed. By default anything that isn't a token is
considered a value. This can be problematic when parsing with
`:lexical-preservation', and which case you should provide an
implementation that also returns falsy for :whitespace, :comment, and
- :discard AST nodes."
+ :discard AST nodes.
+- `:tag-readers'
+ An association list that describes tag handler functions for any possible
+ tag. This options in only available in `parseedn-read', for more
+ information, please refer to its documentation."
(let ((fail-fast (a-get options :fail-fast t))
(value-p (a-get options :value-p (lambda (e) (not (parseclj-lex-token?
e)))))
(stack nil)
