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

Docs: org-ql, org-ql-query

Browse source 
Also rename org-ql--query to org-ql-query.
This commit is contained in:
Adam Porter 2019-06-08 04:24:50 -05:00
parent fc5647aea3
commit 4d186d7054
2 changed files with 33 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

30
README.org
View file

@ -107,6 +107,36 @@ Here are some other examples:
(closed = today))))
#+END_SRC
** Functions / Macros
*** Macro: ~org-ql~
/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.
~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~.
If ~NARROW~ is non-nil, query will run without widening the buffer (the default is to widen and search the entire buffer).
If ~MARKERS~ is non-nil, ~org-agenda-ng--add-markers~ is used to add markers to each item, pointing to the item in its source buffer. In this case, ~ACTION~ should return an Org element.
*** Function: ~org-ql-query~
/Arguments:/ ~(buffers-or-files query &key action narrow sort)~
Return items matching ~QUERY~ in ~BUFFERS-OR-FILES~.
~QUERY~ is an ~org-ql~ query sexp.
~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.
If ~NARROW~ is non-nil, buffers are not widened.
~SORT~ is either nil, in which case items are not sorted; or one or a list of defined ~org-ql~ sorting methods: ~date~, ~deadline~, ~scheduled~, ~todo~, and ~priority~.
** Predicates
Arguments are listed next to predicate names, when applicable.

6
org-ql.el
View file

@ -58,7 +58,7 @@ This list should not contain any duplicates.")
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'
`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
@ -81,7 +81,7 @@ buffer. In this case, ACTION should return an Org element."
;; maybe this should be on the agenda-ng side.
(->> ,action
org-ql--add-markers)))))
`(org-ql--query ,buffers-or-files
`(org-ql-query ,buffers-or-files
',pred-body
:action ,action
:narrow ,narrow
@ -98,7 +98,7 @@ buffer. In this case, ACTION should return an Org element."
;;;; Functions
(cl-defun org-ql--query (buffers-or-files query &key action narrow sort)
(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.