|
|
Boost-Commit : |
From: asutton_at_[hidden]
Date: 2007-09-07 11:24:22
Author: asutton
Date: 2007-09-07 11:24:20 EDT (Fri, 07 Sep 2007)
New Revision: 39154
URL: http://svn.boost.org/trac/boost/changeset/39154
Log:
Added doc framework and concept docs
Added:
sandbox/graph-v2/libs/property_map/doc/Jamfile (contents, props changed)
sandbox/graph-v2/libs/property_map/doc/bibliography.qbk (contents, props changed)
sandbox/graph-v2/libs/property_map/doc/concepts.qbk (contents, props changed)
sandbox/graph-v2/libs/property_map/doc/introduction.qbk (contents, props changed)
sandbox/graph-v2/libs/property_map/doc/lvalue_property_map.qbk (contents, props changed)
sandbox/graph-v2/libs/property_map/doc/property_map.qbk (contents, props changed)
sandbox/graph-v2/libs/property_map/doc/readable_property_map.qbk (contents, props changed)
sandbox/graph-v2/libs/property_map/doc/readwrite_property_map.qbk (contents, props changed)
sandbox/graph-v2/libs/property_map/doc/writable_property_map.qbk (contents, props changed)
Added: sandbox/graph-v2/libs/property_map/doc/Jamfile
==============================================================================
--- (empty file)
+++ sandbox/graph-v2/libs/property_map/doc/Jamfile 2007-09-07 11:24:20 EDT (Fri, 07 Sep 2007)
@@ -0,0 +1,81 @@
+# (C) Copyright Andrew Sutton 2007
+#
+# Use, modification and distribution is subject to 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)
+
+using quickbook ;
+
+xml property_map : property_map.qbk ;
+
+boostbook standalone
+ :
+ property_map
+ :
+ # HTML options first:
+ # Use graphics not text for navigation:
+ <xsl:param>navig.graphics=1
+ # How far down we chunk nested sections, basically all of them:
+ <xsl:param>chunk.section.depth=10
+ # How far down sections get TOC's
+ <xsl:param>toc.section.depth=5
+ # Max depth in each TOC:
+ <xsl:param>toc.max.depth=3
+ # How far down we go with TOC's
+ <xsl:param>generate.section.toc.level=5
+ # Don't put the first section on the same page as the TOC:
+ <xsl:param>chunk.first.sections=0
+ # Logo location:
+ <xsl:param>boost.logo=../boost.png
+ # Enable annotations
+ <xsl:param>annotation.support=1
+
+ # The page style
+ <xsl:param>page.style="'website'"
+ # Show chapters select box
+ <xsl:param>grouped.links.chapters.show="'true'"
+ # GroupedLinks xml definition chapters location
+ <xsl:param>grouped.links.chapters.xml="'boost_libs_grouped_links.xml'"
+ # Select the base url for the chapters GroupedLinks
+ <xsl:param>grouped.links.chapters.url="'http://www.boost.org/libs/'"
+ # Show sections select box
+ <xsl:param>grouped.links.sections.show="'true'"
+ # GroupedLinks xml definition sections location
+ <xsl:param>grouped.links.sections.xml="'sections_grouped_links.xml'"
+ # Select the base url for the chapters GroupedLinks
+ <xsl:param>grouped.links.sections.url="'./'"
+ # Show the Google Search Box
+ <xsl:param>search.box.show="'true'"
+ # Location of the cse defintion
+ <xsl:param>search.box.cse.definition.src="'http://www.drivehq.com/web/matias.capeletto/bimap/doc/html/context8.xml'"
+
+ # PDF Options:
+ # TOC Generation: this is needed for FOP-0.9 and later:
+ # <xsl:param>fop1.extensions=1
+ <xsl:param>xep.extensions=1
+ # TOC generation: this is needed for FOP 0.2, but must not be set to zero for FOP-0.9!
+ <xsl:param>fop.extensions=0
+ # No indent on body text:
+ <xsl:param>body.start.indent=0pt
+ # Margin size:
+ <xsl:param>page.margin.inner=0.5in
+ # Margin size:
+ <xsl:param>page.margin.outer=0.5in
+ # Yes, we want graphics for admonishments:
+ <xsl:param>admon.graphics=1
+ # Set this one for PDF generation *only*:
+ # default pnd graphics are awful in PDF form,
+ # better use SVG's instead:
+ #<xsl:param>admon.graphics.extension=".svg"
+ ;
+
+
+
+
+
+
+
+
+
+
+
Added: sandbox/graph-v2/libs/property_map/doc/bibliography.qbk
==============================================================================
--- (empty file)
+++ sandbox/graph-v2/libs/property_map/doc/bibliography.qbk 2007-09-07 11:24:20 EDT (Fri, 07 Sep 2007)
@@ -0,0 +1,19 @@
+[/
+ / Copyright (c) 2007 Andrew Sutton
+ /
+ / 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 Bibliography]
+
+[bibent stl Helwett-Packard'1994] Hewlett-Packard Company.
+[@http://www.sgi.com/tech/stl/ ['Standard Template Library Programmer's Guide]].
+1994.
+
+[bibent boost_concept_check Siek'2000] Siek, Jeremy, and Lumsdaine, Andrew.
+[@http://www.boost.org/libs/concept_check/ ['The Boost Concept Check Library]].
+2000.
+
+
+[endsect]
\ No newline at end of file
Added: sandbox/graph-v2/libs/property_map/doc/concepts.qbk
==============================================================================
--- (empty file)
+++ sandbox/graph-v2/libs/property_map/doc/concepts.qbk 2007-09-07 11:24:20 EDT (Fri, 07 Sep 2007)
@@ -0,0 +1,114 @@
+[/
+ / Copyright (c) 2007 Andrew Sutton
+ /
+ / 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 Concepts]
+
+[section Overview]
+The property map interface consists of a set of concepts (see definition of /concept/
+in [bibref boost_concept_check Siek'2000] and [bibref stl Hewlett-Packard'1994])
+that define a syntax for mapping key objects to corresponding value objects. Since
+the property map operations are global functions (actually they don't have to be
+global, but they are always called unqualified and may be found via argument dependent
+lookup), it is possible to overload the map functions such that nearly arbitrary
+property map types and key types can be used. The interface for property maps consists
+of three functions: `get()`, `put()`, and `operator[]`. The following concrete example
+from `example1.cpp` shows how the three functions could be used to access the addresses
+associated with various people. We use a separate function template here to highlight
+the parts of the program that use the property map concept interface. In the `main()`
+function we use `std::map` and `boost::associative_property_map`, but it would have been
+OK to use any type (including a custom type that you create) that fulfills the property
+map requirements.
+
+[import ../example/example1.cpp]
+
+[code_example_1]
+
+For each property map object there is a set of valid keys for which the mapping
+to value objects is defined. Invoking a property map function on an invalid key
+results in undefined behavior. The property map concepts do not specify how this
+set of valid keys is created or modified. A function that uses a property map must
+specify the expected set of valid keys in its preconditions.
+
+The need for property maps came out of the design of the Boost.Graph library, whose
+algorithms needed an interface for accessing properties attached to vertices and
+edges in a graph. In this context the vertex and edge descriptors are the key type
+of the property maps.
+
+Several categories of property maps provide different access capabilities:
+
+[variablelist Property Map Concepts
+ [
+ [[ReadablePropertyMap]]
+ [
+ The associated property data can be read using `get()`.
+ ]
+ ]
+ [
+ [[WritablePropertyMap]]
+ [
+ The associated property can be written using `put()`.
+ ]
+ ]
+ [
+ [[ReadWritePropertyMap]]
+ [
+ The associated property can both be written and read using `get()`
+ and `put()`.
+ ]
+ ]
+ [
+ [[LvaluePropertyMap]]
+ [
+ The associated property is actually represented in memory and it is
+ possible to get a reference to it. The property maps in the lvalue
+ category also support the requirements for read/write property maps.
+ ]
+ ]
+]
+
+There is a separate concept defined for each of the four property map categories.
+These property map concepts are listed below, with links to the documentation
+for each of them.
+
+[heading Category Tags]
+There is a tag struct for each of the categories of property maps, which is defined
+in the header `<boost/property_map/property_traits.hpp>`.
+
+ struct readable_property_map_tag { };
+
+ struct writable_property_map_tag { };
+
+ struct read_write_property_map_tag :
+ public readable_property_map_tag,
+ public writable_property_map_tag { };
+
+ struct lvalue_property_map_tag :
+ public read_write_property_map_tag { };
+
+[heading Property Traits]
+Similar to the `std::iterator_traits` class of the STL, there is a `boost::property_traits`
+class that can be used to deduce the types associated with a property map type: the key
+and value types, and the property map category. There is a specialization of
+`boost::property_traits` so that pointers can be used as property map objects.
+
+ template <typename PropertyMap>
+ struct property_traits {
+ typedef typename PropertyMap::key_type key_type;
+ typedef typename PropertyMap::value_type value_type;
+ typedef typename PropertyMap::category category;
+ };
+
+In addition, the property map functions are overloaded for pointers. These traits
+classes and functions are defined in `<boost/property_traits.hpp>`.
+[endsect]
+
+[include readable_property_map.qbk]
+[include writable_property_map.qbk]
+[include readwrite_property_map.qbk]
+[include lvalue_property_map.qbk]
+
+[endsect]
Added: sandbox/graph-v2/libs/property_map/doc/introduction.qbk
==============================================================================
--- (empty file)
+++ sandbox/graph-v2/libs/property_map/doc/introduction.qbk 2007-09-07 11:24:20 EDT (Fri, 07 Sep 2007)
@@ -0,0 +1,55 @@
+[/
+ / Copyright (c) 2007 Andrew Sutton
+ /
+ / 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 Introduction]
+The Boost.Property_Map library consists mainly of interface specifications in the
+form of concepts - similar to the iterator concepts in the Standard Template Library
+(STL) [bibref stl Hewlett-Packard'1994]. The Boost.Property_Map concepts define a
+general purpose interface for mapping key objects to corresponding value objects,
+thereby hiding the details of how the mapping is implemented from algorithms.
+These interface specifications are intended for use by implementors of generic
+libraries because they decouple the interface and implementation of a mapping
+(e.g., a `std::map`) from the algorithms that require it. The implementation of
+types fulfilling the property map interface is up to the client of the algorithm
+to provide. The property map requirements are purposefully vague on the type of
+the key and value objects to allow for the utmost genericity in the function
+templates of the generic library.
+
+The need for the property map interface came from the Boost.Graph library (BGL),
+which contains many examples of algorithms that use the property map concepts to
+specify their interface. For an example, note the `ColorMap` template parameter of
+the `breadth_first_search`. In addition, the BGL contains many examples of concrete
+types that implement the property map interface. The `adjacency_list` class implements
+property maps for accessing objects (properties) that are attached to vertices
+and edges of the graph.
+
+The Boost.Property_Map library also contains a few adaptors that convert commonly
+used data-structures that implement a mapping operation, such as builtin arrays
+(pointers), iterators, and `std::map`, to have the property map interface. These
+adaptors are not meant to fulfill all mapping needs, but are to serve as an
+example of how to implement the interface as well as covering a few common cases.
+See the header files for details.
+
+Property maps are statically-typed entities. If you need to access property maps
+in a more dynamic setting (e.g., because you're reading an unknown set of attributes
+from a file), you can use the `dynamic_properties` class to access a set of property
+maps through a dynamically-typed interface.
+
+[heading History]
+The property map interface originated as data accessors in Dietmar Kühl's Masters
+Thesis on generic graph algorithms. The property map idea also appeared under the
+guise of decorators in early versions of the Generic Graph Component Library (GGCL),
+which is now the Boost.Graph library. The main motivation for the property map
+interface was to support the access of data associated with vertices and edges in a
+graph, though the applicability of property maps goes beyond this.
+
+[heading Acknowledgments]
+Thanks go to Dietmar Kühl for coming up with this mechanism, and thanks go to the
+Boost members who helped refine and improve the property map interface. Thanks to
+Dave Abrahams for managing the formal review of the BGL which included the property
+map library.
+[endsect]
Added: sandbox/graph-v2/libs/property_map/doc/lvalue_property_map.qbk
==============================================================================
--- (empty file)
+++ sandbox/graph-v2/libs/property_map/doc/lvalue_property_map.qbk 2007-09-07 11:24:20 EDT (Fri, 07 Sep 2007)
@@ -0,0 +1,64 @@
+[/
+ / Copyright (c) 2007 Andrew Sutton
+ /
+ / 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 Lvalue Property Map]
+The [LvaluePropertyMap] provides an interface for accessing a reference to a value
+object (as opposed to a copy). An [LvaluePropertyMap] can be /mutable/ or /non-mutable/.
+The mutable [LvaluePropertyMap] returns a reference whereas the non-mutable returns
+a `const` reference. Types that model this concept may also provide both mutable
+and non-mutable accessors.
+
+[heading Notation]
+[table
+ [[Expression] [Description]]
+ [[`PropMap`] [A type that models the [ReadablePropertyMap] concept.]]
+ [[`Key`] [The type of keys used to access values in the `PropMap`.]]
+ [[`Value`] [The type of values accessed using the `PropMap`.]]
+ [[`pm`] [An object of type `PropMap`.]]
+ [[`k`] [An object of type `Key`.]]
+ [[`v`] [An object of type `Value`.]]
+]
+
+[heading Associated Types]
+[table
+ [[Name] [Type] [Description]]
+ [
+ [Reference Type]
+ [`property_traits<PropMap>::reference`]
+ [
+ A reference to `value_type`.
+
+ *Requirements:* This must be either a reference or a `const` reference.
+ It must not be the same type as the `value_type`.
+ ]
+ ]
+ [
+ [Property Map Category]
+ [`property_traits<PropMap>::category`]
+ [
+ The category of the property map.
+
+ *Requirements:* Must be convertible to `lvalue_property_tag`.
+ ]
+ ]
+]
+
+[heading Valid Expressions]
+[table
+ [[Name] [Expression] [Result Type] [Description]]
+ [
+ [Access Property Value]
+ [`pm[k]`]
+ [`property_traits<PropMap>::reference`]
+ [
+ Get a refernce to the value associated with the key `k` using the
+ property map `pm`. The reference can be mutable or non-mutable.
+ ]
+ ]
+]
+
+[endsect]
Added: sandbox/graph-v2/libs/property_map/doc/property_map.qbk
==============================================================================
--- (empty file)
+++ sandbox/graph-v2/libs/property_map/doc/property_map.qbk 2007-09-07 11:24:20 EDT (Fri, 07 Sep 2007)
@@ -0,0 +1,52 @@
+[/
+ / Copyright (c) 2007 Andrew Sutton
+ /
+ / 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)
+ /]
+
+[/ The copyright is a little funky...
+ It should have one or more distinct lines. /]
+[article Boost.Property_Map
+ [quickbook 1.4]
+ [authors [Siek, Jeremy], [Lee, Lie-Quan], [Lumsdaine, Andrew], [Sutton, Andrew]]
+ [copyright 2000 2001 Jeremy Siek, Lie-Quan Lee, Andrew Lumsdaine]
+ [copyright 2007 Andrew Sutton]
+ [category property_map]
+ [id property_map]
+ [dirname property_map]
+ [purpose
+ Abstract concepts and classes for mapping key objects to their
+ corresponding values.
+ ]
+ [license
+ 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])
+ ]
+]
+
+[/ Templates for helping with bibliography stuff /]
+[template bibref[id abbr] '''<link linkend="boost_property_map.bib.'''[id]'''">['''[abbr]''']</link>''']
+[template bibent[id abbr] '''
+<link id="boost_property_map.bib.'''[id]'''" linkend="boost_property_map.bib.'''[id]'''">
+ ['''[abbr]''']
+</link>''']
+
+[/ Quick-link templates /]
+[template ReadablePropertyMap[] [link
+ boost_property_map.concepts.readable_property_map
+ [^ReadablePropertyMap]]]
+[template WritablePropertyMap[] [link
+ boost_property_map.concepts.writable_property_map
+ [^WritablePropertyMap]]]
+[template ReadWritePropertyMap[] [link
+ boost_property_map.concepts.readwrite_property_map
+ [^ReadWritePropertyMap]]]
+[template LvaluePropertyMap[] [link
+ boost_property_map.concepts.lvalue_property_map
+ [^LvaluePropertyMap]]]
+
+[include introduction.qbk]
+[include concepts.qbk]
+[include bibliography.qbk]
\ No newline at end of file
Added: sandbox/graph-v2/libs/property_map/doc/readable_property_map.qbk
==============================================================================
--- (empty file)
+++ sandbox/graph-v2/libs/property_map/doc/readable_property_map.qbk 2007-09-07 11:24:20 EDT (Fri, 07 Sep 2007)
@@ -0,0 +1,89 @@
+[/
+ / Copyright (c) 2007 Andrew Sutton
+ /
+ / 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 Readable Property Map]
+A [ReadablePropertyMap] provides read access to a value object associated with a
+given key via a call to the `get()` function. The `get()` function returns an
+non-mutable value (either a copy of the value or a `const` reference).
+
+[heading Notation]
+[table
+ [[Expression] [Description]]
+ [[`PropMap`] [A type that models the [ReadablePropertyMap] concept.]]
+ [[`Key`] [The type of keys used to access values in the `PropMap`.]]
+ [[`pm`] [An object of type `PropMap`.]]
+ [[`k`] [An object of type `Key`.]]
+]
+
+[heading Associated Types]
+[table
+ [[Name] [Type] [Description]]
+ [
+ [Value Type]
+ [`property_traits<PropMap>::value_type`]
+ [
+ The type of values accessed through the `PropMap`.
+ ]
+ ]
+ [
+ [Reference Type]
+ [`property_traits<PropMap>::reference`]
+ [
+ A type convertible to `value_type`. This is usually either a `const`
+ or non-`const` reference to `value_type`, but can also be the same
+ as `value_type`.
+ ]
+ ]
+ [
+ [Key Type]
+ [`property_traits<PropMap>::key_type`]
+ [
+ The type of key object used to access values in the `PropMap`.
+ ]
+ ]
+ [
+ [Property Map Category]
+ [`property_traits<PropMap>::category`]
+ [
+ The category of the property map.
+
+ *Requirements:* Must be convertible to `readable_property_tag`.
+ ]
+ ]
+]
+
+[heading Valid Expressions]
+[table
+ [[Name] [Expression] [Result Type] [Description]]
+ [
+ [Get Property Value]
+ [`get(pm, k)`]
+ [`property_traits<PropMap>::reference`]
+ [
+ Look up the value associated with the key `k` using the property map
+ `pm`.
+ ]
+ ]
+]
+
+[heading Notes]
+Depending on the type modeling this concept, the return value of the `get()` function
+can be either a reference (`const` or otherwise) or a copy of the value. This depends
+on the semantics of the source that the property map is abstracting. If the underlying
+data source is a container that stores the objects being accessed via the `get()`
+function, then the return type is more likely to be by reference. Moreover, the
+property map that return a reference are also more likely to model the
+[LvaluePropertyMap] concept also. Property maps that /generate/ values (i.e., the
+values cannot be stored in memory) will return copies of those values.
+
+[heading Design Notes]
+At various times the name "read-only" was considered for this concept. However, that
+name is inappropriate because concepts are inherently positive, not negative. This
+becomes obvious when we define the [ReadWritePropertyMap], which refines both the
+[ReadablePropertyMap] and the [WritablePropertyMap] concept. It would not make much
+sense to combine "read-only" and "write-only" concepts.
+[endsect]
Added: sandbox/graph-v2/libs/property_map/doc/readwrite_property_map.qbk
==============================================================================
--- (empty file)
+++ sandbox/graph-v2/libs/property_map/doc/readwrite_property_map.qbk 2007-09-07 11:24:20 EDT (Fri, 07 Sep 2007)
@@ -0,0 +1,35 @@
+[/
+ / Copyright (c) 2007 Andrew Sutton
+ /
+ / 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 ReadWrite Property Map]
+A [ReadWritePropertyMap] can be used to read property values via the `get()`
+function and can be used to write property values via the `put()` function.
+
+[heading Refinement Of]
+[ReadablePropertyMap], [WritablePropertyMap]
+
+[heading Notation]
+[table
+ [[Expression] [Description]]
+ [[`PropMap`] [A type that models the [ReadWritePropertyMap] concept.]]
+]
+
+[heading Associated Types]
+[table
+ [[Name] [Type] [Description]]
+ [
+ [Property Map Category]
+ [`property_traits<PropMap>::category`]
+ [
+ The category of the property map.
+
+ *Requirements:* Must be convertible to `readwrite_property_tag`.
+ ]
+ ]
+]
+
+[endsect]
Added: sandbox/graph-v2/libs/property_map/doc/writable_property_map.qbk
==============================================================================
--- (empty file)
+++ sandbox/graph-v2/libs/property_map/doc/writable_property_map.qbk 2007-09-07 11:24:20 EDT (Fri, 07 Sep 2007)
@@ -0,0 +1,70 @@
+[/
+ / Copyright (c) 2007 Andrew Sutton
+ /
+ / 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 Writable Property Map]
+A [WritablePropertyMap] has the capability of setting a value object associated
+with the given key via the `put()` function.
+
+[heading Notation]
+[table
+ [[Expression] [Description]]
+ [[`PropMap`] [A type that models the [WritablePropertyMap] concept.]]
+ [[`Key`] [The type of keys used to access values in the `PropMap`.]]
+ [[`Value`] [The type of values accessed using the `PropMap`.]]
+ [[`pm`] [An object of type `PropMap`.]]
+ [[`k`] [An object of type `Key`.]]
+ [[`v`] [An object of type `Value`.]]
+]
+
+[heading Associated Types]
+[table
+ [[Type] [Description]]
+ [
+ [`property_traits<PropMap>::value_type`]
+ [
+ The type of values accessed through the `PropMap`.
+ ]
+ ]
+ [
+ [`property_traits<PropMap>::reference`]
+ [
+ A type convertible to `value_type`. This is usually either a `const`
+ or non-`const` reference to `value_type`, but can also be the same
+ as `value_type`.
+ ]
+ ]
+ [
+ [`property_traits<PropMap>::key_type`]
+ [
+ The type of key object used to access values in the `PropMap`.
+ ]
+ ]
+ [
+ [`property_traits<PropMap>::category`]
+ [
+ The category of the property map.
+
+ *Requirements:* Must be convertible to `writable_property_tag`.
+ ]
+ ]
+]
+
+[heading Valid Expressions]
+[table
+ [[Name] [Expression] [Result Type] [Description]]
+ [
+ [Put Property Value]
+ [`put(pm, k, v)`]
+ []
+ [
+ Assign the object `v` to the value associated with key `k` using the
+ property map `pm`. The type of `v` (`Value`) is convertible to `value_type`.
+ ]
+ ]
+]
+
+[endsect]
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk