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

[/==============================================================================
    Copyright (C) 2001-2011 Joel de Guzman
    Copyright (C) 2001-2011 Hartmut Kaiser
    Copyright (C) 2011 Jamboree 

    Distributed under the Boost Software License, Version 1.0. (See accompanying
    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
===============================================================================/]

[section:seek Qi Seek Parser Directive ]

[heading Description]

The `seek[]` parser-directive skips all input until the subject parser matches.

[heading Header]

    // forwards to <boost/spirit/repository/home/qi/directive/seek.hpp>
    #include <boost/spirit/repository/include/qi_seek.hpp>

Also, see __include_structure__.

[heading Namespace]

[table
    [[Name]]
    [[`boost::spirit::repository::qi::seek`]]
]

[heading Model of]

[:__unary_parser_concept__]

[variablelist Notation
    [[`a`]          [A __parser_concept__.]]
]

[heading Expression Semantics]

Semantics of an expression is defined only where it differs from, or is
not defined in __unary_parser_concept__.

[table
    [[Expression]               [Semantics]]
    [[`seek[a]`]                [Advances until the parser `a` matches.]]
]

[heading Attributes]

See __qi_comp_attr_notation__.

[table
    [[Expression]       [Attribute]]
    [[`seek[a]`]
[``a: A --> seek[a]: A
a: Unused --> seek[a]: Unused``]]
]

[heading Complexity]

[:The overall complexity is defined by the complexity of its subject
parser. The complexity of `seek` itself is O(N), where N is the number
of unsuccessful matches.]

[note *seeking sequence with skipping*

Using `seek[a >> b]` with skipping is inefficient, because when sequence fails, the backtracked position is non-skipped.
The solution is to ensure the input will always be pre-skipped, for example:
``
    seek[lexeme[skip[a >> b]]]
``	
does the trick.]

[heading Example]

[import ../../example/qi/seek.cpp]

The following example shows a simple use case of the `seek[]` directive, parsing C-style comment.
(For the full source of the example, see [@../../example/qi/seek.cpp seek.cpp])

Some namespace aliases:

[reference_qi_seek_namespace]

The input string and its iterators:

[reference_qi_seek_vars]

Parsing and showing the result:

[reference_qi_seek_parse]

[endsect]
Commit	Line	Data
7c673cae FG	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]