Merge: org-ql-defpred
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
parent
148a193ca0
commit
57b3eeba49
9 changed files with 1432 additions and 791 deletions
192
org-ql.info
192
org-ql.info
|
|
@ -63,6 +63,7 @@ Functions / Macros
|
|||
|
||||
* Agenda-like views::
|
||||
* Listing / acting-on results::
|
||||
* Custom predicates::
|
||||
|
||||
Changelog
|
||||
|
||||
|
|
@ -565,11 +566,13 @@ File: README.info, Node: Functions / Macros, Next: Dynamic block, Prev: Queri
|
|||
|
||||
•
|
||||
• •
|
||||
• • •
|
||||
• • • • •
|
||||
•
|
||||
* Menu:
|
||||
|
||||
* Agenda-like views::
|
||||
* Listing / acting-on results::
|
||||
* Custom predicates::
|
||||
|
||||
|
||||
File: README.info, Node: Agenda-like views, Next: Listing / acting-on results, Up: Functions / Macros
|
||||
|
|
@ -606,7 +609,7 @@ File: README.info, Node: Agenda-like views, Next: Listing / acting-on results,
|
|||
the block header, otherwise the header is formed automatically.
|
||||
|
||||
|
||||
File: README.info, Node: Listing / acting-on results, Prev: Agenda-like views, Up: Functions / Macros
|
||||
File: README.info, Node: Listing / acting-on results, Next: Custom predicates, Prev: Agenda-like views, Up: Functions / Macros
|
||||
|
||||
4.3.2 Listing / acting-on results
|
||||
---------------------------------
|
||||
|
|
@ -737,6 +740,84 @@ File: README.info, Node: Listing / acting-on results, Prev: Agenda-like views,
|
|||
Expands into a call to ‘org-ql-select’ with the same arguments.
|
||||
For convenience, arguments should be unquoted.
|
||||
|
||||
|
||||
File: README.info, Node: Custom predicates, Prev: Listing / acting-on results, Up: Functions / Macros
|
||||
|
||||
4.3.3 Custom predicates
|
||||
-----------------------
|
||||
|
||||
• See: Custom predicate tutorial (examples/defpred.org)
|
||||
|
||||
1. 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)))’
|
||||
|
||||
|
||||
File: README.info, Node: Dynamic block, Next: Links, Prev: Functions / Macros, Up: Usage
|
||||
|
||||
|
|
@ -859,7 +940,15 @@ File: README.info, Node: 06-pre, Next: 05, Up: Changelog
|
|||
5.1 0.6-pre
|
||||
===========
|
||||
|
||||
Nothing new yet.
|
||||
*Added*
|
||||
• Macro org-ql-defpred, used to define search predicates. (See
|
||||
tutorial (examples/defpred.org).)
|
||||
|
||||
*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.
|
||||
|
||||
|
||||
File: README.info, Node: 05, Next: 049, Prev: 06-pre, Up: Changelog
|
||||
|
|
@ -1348,54 +1437,55 @@ GPLv3
|
|||
|
||||
Tag Table:
|
||||
Node: Top225
|
||||
Node: Contents1606
|
||||
Node: Screenshots1729
|
||||
Node: Installation1847
|
||||
Node: Quelpa2485
|
||||
Node: Usage2928
|
||||
Node: Commands3326
|
||||
Node: org-ql-search3799
|
||||
Node: helm-org-ql5449
|
||||
Node: org-ql-view5861
|
||||
Node: org-ql-view-sidebar6361
|
||||
Node: org-ql-view-recent-items6717
|
||||
Node: org-ql-sparse-tree7201
|
||||
Node: Queries8001
|
||||
Node: Non-sexp query syntax9112
|
||||
Node: General predicates10819
|
||||
Node: Ancestor/descendant predicates16232
|
||||
Node: Date/time predicates17360
|
||||
Node: Functions / Macros20015
|
||||
Node: Agenda-like views20270
|
||||
Node: Listing / acting-on results21675
|
||||
Node: Dynamic block26870
|
||||
Node: Links29568
|
||||
Node: Tips30255
|
||||
Node: Changelog30573
|
||||
Node: 06-pre31269
|
||||
Node: 0531375
|
||||
Node: 04932852
|
||||
Node: 04833126
|
||||
Node: 04733473
|
||||
Node: 04633868
|
||||
Node: 04534268
|
||||
Node: 04434627
|
||||
Node: 04334984
|
||||
Node: 04235179
|
||||
Node: 04135340
|
||||
Node: 0435581
|
||||
Node: 03239514
|
||||
Node: 03139893
|
||||
Node: 0340090
|
||||
Node: 02343065
|
||||
Node: 02243293
|
||||
Node: 02143561
|
||||
Node: 0243760
|
||||
Node: 0147795
|
||||
Node: Notes47896
|
||||
Node: Comparison with Org Agenda searches48058
|
||||
Node: org-sidebar48930
|
||||
Node: License49209
|
||||
Node: Contents1628
|
||||
Node: Screenshots1751
|
||||
Node: Installation1869
|
||||
Node: Quelpa2507
|
||||
Node: Usage2950
|
||||
Node: Commands3348
|
||||
Node: org-ql-search3821
|
||||
Node: helm-org-ql5471
|
||||
Node: org-ql-view5883
|
||||
Node: org-ql-view-sidebar6383
|
||||
Node: org-ql-view-recent-items6739
|
||||
Node: org-ql-sparse-tree7223
|
||||
Node: Queries8023
|
||||
Node: Non-sexp query syntax9134
|
||||
Node: General predicates10841
|
||||
Node: Ancestor/descendant predicates16254
|
||||
Node: Date/time predicates17382
|
||||
Node: Functions / Macros20037
|
||||
Node: Agenda-like views20335
|
||||
Node: Listing / acting-on results21740
|
||||
Node: Custom predicates26961
|
||||
Node: Dynamic block30452
|
||||
Node: Links33150
|
||||
Node: Tips33837
|
||||
Node: Changelog34155
|
||||
Node: 06-pre34851
|
||||
Node: 0535291
|
||||
Node: 04936768
|
||||
Node: 04837042
|
||||
Node: 04737389
|
||||
Node: 04637784
|
||||
Node: 04538184
|
||||
Node: 04438543
|
||||
Node: 04338900
|
||||
Node: 04239095
|
||||
Node: 04139256
|
||||
Node: 0439497
|
||||
Node: 03243430
|
||||
Node: 03143809
|
||||
Node: 0344006
|
||||
Node: 02346981
|
||||
Node: 02247209
|
||||
Node: 02147477
|
||||
Node: 0247676
|
||||
Node: 0151711
|
||||
Node: Notes51812
|
||||
Node: Comparison with Org Agenda searches51974
|
||||
Node: org-sidebar52846
|
||||
Node: License53125
|
||||
|
||||
End Tag Table
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue