gitweb.ps.run Git - toc/blob - antlr4-cpp-runtime-4.9.2-source/runtime/src/tree/xpath/XPath.h

   1 /* Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
   2  * Use of this file is governed by the BSD 3-clause license that
   3  * can be found in the LICENSE.txt file in the project root.
   4  */
   5
   6 #pragma once
   7
   8 #include "antlr4-common.h"
   9
  10 namespace antlr4 {
  11 namespace tree {
  12 namespace xpath {
  13
  14   /// Represent a subset of XPath XML path syntax for use in identifying nodes in
  15   /// parse trees.
  16   ///
  17   /// <para>
  18   /// Split path into words and separators {@code /} and {@code //} via ANTLR
  19   /// itself then walk path elements from left to right. At each separator-word
  20   /// pair, find set of nodes. Next stage uses those as work list.</para>
  21   ///
  22   /// <para>
  23   /// The basic interface is
  24   /// <seealso cref="XPath#findAll ParseTree.findAll"/>{@code (tree, pathString, parser)}.
  25   /// But that is just shorthand for:</para>
  26   ///
  27   /// <pre>
  28   /// <seealso cref="XPath"/> p = new <seealso cref="XPath#XPath XPath"/>(parser, pathString);
  29   /// return p.<seealso cref="#evaluate evaluate"/>(tree);
  30   /// </pre>
  31   ///
  32   /// <para>
  33   /// See {@code org.antlr.v4.test.TestXPath} for descriptions. In short, this
  34   /// allows operators:</para>
  35   ///
  36   /// <dl>
  37   /// <dt>/</dt> <dd>root</dd>
  38   /// <dt>//</dt> <dd>anywhere</dd>
  39   /// <dt>!</dt> <dd>invert; this must appear directly after root or anywhere
  40   /// operator</dd>
  41   /// </dl>
  42   ///
  43   /// <para>
  44   /// and path elements:</para>
  45   ///
  46   /// <dl>
  47   /// <dt>ID</dt> <dd>token name</dd>
  48   /// <dt>'string'</dt> <dd>any string literal token from the grammar</dd>
  49   /// <dt>expr</dt> <dd>rule name</dd>
  50   /// <dt>*</dt> <dd>wildcard matching any node</dd>
  51   /// </dl>
  52   ///
  53   /// <para>
  54   /// Whitespace is not allowed.</para>
  55
  56   class ANTLR4CPP_PUBLIC XPath {
  57   public:
  58     static const std::string WILDCARD; // word not operator/separator
  59     static const std::string NOT; // word for invert operator
  60
  61     XPath(Parser *parser, const std::string &path);
  62     virtual ~XPath() {}
  63
  64     // TODO: check for invalid token/rule names, bad syntax
  65     virtual std::vector<std::unique_ptr<XPathElement>> split(const std::string &path);
  66
  67     static std::vector<ParseTree *> findAll(ParseTree *tree, std::string const& xpath, Parser *parser);
  68
  69     /// Return a list of all nodes starting at {@code t} as root that satisfy the
  70     /// path. The root {@code /} is relative to the node passed to
  71     /// <seealso cref="#evaluate"/>.
  72     virtual std::vector<ParseTree *> evaluate(ParseTree *t);
  73
  74   protected:
  75     std::string _path;
  76     Parser *_parser;
  77
  78     /// Convert word like {@code *} or {@code ID} or {@code expr} to a path
  79     /// element. {@code anywhere} is {@code true} if {@code //} precedes the
  80     /// word.
  81     virtual std::unique_ptr<XPathElement> getXPathElement(Token *wordToken, bool anywhere);
  82   };
  83
  84 } // namespace xpath
  85 } // namespace tree
  86 } // namespace antlr4