You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by bn...@apache.org on 2024/01/30 16:23:27 UTC
(trafficserver-libswoc) 02/04: Updating documentation and examples.
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 <am...@apache.org>
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'{}, amc@apache.org'.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\")/"
+