dissect: no longer dissect Content element by default

Use the new -c/--content option to enable it

Change-Id: Id5692b53a0921918bb029ad653b9f5504ab5e4ab

manpages/conf.py

@@ -1,10 +1,8 @@
-# -*- coding: utf-8 -*-
-#
 # Configuration file for the Sphinx documentation builder.
 #
 # This file only contains a selection of the most common options. For a full
 # list see the documentation:
-# http://www.sphinx-doc.org/en/master/config
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
 
 # -- Path setup --------------------------------------------------------------
 
@@ -20,13 +18,13 @@
 # -- Project information -----------------------------------------------------
 
 project = u'NDN Essential Tools'
-copyright = u'Copyright © 2014-2020 Named Data Networking Project.'
+copyright = u'Copyright © 2014-2021 Named Data Networking Project.'
 author = u'Named Data Networking Project'
 
-# The short X.Y version
+# The short X.Y version.
 #version = ''
 
-# The full version, including alpha/beta/rc tags
+# The full version, including alpha/beta/rc tags.
 #release = ''
 
 # There are two options for replacing |today|: either, you set today to some
@@ -40,7 +38,7 @@ today_fmt = '%Y-%m-%d'
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #
-needs_sphinx = '1.1'
+needs_sphinx = '1.3'
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -51,6 +49,14 @@ extensions = [
 # The master toctree document.
 master_doc = 'index'
 
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['Thumbs.db', '.DS_Store']
+
 
 # -- Options for manual page output ------------------------------------------
 

manpages/ndn-dissect.rst

@@ -1,41 +1,43 @@
 ndn-dissect
 ===========
 
-Usage
------
+Synopsis
+--------
 
-::
-
-    ndn-dissect [-hV] [INPUT-FILE]
+**ndn-dissect** [**-h**] [**-c**] [**-V**] [*file*]
 
 Description
 -----------
 
-``ndn-dissect`` is an NDN packet format inspector.
-It reads zero or more NDN packets from either an input file or the standard input,
-and displays the Type-Length-Value (TLV) structure of those packets on the standard output.
+:program:`ndn-dissect` is an NDN packet format inspector.
+It reads zero or more NDN packets from either an input file or the standard
+input, and displays the Type-Length-Value (TLV) structure of those packets
+on the standard output.
 
 Options
 -------
 
-.. option:: -h
+.. option:: -h, --help
 
-  Print help and exit.
+    Print help and exit.
 
-.. option:: -V
+.. option:: -c, --content
 
-  Print version and exit.
+    Dissect the value of Content elements as well. By default, the value of a
+    Content element is treated as an opaque blob and is not dissected further.
 
-.. option:: INPUT-FILE
+.. option:: -V, --version
 
-  The file to read packets from.
-  If no :option:`INPUT-FILE` is given, the standard input is used.
+    Print program version and exit.
+
+.. option:: file
+
+    The file to read packets from.
+    If no *file* is given, or if *file* is "-", the standard input is used.
 
 Examples
 --------
 
-Inspect the response to Interest ``ndn:/app1/video``
+Inspect the response to Interest ``/app1/video``::
 
-::
-
-    ndnpeek ndn:/app1/video | ndn-dissect
+    ndnpeek /app1/video | ndn-dissect

manpages/ndnpeek.rst

@@ -68,8 +68,8 @@ Exit Status
 
 4: Nack received
 
-Example
--------
+Examples
+--------
 
 Send an Interest for ``/app1/video`` and print the received payload only::
 

manpages/ndnpingserver.rst

@@ -1,5 +1,5 @@
-ndnping
-=======
+ndnpingserver
+=============
 
 Synopsis
 --------
@@ -43,8 +43,8 @@ Options
 ``-V``
   Print version and exit.
 
-Example
--------
+Examples
+--------
 
 Listen on ``/edu/arizona`` and respond to at most 4 pings, printing the timestamp
 on each received ping::

manpages/ndnpoke.rst

@@ -63,8 +63,8 @@ Exit Status
 
 5: Prefix registration failed
 
-Example
--------
+Examples
+--------
 
 Create a Data packet with content ``hello`` and name ``/app/video`` and wait at
 most 3 seconds for a matching Interest to arrive::

manpages/ndnputchunks.rst

@@ -59,16 +59,15 @@ Options
 
     Print program version and exit.
 
-Example
--------
+Examples
+--------
 
 The following command will publish the text of the GPL-3 license under the `/localhost/demo/gpl3`
 prefix::
 
     ndnputchunks /localhost/demo/gpl3 < /usr/share/common-licenses/GPL-3
 
-To find the published version you have to start ndnputchunks with the `-p` command line option,
-for example::
+To see the published version, you can run the program with the **-p** option::
 
     ndnputchunks -p /localhost/demo/gpl3 < /usr/share/common-licenses/GPL-3
 

tools/dissect/README.md

@@ -1,13 +1,14 @@
 # ndn-dissect
 
 **ndn-dissect** is an NDN packet format inspector.
-It reads zero or more NDN packets from either an input file or the standard input,
-and displays the Type-Length-Value (TLV) structure of those packets on the standard output.
+It reads zero or more NDN packets from either an input file or the standard
+input, and displays the Type-Length-Value (TLV) structure of those packets
+on the standard output.
 
 Usage example:
 
-1. start NFD on local machine
-2. execute `echo 'HELLO WORLD' | ndnpoke ndn:/localhost/demo/hello`
-3. on another console, execute `ndnpeek ndn:/localhost/demo/hello | ndn-dissect`
+1. start NFD on the local machine
+2. run `echo 'HELLO WORLD' | ndnpoke /localhost/demo/hello`
+3. on another console, run `ndnpeek /localhost/demo/hello | ndn-dissect`
 
 For more information, consult the manpage.

tools/dissect/dissector.cpp

@@ -18,10 +18,11 @@
  *
  * See AUTHORS.md for complete list of ndn-cxx authors and contributors.
  *
- * @author Alexander Afanasyev <http://lasr.cs.ucla.edu/afanasyev/index.html>
+ * @author Alexander Afanasyev
+ * @author Davide Pesavento
  */
 
-#include "ndn-dissect.hpp"
+#include "dissector.hpp"
 
 #include <map>
 
@@ -31,14 +32,15 @@
 namespace ndn {
 namespace dissect {
 
-NdnDissect::NdnDissect(std::istream& input, std::ostream& output)
-  : m_in(input)
+Dissector::Dissector(std::istream& input, std::ostream& output, const Options& options)
+  : m_options(options)
+  , m_in(input)
   , m_out(output)
 {
 }
 
 void
-NdnDissect::dissect()
+Dissector::dissect()
 {
   size_t offset = 0;
   try {
@@ -60,7 +62,7 @@ static const char GLYPH_UP_AND_RIGHT[]       = "\u2514\u2500"; // "└─"
 static const char GLYPH_SPACE[]              = "  ";
 
 void
-NdnDissect::printBranches()
+Dissector::printBranches()
 {
   for (size_t i = 0; i < m_branches.size(); ++i) {
     if (i == m_branches.size() - 1) {
@@ -114,7 +116,7 @@ static const std::map<uint32_t, const char*> TLV_DICT = {
 };
 
 void
-NdnDissect::printType(uint32_t type)
+Dissector::printType(uint32_t type)
 {
   m_out << type << " (";
 
@@ -139,14 +141,15 @@ NdnDissect::printType(uint32_t type)
 }
 
 void
-NdnDissect::printBlock(const Block& block)
+Dissector::printBlock(const Block& block)
 {
   printBranches();
   printType(block.type());
   m_out << " (size: " << block.value_size() << ")";
 
   try {
-    if (block.type() != tlv::SignatureValue) {
+    if (block.type() != tlv::SignatureValue &&
+        (block.type() != tlv::Content || m_options.dissectContent)) {
       block.parse();
     }
   }

tools/dissect/dissector.hpp

@@ -17,8 +17,8 @@
  * ndn-tools, e.g., in COPYING.md file.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-#ifndef NDN_TOOLS_DISSECT_NDN_DISSECT_HPP
-#define NDN_TOOLS_DISSECT_NDN_DISSECT_HPP
+#ifndef NDN_TOOLS_DISSECT_DISSECTOR_HPP
+#define NDN_TOOLS_DISSECT_DISSECTOR_HPP
 
 #include "core/common.hpp"
 
@@ -27,10 +27,15 @@
 namespace ndn {
 namespace dissect {
 
-class NdnDissect : noncopyable
+struct Options
+{
+  bool dissectContent = false;
+};
+
+class Dissector : noncopyable
 {
 public:
-  NdnDissect(std::istream& input, std::ostream& output);
+  Dissector(std::istream& input, std::ostream& output, const Options& options);
 
   void
   dissect();
@@ -46,6 +51,7 @@ private:
   printBlock(const Block& block);
 
 private:
+  const Options& m_options;
   std::istream& m_in;
   std::ostream& m_out;
 
@@ -56,4 +62,4 @@ private:
 } // namespace dissect
 } // namespace ndn
 
-#endif // NDN_TOOLS_DISSECT_NDN_DISSECT_HPP
+#endif // NDN_TOOLS_DISSECT_DISSECTOR_HPP

tools/dissect/main.cpp

@@ -17,7 +17,7 @@
  * ndn-tools, e.g., in COPYING.md file.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-#include "ndn-dissect.hpp"
+#include "dissector.hpp"
 #include "core/version.hpp"
 
 #include <boost/program_options/options_description.hpp>
@@ -42,12 +42,14 @@ usage(std::ostream& os, const std::string& programName, const po::options_descri
 static int
 main(int argc, char* argv[])
 {
+  Options options;
   std::string inputFileName;
 
   po::options_description visibleOptions("Options");
   visibleOptions.add_options()
-    ("help,h",    "print help and exit")
-    ("version,V", "print version and exit")
+    ("help,h",    "print this help message and exit")
+    ("content,c", po::bool_switch(&options.dissectContent), "dissect the value of Content elements")
+    ("version,V", "print program version and exit")
     ;
 
   po::options_description hiddenOptions;
@@ -91,8 +93,8 @@ main(int argc, char* argv[])
     inputStream = &inputFile;
   }
 
-  NdnDissect program(*inputStream, std::cout);
-  program.dissect();
+  Dissector d(*inputStream, std::cout, options);
+  d.dissect();
 
   return 0;
 }