jiri/org-ql
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Tidy: Docstrings, symbol names

Browse source
This commit is contained in:
Adam Porter 2019-06-08 04:30:52 -05:00
parent 4d186d7054
commit 2722d87460
2 changed files with 21 additions and 7 deletions
Download patch file Download diff file Expand all files Collapse all files

12
README.org
View file

@ -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.

16
org-ql.el
View file

@ -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,