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) (cl-defmacro org-ql-defpred (name args docstring &key body preambles normalizers)
"Define an `org-ql' selector predicate named `org-ql--predicate-NAME'. "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 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 is used as NAME and the rest are aliases. A function is only
normalized to the name using NORMALIZERS). ARGS is a created for NAME, not for aliases, so a normalizer should be used
`cl-defun'-style argument list. DOCSTRING is the function's to replace aliases with NAME in queries (keep reading).
docstring. BODY is the body of the predicate.
Predicate bodies will be evaluated with point on the beginning of ARGS is a `cl-defun'-style argument list. DOCSTRING is the
an Org heading and should return non-nil if the heading's entry function's docstring.
is a match.
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 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 NORMALIZERS are used to normalize query expressions to standard
example, predicate aliases are replaced with predicate names. 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 Also, predicate arguments may be put into a more optimal form so
that the predicate has less work to do at query time. that the predicate has less work to do at query time.
PREAMBLES refer to regular expressions which may be used to PREAMBLES refer to regular expressions which may be used to
search through a buffer directly to a potential match (rather search through a buffer directly to a potential match rather than
than testing the predicate body on each heading). (Naming things testing the predicate body on each heading. (Naming things is
is hard.) In each `pcase' form in PREAMBLES, the expression hard.) In each `pcase' form in PREAMBLES, the `pcase'
should be a plist with the following keys, each value of which expression (not the pattern) should be a plist with the following
should be an expression which may refer to variables bound in the keys, each value of which should be an expression which may refer
pattern: to variables bound in the pattern:
:regexp Regular expression which searches directly to a :regexp Regular expression which searches directly to a
potential match. potential match.
:case-fold Bound to `case-fold-search' around the regexp search. :case-fold Bound to `case-fold-search' around the regexp search.
:query Expression which should replace the query, or `query' :query Expression which should replace the query expression,
if it should not be changed (e.g. if the regexp is or `query' if it should not be changed (e.g. if the
insufficient to determine whether a heading regexp is insufficient to determine whether a
matches, in which case the predicate's body needs heading matches, in which case the predicate's body
to be tested on the heading). 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 For convenience, within the `pcase' patterns, the symbol
`predicate-names' is a special form which is replaced with a `predicate-names' is a special form which is replaced with a