| [/============================================================================== |
| Copyright (C) 2001-2010 Hartmut Kaiser |
| Copyright (C) 2001-2010 Joel de Guzman |
| |
| 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:directive Directive] |
| |
| This module includes different generator directives. It includes alignment |
| directives (`left_align[]`, `center[]`, and `right_align[]`), repetition |
| (`repeat[]`), directives controlling automatic delimiting (`verbatim[]`, |
| `no_delimit[]`, and `delimit[]`), controlling case sensitivity (`upper[]` and |
| `lower[]`), field width (`maxwidth[]`), buffering (`buffer[]`), splitting into |
| columns (`columns[]`) and attribute handling (`duplicate[]`, `omit[]`, and |
| `skip[]`). |
| |
| [heading Module Header] |
| |
| // forwards to <boost/spirit/home/karma/directive.hpp> |
| #include <boost/spirit/include/karma_directive.hpp> |
| |
| Also, see __include_structure__. |
| |
| [/////////////////////////////////////////////////////////////////////////////] |
| [section:alignment Alignment Directives (`left_align[]`, `center[]`, `right_align[]`)] |
| |
| [heading Description] |
| |
| The alignment directives allow to left align, right align or center output |
| emitted by other generators into columns of a specified width while using |
| an arbitrary generator to create the padding. |
| |
| [heading Header] |
| |
| For the `left_align[]` directive: |
| |
| // forwards to <boost/spirit/home/karma/directive/left_alignment.hpp> |
| #include <boost/spirit/include/karma_left_alignment.hpp> |
| |
| For the `center[]` directive: |
| |
| // forwards to <boost/spirit/home/karma/directive/center_alignment.hpp> |
| #include <boost/spirit/include/karma_center_alignment.hpp> |
| |
| For the `right_align[]` directive: |
| |
| // forwards to <boost/spirit/home/karma/directive/right_alignment.hpp> |
| #include <boost/spirit/include/karma_right_alignment.hpp> |
| |
| Also, see __include_structure__. |
| |
| [heading Namespace] |
| |
| [table |
| [[Name]] |
| [[`boost::spirit::left_align // alias: boost::spirit::karma::left_align` ]] |
| [[`boost::spirit::center // alias: boost::spirit::karma::center` ]] |
| [[`boost::spirit::right_align // alias: boost::spirit::karma::right_align` ]] |
| ] |
| |
| [heading Model of] |
| |
| [:__unary_generator_concept__] |
| |
| [variablelist Notation |
| [[`a`] [A generator object]] |
| [[`pad`] [A generator object, or a __karma_lazy_argument__ that |
| evaluates to a generator object]] |
| [[`A`, `Pad`] [Attribute types of the generators `a` and `pad`]] |
| [[`width`] [Numeric literal, any unsigned integer value, or |
| a __karma_lazy_argument__ that evaluates to an unsigned |
| integer value]]] |
| |
| [heading Expression Semantics] |
| |
| Semantics of an expression is defined only where it differs from, or is not |
| defined in __unary_generator_concept__. |
| |
| [table |
| [[Expression] [Semantics]] |
| [[`left_align[a]`] [Generate `a` left aligned in a column of |
| width as defined by the preprocessor constant |
| `BOOST_KARMA_DEFAULT_FIELD_LENGTH` |
| (default: 10), while using `space` to emit |
| the necessary padding. This generator succeeds as |
| long as its embedded generator `a` does not |
| fail (unless the underlying output stream |
| reports an error).]] |
| [[`left_align(width)[a]`] [Generate `a` left aligned in a column of |
| the given `width`, while using `space` to emit |
| the necessary padding. This generator succeeds as |
| long as its embedded generator `a` does not |
| fail (unless the underlying output stream |
| reports an error).]] |
| [[`left_align(pad)[a]`] [Generate `a` left aligned in a column of |
| width as defined by the preprocessor constant |
| `BOOST_KARMA_DEFAULT_FIELD_LENGTH` |
| (default: 10), while using the generator `pad` |
| to emit the necessary padding. This generator |
| succeeds as long as its embedded and padding |
| generators `a` and `pad` do not fail (except |
| if the underlying output stream reports an |
| error).]] |
| [[`left_align(width, pad)[a]`] [Generate `a` left aligned in a column of |
| the given `width`, while using the generator |
| `pad` to emit the necessary padding. This |
| generator succeeds as long as its embedded |
| and padding generators `a` and `pad` do not |
| fail (unless the underlying output stream |
| reports an error).]] |
| |
| [[`center[a]`] [Generate `a` centered in a column of |
| width as defined by the preprocessor constant |
| `BOOST_KARMA_DEFAULT_FIELD_LENGTH` |
| (default: 10), while using `space` to emit |
| the necessary padding. This generator succeeds as |
| long as its embedded generator `a` does not |
| fail (unless the underlying output stream |
| reports an error).]] |
| [[`center(width)[a]`] [Generate `a` centered in a column of |
| the given `width`, while using `space` to emit |
| the necessary padding. This generator succeeds as |
| long as its embedded generator `a` does not |
| fail (unless the underlying output stream |
| reports an error).]] |
| [[`center(pad)[a]`] [Generate `a` centered in a column of |
| width as defined by the preprocessor constant |
| `BOOST_KARMA_DEFAULT_FIELD_LENGTH` |
| (default: 10), while using the generator `pad` |
| to emit the necessary padding. This generator |
| succeeds as long as its embedded and padding |
| generators `a` and `pad` do not fail (except |
| if the underlying output stream reports an |
| error).]] |
| [[`center(width, pad)[a]`] [Generate `a` centered in a column of |
| the given `width`, while using the generator |
| `pad` to emit the necessary padding. This |
| generator succeeds as long as its embedded |
| and padding generators `a` and `pad` do not |
| fail (unless the underlying output stream |
| reports an error).]] |
| |
| [[`right_align[a]`] [Generate `a` right aligned in a column of |
| width as defined by the preprocessor constant |
| `BOOST_KARMA_DEFAULT_FIELD_LENGTH` |
| (default: 10), while using `space` to emit |
| the necessary padding. This generator succeeds as |
| long as its embedded generator `a` does not |
| fail (unless the underlying output stream |
| reports an error).]] |
| [[`right_align(width)[a]`] [Generate `a` right aligned in a column of |
| the given `width`, while using `space` to emit |
| the necessary padding. This generator succeeds as |
| long as its embedded generator `a` does not |
| fail (unless the underlying output stream |
| reports an error).]] |
| [[`right_align(pad)[a]`] [Generate `a` right aligned in a column of |
| width as defined by the preprocessor constant |
| `BOOST_KARMA_DEFAULT_FIELD_LENGTH` |
| (default: 10), while using the generator `pad` |
| to emit the necessary padding. This generator |
| succeeds as long as its embedded and padding |
| generators `a` and `pad` do not fail (except |
| if the underlying output stream reports an |
| error).]] |
| [[`right_align(width, pad)[a]`] [Generate `a` right aligned in a column of |
| the given `width`, while using the generator |
| `pad` to emit the necessary padding. This |
| generator succeeds as long as its embedded |
| and padding generators `a` and `pad` do not |
| fail (unless the underlying output stream |
| reports an error).]] |
| ] |
| |
| [note None of the generator directives listed above limits the emitted output |
| to the respective column width. If the emitted output is longer than |
| the specified (or implied) column width, the generated output overruns |
| the column to the right. |
| |
| If the output needs to be limited to a specified column width, use the |
| `maxwidth[]` directive, for instance: |
| `` |
| maxwidth(8)[right_align(12)["1234567890"]] |
| `` |
| which will output (without the quotes): ``" 123456"`` |
| ] |
| |
| [heading Attributes] |
| |
| See __karma_comp_attr_notation__. |
| |
| [table |
| [[Expression] [Attribute]] |
| [[`left_align[]`] |
| [``a: A --> left_align[a]: A |
| a: Unused --> left_align[a]: Unused``]] |
| [[`left_align(width)[]`] |
| [``a: A --> left_align(width)[a]: A |
| a: Unused --> left_align(width)[a]: Unused``]] |
| [[`left_align(pad)[]`] |
| [``a: A, pad: Pad --> left_align(pad)[a]: A |
| a: Unused, pad: Pad --> left_align(pad)[a]: Unused``]] |
| [[`left_align(pad, width)[]`] |
| [``a: A, pad: Pad --> left_align(pad, width)[a]: A |
| a: Unused, pad: Pad --> left_align(pad, width)[a]: Unused``]] |
| |
| [[`center[]`] |
| [``a: A --> center[a]: A |
| a: Unused --> center[a]: Unused``]] |
| [[`center(width)[]`] |
| [``a: A --> center(width)[a]: A |
| a: Unused --> center(width)[a]: Unused``]] |
| [[`center(pad)[]`] |
| [``a: A, pad: Pad --> center(pad)[a]: A |
| a: Unused, pad: Pad --> center(pad)[a]: Unused``]] |
| [[`center(pad, width)[]`] |
| [``a: A, pad: Pad --> center(pad, width)[a]: A |
| a: Unused, pad: Pad --> center(pad, width)[a]: Unused``]] |
| |
| [[`right_align[]`] |
| [``a: A --> right_align[a]: A |
| a: Unused --> right_align[a]: Unused``]] |
| [[`right_align(width)[]`] |
| [``a: A --> right_align(width)[a]: A |
| a: Unused --> right_align(width)[a]: Unused``]] |
| [[`right_align(pad)[]`] |
| [``a: A, pad: Pad --> right_align(pad)[a]: A |
| a: Unused, pad: Pad --> right_align(pad)[a]: Unused``]] |
| [[`right_align(pad, width)[]`] |
| [``a: A, pad: Pad --> right_align(pad, width)[a]: A |
| a: Unused, pad: Pad --> right_align(pad, width)[a]: Unused``]] |
| ] |
| |
| [heading Complexity] |
| |
| [:The overall complexity of the alignment generator directives is defined by |
| the complexity of its embedded and padding generator. The complexity of the |
| left alignment directive generator itself is O(1). The complexity of the |
| center and right alignment directive generators itself is O(N). where `N` |
| is the number of characters emitted by the embedded and padding generators.] |
| |
| [heading Example] |
| |
| [note The test harness for the example(s) below is presented in the |
| __karma_basics_examples__ section.] |
| |
| Some includes: |
| |
| [reference_karma_includes] |
| |
| Some using declarations: |
| |
| [reference_karma_using_declarations_alignment] |
| |
| Basic usage of the alignment generators: |
| |
| [reference_karma_alignment] |
| |
| [endsect] [/ alignment] |
| |
| [/////////////////////////////////////////////////////////////////////////////] |
| [section:repeat Repetition Directive (`repeat[]`)] |
| |
| [heading Description] |
| |
| The repetition directive allows to repeat an arbitrary generator expression |
| while optionally specifying the lower and upper repetition counts. It provides |
| a more powerful and flexible mechanism for repeating a generator. There are |
| grammars that are impractical and cumbersome, if not impossible, for the basic |
| EBNF iteration syntax ([karma_kleene unary `'*'`] and the [karma_plus unary `'+'`]) |
| to specify. Examples: |
| |
| * A file name may have a maximum of 255 characters only. |
| * A specific bitmap file format has exactly 4096 RGB color information. |
| * A 256 bit binary string (1..256 1s or 0s). |
| |
| [heading Header] |
| |
| // forwards to <boost/spirit/home/karma/directive/repeat.hpp> |
| #include <boost/spirit/include/karma_repeat.hpp> |
| |
| Also, see __include_structure__. |
| |
| [heading Namespace] |
| |
| [table |
| [[Name]] |
| [[`boost::spirit::repeat // alias: boost::spirit::karma::repeat` ]] |
| [[`boost::spirit::inf // alias: boost::spirit::karma::inf` ]] |
| ] |
| |
| [heading Model of] |
| |
| [:__unary_generator_concept__] |
| |
| [variablelist Notation |
| [[`a`] [A generator object]] |
| [[`num, num1, num2`][Numeric literals, any unsigned integer value, or |
| a __karma_lazy_argument__ that evaluates to an |
| unsigned integer value]] |
| [[`inf`] [Placeholder expression standing for 'no upper repeat |
| limit']] |
| ] |
| |
| [heading Expression Semantics] |
| |
| Semantics of an expression is defined only where it differs from, or is not |
| defined in __unary_generator_concept__. |
| |
| [table |
| [[Expression] [Semantics]] |
| [[`repeat[a]`] [Repeat the generator `a` zero or more times. |
| This generator succeeds as long as its |
| embedded generator `a` does not fail (except |
| if the underlying output stream reports an |
| error). This variant of `repeat[]` is |
| semantically equivalent to the |
| [karma_kleene Kleene Star operator `*a`]]] |
| [[`repeat(num)[a]`] [Repeat the generator `a` exactly `num` |
| times. This generator succeeds as long as its |
| embedded generator `a` does not fail and |
| as long as the associated attribute |
| (container) contains at least `num` elements |
| (unless the underlying output stream |
| reports an error).]] |
| [[`repeat(num1, num2)[a]`] [Repeat the generator `a` at least `num1` |
| times but not more than `num2` times. This |
| generator succeeds as long as its |
| embedded generator `a` does not fail and |
| as long as the associated attribute |
| (container) contains at least `num1` elements |
| (unless the underlying output stream |
| reports an error). If the associated |
| attribute (container) does contain more |
| than `num2` elements, this directive |
| limits the repeat count to `num2`. ]] |
| [[`repeat(num, inf)[a]`] [Repeat the generator `a` at least `num1` |
| times. No upper limit for the repeat count |
| is set. This generator succeeds as long as |
| its embedded generator `a` does not fail |
| and as long as the associated attribute |
| (container) contains at least `num` elements |
| (unless the underlying output stream |
| reports an error).]] |
| ] |
| |
| [note All failing iterations of the embedded generator will consume one element |
| from the supplied attribute. The overall `repeat[a]` will succeed as long |
| as the iteration criteria (number of successful invocations of the |
| embedded generator) is fulfilled (unless the underlying output stream |
| reports an error).] |
| |
| [heading Attributes] |
| |
| See __karma_comp_attr_notation__. |
| |
| [table |
| [[Expression] [Attribute]] |
| [[`repeat[a]`] |
| [``a: A --> repeat[a]: vector<A> |
| a: Unused --> repeat[a]: Unused``]] |
| [[`repeat(num)[a]`] |
| [``a: A --> repeat(num)[a]: vector<A> |
| a: Unused --> repeat(num)[a]: Unused``]] |
| [[`repeat(num1, num2)[a]`] |
| [``a: A --> repeat(num1, num2)[a]: vector<A> |
| a: Unused --> repeat(num1, num2)[a]: Unused``]] |
| [[`repeat(num, inf)[a]`] |
| [``a: A --> repeat(num, inf)[a]: vector<A> |
| a: Unused --> repeat(num, inf)[a]: Unused``]] |
| ] |
| |
| [important The table above uses `vector<A>` as placeholders only. |
| |
| The notation of `vector<A>` stands for /any STL container/ holding |
| elements of type `A`.] |
| |
| It is important to note, that the `repeat[]` directive does not perform any |
| buffering of the output generated by its embedded elements. That means that |
| any failing element generator might have already generated some output, which |
| is /not/ rolled back. |
| |
| [tip The simplest way to force a `repeat[]` directive to behave as if it did |
| buffering is to wrap it into a buffering directive (see |
| __karma_buffer__): |
| |
| ``buffer[repeat[a]]`` |
| |
| which will /not/ generate any output in case of a failing generator |
| `repeat[a]`. The expression: |
| |
| ``repeat[buffer[a]]`` |
| |
| will not generate any partial output from a generator `a` if it fails |
| generating in the middle of its output. The overall expression will |
| still generate the output as produced by all succeeded invocations of |
| the generator `a`.] |
| |
| [heading Complexity] |
| |
| [:The overall complexity of the repetition generator is defined by the |
| complexity of its embedded generator. The complexity of the repeat itself is |
| O(N), where N is the number of repetitions to execute.] |
| |
| [heading Example] |
| |
| [note The test harness for the example(s) below is presented in the |
| __karma_basics_examples__ section.] |
| |
| Some includes: |
| |
| [reference_karma_includes] |
| |
| Some using declarations: |
| |
| [reference_karma_using_declarations_repeat] |
| |
| Basic usage of `repeat` generator directive: |
| |
| [reference_karma_repeat] |
| |
| [endsect] [/ repeat] |
| |
| [/////////////////////////////////////////////////////////////////////////////] |
| [section:delimit Directives Controlling Automatic Delimiting (`verbatim[]`, `no_delimit[]`, `delimit[]`)] |
| |
| [heading Description] |
| |
| The directives `delimit[]`, `no_delimit[]`, and `verbatim[]` can be used to |
| control automatic delimiting. The directives `verbatim[]` and `no_delimit[]` |
| disable any automatic delimiting, while the directive `delimit[]` (re-)enables |
| automatic delimiting. |
| |
| [heading Header] |
| |
| For the `verbatim[]` directive: |
| |
| // forwards to <boost/spirit/home/karma/directive/verbatim.hpp> |
| #include <boost/spirit/include/karma_verbatim.hpp> |
| |
| For the `no_delimit[]` directive: |
| |
| // forwards to <boost/spirit/home/karma/directive/no_delimit.hpp> |
| #include <boost/spirit/include/karma_no_delimit.hpp> |
| |
| For the `delimit[]` directive: |
| |
| // forwards to <boost/spirit/home/karma/directive/delimit.hpp> |
| #include <boost/spirit/include/karma_delimit.hpp> |
| |
| Also, see __include_structure__. |
| |
| [heading Namespace] |
| |
| [table |
| [[Name]] |
| [[`boost::spirit::verbatim // alias: boost::spirit::karma::verbatim` ]] |
| [[`boost::spirit::no_delimit // alias: boost::spirit::karma::no_delimit` ]] |
| [[`boost::spirit::delimit // alias: boost::spirit::karma::delimit` ]] |
| ] |
| |
| [heading Model of] |
| |
| [:__unary_generator_concept__] |
| |
| [variablelist Notation |
| [[`a`] [A generator object]] |
| [[`d`] [A generator object, or a __karma_lazy_argument__ that |
| evaluates to a generator object]] |
| [[`A`, `D`] [Attribute types of the generators `a` and `d`]]] |
| |
| [heading Expression Semantics] |
| |
| Semantics of an expression is defined only where it differs from, or is not |
| defined in __unary_generator_concept__. |
| |
| [table |
| [[Expression] [Semantics]] |
| [[`delimit[a]`] [Enable automatic delimiting for the embedded generator |
| `a` while using the `space` generator as the |
| delimiting generator. If used inside a `verbatim[]` |
| directive it re-enables the delimiter generator as used |
| outside of this `verbatim[]` instead. The directive succeeds |
| as long as the embedded generator succeeded (unless |
| the underlying output stream reports an error).]] |
| [[`delimit(d)[a]`] [Enable automatic delimiting for the embedded generator |
| `a` while using the generator `d` as the |
| delimiting generator. The directive succeeds |
| as long as the embedded generator succeeded (unless |
| the underlying output stream reports an error).]] |
| [[`verbatim[a]`] [Disable automatic delimiting for the embedded generator |
| `a`. The directive succeeds |
| as long as the embedded generator succeeded (unless |
| the underlying output stream reports an error). This |
| directive it has no effect if it is used when no |
| delimiting is active. When delimiting is active this |
| directive performs a post-delimit step (which is |
| different from the behavior of `no_delimit[]`).]] |
| [[`no_delimit[a]`] [Disable automatic delimiting for the embedded generator |
| `a`. The directive succeeds |
| as long as the embedded generator succeeded (unless |
| the underlying output stream reports an error). This |
| directive it has no effect if it is used when no |
| delimiting is active. When delimiting is active this |
| directive does not perform a post-delimit step (which is |
| different from the behavior of `verbatim[]`.]] |
| ] |
| |
| [heading Attributes] |
| |
| See __karma_comp_attr_notation__. |
| |
| [table |
| [[Expression] [Attribute]] |
| [[`delimit[a]`] |
| [``a: A --> delimit[a]: A |
| a: Unused --> delimit[a]: Unused``]] |
| [[`delimit(d)[a]`] |
| [``a: A, d: D --> delimit(d)[a]: A |
| a: Unused, d: D --> delimit(d)[a]: Unused``]] |
| [[`verbatim[a]`] |
| [``a: A --> verbatim[a]: A |
| a: Unused --> verbatim[a]: Unused``]] |
| [[`no_delimit[a]`] |
| [``a: A --> no_delimit[a]: A |
| a: Unused --> no_delimit[a]: Unused``]] |
| ] |
| |
| [heading Complexity] |
| |
| [:The overall complexity of the generator directives `delimit[]`, `verbatim[]`, |
| and `no_delimit[]` is defined by the complexity of its embedded generators. |
| The complexity of the directives themselves is O(1).] |
| |
| [heading Example] |
| |
| [note The test harness for the example(s) below is presented in the |
| __karma_basics_examples__ section.] |
| |
| Some includes: |
| |
| [reference_karma_includes_simple] |
| |
| Some using declarations: |
| |
| [reference_karma_using_declarations_delimit] |
| |
| Basic usage of `delimit` generator directive: |
| |
| [reference_karma_delimit] |
| |
| [endsect] [/ verbatim/delimit/no_delimit] |
| |
| [/////////////////////////////////////////////////////////////////////////////] |
| [section:upperlower Directives Controlling Case Sensitivity (`upper[]`, `lower[]`)] |
| |
| [heading Description] |
| |
| The generator directives `ns::lower[]` and `ns::upper[]` force their embedded |
| generators to emit lower case or upper case only characters based on the |
| interpretation of the generated characters in the character set defined by |
| `ns` (see __karma_char_encoding_namespace__). |
| |
| [heading Header] |
| |
| // forwards to <boost/spirit/home/karma/directive/upper_lower_case.hpp> |
| #include <boost/spirit/include/karma_upper_lower_case.hpp> |
| |
| Also, see __include_structure__. |
| |
| [heading Namespace] |
| |
| [table |
| [[Name]] |
| [[`ns::lower`]] |
| [[`ns::upper`]] |
| ] |
| |
| In the table above, `ns` represents a __karma_char_encoding_namespace__. |
| |
| [heading Model of] |
| |
| [:The model of `lower[]` and `upper[]` is the model of its subject generator.] |
| |
| [variablelist Notation |
| [[`a`] [A generator object]] |
| [[`A`] [Attribute type of the generator `a`]] |
| [[`ns`] [A __karma_char_encoding_namespace__.]]] |
| |
| [heading Expression Semantics] |
| |
| The `lower[]` and `upper[]` directives have no special generator semantics. |
| They are pure modifier directives. They indirectly influence the way all |
| subject generators work. They add information (the `tag::upper` or `tag::lower`) |
| to the `Modifier` template parameter used while transforming the `proto::expr` |
| into the corresponding generator expression. This is achieved by the |
| following specializations: |
| |
| namespace boost { namespace spirit |
| { |
| template <typename CharEncoding> |
| struct is_modifier_directive< |
| karma::domain |
| , tag::char_code<tag::lower, CharEncoding> > |
| : mpl::true_ |
| {}; |
| |
| template <typename CharEncoding> |
| struct is_modifier_directive< |
| karma::domain |
| , tag::char_code<tag::upper, CharEncoding> > |
| : mpl::true_ |
| }} |
| |
| (for more details see the section describing the compilation process of the |
| __boost_proto__ expression into the corresponding generator expressions). |
| |
| [table |
| [[Expression] [Semantics]] |
| [[`ns::lower[a]`] [Generate `a` as lower case, interpreted in the |
| character set defined by `ns`. The directive succeeds |
| as long as the embedded generator succeeded (unless |
| the underlying output stream reports an error).]] |
| [[`ns::upper[a]`] [Generate `a` as upper case, interpreted in the |
| character set defined by `ns`. The directive succeeds |
| as long as the embedded generator succeeded (unless |
| the underlying output stream reports an error).]] |
| ] |
| |
| [note If both directives are 'active' with regard to a generator, the |
| innermost of those directives takes precedence. For instance: |
| `` |
| generate(sink, ascii::lower['A' << ascii::upper['b']]) |
| `` |
| will generate `"aB"` (without the quotes). |
| |
| Further, the directives will have no effect on generators emitting |
| characters not having an upper case or lower case equivalent in the |
| character set defined by `ns`. |
| ] |
| |
| [heading Attributes] |
| |
| See __karma_comp_attr_notation__. |
| |
| [table |
| [[Expression] [Attribute]] |
| [[`ns:lower[a]`] |
| [``a: A --> ns:lower[a]: A |
| a: Unused --> ns:lower[a]: Unused``]] |
| [[`ns:upper[a]`] |
| [``a: A --> ns:upper[a]: A |
| a: Unused --> ns:upper[a]: Unused``]] |
| ] |
| |
| [heading Complexity] |
| |
| [:The overall complexity of the generator directives `ns::lower[]` and `ns::upper[]` |
| is defined by the complexity of its embedded generators. The directives |
| themselves are compile time only directives, having no impact on runtime |
| performance.] |
| |
| [heading Example] |
| |
| [note The test harness for the example(s) below is presented in the |
| __karma_basics_examples__ section.] |
| |
| Some includes: |
| |
| [reference_karma_includes_simple] |
| |
| Some using declarations: |
| |
| [reference_karma_using_declarations_upperlower] |
| |
| Basic usage of the `upper` and `lower` generator directives: |
| |
| [reference_karma_upperlower] |
| |
| [endsect] [/ upper/lower] |
| |
| [/////////////////////////////////////////////////////////////////////////////] |
| [section:maxwidth Controlling the Maximum Field Width (`maxwidth[]`)] |
| |
| [heading Description] |
| |
| The `maxwidth[]` directive allows to limit (truncate) the overall length of the |
| output generated by the embedded generator. |
| |
| [heading Header] |
| |
| // forwards to <boost/spirit/home/karma/directive/maxwidth.hpp> |
| #include <boost/spirit/include/karma_maxwidth.hpp> |
| |
| Also, see __include_structure__. |
| |
| [table |
| [[Name]] |
| [[`boost::spirit::maxwidth // alias: boost::spirit::karma::maxwidth` ]] |
| ] |
| |
| [heading Model of] |
| |
| [:__unary_generator_concept__] |
| |
| [variablelist Notation |
| [[`a`] [A generator object]] |
| [[`A`] [Attribute type of the generator `a`]] |
| [[`num`] [Numeric literal, any unsigned integer value, or |
| a __karma_lazy_argument__ that evaluates to an unsigned |
| integer value]]] |
| |
| [heading Expression Semantics] |
| |
| Semantics of an expression is defined only where it differs from, or is not |
| defined in __unary_generator_concept__. |
| |
| [table |
| [[Expression] [Semantics]] |
| [[`maxwidth[a]`] [Limit the overall length of the emitted output of |
| the embedded generator (including characters |
| generated by automatic delimiting) to the number |
| of characters as defined by the preprocessor constant |
| `BOOST_KARMA_DEFAULT_FIELD_MAXWIDTH`. Any additional |
| output is truncated. The directive succeeds as long |
| as the embedded generator succeeded (unless |
| the underlying output stream reports an error).]] |
| [[`maxwidth(num)[a]`] [Limit the overall length of the emitted output of |
| the embedded generator (including characters |
| generated by automatic delimiting) to the number |
| of characters as defined by `num`. Any additional |
| output is truncated. The directive succeeds as long |
| as the embedded generator succeeded (unless the |
| underlying output stream reports an error).]] |
| ] |
| |
| [note The `maxwidth[]` generator directive does not pad the generated output |
| to fill the specified column width. If the emitted output is shorter |
| than the specified (or implied) column width, the generated output will |
| be more narrow than the column width. |
| |
| If the output needs to always be equal to a specified column width, use |
| one of the alignment directives `left-align[]`, `center[]`, or |
| `right_align[]`, for instance: |
| `` |
| maxwidth(8)[left_align(8)["1234"]] |
| `` |
| which will output: `"1234 "` (without the quotes). |
| ] |
| |
| [heading Attributes] |
| |
| See __karma_comp_attr_notation__. |
| |
| [table |
| [[Expression] [Attribute]] |
| [[`maxwidth[a]`] |
| [``a: A --> maxwidth[a]: A |
| a: Unused --> maxwidth[a]: Unused``]] |
| [[`maxwidth(num)[a]`] |
| [``a: A --> maxwidth(num)[a]: A |
| a: Unused --> maxwidth(num)[a]: Unused``]] |
| ] |
| |
| [heading Complexity] |
| |
| [:The overall complexity of the generator directive `maxwidth[]` |
| is defined by the complexity of its embedded generator. The complexity of the |
| directive itself is O(N), where `N` is the number of characters generated |
| by the maxwidth directive.] |
| |
| [heading Example] |
| |
| [note The test harness for the example(s) below is presented in the |
| __karma_basics_examples__ section.] |
| |
| Some includes: |
| |
| [reference_karma_includes_simple] |
| |
| Some using declarations: |
| |
| [reference_karma_using_declarations_maxwidth] |
| |
| Basic usage of `maxwidth` generator directive: |
| |
| [reference_karma_maxwidth] |
| |
| [endsect] [/ maxwidth] |
| |
| [/////////////////////////////////////////////////////////////////////////////] |
| [section:buffer Temporary Output Buffering (`buffer[]`)] |
| |
| [heading Description] |
| |
| All generator components (except the __karma_alternative__ generator) pass |
| their generated output directly to the underlying output stream. If a generator |
| fails halfway through, the output generated so far is not 'rolled back'. The |
| buffering generator directive allows to avoid this unwanted output to be |
| generated. It temporarily redirects the output produced by the embedded |
| generator into a buffer. This buffer is flushed to the underlying stream only |
| after the embedded generator succeeded, but is discarded otherwise. |
| |
| [heading Header] |
| |
| // forwards to <boost/spirit/home/karma/directive/buffer.hpp> |
| #include <boost/spirit/include/karma_buffer.hpp> |
| |
| Also, see __include_structure__. |
| |
| [table |
| [[Name]] |
| [[`boost::spirit::buffer // alias: boost::spirit::karma::buffer` ]] |
| ] |
| |
| [heading Model of] |
| |
| [:__unary_generator_concept__] |
| |
| [variablelist Notation |
| [[`a`] [A generator object]] |
| [[`A`] [Attribute type of generator `a`]]] |
| |
| [heading Expression Semantics] |
| |
| Semantics of an expression is defined only where it differs from, or is not |
| defined in __unary_generator_concept__. |
| |
| [table |
| [[Expression] [Semantics]] |
| [[`buffer[a]`] [The embedded generator `a` is invoked but its output |
| is temporarily intercepted and stored in an internal |
| buffer. If `a` succeeds the buffer content is flushed |
| to the underlying output stream, otherwise the buffer |
| content is discarded. The buffer directive succeeds |
| as long as the embedded generator succeeded (unless |
| the underlying output stream reports an error).]] |
| ] |
| |
| [tip If you want to make the buffered generator succeed regardless of the |
| outcome of the embedded generator, simply wrap the `buffer[a]` into an |
| additional optional: `-buffer[a]` (see __karma_optional__).] |
| |
| [heading Attributes] |
| |
| See __karma_comp_attr_notation__. |
| |
| [table |
| [[Expression] [Attribute]] |
| [[`buffer[a]`] |
| [``a: A --> buffer[a]: A |
| a: Unused --> buffer[a]: Unused``]] |
| ] |
| |
| [heading Complexity] |
| |
| [:The overall complexity of the buffering generator directive is defined by the |
| complexity of its embedded generator. The complexity of the buffering |
| directive generator itself is O(N), where N is the number of characters |
| buffered.] |
| |
| [heading Example] |
| |
| [note The test harness for the example(s) below is presented in the |
| __karma_basics_examples__ section.] |
| |
| Some includes: |
| |
| [reference_karma_includes] |
| |
| Some using declarations: |
| |
| [reference_karma_using_declarations_buffer] |
| |
| Basic usage of a buffering generator directive. It shows how the partial |
| output generated in the first example does not show up in the generated output |
| as the plus generator fails (no data is available, see __karma_plus__). |
| |
| [reference_karma_buffer] |
| |
| [endsect] [/ buffer] |
| |
| [/////////////////////////////////////////////////////////////////////////////] |
| [section:omit Consume Attribute (`omit[]` and `skip[]`)] |
| |
| [heading Description] |
| |
| The directives `omit[]` and `skip[]` consumes the attribute type of the |
| embedded generator without generating any output. The `omit[]` directive |
| will still execute the embedded generator while discarding the generated output |
| afterwards. The `skip[]` directive will not execute the embedded generator, but |
| will use it only to extract the exposed attribute type. |
| |
| [heading Header] |
| |
| // forwards to <boost/spirit/home/karma/directive/omit.hpp> |
| #include <boost/spirit/include/karma_omit.hpp> |
| |
| Also, see __include_structure__. |
| |
| [table |
| [[Name]] |
| [[`boost::spirit::omit // alias: boost::spirit::karma::omit` ]] |
| [[`boost::spirit::skip // alias: boost::spirit::karma::skip` ]] |
| ] |
| |
| [heading Model of] |
| |
| [:__unary_generator_concept__] |
| |
| [variablelist Notation |
| [[`a`] [A generator object]] |
| [[`A`] [Attribute type of generator `a`]]] |
| |
| [heading Expression Semantics] |
| |
| Semantics of an expression is defined only where it differs from, or is not |
| defined in __unary_generator_concept__. |
| |
| [table |
| [[Expression] [Semantics]] |
| [[`omit[a]`] [The `omit` directive consumes the attribute type of the |
| embedded generator `A` without generating any output. |
| It succeeds always. The embedded generator is executed |
| and any generated output is discarded.]] |
| [[`skip[a]`] [The `skip` directive consumes the attribute type of the |
| embedded generator `A` without generating any output. |
| It succeeds always. The embedded generator is not |
| executed.]] |
| ] |
| |
| [heading Attributes] |
| |
| See __karma_comp_attr_notation__. |
| |
| [table |
| [[Expression] [Attribute]] |
| [[`omit[a]`] |
| [``a: A --> omit[a]: A |
| a: Unused --> omit[a]: Unused``]] |
| [[`skip[a]`] |
| [``a: A --> skip[a]: A |
| a: Unused --> skip[a]: Unused``]] |
| ] |
| |
| [heading Complexity] |
| |
| [:The overall complexity of the `omit[]` directive depends on the complexity |
| of the embedded generator. The overall complexity of the `skip[]` generator |
| directive is O(1) as it does not generate any output.] |
| |
| [heading Example] |
| |
| [note The test harness for the example(s) below is presented in the |
| __karma_basics_examples__ section.] |
| |
| Some includes: |
| |
| [reference_karma_includes] |
| |
| Some using declarations: |
| |
| [reference_karma_using_declarations_omit] |
| |
| Basic usage of a `omit` generator directive. It shows how it consumes the first |
| element of the provided attribute without generating anything, leaving the |
| second element of the attribute to the non-wrapped `double_` generator. |
| |
| [reference_karma_omit] |
| |
| Generally, this directive is helpful in situations, where the attribute type |
| contains more information (elements) than need to be used to generate the |
| required output. Normally in such situations we would resolve to use semantic |
| actions to explicitly pass the correct parts of the overall attribute to the |
| generators. The `omit` directive helps achieving the same without having to use |
| semantic actions. |
| |
| Consider the attribute type: |
| |
| typedef fusion::vector<int, double, std::string> attribute_type; |
| |
| where we need to generate output only from the first and last element: |
| |
| typedef std::back_insert:iterator<std::string> iterator_type; |
| |
| karma::rule<iterator_type, attribute_type()> r; |
| r = int_[_1 = phoenix::at_c<0>(_val)] << string[_1 = phoenix::at_c<2>(_val)]; |
| |
| std::string str; |
| iterator_type sink(str); |
| generate(sink, r, attribute_type(1, 2.0, "example")); // will generate: '1example' |
| |
| This is error prone and not really readable. The same can be achieved by using |
| the `omit` directive: |
| |
| r = int_ << omit[double_] << string; |
| |
| which is at the same time more readable and more efficient as we don't have to |
| use semantic actions. |
| |
| The semantics of using the `skip[]` directive are identical to the `omit[]` |
| directive, except that it does not actually execute the embedded generator. |
| For this reason it is usually preferable to utilize the `skip[]` directive |
| instead of the `omit[]` directive. On the other hand, the `omit[]` directive |
| is very useful whenever the embedded generator produces side effects (has |
| semantic actions which need to be executed). |
| |
| [endsect] [/ omit] |
| |
| [/////////////////////////////////////////////////////////////////////////////] |
| [section:duplicate Duplicate Attribute (`duplicate[]`)] |
| |
| [heading Description] |
| |
| The directive `duplicate[]` duplicates its attribute to all elements of the |
| embedded generator if this is a sequence generator. Otherwise it does nothing. |
| |
| [heading Header] |
| |
| // forwards to <boost/spirit/home/karma/directive/duplicate.hpp> |
| #include <boost/spirit/include/karma_duplicate.hpp> |
| |
| Also, see __include_structure__. |
| |
| [table |
| [[Name]] |
| [[`boost::spirit::duplicate // alias: boost::spirit::karma::duplicate` ]] |
| ] |
| |
| [heading Model of] |
| |
| [:__unary_generator_concept__] |
| |
| [variablelist Notation |
| [[`a`] [A generator object]] |
| [[`A`] [Attribute type of generator `a`]]] |
| |
| [heading Expression Semantics] |
| |
| Semantics of an expression is defined only where it differs from, or is not |
| defined in __unary_generator_concept__. |
| |
| [table |
| [[Expression] [Semantics]] |
| [[`duplicate[a]`] [The `duplicate` directive duplicates the supplied |
| attribute for all elements of a embedded sequence |
| generator. For all other types of embedded generators |
| it has no effect. It succeeds as long as its embedded |
| generator does not fail.]] |
| ] |
| |
| [heading Attributes] |
| |
| See __karma_comp_attr_notation__. |
| |
| [table |
| [[Expression] [Attribute]] |
| [[`duplicate[a]`] |
| [``a: A --> duplicate[a]: A |
| a: tuple<A, A, ...> --> duplicate[a]: A |
| a: Unused --> duplicate[a]: Unused``]] |
| ] |
| |
| If the embedded generator of the `duplicate[]` directive is a sequence it is |
| expected that all elements of this sequence expose either the same attribute |
| type, an compatible attribute type, or `unused`. In this case, the |
| `duplicate[]` directive exposes the attribute type of its first element. The |
| behavior of the `duplicate[]` directive is undefined if the elements of an |
| embedded sequence do not expose the same attributes. Most likely, the |
| corresponding expression will not compile. |
| |
| [heading Complexity] |
| |
| [:The overall complexity of the `duplicate[]` directive depends on the complexity |
| of the embedded generator.] |
| |
| [heading Example] |
| |
| [note The test harness for the example(s) below is presented in the |
| __karma_basics_examples__ section.] |
| |
| Some includes: |
| |
| [reference_karma_includes] |
| |
| Some using declarations: |
| |
| [reference_karma_using_declarations_duplicate] |
| |
| Basic usage of the `duplicate` generators: |
| |
| [reference_karma_duplicate] |
| |
| [endsect] [/ duplicate] |
| |
| [/////////////////////////////////////////////////////////////////////////////] |
| [section:columns Separate Output Into Columns (`columns[]`)] |
| |
| [heading Description] |
| |
| The `columns[]` directive separates the output emitted by the embedded |
| generator by inserting special column separators. |
| |
| [heading Header] |
| |
| // forwards to <boost/spirit/home/karma/directive/columns.hpp> |
| #include <boost/spirit/include/karma_columns.hpp> |
| |
| Also, see __include_structure__. |
| |
| [table |
| [[Name]] |
| [[`boost::spirit::columns // alias: boost::spirit::karma::columns` ]] |
| ] |
| |
| [heading Model of] |
| |
| [:__unary_generator_concept__] |
| |
| [variablelist Notation |
| [[`a`] [A generator object]] |
| [[`g`] [A generator object, or a __karma_lazy_argument__ that |
| evaluates to a generator object, will be used to emit column |
| separators]] |
| [[`A`] [Attribute type of generator `a`] |
| [[`num`] [Numeric literal, any unsigned integer value, or |
| a __karma_lazy_argument__ that evaluates to an unsigned |
| integer value defining the number of items to emit in between |
| the column separators]]] |
| |
| [heading Expression Semantics] |
| |
| Semantics of an expression is defined only where it differs from, or is not |
| defined in __unary_generator_concept__. |
| |
| [table |
| [[Expression] [Semantics]] |
| [[`columns[a]`] [The `columns` directive invokes a generator after |
| each N-th element of the embedded generator has been |
| emitted. The number of columns is defined by the |
| preprocessor constant `BOOST_KARMA_DEFAULT_COLUMNS`. |
| The column separator used will be `karma::eol`.]] |
| [[`columns(num)[a]`][The `columns` directive invokes a generator after |
| each N-th element of the embedded generator has been |
| emitted. The number of columns is defined by the |
| argument to the directive `num`. |
| The column separator used will be `karma::eol`.]] |
| [[`columns(g)[a]`] [The `columns` directive invokes a generator after |
| each N-th element of the embedded generator has been |
| emitted. The number of columns is defined by the |
| preprocessor constant `BOOST_KARMA_DEFAULT_COLUMNS`. |
| The column separator used will be `g`.]] |
| [[`columns(num, g)[a]`] [The `columns` directive invokes a generator after |
| each N-th element of the embedded generator has been |
| emitted. The number of columns is defined by the |
| argument to the directive `num`. |
| The column separator used will be `g`.]] |
| ] |
| |
| [heading Attributes] |
| |
| See __karma_comp_attr_notation__. |
| |
| [table |
| [[Expression] [Attribute]] |
| [[`columns[a]`] |
| [``a: A --> columns[a]: A |
| a: Unused --> columns[a]: Unused``]] |
| [[`columns(num)[a]`] |
| [``a: A --> columns(num)[a]: A |
| a: Unused --> columns(num)[a]: Unused``]] |
| [[`columns(g)[a]`] |
| [``a: A --> columns(g)[a]: A |
| a: Unused --> columns(g)[a]: Unused``]] |
| [[`columns(num, g)[a]`] |
| [``a: A --> columns(num, g)[a]: A |
| a: Unused --> columns(num, g)[a]: Unused``]] |
| ] |
| |
| [heading Complexity] |
| |
| [:The overall complexity of the `columns` generator directive depends on the |
| complexity of the embedded generator. The complexity of the `columns` generator |
| directive itself is O(N), where `N` is the number of inserted column |
| separators.] |
| |
| [heading Example] |
| |
| [note The test harness for the example(s) below is presented in the |
| __karma_basics_examples__ section.] |
| |
| Some includes: |
| |
| [reference_karma_includes] |
| |
| Some using declarations: |
| |
| [reference_karma_using_declarations_columns] |
| |
| Basic usage of the `columns` generators: |
| |
| [reference_karma_columns] |
| |
| [endsect] [/ columns] |
| |
| [endsect] [/ directives] |
