This is an automated email from the ASF dual-hosted git repository. bneradt pushed a commit to branch dev-1-0-13 in repository https://gitbox.apache.org/repos/asf/trafficserver-libswoc.git
commit 9052965c72356b714d4d37f00bbdf061f7b5f421 Author: Alan M. Carroll <[email protected]> AuthorDate: Tue Feb 25 07:26:49 2020 -0600 Updating documentation and examples. --- doc/Doxyfile | 2 +- doc/Makefile | 5 +++-- doc/code/IPSpace.en.rst | 34 +++++++++++++++++++++++++++++++--- doc/code/TextView.en.rst | 9 +++++---- doc/conf.py | 2 +- swoc++/CMakeLists.txt | 2 +- swoc++/include/swoc/swoc_ip.h | 2 +- swoc++/include/swoc/swoc_version.h | 2 +- swoc++/swoc++.part | 2 +- tools/update-version.sh | 2 ++ 10 files changed, 47 insertions(+), 15 deletions(-) diff --git a/doc/Doxyfile b/doc/Doxyfile index 3f76a56..a2ad52d 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -38,7 +38,7 @@ PROJECT_NAME = "LibSWOC++" # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = "1.0.12" +PROJECT_NUMBER = "1.0.13" # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a diff --git a/doc/Makefile b/doc/Makefile index 047a4dc..122bc93 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -50,5 +50,6 @@ ext/local-config.py : Makefile doxygen: doxygen -reference: - @if [ ! -r _build/html/reference ] ; then mkdir -p _build/html; ln -s ../../doxygen/html _build/html/reference ; fi +reference: doxygen + @if [ ! -d _build/html ] ; then mkdir -p _build/html ; fi + @if [ ! -d _build/html/reference ] ; then ln -s ../../doxygen/html _build/html/reference ; fi diff --git a/doc/code/IPSpace.en.rst b/doc/code/IPSpace.en.rst index e5918cd..ecfe09e 100644 --- a/doc/code/IPSpace.en.rst +++ b/doc/code/IPSpace.en.rst @@ -17,13 +17,21 @@ Synopsis Usage ***** -.. class:: IPEndpoint - - :libswoc:`Reference documentation <swoc::IPEndpoint>`. +:libswoc:`Reference documentation <swoc::IPEndpoint>`. This library is for storing and manipulating IP addresses as data. It has no support for actual network operations. +IPEndpoint +========== + +:libswoc:`swoc::IPEndpoint` is a wrapper around :code:`sockaddr` and provides a number of utilities. +It enables constructing an instance from the string representation of an address, supporting IPv4 +and IPv6. It will also parse and store the port if that is part of the string. Some of the internal +logic is exposed via :libswoc:`swoc::IPEndpoint::tokenize` which finds and returns the elements of +an address string, the host (address), port, and any trailing remnants. This is useful for doing +syntax checks or more specialized processing of the address string. + IPAddr ====== @@ -41,6 +49,9 @@ address. This can be reasonable in situations where those addresses are not vali in general the :libswoc:`swoc::IPAddr::load` method should be used, which both initializes the instance and provides an indication of whether the input was valid. +Conversions to and from :code:`sockaddr` are provided. This is handier with :code:`IPAddr` as it +will conform to the family of the address in the :code:`sockaddr`. + IPRange ======= @@ -151,6 +162,23 @@ There is a small implementation wrinkle, however, in dealing with unmapped addre is done by default constructing a :code:`PAYLOAD` instance and then calling :code:`blend` on that and the :arg:`color`. If this returns :code:`false` then unmapped addresses will remain unmapped. +Examples +******** + +Blending Bitsets +================ + +As an example of blending, consider a mapping of IP addresses to a bit set, each representing some +independent property of the address (e.g., production, externally accessible, secure, etc.). It +might be the case that each of these was in a separate data source. In that case one approach +would be to blend each data source into the IPSpace, combining the bits in the blending functor. +The declarations could be + +.. literalinclude:: ../../unit_tests/ex_ipspace_properties.cc + :start-after: "IPSpace bitset blending" + :lines: 1-4 + :emphasize-lines: 2,4 + History ******* diff --git a/doc/code/TextView.en.rst b/doc/code/TextView.en.rst index 0796e27..9273d9b 100644 --- a/doc/code/TextView.en.rst +++ b/doc/code/TextView.en.rst @@ -275,7 +275,7 @@ separated by commas. .. sidebar:: Verification - `Test code for example <https://github.com/SolidWallOfCode/libswoc/blob/master/src/unit_tests/ex_TextView.cc#L66>`__. + `Test code for example <https://github.com/SolidWallOfCode/libswoc/blob/1.0.13/unit_tests/ex_TextView.cc#L67>`__. If :arg:`value` was :literal:`bob ,dave, sam` then :arg:`token` would be successively :literal:`bob`, :literal:`dave`, :literal:`sam`. After :literal:`sam` was extracted :arg:`value` @@ -297,7 +297,7 @@ for values that are boolean. .. sidebar:: Verification - `Test code for example <https://github.com/SolidWallOfCode/libswoc/blob/master/src/unit_tests/ex_TextView.cc#L73>`__. + `Test code for example <https://github.com/SolidWallOfCode/libswoc/blob/1.0.13/unit_tests/ex_TextView.cc#L74>`__. The basic list processing is the same as the previous example, with each element being treated as a "list" with ``=`` as the separator. Note if there is no ``=`` character then all of the list @@ -343,11 +343,12 @@ reference in order to be updated by the tokenizer. Further, some callers want th do not, so a flag to strip quotes from the resulting elements is needed. The final result looks like .. literalinclude:: ../../unit_tests/ex_TextView.cc - :lines: 91-123 + :start-after: "TextView Tokens" + :lines: 2-26 .. sidebar:: Verification - `Test code for example <https://github.com/SolidWallOfCode/libswoc/blob/master/src/unit_tests/ex_TextView.cc#L125>`__. + `Test code for example <https://github.com/SolidWallOfCode/libswoc/blob/1.0.13/unit_tests/ex_TextView.cc#L90>`__. This takes a :code:`TextView&` which is the source view which will be updated as tokens are removed (therefore the caller must do the empty view check). The other arguments are the separator character diff --git a/doc/conf.py b/doc/conf.py index e75006c..f5a2257 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -80,7 +80,7 @@ project = u'Solid Wall Of C++' copyright = u'{}, [email protected]'.format(date.today().year) # The full version, including alpha/beta/rc tags. -release = "1.0.12" +release = "1.0.13" # The short X.Y version. version = '.'.join(release.split('.', 2)[:2]) diff --git a/swoc++/CMakeLists.txt b/swoc++/CMakeLists.txt index 067ba2d..f4947d5 100644 --- a/swoc++/CMakeLists.txt +++ b/swoc++/CMakeLists.txt @@ -1,7 +1,7 @@ cmake_minimum_required(VERSION 3.12) project(lib-swoc++ CXX) -set(LIBSWOC_VERSION "1.0.12") +set(LIBSWOC_VERSION "1.0.13") set(CMAKE_CXX_STANDARD 17) include(GNUInstallDirs) diff --git a/swoc++/include/swoc/swoc_ip.h b/swoc++/include/swoc/swoc_ip.h index 61165a9..9070ebd 100644 --- a/swoc++/include/swoc/swoc_ip.h +++ b/swoc++/include/swoc/swoc_ip.h @@ -42,7 +42,7 @@ union IPEndpoint { /// Default construct invalid instance. IPEndpoint(); - /// Construct from string representation of an address. + /// Construct from the @a text representation of an address. IPEndpoint(string_view const &text); // Construct from @a IPAddr IPEndpoint(IPAddr const &addr); diff --git a/swoc++/include/swoc/swoc_version.h b/swoc++/include/swoc/swoc_version.h index 925ae60..4f7cb85 100644 --- a/swoc++/include/swoc/swoc_version.h +++ b/swoc++/include/swoc/swoc_version.h @@ -39,5 +39,5 @@ namespace swoc { static constexpr unsigned MAJOR_VERSION = 1; static constexpr unsigned MINOR_VERSION = 0; -static constexpr unsigned POINT_VERSION = 12; +static constexpr unsigned POINT_VERSION = 13; } // namespace swoc diff --git a/swoc++/swoc++.part b/swoc++/swoc++.part index 93a165d..b737458 100644 --- a/swoc++/swoc++.part +++ b/swoc++/swoc++.part @@ -1,7 +1,7 @@ import os Import("*") PartName("libswoc") -PartVersion("1.0.12") +PartVersion("1.0.13") files = [ "src/ArenaWriter.cc", diff --git a/tools/update-version.sh b/tools/update-version.sh index c12569b..7cca62e 100644 --- a/tools/update-version.sh +++ b/tools/update-version.sh @@ -12,6 +12,8 @@ sed -i swoc++/include/swoc/swoc_version.h --expr "s/\(POINT_VERSION *= *\).*\$/\ sed -i doc/conf.py --expr "s/release = .*\$/release = \"$1.$2.$3\"/" sed -i doc/Doxyfile --expr "s/\(PROJECT_NUMBER *= *\).*\$/\\1\"$1.$2.$3\"/" +find doc -name "*.en.rst" -exec sed -i {} --expr "s!/libswoc/blob/[0-9.]*/unit_tests/!/libswoc/blob/$1.$2.$3/unit_tests/!" \; sed -i swoc++/CMakeLists.txt --expr "s/\(LIBSWOC_VERSION *\)\"[^\"]*\"/\\1\"$1.$2.$3\"/" sed -i swoc++/swoc++.part --expr "s/PartVersion(\"[0-9.]*\")/PartVersion(\"$1.$2.$3\")/" +
