From: rankoo Date: Sun, 4 Jul 2010 03:37:50 +0000 (+0000) Subject: API support for DocBook 5: X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=d93090ad4953dea3d11a8186609a1bad69ea7a00;p=docbook-dsssl API support for DocBook 5: -> Relax NG grammar for API support -> Test documents to work with new grammar -> Design Documents of BoostBook grammar --- diff --git a/docbook/relaxng/api/design/BoostBook_DTD_Library.png b/docbook/relaxng/api/design/BoostBook_DTD_Library.png new file mode 100644 index 000000000..d9e2376fa Binary files /dev/null and b/docbook/relaxng/api/design/BoostBook_DTD_Library.png differ diff --git a/docbook/relaxng/api/design/BoostBook_DTD_Namespace.png b/docbook/relaxng/api/design/BoostBook_DTD_Namespace.png new file mode 100644 index 000000000..97bda4813 Binary files /dev/null and b/docbook/relaxng/api/design/BoostBook_DTD_Namespace.png differ diff --git a/docbook/relaxng/api/src/api.rng b/docbook/relaxng/api/src/api.rng new file mode 100644 index 000000000..b34578039 --- /dev/null +++ b/docbook/relaxng/api/src/api.rng @@ -0,0 +1,1213 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docbook/relaxng/api/tests/any.xml b/docbook/relaxng/api/tests/any.xml new file mode 100644 index 000000000..ffa13c1c5 --- /dev/null +++ b/docbook/relaxng/api/tests/any.xml @@ -0,0 +1,481 @@ + + + + + Kevlin Henney + + + + 2001 + Kevlin Henney + + + + 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) + + + + + Safe, generic container for single values of different value types + + + + + + + Boost.Any + +
+ Introduction + + There are times when a generic (in the sense of + general as opposed to + template-based programming) type is needed: + variables that are truly variable, accommodating values of many + other more specific types rather than C++'s normal strict and + static types. We can distinguish three basic kinds of generic + type: + + + + Converting types that can hold one of a number of + possible value types, e.g. int and + string, and freely convert between them, for + instance interpreting 5 as "5" or + vice-versa. Such types are common in scripting and other + interpreted + languages. + boost::lexical_cast + supports such conversion functionality. + + + + Discriminated types that contain values of different types but + do not attempt conversion between them, i.e. 5 is + held strictly as an int and is not implicitly + convertible either to "5" or to + 5.0. Their indifference to interpretation but + awareness of type effectively makes them safe, generic + containers of single values, with no scope for surprises from + ambiguous conversions. + + + + Indiscriminate types that can refer to anything but are + oblivious to the actual underlying type, entrusting all forms + of access and interpretation to the programmer. This niche is + dominated by void *, which offers plenty of scope + for surprising, undefined behavior. + + + + The boost::any class + (based on the class of the same name described in "Valued + Conversions" by Kevlin Henney, C++ + Report 12(7), July/August 2000) is a variant value type + based on the second category. It supports copying of any value + type and safe checked extraction of that value strictly against + its type. A similar design, offering more appropriate operators, + can be used for a generalized function adaptor, + any_function, a generalized iterator adaptor, + any_iterator, and other object types that need + uniform runtime treatment but support only compile-time template + parameter conformance. +
+ +
+ Examples + + + + + The following code demonstrates the syntax for using + implicit conversions to and copying of any objects: + + +#include <list> +#include <boost/any.hpp> + +using boost::any_cast; +typedef std::list<boost::any> many; + +void append_int(many & values, int value) +{ + boost::any to_append = value; + values.push_back(to_append); +} + +void append_string(many & values, const std::string & value) +{ + values.push_back(value); +} + +void append_char_ptr(many & values, const char * value) +{ + values.push_back(value); +} + +void append_any(many & values, const boost::any & value) +{ + values.push_back(value); +} + +void append_nothing(many & values) +{ + values.push_back(boost::any()); +} + + + The following predicates follow on from the previous + definitions and demonstrate the use of queries on any + objects: + + +bool is_empty(const boost::any & operand) +{ + return operand.empty(); +} + +bool is_int(const boost::any & operand) +{ + return operand.type() == typeid(int); +} + +bool is_char_ptr(const boost::any & operand) +{ + try + { + any_cast<const char *>(operand); + return true; + } + catch(const boost::bad_any_cast &) + { + return false; + } +} + +bool is_string(const boost::any & operand) +{ + return any_cast<std::string>(&operand); +} + +void count_all(many & values, std::ostream & out) +{ + out << "#empty == " + << std::count_if(values.begin(), values.end(), is_empty) << std::endl; + out << "#int == " + << std::count_if(values.begin(), values.end(), is_int) << std::endl; + out << "#const char * == " + << std::count_if(values.begin(), values.end(), is_char_ptr) << std::endl; + out << "#string == " + << std::count_if(values.begin(), values.end(), is_string) << std::endl; +} + + + The following type, patterned after the OMG's Property Service, defines name-value pairs for arbitrary value types: + + +struct property +{ + property(); + property(const std::string &, const boost::any &); + + std::string name; + boost::any value; +}; + +typedef std::list<property> properties; + + + The following base class demonstrates one approach to + runtime polymorphism based callbacks that also require arbitrary + argument types. The absence of virtual member templates requires + that different solutions have different trade-offs in terms of + efficiency, safety, and generality. Using a checked variant type + offers one approach: + + +class consumer +{ +public: + virtual void notify(const any &) = 0; + ... +}; + +
+ + +
+ <emphasis>ValueType</emphasis> requirements + + Values are strongly informational objects for which + identity is not significant, i.e. the focus is principally on + their state content and any behavior organized around + that. Another distinguishing feature of values is their + granularity: normally fine-grained objects representing simple + concepts in the system such as quantities. + + As the emphasis of a value lies in its state not its + identity, values can be copied and typically assigned one to + another, requiring the explicit or implicit definition of a + public copy constructor and public assignment operator. Values + typically live within other scopes, i.e. within objects or + blocks, rather than on the heap. Values are therefore normally + passed around and manipulated directly as variables or through + references, but not as pointers that emphasize identity and + indirection. + + The specific requirements on value types to be used in an + any + are: + + + A ValueType is + CopyConstructible [20.1.3]. + + + A ValueType is + optionally Assignable [23.1]. The strong + exception-safety guarantee is required for all forms of + assignment. + + + The destructor for a + ValueType upholds the no-throw + exception-safety guarantee. + + +
+ +
+ + + + std::bad_cast + + The exception thrown in the event of a failed + any_cast of an + any value. + + + const char * + + + + + A class whose instances can hold instances of any + type that satisfies ValueType + requirements. + + + this->empty() + + + + + const any & + + + Copy constructor that copies content of + other into new instance, so that any content + is equivalent in both type and value to the content of + other, or empty if other is + empty. + + May fail with a + std::bad_alloc + exception or any exceptions arising from the copy + constructor of the contained type. + + + + + + + const ValueType & + + + Makes a copy of value, so + that the initial content of the new instance is equivalent + in both type and value to + value. + + std::bad_alloc + or any exceptions arising from the copy constructor of the + contained type. + + + + Releases any and all resources used in + management of instance. + Nothing. + + + + any & + + + const any & + + + Copies content of rhs into + current instance, discarding previous content, so that the + new content is equivalent in both type and value to the + content of rhs, or empty if + rhs.empty(). + + std::bad_alloc + or any exceptions arising from the copy constructor of the + contained type. Assignment satisfies the strong guarantee + of exception safety. + + + + + + any & + + + const ValueType & + + + Makes a copy of rhs, + discarding previous content, so that the new content of is + equivalent in both type and value to + rhs. + + std::bad_alloc + or any exceptions arising from the copy constructor of the + contained type. Assignment satisfies the strong guarantee + of exception safety. + + + + + any & + + + any & + + + Exchange of the contents of + *this and + rhs. + + *this + + Nothing. + + + + + + bool + + true if instance is + empty, otherwise false. + + Will not throw. + + + + const std::type_info & + + the typeid of the + contained value if instance is non-empty, otherwise + typeid(void). + + Useful for querying against types known + either at compile time or only at + runtime. + + + + + + + + + T + + + any & + + + + + + + T + + + const any & + + + + + + + const ValueType * + + + const any * + + + + + + + ValueType * + + + any * + + + + Custom keyword cast for extracting a value + of a given type from an + any. + + If passed a pointer, it returns a + similarly qualified pointer to the value content if + successful, otherwise null is returned. + If T is ValueType, it returns a copy of the held value, otherwise, if T is a reference + to (possibly const qualified) ValueType, it returns a reference to the held + value. + + Overloads taking an + any pointer do not + throw; overloads taking an + any value or reference + throws bad_any_cast if + unsuccessful. + + + +
+ + +
+ Acknowledgements + + Doug Gregor ported the documentation to the BoostBook format. +
+ diff --git a/docbook/relaxng/api/tests/array.xml b/docbook/relaxng/api/tests/array.xml new file mode 100644 index 000000000..e35bb66e6 --- /dev/null +++ b/docbook/relaxng/api/tests/array.xml @@ -0,0 +1,548 @@ + + + + + + Nicolai + Josuttis + + + + + 2001 + 2002 + 2003 + 2004 + Nicolai M. Josuttis + + + + 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) + + + + STL compliant container wrapper for arrays of constant size + + + + Boost.Array + +
+ Introduction + + + + + The C++ Standard Template Library STL as part of the C++ + Standard Library provides a framework for processing algorithms on + different kind of containers. However, ordinary arrays don't + provide the interface of STL containers (although, they provide + the iterator interface of STL containers). + + As replacement for ordinary arrays, the STL provides class + std::vector. However, + std::vector<> provides + the semantics of dynamic arrays. Thus, it manages data to be able + to change the number of elements. This results in some overhead in + case only arrays with static size are needed. + + In his book, Generic Programming and the + STL, Matthew H. Austern introduces a useful wrapper + class for ordinary arrays with static size, called + block. It is safer and has no worse performance than + ordinary arrays. In The C++ Programming + Language, 3rd edition, Bjarne Stroustrup introduces a + similar class, called c_array, which I (Nicolai Josuttis) present + slightly modified in my book The C++ Standard Library - + A Tutorial and Reference, called + carray. This is the essence of these approaches + spiced with many feedback from boost. + + After considering different names, we decided to name this + class simply array. + + Note that this class is suggested to be part of the next + Technical Report, which will extend the C++ Standard (see + http://std.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1548.htm). + + Class array fulfills most + but not all of the requirements of "reversible containers" (see + Section 23.1, [lib.container.requirements] of the C++ + Standard). The reasons array is not an reversible STL container is + because: + + No constructors are provided. + Elements may have an undetermined initial value (see ). + swap() has no constant complexity. + size() is always constant, based on the second template argument of the type. + The container provides no allocator support. + + + + It doesn't fulfill the requirements of a "sequence" (see Section 23.1.1, [lib.sequence.reqmts] of the C++ Standard), except that: + + front() and back() are provided. + operator[] and at() are provided. + + +
+ + +
+ + + + + STL compliant container wrapper for arrays of constant size + + T + + + T* + + + const T* + + + std::reverse_iterator<iterator> + + + std::reverse_iterator<const_iterator> + + + T& + + + const T& + + + std::size_t + + + std::ptrdiff_t + + + + size_type + N + + + + + + const array<U, N>& + + std::copy(rhs.begin(),rhs.end(), begin()) + + + + + + iterator + + + const_iterator + + + iterator for the first element + will not throw + + + + + iterator + + + const_iterator + + + iterator for position after the last element + will not throw + + + + + + + reverse_iterator + + + const_reverse_iterator + + + reverse iterator for the first element of reverse iteration + + + + + reverse_iterator + + + const_reverse_iterator + + + reverse iterator for position after the last element in reverse iteration + + + + + + size_type + N + + + bool + N==0 + will not throw + + + size_type + N + will not throw + + + + + + + reference + + size_type + + + + + const_reference + + size_type + + + + i < N + element with index i + will not throw. + + + + + reference + + size_type + + + + + const_reference + + size_type + + + + element with index i + std::range_error if i >= N + + + + + reference + + + const_reference + + N > 0 + the first element + will not throw + + + + + reference + + + const_reference + + N > 0 + the last element + will not throw + + + + const T* + elems + will not throw + + + + T* + elems + will not throw + + + + + + void + + array<T, N>& + + std::swap_ranges(begin(), end(), other.begin()) + linear in N + + + void + + const T& + + std::fill_n(begin(), N, value) + + + + + T + + + + + + + void + + + array<T, N>& + + + array<T, N>& + + + x.swap(y) + will not throw. + + + + + + + + bool + + + const array<T, N>& + + + const array<T, N>& + + + std::equal(x.begin(), x.end(), y.begin()) + + + + + + + bool + + + const array<T, N>& + + + const array<T, N>& + + + !(x == y) + + + + + + + bool + + + const array<T, N>& + + + const array<T, N>& + + + std::lexicographical_compare(x.begin(), x.end(), y.begin(), y.end()) + + + + + + + bool + + + const array<T, N>& + + + const array<T, N>& + + + y < x + + + + + + bool + + + const array<T, N>& + + + const array<T, N>& + + + !(y < x) + + + + + + bool + + + const array<T, N>& + + + const array<T, N>& + + + !(x < y) + + + + +
+ + +
+ Design Rationale + + There was an important design tradeoff regarding the + constructors: We could implement array as an "aggregate" (see + Section 8.5.1, [dcl.init.aggr], of the C++ Standard). This would + mean: + + An array can be initialized with a + brace-enclosing, comma-separated list of initializers for the + elements of the container, written in increasing subscript + order: + + boost::array<int,4> a = { { 1, 2, 3 } }; + + Note that if there are fewer elements in the + initializer list, then each remaining element gets + default-initialized (thus, it has a defined value). + + + However, this approach has its drawbacks: passing no initializer list means that the elements + have an indetermined initial value, because the rule says + that aggregates may have: + + No user-declared constructors. + No private or protected non-static data members. + No base classes. + No virtual functions. + + + + Nevertheless, The current implementation uses this approach. + + Note that for standard conforming compilers it is possible to + use fewer braces (according to 8.5.1 (11) of the Standard). That is, + you can initialize an array as follows: + + +boost::array<int,4> a = { 1, 2, 3 }; + + + I'd appreciate any constructive feedback. Please note: I don't have time to read all boost + mails. Thus, to make sure that feedback arrives to me, please send + me a copy of each mail regarding this class. + + The code is provided "as is" without expressed or implied + warranty. + +
+ +
+ For more information... + To find more details about using ordinary arrays in C++ and + the framework of the STL, see e.g. + + The C++ Standard Library - A Tutorial and Reference +by Nicolai M. Josuttis +Addison Wesley Longman, 1999 +ISBN 0-201-37926-0 + + + Home Page of Nicolai + Josuttis +
+ +
+ Acknowledgements + + Doug Gregor ported the documentation to the BoostBook format. +
+ + + + diff --git a/docbook/relaxng/api/tests/concept.xml b/docbook/relaxng/api/tests/concept.xml new file mode 100644 index 000000000..4b5bd0955 --- /dev/null +++ b/docbook/relaxng/api/tests/concept.xml @@ -0,0 +1,204 @@ + + + +
+ Concepts + + + + +
+ Definitions + + + Notation + + + + F + A type that is a model of Finder + + + Fmt + A type that is a model of Formatter + + + Iter + + Iterator Type + + + + f + Object of type F + + + fmt + Object of type Fmt + + + i,j + Objects of type Iter + + + +
+
+ +
+ Finder Concept + + + Finder is a functor which searches for an arbitrary part of a container. + The result of the search is given as an iterator_range + delimiting the selected part. + + + + Valid Expressions + + + + Expression + Return Type + Effects + + + + + f(i,j) + Convertible to iterator_range<Iter> + Perform the search on the interval [i,j) and returns the result of the search + + + +
+ + + Various algorithms need to perform a search in a container and a Finder is a generalization of such + search operations that allows algorithms to abstract from searching. For instance, generic replace + algorithms can replace any part of the input, and the Finder is used to select the desired one. + + + Note, that it is only required that the finder works with a particular iterator type. However, + a Finder operation can be defined as a template, allowing the Finder to work with any iterator. + + + Examples + + + + + Finder implemented as a class. This Finder always returns the whole input as a match. operator() + is templated, so that the finder can be used on any iterator type. + + +struct simple_finder +{ + template<typename ForwardIteratorT> + boost::iterator_range<ForwardIteratorT> operator()( + ForwardIteratorT Begin, + ForwardIteratorT End ) + { + return boost::make_range( Begin, End ); + } +}; + + + + Function Finder. Finder can be any function object. That is, any ordinary function with the + required signature can be used as well. However, such a function can be used only for + a specific iterator type. + + +boost::iterator_range<std::string> simple_finder( + std::string::const_iterator Begin, + std::string::const_iterator End ) +{ + return boost::make_range( Begin, End ); +} + + + + +
+
+ Formatter concept + + + Formatters are used by replace algorithms. + They are used in close combination with finders. + A formatter is a functor, which takes a result from a Finder operation and transforms it in a specific way. + The operation of the formatter can use additional information provided by a specific finder, + for example regex_formatter() uses the match information from + regex_finder() to format the result of formatter operation. + + + + Valid Expressions + + + + Expression + Return Type + Effects + + + + + fmt(f(i,j)) + A container type, accessible using container traits + Formats the result of the finder operation + + + +
+ + + Similarly to finders, formatters generalize format operations. When a finder is used to + select a part of the input, formatter takes this selection and performs some formating + on it. Algorithms can abstract from formating using a formatter. + + + Examples + + + + + Formatter implemented as a class. This Formatter does not perform any formating and + returns the match, repackaged. operator() + is templated, so that the Formatter can be used on any Finder type. + + +struct simple_formatter +{ + template<typename FindResultT> + std::string operator()( const FindResultT& Match ) + { + std::string Temp( Match.begin(), Match.end() ); + return Temp; + } +}; + + + + Function Formatter. Similarly to Finder, Formatter can be any function object. + However, as a function, it can be used only with a specific Finder type. + + +std::string simple_formatter( boost::iterator_range<std::string::const_iterator>& Match ) +{ + std::string Temp( Match.begin(), Match.end() ); + return Temp; +} + + + + +
+