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)))) (closed = today))))
#+END_SRC #+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 ** Predicates
Arguments are listed next to predicate names, when applicable. 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 ACTION is a sexp which will be evaluated at each matching entry
with point at the beginning of its heading. It is passed to 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. is called to return an Org element.
SORT is a user defined sorting function, or an unquoted list of 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. ;; maybe this should be on the agenda-ng side.
(->> ,action (->> ,action
org-ql--add-markers))))) org-ql--add-markers)))))
`(org-ql--query ,buffers-or-files `(org-ql-query ,buffers-or-files
',pred-body ',pred-body
:action ,action :action ,action
:narrow ,narrow :narrow ,narrow
@ -98,7 +98,7 @@ buffer. In this case, ACTION should return an Org element."
;;;; Functions ;;;; 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. "Return items matching QUERY in BUFFERS-OR-FILES.
QUERY is an `org-ql' query sexp. QUERY is an `org-ql' query sexp.