123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151 |
- [/==============================================================================
- Copyright (C) 2001-2011 Hartmut Kaiser
- Copyright (C) 2001-2011 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 Karma Confix Generator]
- [heading Description]
- The __karma__ `confix` generator is a generator directive component
- allowing to embed any generated ouput inside an opening (a prefix) and a
- closing (a suffix). A simple example is a C comment: `/* This is a C comment */`
- which can be generated using the `confix` generator as:
- `confix("/*", "*/")["This is a C comment"]`. The general syntax for using the
- `confix` is:
- confix(prefix, suffix)[subject]
- which results in generating a sequence equivalent to
- prefix << subject << suffix
- Using the `confix` component instead of the explicit sequence has the advantage
- of being able to encapsulate the prefix and the suffix into a separate generator
- construct. The following code snippet illustrates the idea:
- // Define a metafunction allowing to compute the type of the confix()
- // construct
- namespace traits
- {
- using namespace boost::spirit;
- template <typename Prefix, typename Suffix = Prefix>
- struct confix_spec
- : spirit::result_of::terminal<repository::tag::confix(Prefix, Suffix)>
- {};
- };
- // Define a helper function allowing to create a confix() construct from
- // arbitrary prefix and suffix generators
- template <typename Prefix, typename Suffix>
- typename traits::confix_spec<Prefix, Suffix>::type
- confix_spec(Prefix const& prefix, Suffix const& suffix)
- {
- using namespace boost::spirit;
- return repository::confix(prefix, suffix);
- }
- // Define a helper function to construct a HTML tag from the tag name
- inline typename traits::confix_spec<std::string>::type
- tag (std::string const& tagname)
- {
- return confix_spec("<" + tagname + ">", "</" + tagname + ">");
- }
- // Define generators for different HTML tags the HTML tag
- typedef traits::confix_spec<std::string>::type ol = tag("ol"); // <ol>...</ol>
- typedef traits::confix_spec<std::string>::type li = tag("li"); // <li>...</li>
- Now, for instance, the above definitions allow to generate the HTML 'ol' tag
- using a simple: `ol["Some text"]` (which results in `<ol>Some text</ol>`).
- [heading Header]
- // forwards to <boost/spirit/repository/home/karma/directive/confix.hpp>
- #include <boost/spirit/repository/include/karma_confix.hpp>
- [heading Synopsis]
- confix(prefix, suffix)[subject]
- [heading Parameters]
- [table
- [[Parameter] [Description]]
- [[`prefix`] [The generator construct to use to format the
- opening (the prefix). The prefix is the part
- generated /before/ any output as generated by
- the `subject`.]]
- [[`suffix`] [The generator construct to use to format the
- ending (the suffix). The suffix is the part
- generated /after/ any output as generated by
- the `subject`.]]
- [[`subject`] [The generator construct to use to format the
- actual output in between the `prefix` and `suffix`
- parts.]]
- ]
- All three parameters can be arbitrary complex generators themselves.
- [heading Attribute]
- The `confix` component exposes the attribute type of its subject as its own
- attribute type. If the `subject` does not expose any attribute (the type is
- `unused_type`), then the `confix` does not expose any attribute either.
- a: A --> confix(p, s)[a]: A
- [note This notation is used all over the Spirit documentation and reads as:
- Given, `a` is generator, and `A` is the type of the attribute of generator
- `a`, then the type of the attribute exposed by `confix(p, s)[a]` will be
- `A` as well.]
- [heading Example]
- The following example shows simple use cases of the `confix` generator. We will
- illustrate its usage by generating different comment styles and a function
- prototype (for the full example code see here:
- [@../../example/karma/confix.cpp confix.cpp])
- [import ../../example/karma/confix.cpp]
- [heading Prerequisites]
- In addition to the main header file needed to include the core components
- implemented in __karma__ we add the header file needed for the new `confix`
- generator.
- [karma_confix_includes]
- To make all the code below more readable we introduce the following namespaces.
- [karma_confix_namespace]
- [heading Generating Different Comment Styles]
- We will show how to generate different comment styles. First we will generate
- a C++ comment:
- [karma_confix_cpp_comment]
- This code snippet will obviouly generate `// This is a comment \n `. Similarily
- generating a 'C'-style comment proves to be straightforward:
- [karma_confix_c_comment]
- which again will generate `/* This is a comment */ `.
- [heading Generating a Function Prototype]
- Generating a function prototype given a function name a vector or parameter
- names is simple as well:
- [karma_confix_function]
- which generates the expected output: `func(par1,par2,par3)`.
- [endsect]
|