ceph/src/boost/libs/spirit/repository/doc/qi/seek.qbk

   1 [/==============================================================================
   2     Copyright (C) 2001-2011 Joel de Guzman
   3     Copyright (C) 2001-2011 Hartmut Kaiser
   4     Copyright (C) 2011 Jamboree
   5
   6     Distributed under the Boost Software License, Version 1.0. (See accompanying
   7     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   8 ===============================================================================/]
   9
  10 [section:seek Qi Seek Parser Directive ]
  11
  12 [heading Description]
  13
  14 The `seek[]` parser-directive skips all input until the subject parser matches.
  15
  16 [heading Header]
  17
  18     // forwards to <boost/spirit/repository/home/qi/directive/seek.hpp>
  19     #include <boost/spirit/repository/include/qi_seek.hpp>
  20
  21 Also, see __include_structure__.
  22
  23 [heading Namespace]
  24
  25 [table
  26     [[Name]]
  27     [[`boost::spirit::repository::qi::seek`]]
  28 ]
  29
  30 [heading Model of]
  31
  32 [:__unary_parser_concept__]
  33
  34 [variablelist Notation
  35     [[`a`]          [A __parser_concept__.]]
  36 ]
  37
  38 [heading Expression Semantics]
  39
  40 Semantics of an expression is defined only where it differs from, or is
  41 not defined in __unary_parser_concept__.
  42
  43 [table
  44     [[Expression]               [Semantics]]
  45     [[`seek[a]`]                [Advances until the parser `a` matches.]]
  46 ]
  47
  48 [heading Attributes]
  49
  50 See __qi_comp_attr_notation__.
  51
  52 [table
  53     [[Expression]       [Attribute]]
  54     [[`seek[a]`]
  55 [``a: A --> seek[a]: A
  56 a: Unused --> seek[a]: Unused``]]
  57 ]
  58
  59 [heading Complexity]
  60
  61 [:The overall complexity is defined by the complexity of its subject
  62 parser. The complexity of `seek` itself is O(N), where N is the number
  63 of unsuccessful matches.]
  64
  65 [note *seeking sequence with skipping*
  66
  67 Using `seek[a >> b]` with skipping is inefficient, because when sequence fails, the backtracked position is non-skipped.
  68 The solution is to ensure the input will always be pre-skipped, for example:
  69 ``
  70     seek[lexeme[skip[a >> b]]]
  71 ``
  72 does the trick.]
  73
  74 [heading Example]
  75
  76 [import ../../example/qi/seek.cpp]
  77
  78 The following example shows a simple use case of the `seek[]` directive, parsing C-style comment.
  79 (For the full source of the example, see [@../../example/qi/seek.cpp seek.cpp])
  80
  81 Some namespace aliases:
  82
  83 [reference_qi_seek_namespace]
  84
  85 The input string and its iterators:
  86
  87 [reference_qi_seek_vars]
  88
  89 Parsing and showing the result:
  90
  91 [reference_qi_seek_parse]
  92
  93 [endsect]