From mboxrd@z Thu Jan 1 00:00:00 1970 From: Christopher Genovese Subject: new tag query parser [5/5] -- a (very) brief guide to the code Date: Thu, 16 Aug 2012 00:04:40 -0400 Message-ID: Mime-Version: 1.0 Content-Type: multipart/alternative; boundary=e89a8ff24965b9b91c04c75a2501 Return-path: Received: from eggs.gnu.org ([208.118.235.92]:41670) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1T1rKR-0007Ua-KX for emacs-orgmode@gnu.org; Thu, 16 Aug 2012 00:05:04 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1T1rKQ-0006lI-5q for emacs-orgmode@gnu.org; Thu, 16 Aug 2012 00:05:03 -0400 Received: from mail-pz0-f41.google.com ([209.85.210.41]:55718) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1T1rKP-0006kb-T0 for emacs-orgmode@gnu.org; Thu, 16 Aug 2012 00:05:02 -0400 Received: by dadi14 with SMTP id i14so361321dad.0 for ; Wed, 15 Aug 2012 21:05:00 -0700 (PDT) List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: emacs-orgmode@gnu.org --e89a8ff24965b9b91c04c75a2501 Content-Type: text/plain; charset=ISO-8859-1 A few comments that might help navigate the new parser code in org-tag-query-parse.el. All diffs are relative to the 7.8.11 org.el. Let me know if you have any questions. * High Level Changes Two existing org functions are altered: 1. org-make-tags-matcher 2. org-scan-tags The changes to the latter are minor, only defining two new let-bindings to capture information already grabbed, and a slightly modified regex. A unified diff between the new and old org-scan-tags is given in the comments preceding the function in the new code. * Low Level Entry Points 1. org-tag-query-parse -- the workhorse function 2. org-todo-query-parse -- handles /!? style todo components Tag style and /!? todo style queries are handled in a unified way; org-tag-query-parse delegates the latter to org-todo-query-parse but manages the overall parsing. Note that /!? style matches must either end the query string or end the current parenthesized expression. For instance, "-(foo+bar/!{^T}-TODO)|LEVEL==5" is a valid query. * Utilities 1. org-match-cond 2. org-read-balanced-string 3. org-read-quoted-string-in-query 4. org-tquery-error 5. org-defhash-at-compile The first is a macro that lets the parser be expressed in very readable terms. It does much of its work at compile-time, and produces code that is optimized in several ways. This makes it beneficial to byte-compile org-tag-query-parse.el. The second and third parse delimited strings, the first with balanced delimiters and doubling for escape, the second using standard string semantics. The fourth handles errors, giving useful information in messages. The fifth is a macro that makes it pleasant to define literal hash tables that will be defined at both compile and load time. See examples of use in the code. --e89a8ff24965b9b91c04c75a2501 Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable A few comments that might= help navigate the new parser code in
org-tag-= query-parse.el. All diffs are relative to the 7.8.11 org.el.
Let me know if you have a= ny questions.

* High Level Changes

=A0 Two existing org functions are altered:
=A0 1. org-make-tags-matc= her
=A0 2. org-scan-tags

=A0 The changes to the latter are minor, only defini= ng two new
=A0 let-bindings to capture informa= tion already grabbed, and a slightly
=A0 modified regex. A uni= fied diff between the new and old org-scan-tags

* Low Level Entry Points

= =A0 1. org-tag-query-pars= e=A0 -- the workhorse function
=A0 2. org-todo-query-par= se -- handles /!? style todo components

=A0 Tag style and /!? todo style = queries are handled in a unified way;
=A0 org-tag-query-parse d= elegates the latter to org-todo-query-parse but
=A0 end the query string = or end the current parenthesized expression. For
=A0 instance, "-(foo+bar/!{^T}-TODO)|LEVEL=3D=3D5" is a valid = query.

* Utilities
=A0 1. org-= match-cond
=A0 2. org-read-balanced-= string=A0=A0
=A0 3. org-read-quoted-string-in= -query
=A0 4. org-tquery-error
=A0 5. org-defhash-at-compile

=A0 The first is a macro that lets the parser be exp= ressed in very
=A0 readable terms. It does muc= h of its work at compile-time, and produces
=A0 code that is optimize= d in several ways. This makes it beneficial to
=A0 byte-compile org-tag-query-parse.el.

=A0 The second and third parse delimited strings, th= e first with
=A0 balanced delimiters and doubl= ing for escape, the second using
=A0 standard string seman= tics.

=A0 The fourth handles errors, giving useful information in message= s.

=A0 The fifth is a macro that makes it pleasant to d= efine literal
=A0 hash tables that will be def= ined at both compile and load time.
=A0 See examples of use i= n the code.

--e89a8ff24965b9b91c04c75a2501--