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

WIP

Browse source
This commit is contained in:
Adam Porter 2020-11-22 14:21:33 -06:00
parent f14d84fd48
commit b448be874a
1 changed files with 33 additions and 21 deletions
Download patch file Download diff file Expand all files Collapse all files

54
org-ql.el
View file

@ -905,40 +905,52 @@ PREDICATES should be the value of `org-ql-predicates'."
(cl-defmacro org-ql-defpred (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 (which should be
normalized to the name using NORMALIZERS). ARGS is a
`cl-defun'-style argument list. DOCSTRING is the function's
docstring. BODY is the body of the predicate.
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).
Predicate bodies 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.
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.
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-preamble-fn' and `org-ql--define-normalize-query'.
NORMALIZERS are used to normalize queries to standard forms. For
example, predicate aliases are replaced with predicate names.
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 expression
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:
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, 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).
: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