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

Merge: org-ql-defpred

Browse source 
Squashed commit of the following:

commit a0ace307b0de3f5e811f042fd9f0b821a0bbc95c
Author: Adam Porter <adam@alphapapa.net>
Date:   Mon Nov 23 01:11:07 2020 -0600

    Docs: Fix TOC

commit bef9f3c9b5b762070445c76ac3c833e51dd893ba
Author: Adam Porter <adam@alphapapa.net>
Date:   Mon Nov 23 01:09:33 2020 -0600

    Docs: (README.org) Add org-ql-defpred

commit ff0257696fe87764e3289e12ddc336377a9a5d01
Author: Adam Porter <adam@alphapapa.net>
Date:   Mon Nov 23 00:52:06 2020 -0600

    Docs: Improve defpred.org

    Thanks to piyo in #emacsconf@freenode.

commit 18d6d73a99c336cd637c99309ee5d150106b73b7
Author: Adam Porter <adam@alphapapa.net>
Date:   Mon Nov 23 00:35:24 2020 -0600

    Docs: Improve custom predicate tutorial

    Closes #155.  Thanks to Merlin Göttlinger (@mgttlinger) for suggesting
    improvements.

commit b8cbe36fb3
Author: Adam Porter <adam@alphapapa.net>
Date:   Mon Nov 23 00:05:52 2020 -0600

    Docs: Add custom predicate tutorial

commit b1008d0c52
Author: Adam Porter <adam@alphapapa.net>
Date:   Sun Nov 22 19:34:16 2020 -0600

    Docs: Update readme

commit 73d4f95cd4
Merge: 9a2719f 148a193
Author: Adam Porter <adam@alphapapa.net>
Date:   Sun Nov 22 19:29:15 2020 -0600

    Merge branch 'wip/0.6-pre' into wip/define-predicate

...
This commit is contained in:
Adam Porter 2020-11-23 01:13:03 -06:00
parent 148a193ca0
commit 57b3eeba49
9 changed files with 1432 additions and 791 deletions
Download patch file Download diff file Expand all files Collapse all files

64
README.org
View file

@ -258,15 +258,19 @@ The following predicates, in addition to the keyword arguments, can also take a
** Functions / Macros
:PROPERTIES:
:TOC: ignore-children
:TOC: :include descendants
:END:
:CONTENTS:
- [[#agenda-like-views][Agenda-like views]]
- [[#function-org-ql-block][Function: org-ql-block]]
- [[#listing--acting-on-results][Listing / acting-on results]]
- [[#caching][Caching]]
- [[#function-org-ql-select][Function: org-ql-select]]
- [[#function-org-ql-query][Function: org-ql-query]]
- [[#macro-org-ql][Macro: org-ql]]
- [[#custom-predicates][Custom predicates]]
- [[#macro-org-ql-defpred][Macro: org-ql-defpred]]
:END:
- [[#agenda-like-views][Agenda-like views]]
- [[#function-org-ql-block][Function: org-ql-block]]
- [[#listing--acting-on-results][Listing / acting-on results]]
- [[#function-org-ql-select][Function: org-ql-select]]
- [[#function-org-ql-query][Function: org-ql-query]]
- [[#macro-org-ql][Macro: org-ql]]
*** Agenda-like views
@ -405,6 +409,44 @@ Examples:
Expands into a call to ~org-ql-select~ with the same arguments. For convenience, arguments should be unquoted.
*** Custom predicates
+ See: [[file:examples/defpred.org][Custom predicate tutorial]]
**** Macro: =org-ql-defpred=
/Arguments:/ ~(name args docstring &key body preambles normalizers)~
Define an ~org-ql~ selector predicate named ~org-ql--predicate-NAME~. ~NAME~ may be a symbol or a list of symbols: if a list, the first is used as ~NAME~ and the rest are aliases. ~A~ function is only created for ~NAME~, not for aliases, so a normalizer should be used to replace aliases with ~NAME~ in queries (keep reading).
~ARGS~ is a ~cl-defun~-style argument list. ~DOCSTRING~ is the function's docstring.
~BODY~ is the body of the predicate. It will be evaluated with point on the beginning of an Org heading and should return non-nil if the heading's entry is a match.
~PREAMBLES~ and ~NORMALIZERS~ are lists of ~pcase~ forms matched against Org ~QL~ query sexps. They are spliced into ~pcase~ forms in the definitions of the functions ~org-ql--query-preamble~ and ~org-ql--normalize-query~, which see. Those functions are redefined when this macro is expanded, unless variable ~org-ql-defpred-defer~ is non-nil, in which case those functions should be redefined manually after defining predicates by calling ~org-ql--define-query-preamble-fn~ and ~org-ql--define-normalize-query-fn~.
~NORMALIZERS~ are used to normalize query expressions to standard forms. For example, when the predicate has aliases, the aliases should be replaced with predicate names using a normalizer. Also, predicate arguments may be put into a more optimal form so that the predicate has less work to do at query time.
~PREAMBLES~ refer to regular expressions which may be used to search through a buffer directly to a potential match rather than testing the predicate body on each heading. (Naming things is hard.) In each ~pcase~ form in ~PREAMBLES~, the ~pcase~ expression (not the pattern) should be a plist with the following keys, each value of which should be an expression which may refer to variables bound in the pattern:
~:regexp~ Regular expression which searches directly to a potential match.
~:case-fold~ Bound to ~case-fold-search~ around the regexp search.
~:query~ Expression which should replace the query expression, or ~query~ if it should not be changed (e.g. if the regexp is insufficient to determine whether a heading matches, in which case the predicate's body needs to be tested on the heading). If the regexp guarantees a match, this may be simply ~t~, leaving the query expression with no work to do, which improves performance.
For convenience, within the ~pcase~ patterns, the symbol ~predicate-names~ is a special form which is replaced with a pattern matching any of the predicate's name and aliases. For example, if ~NAME~ were:
~(heading h)~
Then if ~NORMALIZERS~ were:
~((`(,predicate-names . ,args) `(heading ,@args)))~
It would be expanded to:
~((`(,(or 'heading 'h) . ,args) `(heading ,@args)))~
** Dynamic block
Org QL provides a dynamic block that lists entries in the current document matching a query. In the header, these parameters are supported:
@ -463,7 +505,11 @@ Simple links may also be written manually in either sexp or non-sexp form, like:
** 0.6-pre
Nothing new yet.
*Added*
+ Macro =org-ql-defpred=, used to define search predicates. (See [[file:examples/defpred.org][tutorial]].)
*Internal*
+ Predicates are now defined more cleanly with a macro (=org-ql-defpred=) that consolidates functionality related to each predicate. This will also allow users to more easily define custom predicates.
** 0.5