From 2722d874605b13ae48cadd75df1820438b2b46b3 Mon Sep 17 00:00:00 2001 From: Adam Porter Date: Sat, 8 Jun 2019 04:30:52 -0500 Subject: [PATCH] Tidy: Docstrings, symbol names --- README.org | 12 +++++++++--- org-ql.el | 16 ++++++++++++---- 2 files changed, 21 insertions(+), 7 deletions(-) diff --git a/README.org b/README.org index b1903da..ead7d66 100644 --- a/README.org +++ b/README.org @@ -113,9 +113,13 @@ Here are some other examples: /Arguments:/ ~(buffers-or-files pred-body &key sort narrow markers action)~ -Find entries in ~BUFFERS-OR-FILES~ that match ~PRED-BODY~, and return the results of running ~ACTION-FN~ on each matching entry. +Find entries in ~BUFFERS-OR-FILES~ that match ~QUERY~, and return the results of running ~ACTION-FN~ on each matching entry. -~ACTION~ is a sexp which will be evaluated at each matching entry with point at the beginning of its heading. It is passed to ~org-ql--query~ as a lambda. By default, ~org-element-headline-parser~ is called to return an Org element. +~BUFFERS-OR-FILES~ is a form which should evaluate to one (or a list of) file(s) or buffer(s). + +~QUERY~ is an ~org-ql~ query sexp, unquoted. + +~ACTION~ is a sexp which will be evaluated at each matching entry with point at the beginning of its heading. It is passed to ~org-ql-query~ as a lambda. By default, ~org-element-headline-parser~ is called to return an Org element. ~SORT~ is a user defined sorting function, or an unquoted list of one or more sorting methods, including: ~date~, ~deadline~, ~scheduled~, ~todo~, and ~priority~. @@ -129,7 +133,9 @@ If ~MARKERS~ is non-nil, ~org-agenda-ng--add-markers~ is used to add markers to Return items matching ~QUERY~ in ~BUFFERS-OR-FILES~. -~QUERY~ is an ~org-ql~ query sexp. +~BUFFERS-OR-FILES~ is a one (or a list of) file(s) or buffer(s). + +~QUERY~ is an ~org-ql~ query sexp (quoted, since this is a function). ~ACTION~ is a function which is called on each matching entry, with point at the beginning of its heading. For example, ~org-element-headline-parser~ may be used to parse an entry into an Org element (note that it must be called with a limit argument, so a lambda must be used to do so). Also see ~org-ql--add-markers~, which may be used to add markers compatible with Org Agenda code. diff --git a/org-ql.el b/org-ql.el index 06c8438..20667ec 100644 --- a/org-ql.el +++ b/org-ql.el @@ -52,9 +52,14 @@ This list should not contain any duplicates.") (push (list :name ',pred-name :fn ',fn-name :docstring ,docstring) org-ql-predicates) (cl-defun ,fn-name ,args ,docstring ,@body)))) -(cl-defmacro org-ql (buffers-or-files pred-body &key sort narrow markers +(cl-defmacro org-ql (buffers-or-files query &key sort narrow markers (action '(org-element-headline-parser (line-end-position)))) - "Find entries in BUFFERS-OR-FILES that match PRED-BODY, and return the results of running ACTION-FN on each matching entry. + "Find entries in BUFFERS-OR-FILES that match QUERY, and return the results of running ACTION-FN on each matching entry. + +BUFFERS-OR-FILES is a form which should evaluate to one (or a +list of) file(s) or buffer(s). + +QUERY is an `org-ql' query sexp, unquoted. ACTION is a sexp which will be evaluated at each matching entry with point at the beginning of its heading. It is passed to @@ -82,7 +87,7 @@ buffer. In this case, ACTION should return an Org element." (->> ,action org-ql--add-markers))))) `(org-ql-query ,buffers-or-files - ',pred-body + ',query :action ,action :narrow ,narrow :sort ',sort)) @@ -101,7 +106,10 @@ buffer. In this case, ACTION should return an Org element." (cl-defun org-ql-query (buffers-or-files query &key action narrow sort) "Return items matching QUERY in BUFFERS-OR-FILES. -QUERY is an `org-ql' query sexp. +BUFFERS-OR-FILES is a one (or a list of) file(s) or buffer(s). + +QUERY is an `org-ql' query sexp (quoted, since this is a +function). ACTION is a function which is called on each matching entry, with point at the beginning of its heading. For example,