[O] new tag query parser [5/5] -- a (very) brief guide to the code

[Christopher Genovese]

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.