From 6bb2db93921e70293fb2f73f6cfe51811a9b28db Mon Sep 17 00:00:00 2001 From: Adam Porter Date: Fri, 20 Nov 2020 08:22:41 -0600 Subject: [PATCH] Docs: Improve query explanation See #92. --- README.org | 2 +- org-ql.info | 79 +++++++++++++++++++++++++++-------------------------- 2 files changed, 42 insertions(+), 39 deletions(-) diff --git a/README.org b/README.org index 741e745..2d7f300 100644 --- a/README.org +++ b/README.org @@ -165,7 +165,7 @@ Show a sparse tree for ~QUERY~ in ~BUFFER~ and return number of results. The tr - [[#datetime-predicates][Date/time predicates]] :END: -An =org-ql= query is a lisp form which may contain arbitrary lisp forms, as well as certain built-in predicates. It is byte-compiled into a predicate function which is tested with point on each heading in an Org buffer; when it returns non-nil, the heading matches the query. +An =org-ql= query is a Lisp expression which may contain arbitrary expressions, as well as calling certain built-in predicates. It is byte-compiled into a predicate function which is tested with point on each heading in an Org buffer; when it returns non-nil, the heading matches the query. When possible, certain built-in predicates are optimized away to whole-buffer regular expression searches, which are much faster to search for than testing the predicate on each heading. *Notes:* + Bare strings like ~"string"~ are automatically converted to ~(regexp "string")~ predicates. diff --git a/org-ql.info b/org-ql.info index 519f605..da41319 100644 --- a/org-ql.info +++ b/org-ql.info @@ -318,10 +318,13 @@ File: README.info, Node: Queries, Next: Functions / Macros, Prev: Commands, =========== • • • • - An org-ql query is a lisp form which may contain arbitrary lisp -forms, as well as certain built-in predicates. It is byte-compiled into -a predicate function which is tested with point on each heading in an -Org buffer; when it returns non-nil, the heading matches the query. + An org-ql query is a Lisp expression which may contain arbitrary +expressions, as well as calling certain built-in predicates. It is +byte-compiled into a predicate function which is tested with point on +each heading in an Org buffer; when it returns non-nil, the heading +matches the query. When possible, certain built-in predicates are +optimized away to whole-buffer regular expression searches, which are +much faster to search for than testing the predicate on each heading. *Notes:* • Bare strings like ‘"string"’ are automatically converted to @@ -1342,40 +1345,40 @@ Node: org-ql-view-sidebar6349 Node: org-ql-view-recent-items6705 Node: org-ql-sparse-tree7189 Node: Queries7989 -Node: Non-sexp query syntax8897 -Node: General predicates10604 -Node: Ancestor/descendant predicates16017 -Node: Date/time predicates17145 -Node: Functions / Macros19800 -Node: Agenda-like views20055 -Node: Listing / acting-on results21460 -Node: Dynamic block26655 -Node: Links29353 -Node: Tips30040 -Node: Changelog30358 -Node: 05-pre31042 -Node: 04932281 -Node: 04832559 -Node: 04732906 -Node: 04633301 -Node: 04533701 -Node: 04434060 -Node: 04334417 -Node: 04234612 -Node: 04134771 -Node: 0435012 -Node: 03238945 -Node: 03139324 -Node: 0339521 -Node: 02342496 -Node: 02242724 -Node: 02142992 -Node: 0243191 -Node: 0147226 -Node: Notes47327 -Node: Comparison with Org Agenda searches47489 -Node: org-sidebar48361 -Node: License48640 +Node: Non-sexp query syntax9100 +Node: General predicates10807 +Node: Ancestor/descendant predicates16220 +Node: Date/time predicates17348 +Node: Functions / Macros20003 +Node: Agenda-like views20258 +Node: Listing / acting-on results21663 +Node: Dynamic block26858 +Node: Links29556 +Node: Tips30243 +Node: Changelog30561 +Node: 05-pre31245 +Node: 04932484 +Node: 04832762 +Node: 04733109 +Node: 04633504 +Node: 04533904 +Node: 04434263 +Node: 04334620 +Node: 04234815 +Node: 04134974 +Node: 0435215 +Node: 03239148 +Node: 03139527 +Node: 0339724 +Node: 02342699 +Node: 02242927 +Node: 02143195 +Node: 0243394 +Node: 0147429 +Node: Notes47530 +Node: Comparison with Org Agenda searches47692 +Node: org-sidebar48564 +Node: License48843  End Tag Table