rb-wartslib 0.9.11 → 0.9.12

data/docs/tut-1-count.rb

@@ -0,0 +1,13 @@
+require 'rubygems'
+require 'wartslib'
+
+file = Warts::File::open ARGV[0]
+file.add_filters Warts::File::TRACE
+
+count = 0
+while (trace = file.read)
+  count += 1
+end
+
+file.close
+puts count

data/docs/tut-10-list2.rb

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'wartslib'
+
+num_traces = 0
+Warts::File.open(ARGV[0]) do |file|
+  file.add_filters Warts::File::TRACE, Warts::File::LIST
+  file.read do |element|
+    case element.element_type
+    when Warts::File::TRACE
+      num_traces += 1
+    when Warts::File::LIST
+      puts "     id: " + element.id.to_s
+      puts "   name: " + element.name
+      puts "  descr: " + element.descr
+      puts "monitor: " + element.monitor
+    end
+  end
+end
+
+puts "# traces: " + num_traces.to_s

data/docs/tut-11-cycle.rb

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'wartslib'
+
+def t(timestamp)
+  timestamp.to_s + " (" + Time.at(timestamp).to_s + ")"
+end
+
+Warts::File.open(ARGV[0]) do |file|
+  file.add_filters Warts::File::TRACE
+  trace = file.read
+  if trace
+    cycle = trace.cycle
+    puts "        id: " + cycle.id.to_s
+    puts "start_time: " + t(cycle.start_time)
+    puts " stop_time: " + t(cycle.stop_time)
+    puts "  hostname: " + cycle.hostname
+  end
+end

data/docs/tut-12-cycle2.rb

@@ -0,0 +1,36 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'wartslib'
+
+CYCLE_TYPE = {
+  Warts::File::CYCLE_START => "start",
+  Warts::File::CYCLE_STOP => "stop",
+  Warts::File::CYCLE_DEF => "def"
+}
+
+def t(timestamp)
+  timestamp.to_s + " (" + Time.at(timestamp).to_s + ")"
+end
+
+num_traces = 0
+Warts::File.open(ARGV[0]) do |file|
+  file.add_filters Warts::File::TRACE, Warts::File::CYCLE_START,
+    Warts::File::CYCLE_STOP, Warts::File::CYCLE_DEF
+
+  file.read do |element|
+    case element.element_type
+    when Warts::File::TRACE
+      num_traces += 1
+    when Warts::File::CYCLE_START, Warts::File::CYCLE_STOP,
+      Warts::File::CYCLE_DEF
+      puts "\n===> cycle " + CYCLE_TYPE[element.element_type]
+      puts "        id: " + element.id.to_s
+      puts "start_time: " + t(element.start_time)
+      puts " stop_time: " + t(element.stop_time)
+      puts "  hostname: " + element.hostname
+    end
+  end
+end
+
+puts "# traces: " + num_traces.to_s

data/docs/tut-13-write.rb

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'wartslib'
+
+out = Warts::File::open "out.warts", "w"
+
+Warts::File::open(ARGV[0]) do |file|
+  file.add_filters Warts::File::TRACE
+  file.read do |trace|
+    if trace.dest_responded? && trace.path_length > 5
+      out.write trace
+    end
+  end
+end
+
+out.close

data/docs/tut-14-write2.rb

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'wartslib'
+
+out = Warts::File::open "out.warts", "w"
+
+Warts::File::open(ARGV[0]) do |file|
+  file.add_filters Warts::File::TRACE, Warts::File::CYCLE_START,
+    Warts::File::CYCLE_STOP
+  file.read do |element|
+    if element.element_type == Warts::File::TRACE
+      if element.dest_responded? && element.path_length > 5
+        out.write element
+      end
+    else
+      out.write element
+    end
+  end
+end
+
+out.close

data/docs/tut-15-write3.rb

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'wartslib'
+
+out = Warts::File::open "out.txt", "w", Warts::File::TRACEROUTE
+
+Warts::File::open(ARGV[0]) do |file|
+  file.add_filters Warts::File::TRACE
+  file.read do |trace|
+    out.write trace
+  end
+end
+
+out.close

data/docs/tut-16-write4.rb

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'wartslib'
+
+out = Warts::File::open $stdout, "w", Warts::File::TRACEROUTE
+
+Warts::File::open(ARGV[0]) do |file|
+  file.add_filters Warts::File::TRACE
+  file.read do |trace|
+    out.write trace
+  end
+end

data/docs/tut-17-modify.rb

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'wartslib'
+
+out = Warts::File::open "out.warts", "w"
+
+cycle = nil
+Warts::File.open(ARGV[0]) do |file|
+  file.add_all_filters
+  file.read do |element|
+    case element.element_type
+    when Warts::File::TRACE
+      element.cycle = cycle
+
+    when Warts::File::CYCLE_START, Warts::File::CYCLE_DEF,
+      Warts::File::CYCLE_STOP
+      element = element.derive(:id => 5, :hostname => "foo.bar.com")
+      unless element.element_type == Warts::File::CYCLE_STOP
+        cycle = element 
+      end
+    end
+
+    out.write element
+  end
+end
+
+out.close

data/docs/tut-18-modify2.rb

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'wartslib'
+
+out = Warts::File::open "out.warts", "w"
+
+cycle = nil
+Warts::File.open(ARGV[0]) do |file|
+  file.add_all_filters
+  file.read do |element|
+    case element.element_type
+    when Warts::File::TRACE
+      element.cycle = cycle
+
+    when Warts::File::CYCLE_START, Warts::File::CYCLE_DEF,
+      Warts::File::CYCLE_STOP
+      list = element.list.derive(:name => "dnssurvey")
+      element = element.derive(:id => 5, :list => list)
+      unless element.element_type == Warts::File::CYCLE_STOP
+        cycle = element 
+      end
+    end
+
+    out.write element
+  end
+end
+
+out.close

data/docs/tut-2-count-block.rb

@@ -0,0 +1,10 @@
+require 'rubygems'
+require 'wartslib'
+
+Warts::File::open(ARGV[0]) do |file|
+  file.add_filters Warts::File::TRACE
+
+  count = 0
+  file.read { count += 1 }
+  puts count
+end

data/docs/tut-3-count-resp.rb

@@ -0,0 +1,16 @@
+require 'rubygems'
+require 'wartslib'
+
+Warts::File::open(ARGV[0]) do |file|
+  file.add_filters Warts::File::TRACE
+
+  count = 0
+  file.read do |trace|
+    if trace.dest_responded? && trace.path_length > 5
+      print trace.start, " ", trace.dst, " ", trace.path_length, "\n"
+      count += 1
+    end
+  end
+
+  puts count
+end

data/docs/tut-4-path-length.rb

@@ -0,0 +1,44 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'wartslib'
+
+num_traces = 0
+num_responding = 0
+stop_reason = Hash.new 0
+hop_histogram = Hash.new 0
+
+Warts::File.open(ARGV[0]) do |file|
+  file.add_filters Warts::File::TRACE
+  file.read do |trace|
+    num_traces += 1
+    num_responding += 1 if trace.dest_responded?
+    stop_reason[trace.stop_reason] += 1
+    hop_histogram[trace.path_length] += 1
+  end
+end
+
+puts "%8d traces" % [num_traces]
+puts "%8d responding" % [num_responding]
+
+# from scamper_trace.h:SCAMPER_TRACE_STOP_*
+stop_text = {
+  0 => "none (null reason)",
+  1 => "completed (got an ICMP port unreach)",
+  2 => "unreach (got an other ICMP unreach code)",
+  3 => "icmp (got an ICMP msg, not unreach)",
+  4 => "loop (loop detected)",
+  5 => "dead (unresponsive target)",
+  6 => "error (sendto error)"
+}
+stop_text.default = "<<UNKNOWN STOP CODE>>"
+
+puts
+stop_reason.to_a.sort.each do |k, v|
+  puts "%8d stop reason %d, %s" % [v, k, stop_text[k]]
+end
+
+puts
+hop_histogram.to_a.sort.each do |k, v|
+  puts "%8d %d hops" % [v, k]
+end

data/docs/tut-5-hop-addr.rb

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'wartslib'
+
+Warts::File.open(ARGV[0]) do |file|
+  file.add_filters Warts::File::TRACE
+  file.read do |trace|
+    puts "trace to " + trace.dst
+    (0 ... trace.hop_count).each do |i|
+      puts "  #{i+1} " + (trace.hop_addr(i) || "*")
+    end
+  end
+end

data/docs/tut-6-hop-addr2.rb

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'wartslib'
+
+Warts::File.open(ARGV[0]) do |file|
+  file.add_filters Warts::File::TRACE
+  file.read do |trace|
+    puts "trace to " + trace.dst
+    trace.each_hop do |i, exists|
+      puts "  #{i+1} " + (exists ? trace.hop_addr(i) : "*")
+    end
+  end
+end

data/docs/tut-7-hop-addr3.rb

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'wartslib'
+
+Warts::File.open(ARGV[0]) do |file|
+  file.add_filters Warts::File::TRACE
+  file.read do |trace|
+    puts "trace to " + trace.dst
+    trace.each_hop do |hop, exists|
+      print "  #{hop+1}"
+      if exists
+        trace.each_response(hop) do |response|
+          print "  ", trace.hop_addr(hop, response)
+        end
+        puts
+      else
+        puts " *"
+      end
+    end
+  end
+end

data/docs/tut-8-hop-addr4.rb

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'wartslib'
+
+Warts::File.open(ARGV[0]) do |file|
+  file.add_filters Warts::File::TRACE
+  file.read do |trace|
+    puts "trace to " + trace.dst
+    trace.each_hop_and_response do |hop, response, hop_exists|
+      printf "  hop=%d, resp=%d: %s\n", hop, response,
+        (hop_exists ? trace.hop_addr(hop, response) : "*")
+    end
+  end
+end

data/docs/tut-9-list.rb

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'wartslib'
+
+Warts::File.open(ARGV[0]) do |file|
+  file.add_filters Warts::File::TRACE
+  trace = file.read
+  if trace
+    list = trace.list
+    puts "     id: " + list.id.to_s
+    puts "   name: " + list.name
+    puts "  descr: " + list.descr
+    puts "monitor: " + list.monitor
+  end
+end

data/docs/tutorial.html

@@ -0,0 +1,950 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+  <title>rb-wartslib: Tutorial</title>
+  <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+  <link rel="stylesheet" type="text/css" href="layout.css">
+  <link rel="stylesheet" type="text/css" href="style.css">
+  <link rel="stylesheet" type="text/css" href="ruby.css">
+</head>
+
+<body>
+
+<div class="twikiTopBar">
+<div class="twikiTopBarContents">
+<h1 class="pagetitle">rb-wartslib: Ruby Warts Library</h1>
+</div>
+</div>
+
+<a name="PageTop"></a>
+<div class="twikiLeftBar">
+<div class="twikiLeftBarContents">
+<ul>
+<li> <a href="index.html">Project Home Page</a></li>
+<li> <a href="http://rubyforge.org/projects/rb-wartslib/">RubyForge Page</a></li>
+</ul>
+<hr>
+<ul>
+<li> <a href="index.html#installation">Installation</a></li>
+<li> <a href="tutorial.html"><b>Tutorial</b></a></li>
+<li> <a href="#basic_usage">&nbsp;&nbsp;&bull; Basic Usage</a></li>
+<li> <a href="#trace_attributes">&nbsp;&nbsp;&bull; Trace Attributes</a></li>
+<li> <a href="#hop_attributes">&nbsp;&nbsp;&bull; Hop Attributes</a></li>
+<li> <a href="#list_attributes">&nbsp;&nbsp;&bull; List Attributes</a></li>
+<li> <a href="#cycle_attributes">&nbsp;&nbsp;&bull; Cycle Attributes</a></li>
+<li> <a href="#writing_files">&nbsp;&nbsp;&bull; Writing Files</a></li>
+<li> <a href="#modifying_data">&nbsp;&nbsp;&bull; Modifying Data</a></li>
+<li> <a href="reference.html">Class Reference</a></li>
+<li> <a href="samples.html">Sample Scripts</a></li>
+</ul>
+<hr>
+<ul>
+<li> <a href="index.html#contact">Contact</a></li>
+<li> <a href="index.html#license">License</a></li>
+</ul>
+</div></div>
+
+<div class="twikiMain">
+<div class="twikiTopic">
+<h1>Tutorial</h1>
+
+<h2><a name="basic_usage"></a>Basic Usage</h2>
+<p>
+Only a minimal amount of code is needed to use <i>rb-wartslib</i>, as the
+following script shows.  This script counts the number of traces in a file.
+</p>
+
+<!-- 1. count =========================================================== -->
+<pre class="ruby snippet">
+<span class="comment">#!/usr/bin/env ruby</span>
+
+<span class="ident">require</span> <span class="punct">'</span><span class="string">rubygems</span><span class="punct">'</span>
+<span class="ident">require</span> <span class="punct">'</span><span class="string">wartslib</span><span class="punct">'</span>
+
+<span class="ident">file</span> <span class="punct">=</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="ident">open</span> <span class="constant">ARGV</span><span class="punct">[</span><span class="number">0</span><span class="punct">]</span>
+<span class="ident">file</span><span class="punct">.</span><span class="ident">add_filters</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">TRACE</span>
+
+<span class="ident">count</span> <span class="punct">=</span> <span class="number">0</span>
+<span class="keyword">while</span> <span class="punct">(</span><span class="ident">trace</span> <span class="punct">=</span> <span class="ident">file</span><span class="punct">.</span><span class="ident">read</span><span class="punct">)</span>
+  <span class="ident">count</span> <span class="punct">+=</span> <span class="number">1</span>
+<span class="keyword">end</span>
+
+<span class="ident">file</span><span class="punct">.</span><span class="ident">close</span>
+<span class="ident">puts</span> <span class="ident">count</span>
+</pre>
+
+<p>
+You use the warts library in your scripts with the statement <code>require
+'wartslib'</code>.  There are no other <code>require</code> statements
+(other than <code>require 'rubygems'</code>) or other setup work you need
+to worry about.  As you can see, everything is contained inside
+the <code>Warts</code> top-level module.  The library is small, so there
+are only a handful of classes inside the <code>Warts</code> module.
+</p>
+
+<p>
+The Ruby binding has transparent support for reading (but not writing)
+files compressed with <a href="http://www.gzip.org/">gzip</a>,
+<a href="http://www.bzip.org/">bzip2</a>, or
+<a href="http://www.lzop.org/">lzop</a>.  In fact,
+the above example script (call it <code>count-traces</code>) will
+automatically work as-is on compressed files; for example:
+</p>
+
+<pre class="snippet">
+<span class="shell_command">$ ./count-traces 00024353.hourly.l7.t1.20071031-19.mnl-ph.warts.gz</span>
+<span class="command_output">17496</span>
+</pre>
+
+<p>
+You can manually specify the input file type with a parameter to
+the <code>Warts::File::open</code> method, but it is often easier to just
+let the library figure it out; for example, the above script works unchanged
+on an <a href="http://www.caida.org/tools/utilities/arts/">arts++</a> file:
+</p>
+
+<pre class="snippet">
+<span class="shell_command">$ ./count-traces l006.mwest.20070404_000.arts</span>
+<span class="command_output">155830</span>
+</pre>
+
+<p>
+Another convenient feature of the library is its support of Ruby blocks.
+For example, we can minimize the above script even further by rewriting it
+to use blocks (from now on, we will leave out the two <code>require</code>
+lines in code listings):
+</p>
+
+<!-- 2. count+blocks ==================================================== -->
+<pre class="ruby snippet">
+<span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="ident">open</span><span class="punct">(<span class="constant">ARGV</span><span class="punct">[</span><span class="number">0</span><span class="punct">]</span>)</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">file</span><span class="punct">|</span>
+  <span class="ident">file</span><span class="punct">.</span><span class="ident">add_filters</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">TRACE</span>
+
+  <span class="ident">count</span> <span class="punct">=</span> <span class="number">0</span>
+  <span class="ident">file</span><span class="punct">.</span><span class="ident">read</span> <span class="punct">{</span> <span class="ident">count</span> <span class="punct">+=</span> <span class="number">1</span> <span class="punct">}</span>
+  <span class="ident">puts</span> <span class="ident">count</span>
+<span class="keyword">end</span>
+</pre>
+
+<p>
+The advantage to using a block for <code>Warts::File::open</code> is that
+the file is closed for you when the block finishes or if an exception occurs.
+</p>
+
+
+<h2><a name="trace_attributes"></a>Accessing Trace Attributes</h2>
+
+<p>
+Trace objects are instances of <code>Warts::Trace</code>.  Once you get a
+trace from <code>Warts::File#read</code>, you can use accessor methods to
+examine both the data and the metadata of a traceroute
+path.  <code>Warts::Trace</code> also provides a number of convenience methods.
+</p>
+
+<p>
+For example, the following script gives a count of the traces that have
+both a responding destination and a path length greater than 5.  For these
+traces, it prints out the trace timestamp, destination IP address, and the
+path length.
+</p>
+
+<!--- 3. count+resp ------------------------------------------------------>
+<pre class="ruby snippet">
+<span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="ident">open</span><span class="punct">(<span class="constant">ARGV</span><span class="punct">[</span><span class="number">0</span><span class="punct">]</span>)</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">file</span><span class="punct">|</span>
+  <span class="ident">file</span><span class="punct">.</span><span class="ident">add_filters</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">TRACE</span>
+
+  <span class="ident">count</span> <span class="punct">=</span> <span class="number">0</span>
+  <span class="ident">file</span><span class="punct">.</span><span class="ident">read</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">trace</span><span class="punct">|</span>
+    <span class="keyword">if</span> <span class="ident">trace</span><span class="punct">.</span><span class="ident">dest_responded?</span> <span class="punct">&amp;&amp;</span> <span class="ident">trace</span><span class="punct">.</span><span class="ident">path_length</span> <span class="punct">&gt;</span> <span class="number">5</span>
+      <span class="ident">print</span> <span class="ident">trace</span><span class="punct">.</span><span class="ident">start</span><span class="punct">,</span> <span class="punct">&quot;</span><span class="string"> </span><span class="punct">&quot;,</span> <span class="ident">trace</span><span class="punct">.</span><span class="ident">dst</span><span class="punct">,</span> <span class="punct">&quot;</span><span class="string"> </span><span class="punct">&quot;,</span> <span class="ident">trace</span><span class="punct">.</span><span class="ident">path_length</span><span class="punct">,</span> <span class="punct">&quot;</span><span class="string"><span class="escape">\n</span></span><span class="punct">&quot;</span>
+      <span class="ident">count</span> <span class="punct">+=</span> <span class="number">1</span>
+    <span class="keyword">end</span>
+  <span class="keyword">end</span>
+
+  <span class="ident">puts</span> <span class="ident">count</span>
+<span class="keyword">end</span>
+</pre>
+
+<pre class="snippet">
+<span class="shell_command">$ ./count-traces3 traces.warts</span>
+<span class="command_output">1169577966 10.205.150.148 17</span>
+<span class="command_output">1169577964 10.198.133.11 18</span>
+<span class="command_output">2</span>
+</pre>
+
+<p>
+It doesn't take much additional code to turn the above script into the
+beginnings of a full-featured trace statistics script; for example:
+</p>
+
+<!-- 4. stat-traces ====================================================== -->
+<pre class="ruby snippet">
+<span class="ident">num_traces</span> <span class="punct">=</span> <span class="number">0</span>
+<span class="ident">num_responding</span> <span class="punct">=</span> <span class="number">0</span>
+<span class="ident">stop_reason</span> <span class="punct">=</span> <span class="constant">Hash</span><span class="punct">.</span><span class="ident">new</span> <span class="number">0</span>
+<span class="ident">hop_histogram</span> <span class="punct">=</span> <span class="constant">Hash</span><span class="punct">.</span><span class="ident">new</span> <span class="number">0</span>
+
+<span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">.</span><span class="ident">open</span><span class="punct">(</span><span class="constant">ARGV</span><span class="punct">[</span><span class="number">0</span><span class="punct">])</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">file</span><span class="punct">|</span>
+  <span class="ident">file</span><span class="punct">.</span><span class="ident">add_filters</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">TRACE</span>
+  <span class="ident">file</span><span class="punct">.</span><span class="ident">read</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">trace</span><span class="punct">|</span>
+    <span class="ident">num_traces</span> <span class="punct">+=</span> <span class="number">1</span>
+    <span class="ident">num_responding</span> <span class="punct">+=</span> <span class="number">1</span> <span class="keyword">if</span> <span class="ident">trace</span><span class="punct">.</span><span class="ident">dest_responded?</span>
+    <span class="ident">stop_reason</span><span class="punct">[</span><span class="ident">trace</span><span class="punct">.</span><span class="ident">stop_reason</span><span class="punct">]</span> <span class="punct">+=</span> <span class="number">1</span>
+    <span class="ident">hop_histogram</span><span class="punct">[</span><span class="ident">trace</span><span class="punct">.</span><span class="ident">path_length</span><span class="punct">]</span> <span class="punct">+=</span> <span class="number">1</span>
+  <span class="keyword">end</span>
+<span class="keyword">end</span>
+
+<span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">%8d traces</span><span class="punct">&quot;</span> <span class="punct">%</span> <span class="punct">[</span><span class="ident">num_traces</span><span class="punct">]</span>
+<span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">%8d responding</span><span class="punct">&quot;</span> <span class="punct">%</span> <span class="punct">[</span><span class="ident">num_responding</span><span class="punct">]</span>
+
+<span class="comment"># from scamper_trace.h:SCAMPER_TRACE_STOP_*</span>
+<span class="ident">stop_text</span> <span class="punct">=</span> <span class="punct">{</span>
+  <span class="number">0</span> <span class="punct">=&gt;</span> <span class="punct">&quot;</span><span class="string">none (null reason)</span><span class="punct">&quot;,</span>
+  <span class="number">1</span> <span class="punct">=&gt;</span> <span class="punct">&quot;</span><span class="string">completed (got an ICMP port unreach)</span><span class="punct">&quot;,</span>
+  <span class="number">2</span> <span class="punct">=&gt;</span> <span class="punct">&quot;</span><span class="string">unreach (got an other ICMP unreach code)</span><span class="punct">&quot;,</span>
+  <span class="number">3</span> <span class="punct">=&gt;</span> <span class="punct">&quot;</span><span class="string">icmp (got an ICMP msg, not unreach)</span><span class="punct">&quot;,</span>
+  <span class="number">4</span> <span class="punct">=&gt;</span> <span class="punct">&quot;</span><span class="string">loop (loop detected)</span><span class="punct">&quot;,</span>
+  <span class="number">5</span> <span class="punct">=&gt;</span> <span class="punct">&quot;</span><span class="string">dead (unresponsive target)</span><span class="punct">&quot;,</span>
+  <span class="number">6</span> <span class="punct">=&gt;</span> <span class="punct">&quot;</span><span class="string">error (sendto error)</span><span class="punct">&quot;</span>
+<span class="punct">}</span>
+<span class="ident">stop_text</span><span class="punct">.</span><span class="ident">default</span> <span class="punct">=</span> <span class="punct">&quot;</span><span class="string">&lt;&lt;UNKNOWN STOP CODE&gt;&gt;</span><span class="punct">&quot;</span>
+
+<span class="ident">puts</span>
+<span class="ident">stop_reason</span><span class="punct">.</span><span class="ident">to_a</span><span class="punct">.</span><span class="ident">sort</span><span class="punct">.</span><span class="ident">each</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">k</span><span class="punct">,</span> <span class="ident">v</span><span class="punct">|</span>
+  <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">%8d stop reason %d, %s</span><span class="punct">&quot;</span> <span class="punct">%</span> <span class="punct">[</span><span class="ident">v</span><span class="punct">,</span> <span class="ident">k</span><span class="punct">,</span> <span class="ident">stop_text</span><span class="punct">[</span><span class="ident">k</span><span class="punct">]]</span>
+<span class="keyword">end</span>
+
+<span class="ident">puts</span>
+<span class="ident">hop_histogram</span><span class="punct">.</span><span class="ident">to_a</span><span class="punct">.</span><span class="ident">sort</span><span class="punct">.</span><span class="ident">each</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">k</span><span class="punct">,</span> <span class="ident">v</span><span class="punct">|</span>
+  <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">%8d %d hops</span><span class="punct">&quot;</span> <span class="punct">%</span> <span class="punct">[</span><span class="ident">v</span><span class="punct">,</span> <span class="ident">k</span><span class="punct">]</span>
+<span class="keyword">end</span>
+</pre>
+
+<pre class="snippet">
+<span class="shell_command">$ ./stat-traces traces.warts</span>
+<span class="command_output">      49 traces</span>
+<span class="command_output">       2 responding</span>
+<span class="command_output"></span>
+<span class="command_output">       2 stop reason 1, completed (got an ICMP port unreach)</span>
+<span class="command_output">      13 stop reason 2, unreach (got an other ICMP unreach code)</span>
+<span class="command_output">      17 stop reason 4, loop (loop detected)</span>
+<span class="command_output">      17 stop reason 5, dead (unresponsive target)</span>
+<span class="command_output"></span>
+<span class="command_output">       3 2 hops</span>
+<span class="command_output">       1 4 hops</span>
+<span class="command_output">       1 6 hops</span>
+<span class="command_output">      11 7 hops</span>
+<span class="command_output">       5 8 hops</span>
+<span class="command_output">       2 9 hops</span>
+<span class="command_output">       1 10 hops</span>
+<span class="command_output">       ...</span>
+</pre>
+
+<h2><a name="hop_attributes"></a>Accessing Hop Attributes</h2>
+
+<p>
+You access information about a hop via the <code>Warts::Trace</code>
+object returned by <code>Warts::File#read</code>.  (Note: There isn't a
+separate class for trace hops, unlike in the underlying <i>scamper</i>
+implementation).
+</p>
+
+<p>
+Each accessor method for hop data is named with a <code>hop_</code> prefix;
+for example, <code>hop_addr</code> to obtain the IP address of a hop,
+and <code>hop_rtt</code> to obtain the RTT.  You pass an index to these
+hop accessor methods to indicate which hop to examine.  For example,
+<code>trace.hop_addr(0)</code> returns the address of the first hop (using
+zero-based indexing).
+</p>
+
+<p>
+If <i>scamper</i> did not receive a response at a given hop, then no hop
+data will be available in the trace object at that hop, and all of the hop
+accessor methods will return <code>nil</code> for that hop.  (The accessor
+methods will also return <code>nil</code> if the index you provide exceeds
+the highest available hop.)  You can also use the
+method <code>Warts::Trace#hop_exists?</code> to determine whether there is
+any hop data at a given index.
+</p>
+
+<p>
+Use the method <code>Warts::Trace#hop_count</code> to determine the upper
+bound on the hop indexes; in particular, all valid hop indexes must be
+strictly less than this value.  However, you shouldn't ascribe too much
+meaning to <code>hop_count</code>.  This value is not necessarily equal to
+the path length (you should use <code>Warts::Trace#path_length</code> to
+compute that) because of possible unresponsive hops at the end of a trace.
+This also means that there may be missing hop data at indexes leading up
+to <code>hop_count</code>.
+</p>
+
+<p>
+The following script prints out the IP path of each trace using hop
+accessor methods.
+</p>
+
+<!-- 5. hop-addr ========================================================= -->
+<pre class="ruby snippet">
+<span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">.</span><span class="ident">open</span><span class="punct">(</span><span class="constant">ARGV</span><span class="punct">[</span><span class="number">0</span><span class="punct">])</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">file</span><span class="punct">|</span>
+  <span class="ident">file</span><span class="punct">.</span><span class="ident">add_filters</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">TRACE</span>
+  <span class="ident">file</span><span class="punct">.</span><span class="ident">read</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">trace</span><span class="punct">|</span>
+    <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">trace to </span><span class="punct">&quot;</span> <span class="punct">+</span> <span class="ident">trace</span><span class="punct">.</span><span class="ident">dst</span>
+    <span class="punct">(</span><span class="number">0</span> <span class="punct">...</span> <span class="ident">trace</span><span class="punct">.</span><span class="ident">hop_count</span><span class="punct">).</span><span class="ident">each</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">i</span><span class="punct">|</span>
+      <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">  <span class="expr">#{i+1}</span> </span><span class="punct">&quot;</span> <span class="punct">+</span> <span class="punct">(</span><span class="ident">trace</span><span class="punct">.</span><span class="ident">hop_addr</span><span class="punct">(</span><span class="ident">i</span><span class="punct">)</span> <span class="punct">||</span> <span class="punct">&quot;</span><span class="string">*</span><span class="punct">&quot;)</span>
+    <span class="keyword">end</span>
+  <span class="keyword">end</span>
+<span class="keyword">end</span>
+</pre>
+
+<pre class="snippet">
+<span class="shell_command">$ hop-addr traces.warts</span>
+<span class="command_output">trace to 10.72.146.120</span>
+<span class="command_output">  1 10.172.226.1</span>
+<span class="command_output">  2 10.17.46.8</span>
+<span class="command_output">  3 10.164.24.205</span>
+<span class="command_output">  4 10.71.128.5</span>
+<span class="command_output">  5 10.68.102.97</span>
+<span class="command_output">  6 10.68.128.157</span>
+<span class="command_output">  7 10.68.121.194</span>
+<span class="command_output">  8 10.68.110.162</span>
+<span class="command_output">  9 10.171.214.137</span>
+<span class="command_output">  10 *</span>
+<span class="command_output">  11 10.171.14.170</span>
+<span class="command_output">  12 10.115.84.234</span>
+<span class="command_output">trace to 10.252.182.175</span>
+<span class="command_output">  1 10.172.226.1</span>
+<span class="command_output">  2 10.17.46.8</span>
+<span class="command_output">  3 10.164.24.157</span>
+<span class="command_output">  4 10.164.22.231</span>
+<span class="command_output">  5 *</span>
+<span class="command_output">  6 *</span>
+<span class="command_output">  7 *</span>
+<span class="command_output">  8 *</span>
+<span class="command_output">  9 *</span>
+<span class="command_output">trace to 10.98.198.154</span>
+<span class="command_output">  ...</span>
+</pre>
+
+<p>
+In the second trace above, there are five consecutive unresponsive hops
+at the end of the trace.  Therefore, <code>Trace#path_length</code>
+will return 4, while <code>Trace#hop_count</code> will return 9.
+As you can see, <code>path_length</code> indicates the highest
+<b>responding</b> hop, while <code>hop_count</code> indicates the
+highest <b>attempted</b> hop.
+</p>
+
+<p>
+<code>Warts::Trace#each_hop</code> provides a more succinct way of
+iterating over all hops and, at the same time, getting an indication of hop
+existence, as demonstrated in the following script:
+</p>
+
+<!-- 6. hop-addr2 ======================================================== -->
+<pre class="ruby snippet">
+<span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">.</span><span class="ident">open</span><span class="punct">(</span><span class="constant">ARGV</span><span class="punct">[</span><span class="number">0</span><span class="punct">])</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">file</span><span class="punct">|</span>
+  <span class="ident">file</span><span class="punct">.</span><span class="ident">add_filters</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">TRACE</span>
+  <span class="ident">file</span><span class="punct">.</span><span class="ident">read</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">trace</span><span class="punct">|</span>
+    <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">trace to </span><span class="punct">&quot;</span> <span class="punct">+</span> <span class="ident">trace</span><span class="punct">.</span><span class="ident">dst</span>
+    <span class="ident">trace</span><span class="punct">.</span><span class="ident">each_hop</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">i</span><span class="punct">,</span> <span class="ident">exists</span><span class="punct">|</span>
+      <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">  <span class="expr">#{i+1}</span> </span><span class="punct">&quot;</span> <span class="punct">+</span> <span class="punct">(</span><span class="ident">exists</span> <span class="punct">?</span> <span class="ident">trace</span><span class="punct">.</span><span class="ident">hop_addr</span><span class="punct">(</span><span class="ident">i</span><span class="punct">)</span> <span class="punct">:</span> <span class="punct">&quot;</span><span class="string">*</span><span class="punct">&quot;)</span>
+    <span class="keyword">end</span>
+  <span class="keyword">end</span>
+<span class="keyword">end</span>
+</pre>
+
+<h3>Multiple Hop Responses</h3>
+
+<p>
+All sample scripts so far have assumed that a hop can only have one
+response, if it has a response at all.  This is the case most of the time,
+and making this assumption simplifies the analysis with usually only a
+slight loss of information.  However, <i>scamper</i> may store as many
+as <i>N</i> different responses at a given hop, depending on <i>scamper</i>
+settings and the responsiveness of intermediate hops during probing.  With
+the default settings, <i>scamper</i> makes up to 2 attempts per hop; that
+is, if the first probe to a hop doesn't elicit a response within some
+timeout period, then <i>scamper</i> will send out a second probe.  As a
+result, a hop can have 0, 1, or 2 recorded responses, although the case of
+2 recorded responses will only happen under a rare scenario--namely, when
+the response to the first attempt is delayed and arrives after the second
+attempt is made.  Of course, if you increase the setting for the maximum
+number of attempts per hop, then the chance of getting multiple responses
+at a hop will also increase.
+</p>
+
+<p>
+You are much more likely to encounter multiple responses at a hop if you
+explicitly configure <i>scamper</i> to always try <i>N</i> attempts at each
+hop, regardless of responsiveness, and to store all received responses.
+This is the way that <code>traceroute</code> is normally run, with it
+always making 3 attempts at each hop.
+</p>
+
+<p>
+Fortunately, working with multiple responses at a hop is easy.  Every hop
+accessor method, like <code>hop_addr</code>, can actually take two
+parameters.  The first parameter is the hop index, as you've already seen.
+The second parameter is the <b>response</b> index, beginning with 0 for the
+first response.  The response parameter has a default value of 0, which is
+the reason we were able to leave it out in the sample code so far.  Hence,
+the call <code>hop_addr(i)</code> is equivalent to <code>hop_addr(i,
+0)</code>.  One way to iterate over all responses at a given hop is to
+use <code>Warts::Trace#each_response</code>, as illustrated by the
+following script, which prints out the IP address of all responses at all
+hops:
+</p>
+
+<!-- 7. hop-addr3 ======================================================== -->
+<pre class="ruby snippet">
+<span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">.</span><span class="ident">open</span><span class="punct">(</span><span class="constant">ARGV</span><span class="punct">[</span><span class="number">0</span><span class="punct">])</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">file</span><span class="punct">|</span>
+  <span class="ident">file</span><span class="punct">.</span><span class="ident">add_filters</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">TRACE</span>
+  <span class="ident">file</span><span class="punct">.</span><span class="ident">read</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">trace</span><span class="punct">|</span>
+    <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">trace to </span><span class="punct">&quot;</span> <span class="punct">+</span> <span class="ident">trace</span><span class="punct">.</span><span class="ident">dst</span>
+    <span class="ident">trace</span><span class="punct">.</span><span class="ident">each_hop</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">hop</span><span class="punct">,</span> <span class="ident">exists</span><span class="punct">|</span>
+      <span class="ident">print</span> <span class="punct">&quot;</span><span class="string">  <span class="expr">#{hop+1}</span></span><span class="punct">&quot;</span>
+      <span class="keyword">if</span> <span class="ident">exists</span>
+        <span class="ident">trace</span><span class="punct">.</span><span class="ident">each_response</span><span class="punct">(</span><span class="ident">hop</span><span class="punct">)</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">response</span><span class="punct">|</span>
+          <span class="ident">print</span> <span class="punct">&quot;</span><span class="string">  </span><span class="punct">&quot;,</span> <span class="ident">trace</span><span class="punct">.</span><span class="ident">hop_addr</span><span class="punct">(</span><span class="ident">hop</span><span class="punct">,</span> <span class="ident">response</span><span class="punct">)</span>
+        <span class="keyword">end</span>
+        <span class="ident">puts</span>
+      <span class="keyword">else</span>
+        <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string"> *</span><span class="punct">&quot;</span>
+      <span class="keyword">end</span>
+    <span class="keyword">end</span>
+  <span class="keyword">end</span>
+<span class="keyword">end</span>
+</pre>
+
+<pre class="snippet">
+<span class="shell_command">$ hop-response traces.warts</span>
+<span class="command_output">trace to 10.72.146.120</span>
+<span class="command_output">  1  10.172.226.1</span>
+<span class="command_output">  2  10.17.46.8  10.17.46.10</span>
+<span class="command_output">  3  10.164.24.205  10.164.24.207</span>
+<span class="command_output">  4  *</span>
+<span class="command_output">  5  10.68.121.194</span>
+<span class="command_output">  6  10.72.146.120</span>
+</pre>
+
+<p>
+You can iterate over both hops and responses at the same time with
+<code>Warts::Trace#each_hop_and_response</code> (or more simply
+<code>Warts::Trace#each</code>).  The following script prints out the
+IP address of all responses of all hops:
+</p>
+
+<!-- 8. hop-addr4 ======================================================== -->
+<pre class="ruby snippet">
+<span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">.</span><span class="ident">open</span><span class="punct">(</span><span class="constant">ARGV</span><span class="punct">[</span><span class="number">0</span><span class="punct">])</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">file</span><span class="punct">|</span>
+  <span class="ident">file</span><span class="punct">.</span><span class="ident">add_filters</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">TRACE</span>
+  <span class="ident">file</span><span class="punct">.</span><span class="ident">read</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">trace</span><span class="punct">|</span>
+    <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">trace to </span><span class="punct">&quot;</span> <span class="punct">+</span> <span class="ident">trace</span><span class="punct">.</span><span class="ident">dst</span>
+    <span class="ident">trace</span><span class="punct">.</span><span class="ident">each_hop_and_response</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">hop</span><span class="punct">,</span> <span class="ident">response</span><span class="punct">,</span> <span class="ident">hop_exists</span><span class="punct">|</span>
+      <span class="ident">printf</span> <span class="punct">&quot;</span><span class="string">  hop=%d, resp=%d: %s<span class="escape">\n</span></span><span class="punct">&quot;,</span> <span class="ident">hop</span><span class="punct">,</span> <span class="ident">response</span><span class="punct">,</span>
+        <span class="punct">(</span><span class="ident">hop_exists</span> <span class="punct">?</span> <span class="ident">trace</span><span class="punct">.</span><span class="ident">hop_addr</span><span class="punct">(</span><span class="ident">hop</span><span class="punct">,</span> <span class="ident">response</span><span class="punct">)</span> <span class="punct">:</span> <span class="punct">&quot;</span><span class="string">*</span><span class="punct">&quot;)</span>
+    <span class="keyword">end</span>
+  <span class="keyword">end</span>
+<span class="keyword">end</span>
+</pre>
+
+<pre class="snippet">
+<span class="shell_command">$ hop-response2 traces.warts</span>
+<span class="command_output">trace to 10.72.146.120</span>
+<span class="command_output">  hop=0, resp=0: 10.172.226.1</span>
+<span class="command_output">  hop=1, resp=0: 10.17.46.8</span>
+<span class="command_output">  hop=1, resp=1: 10.17.46.10</span>
+<span class="command_output">  hop=2, resp=0: 10.164.24.205</span>
+<span class="command_output">  hop=2, resp=1: 10.164.24.207</span>
+<span class="command_output">  hop=3, resp=0: *</span>
+<span class="command_output">  hop=4, resp=0: 10.68.121.194</span>
+<span class="command_output">  hop=5, resp=0: 10.72.146.120</span>
+</pre>
+
+
+<h2><a name="list_attributes"></a>Accessing List Attributes</h2>
+
+<p>
+In the terminology of <i>scamper</i>, a <b>list</b> is a set of destination
+addresses.  You typically store a list in a file, and give the name of the
+file to <i>scamper</i> on the command line.  A list has some logical
+identity, and for the purposes of keeping track of which list a trace
+belongs to, it is helpful to record the list ID number, name, and/or a
+description in a trace file.  <i>scamper</i> itself doesn't need or use
+this sort of descriptive information about a list, but it can store this
+information in generated trace files on your behalf.
+</p>
+
+<p>
+Given a warts file, you can examine any recorded information about lists in
+one of two ways.  The first way is to use the accessor
+method <code>Warts::Trace#list</code> to get information about the list to
+which a particular trace belongs (a warts file can contain traces from more
+than one list, but a given trace can only belong to a single list).  The
+list information is returned in the form of a <code>Warts::List</code>
+object, which has accessors for the list ID, name, and description.
+(<code>Warts::List</code> also stores the canonical name of the measurement
+monitor.)  For example, the following script prints out the list
+information for the first trace in a warts file:
+</p>
+
+<!-- 9. list =========================================================== -->
+<pre class="ruby snippet">
+<span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">.</span><span class="ident">open</span><span class="punct">(</span><span class="constant">ARGV</span><span class="punct">[</span><span class="number">0</span><span class="punct">])</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">file</span><span class="punct">|</span>
+  <span class="ident">file</span><span class="punct">.</span><span class="ident">add_filters</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">TRACE</span>
+  <span class="ident">trace</span> <span class="punct">=</span> <span class="ident">file</span><span class="punct">.</span><span class="ident">read</span>
+  <span class="keyword">if</span> <span class="ident">trace</span>
+    <span class="ident">list</span> <span class="punct">=</span> <span class="ident">trace</span><span class="punct">.</span><span class="ident">list</span>
+    <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">     id: </span><span class="punct">&quot;</span> <span class="punct">+</span> <span class="ident">list</span><span class="punct">.</span><span class="ident">id</span><span class="punct">.</span><span class="ident">to_s</span>
+    <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">   name: </span><span class="punct">&quot;</span> <span class="punct">+</span> <span class="ident">list</span><span class="punct">.</span><span class="ident">name</span>
+    <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">  descr: </span><span class="punct">&quot;</span> <span class="punct">+</span> <span class="ident">list</span><span class="punct">.</span><span class="ident">descr</span>
+    <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">monitor: </span><span class="punct">&quot;</span> <span class="punct">+</span> <span class="ident">list</span><span class="punct">.</span><span class="ident">monitor</span>
+  <span class="keyword">end</span>
+<span class="keyword">end</span>
+</pre>
+
+<pre class="snippet">
+<span class="shell_command">$ ./list-info traces.warts</span>
+<span class="command_output">     id: 2</span>
+<span class="command_output">   name: allpref24</span>
+<span class="command_output">  descr: One randomly-selected address in every routed /24.</span>
+<span class="command_output">monitor: mnl-ph</span>
+</pre>
+
+<p>
+The second way to examine list information is to directly retrieve the
+<code>Warts::List</code> objects stored in a warts file rather than
+accessing them indirectly via a <code>Warts::Trace</code> object.  For
+example, the following script examines all list and trace objects in a
+warts file, printing out the details of each encountered list object and
+counting encountered traces (note the
+additional <code>Warts::File::LIST</code> passed
+to <code>File#add_filters</code>):
+</p>
+
+<!-- 10. list2 ========================================================== -->
+<pre class="ruby snippet">
+<span class="ident">num_traces</span> <span class="punct">=</span> <span class="number">0</span>
+<span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">.</span><span class="ident">open</span><span class="punct">(</span><span class="constant">ARGV</span><span class="punct">[</span><span class="number">0</span><span class="punct">])</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">file</span><span class="punct">|</span>
+  <span class="ident">file</span><span class="punct">.</span><span class="ident">add_filters</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">TRACE</span><span class="punct">,</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">LIST</span>
+  <span class="ident">file</span><span class="punct">.</span><span class="ident">read</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">element</span><span class="punct">|</span>
+    <span class="keyword">case</span> <span class="ident">element</span><span class="punct">.</span><span class="ident">element_type</span>
+    <span class="keyword">when</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">TRACE</span>
+      <span class="ident">num_traces</span> <span class="punct">+=</span> <span class="number">1</span>
+    <span class="keyword">when</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">LIST</span>
+      <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">     id: </span><span class="punct">&quot;</span> <span class="punct">+</span> <span class="ident">element</span><span class="punct">.</span><span class="ident">id</span><span class="punct">.</span><span class="ident">to_s</span>
+      <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">   name: </span><span class="punct">&quot;</span> <span class="punct">+</span> <span class="ident">element</span><span class="punct">.</span><span class="ident">name</span>
+      <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">  descr: </span><span class="punct">&quot;</span> <span class="punct">+</span> <span class="ident">element</span><span class="punct">.</span><span class="ident">descr</span>
+      <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">monitor: </span><span class="punct">&quot;</span> <span class="punct">+</span> <span class="ident">element</span><span class="punct">.</span><span class="ident">monitor</span>
+    <span class="keyword">end</span>
+  <span class="keyword">end</span>
+<span class="keyword">end</span>
+
+<span class="ident">puts</span> <span class="punct">&quot;</span><span class="string"># traces: </span><span class="punct">&quot;</span> <span class="punct">+</span> <span class="ident">num_traces</span><span class="punct">.</span><span class="ident">to_s</span>
+</pre>
+
+<pre class="snippet">
+<span class="shell_command">$ ./list-info2 traces.warts</span>
+<span class="command_output">     id: 2</span>
+<span class="command_output">   name: allpref24</span>
+<span class="command_output">  descr: One randomly-selected address in every routed /24.</span>
+<span class="command_output">monitor: mnl-ph</span>
+<span class="command_output">     id: 3</span>
+<span class="command_output">   name: dnssurvey</span>
+<span class="command_output">  descr: Top 500 DNS servers.</span>
+<span class="command_output">monitor: mnl-ph</span>
+<span class="command_output"># traces: 17496</span>
+</pre>
+
+
+<h2><a name="cycle_attributes"></a>Accessing Cycle Attributes</h2>
+
+<p>
+In the terminology of <i>scamper</i>, a <b>cycle</b> is a single pass
+through a destination list.  A single warts file can contain multiple
+cycles of data.
+</p>
+
+<p>
+Just as for list information, there are two ways of getting at cycle
+information stored in a warts file.  The first way is to use the accessor
+method <code>Warts::Trace#cycle</code> to get information about the cycle
+in which a trace was collected.  The cycle information is returned in the
+form of a <code>Warts::Cycle</code> object, which has accessors for the
+cycle ID, start time, and stop time.  (<code>Warts::Cycle</code> also
+stores the hostname of the measurement monitor at the start of the cycle,
+and you can get the associated list with <code>Warts::Cycle#list</code>.)
+For example, the following script prints out the cycle information for the
+first trace in a warts file:
+</p>
+
+<!-- 11. cycle ========================================================== -->
+<pre class="ruby snippet">
+<span class="keyword">def </span><span class="method">t</span><span class="punct">(</span><span class="ident">timestamp</span><span class="punct">)</span>
+  <span class="ident">timestamp</span><span class="punct">.</span><span class="ident">to_s</span> <span class="punct">+</span> <span class="punct">&quot;</span><span class="string"> (</span><span class="punct">&quot;</span> <span class="punct">+</span> <span class="constant">Time</span><span class="punct">.</span><span class="ident">at</span><span class="punct">(</span><span class="ident">timestamp</span><span class="punct">).</span><span class="ident">to_s</span> <span class="punct">+</span> <span class="punct">&quot;</span><span class="string">)</span><span class="punct">&quot;</span>
+<span class="keyword">end</span>
+
+<span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">.</span><span class="ident">open</span><span class="punct">(</span><span class="constant">ARGV</span><span class="punct">[</span><span class="number">0</span><span class="punct">])</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">file</span><span class="punct">|</span>
+  <span class="ident">file</span><span class="punct">.</span><span class="ident">add_filters</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">TRACE</span>
+  <span class="ident">trace</span> <span class="punct">=</span> <span class="ident">file</span><span class="punct">.</span><span class="ident">read</span>
+  <span class="keyword">if</span> <span class="ident">trace</span>
+    <span class="ident">cycle</span> <span class="punct">=</span> <span class="ident">trace</span><span class="punct">.</span><span class="ident">cycle</span>
+    <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">        id: </span><span class="punct">&quot;</span> <span class="punct">+</span> <span class="ident">cycle</span><span class="punct">.</span><span class="ident">id</span><span class="punct">.</span><span class="ident">to_s</span>
+    <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">start_time: </span><span class="punct">&quot;</span> <span class="punct">+</span> <span class="ident">t</span><span class="punct">(</span><span class="ident">cycle</span><span class="punct">.</span><span class="ident">start_time</span><span class="punct">)</span>
+    <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string"> stop_time: </span><span class="punct">&quot;</span> <span class="punct">+</span> <span class="ident">t</span><span class="punct">(</span><span class="ident">cycle</span><span class="punct">.</span><span class="ident">stop_time</span><span class="punct">)</span>
+    <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">  hostname: </span><span class="punct">&quot;</span> <span class="punct">+</span> <span class="ident">cycle</span><span class="punct">.</span><span class="ident">hostname</span>
+  <span class="keyword">end</span>
+<span class="keyword">end</span>
+</pre>
+
+<p>
+The second way to examine cycle information is to directly retrieve
+the <code>Warts::Cycle</code> objects stored in a warts file rather than
+accessing them indirectly via a <code>Warts::Trace</code> object.  There
+are actually three types of cycle objects: cycle <b>start</b>, cycle
+<b>stop</b>, and cycle <b>def</b>.  However, all three types of objects are
+represented with the same class.  You can determine the cycle type
+with <code>Warts::Cycle#element_type</code>.
+</p>
+
+<p>
+<i>scamper</i> writes out cycle-start and cycle-stop records at the
+beginning and end of a cycle, as you would expect.  <i>scamper</i> writes
+out a cycle-def record only when needed and only when the traces in a cycle
+are stored across multiple files.  The following figure should help clarify
+the role of cycle-def records.  Because the traces of the second cycle
+spill over from <code>trace1.warts</code>
+to <code>trace2.warts</code>, <i>scamper</i> writes out a cycle-def record
+at the beginning of the latter file.
+</p>
+
+<pre>
+    +====================+
+    | cycle <span class="fig_green">start</span> record |   <span class="fig_blue">trace1.warts</span>
+    +--------------------+
+    |       trace 1      |
+    |       trace 2      |
+    |         ...        |
+    |       trace n      |
+    +--------------------+
+    | cycle <span class="fig_green">stop</span> record  |
+    +--------------------+
+    | cycle <span class="fig_green">start</span> record |
+    +--------------------+
+    |       trace 1      |
+    |       trace 2      |
+    |         ...        |
+    |     trace k < n    |
+    +====================+
+
+    +====================+
+    |  cycle <span class="fig_red">def</span> record  |   <span class="fig_blue">trace2.warts</span>
+    +--------------------+
+    |     trace k + 1    |
+    |     trace k + 2    |
+    |         ...        |
+    |       trace n      |
+    +--------------------+
+    | cycle <span class="fig_green">stop</span> record  |
+    +====================+
+</pre>
+
+<p>
+The following script examines all cycle and trace objects in a warts file,
+printing out the details of each encountered cycle object and counting
+encountered traces (note the additional <code>Warts::File::CYCLE_xxx</code>
+values passed to <code>File#add_filters</code>):
+</p>
+
+<!-- 12. cycle2 ========================================================== -->
+<pre class="ruby snippet">
+<span class="constant">CYCLE_TYPE</span> <span class="punct">=</span> <span class="punct">{</span>
+  <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">CYCLE_START</span> <span class="punct">=&gt;</span> <span class="punct">&quot;</span><span class="string">start</span><span class="punct">&quot;,</span>
+  <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">CYCLE_STOP</span> <span class="punct">=&gt;</span> <span class="punct">&quot;</span><span class="string">stop</span><span class="punct">&quot;,</span>
+  <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">CYCLE_DEF</span> <span class="punct">=&gt;</span> <span class="punct">&quot;</span><span class="string">def</span><span class="punct">&quot;</span>
+<span class="punct">}</span>
+
+<span class="keyword">def </span><span class="method">t</span><span class="punct">(</span><span class="ident">timestamp</span><span class="punct">)</span>
+  <span class="ident">timestamp</span><span class="punct">.</span><span class="ident">to_s</span> <span class="punct">+</span> <span class="punct">&quot;</span><span class="string"> (</span><span class="punct">&quot;</span> <span class="punct">+</span> <span class="constant">Time</span><span class="punct">.</span><span class="ident">at</span><span class="punct">(</span><span class="ident">timestamp</span><span class="punct">).</span><span class="ident">to_s</span> <span class="punct">+</span> <span class="punct">&quot;</span><span class="string">)</span><span class="punct">&quot;</span>
+<span class="keyword">end</span>
+
+<span class="ident">num_traces</span> <span class="punct">=</span> <span class="number">0</span>
+<span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">.</span><span class="ident">open</span><span class="punct">(</span><span class="constant">ARGV</span><span class="punct">[</span><span class="number">0</span><span class="punct">])</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">file</span><span class="punct">|</span>
+  <span class="ident">file</span><span class="punct">.</span><span class="ident">add_filters</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">TRACE</span><span class="punct">,</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">CYCLE_START</span><span class="punct">,</span>
+    <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">CYCLE_STOP</span><span class="punct">,</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">CYCLE_DEF</span>
+
+  <span class="ident">file</span><span class="punct">.</span><span class="ident">read</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">element</span><span class="punct">|</span>
+    <span class="keyword">case</span> <span class="ident">element</span><span class="punct">.</span><span class="ident">element_type</span>
+    <span class="keyword">when</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">TRACE</span>
+      <span class="ident">num_traces</span> <span class="punct">+=</span> <span class="number">1</span>
+    <span class="keyword">when</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">CYCLE_START</span><span class="punct">,</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">CYCLE_STOP</span><span class="punct">,</span>
+      <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">CYCLE_DEF</span>
+      <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string"><span class="escape">\n</span>===&gt; cycle </span><span class="punct">&quot;</span> <span class="punct">+</span> <span class="constant">CYCLE_TYPE</span><span class="punct">[</span><span class="ident">element</span><span class="punct">.</span><span class="ident">element_type</span><span class="punct">]</span>
+      <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">        id: </span><span class="punct">&quot;</span> <span class="punct">+</span> <span class="ident">element</span><span class="punct">.</span><span class="ident">id</span><span class="punct">.</span><span class="ident">to_s</span>
+      <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">start_time: </span><span class="punct">&quot;</span> <span class="punct">+</span> <span class="ident">t</span><span class="punct">(</span><span class="ident">element</span><span class="punct">.</span><span class="ident">start_time</span><span class="punct">)</span>
+      <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string"> stop_time: </span><span class="punct">&quot;</span> <span class="punct">+</span> <span class="ident">t</span><span class="punct">(</span><span class="ident">element</span><span class="punct">.</span><span class="ident">stop_time</span><span class="punct">)</span>
+      <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">  hostname: </span><span class="punct">&quot;</span> <span class="punct">+</span> <span class="ident">element</span><span class="punct">.</span><span class="ident">hostname</span>
+    <span class="keyword">end</span>
+  <span class="keyword">end</span>
+<span class="keyword">end</span>
+
+<span class="ident">puts</span> <span class="punct">&quot;</span><span class="string"># traces: </span><span class="punct">&quot;</span> <span class="punct">+</span> <span class="ident">num_traces</span><span class="punct">.</span><span class="ident">to_s</span>
+</pre>
+
+
+<pre class="snippet">
+<span class="shell_command">$ ./cycle-info2 traces.warts</span>
+<span class="command_output"></span>
+<span class="command_output">===> cycle start</span>
+<span class="command_output">        id: 28</span>
+<span class="command_output">start_time: 1190158509 (Tue Sep 18 16:35:09 -0700 2007)</span>
+<span class="command_output"> stop_time: 0 (Wed Dec 31 16:00:00 -0800 1969)</span>
+<span class="command_output">  hostname: mnl-ph.ark.caida.org</span>
+<span class="command_output"></span>
+<span class="command_output">===> cycle stop</span>
+<span class="command_output">        id: 28</span>
+<span class="command_output">start_time: 1190158509 (Tue Sep 18 16:35:09 -0700 2007)</span>
+<span class="command_output"> stop_time: 1190159039 (Tue Sep 18 16:43:59 -0700 2007)</span>
+<span class="command_output">  hostname: mnl-ph.ark.caida.org</span>
+<span class="command_output"># traces: 17496</span>
+</pre>
+
+<p>
+<b>NOTE:</b> Warts files produced by
+the <a href="http://www.caida.org/projects/ark/">Archipelago
+Measurement Infrastructure</a> (Ark) don't have cycle start or stop
+records.  They only contain cycle def records, and there may be more
+than one cycle def record per file.  This happens because Ark
+reorganizes raw scamper traces into hourly and daily files, and the
+current implementation of the reorganization procedure doesn't
+preserve cycle start/stop records.  However, if you
+use <i>rb-wartslib</i> to process scamper traces you've collected
+yourself, then you will see cycle start, stop, and def records in the
+manner described above.
+</p>
+
+<h2><a name="writing_files"></a>Writing Files</h2>
+
+<p>
+You can write new warts files with this library.  This ability is useful
+for filtering out traces and for re-organizing traces into a different set
+of files (for example, into daily files).  Please note, however, that you
+can't create completely new traces in memory--that is, you can only write
+out traces you've read in from another file.
+</p>
+
+<p>
+For example, the following script writes a new file <code>out.warts</code>
+containing only the traces in the input file that have both a responding
+destination and a path length greater than 5:
+</p>
+
+<!-- 13. write ========================================================== -->
+<pre class="ruby snippet">
+<span class="ident">out</span> <span class="punct">=</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="ident">open</span> <span class="punct">&quot;</span><span class="string">out.warts</span><span class="punct">&quot;,</span> <span class="punct">&quot;</span><span class="string">w</span><span class="punct">&quot;</span>
+
+<span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="ident">open</span><span class="punct">(</span><span class="constant">ARGV</span><span class="punct">[</span><span class="number">0</span><span class="punct">])</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">file</span><span class="punct">|</span>
+  <span class="ident">file</span><span class="punct">.</span><span class="ident">add_filters</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">TRACE</span>
+  <span class="ident">file</span><span class="punct">.</span><span class="ident">read</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">trace</span><span class="punct">|</span>
+    <span class="keyword">if</span> <span class="ident">trace</span><span class="punct">.</span><span class="ident">dest_responded?</span> <span class="punct">&amp;&amp;</span> <span class="ident">trace</span><span class="punct">.</span><span class="ident">path_length</span> <span class="punct">&gt;</span> <span class="number">5</span>
+      <span class="ident">out</span><span class="punct">.</span><span class="ident">write</span> <span class="ident">trace</span>
+    <span class="keyword">end</span>
+  <span class="keyword">end</span>
+<span class="keyword">end</span>
+
+<span class="ident">out</span><span class="punct">.</span><span class="ident">close</span>
+</pre>
+
+<p>
+When you write out a trace object, the associated list and cycle objects
+are written out automatically, which is the reason why the above script is
+so simple.  However, only a cycle-def object is written out automatically,
+so information about the cycle end time will be missing in the output file
+(a cycle-def object has the start time so the lack of a cycle-start object
+isn't a real problem).  If all you want to do is analyze trace data, then
+having only the cycle-def object should be fine.  It's easy enough, though,
+to write out the cycle start and end objects yourself if you need them, as
+in the following script:
+</p>
+
+<!-- 14. write2 ========================================================== -->
+<pre class="ruby snippet">
+<span class="ident">out</span> <span class="punct">=</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="ident">open</span> <span class="punct">&quot;</span><span class="string">out.warts</span><span class="punct">&quot;,</span> <span class="punct">&quot;</span><span class="string">w</span><span class="punct">&quot;</span>
+
+<span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="ident">open</span><span class="punct">(</span><span class="constant">ARGV</span><span class="punct">[</span><span class="number">0</span><span class="punct">])</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">file</span><span class="punct">|</span>
+  <span class="ident">file</span><span class="punct">.</span><span class="ident">add_filters</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">TRACE</span><span class="punct">,</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">CYCLE_START</span><span class="punct">,</span>
+    <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">CYCLE_STOP</span>
+  <span class="ident">file</span><span class="punct">.</span><span class="ident">read</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">element</span><span class="punct">|</span>
+    <span class="keyword">if</span> <span class="ident">element</span><span class="punct">.</span><span class="ident">element_type</span> <span class="punct">==</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">TRACE</span>
+      <span class="keyword">if</span> <span class="ident">element</span><span class="punct">.</span><span class="ident">dest_responded?</span> <span class="punct">&amp;&amp;</span> <span class="ident">element</span><span class="punct">.</span><span class="ident">path_length</span> <span class="punct">&gt;</span> <span class="number">5</span>
+        <span class="ident">out</span><span class="punct">.</span><span class="ident">write</span> <span class="ident">element</span>
+      <span class="keyword">end</span>
+    <span class="keyword">else</span>
+      <span class="ident">out</span><span class="punct">.</span><span class="ident">write</span> <span class="ident">element</span>
+    <span class="keyword">end</span>
+  <span class="keyword">end</span>
+<span class="keyword">end</span>
+
+<span class="ident">out</span><span class="punct">.</span><span class="ident">close</span>
+</pre>
+
+<p>
+By default, files are written in the warts format.  You can also write out
+files in the traditional textual traceroute format, as illustrated by the
+following script:
+</p>
+
+<!-- 15. write3 ========================================================== -->
+<pre class="ruby snippet">
+<span class="ident">out</span> <span class="punct">=</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="ident">open</span> <span class="punct">&quot;</span><span class="string">out.txt</span><span class="punct">&quot;,</span> <span class="punct">&quot;</span><span class="string">w</span><span class="punct">&quot;,</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">TRACEROUTE</span>
+
+<span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="ident">open</span><span class="punct">(</span><span class="constant">ARGV</span><span class="punct">[</span><span class="number">0</span><span class="punct">])</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">file</span><span class="punct">|</span>
+  <span class="ident">file</span><span class="punct">.</span><span class="ident">add_filters</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">TRACE</span>
+  <span class="ident">file</span><span class="punct">.</span><span class="ident">read</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">trace</span><span class="punct">|</span>
+    <span class="ident">out</span><span class="punct">.</span><span class="ident">write</span> <span class="ident">trace</span>
+  <span class="keyword">end</span>
+<span class="keyword">end</span>
+
+<span class="ident">out</span><span class="punct">.</span><span class="ident">close</span>
+</pre>
+
+
+<pre class="snippet">
+<span class="shell_command">$ ./trace-txt traces.warts</span>
+<span class="shell_command">$ cat out.txt</span>
+<span class="command_output">traceroute from 10.172.226.88 to 10.58.204.93</spa
+n>
+<span class="command_output"> 1  10.172.226.1  0.789 ms</span>
+<span class="command_output"> 2  10.17.46.8  40.779 ms !N</span>
+<span class="command_output">traceroute from 10.172.226.88 to 10.237.229.96</sp
+an>
+<span class="command_output"> 1  10.172.226.1  0.805 ms</span>
+<span class="command_output"> 2  10.17.46.8  33.306 ms</span>
+<span class="command_output"> 3  10.164.24.205  5.271 ms</span>
+<span class="command_output"> 4  10.71.128.5  5.371 ms</span>
+<span class="command_output"> 5  10.68.102.190  5.841 ms</span>
+<span class="command_output"> 6  10.69.132.9  16.056 ms</span>
+<span class="command_output"> 7  10.69.132.9  13.406 ms</span>
+</pre>
+
+
+<p>
+The examples so far have opened files by path.  You can also read/write
+files that are already open by passing either an <code>IO</code> object
+(and by extension anything that derives from <code>IO</code> like files,
+pipes, and sockets) or a numeric file descriptor (a la Unix).  For example,
+the following script prints a warts file to stdout in the textual
+traceroute format:
+</p>
+
+<!-- 16. write4 ========================================================== -->
+<pre class="ruby snippet">
+<span class="ident">out</span> <span class="punct">=</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="ident">open</span> <span class="global">$stdout</span><span class="punct">,</span> <span class="punct">&quot;</span><span class="string">w</span><span class="punct">&quot;,</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">TRACEROUTE</span>
+
+<span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="ident">open</span><span class="punct">(</span><span class="constant">ARGV</span><span class="punct">[</span><span class="number">0</span><span class="punct">])</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">file</span><span class="punct">|</span>
+  <span class="ident">file</span><span class="punct">.</span><span class="ident">add_filters</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">TRACE</span>
+  <span class="ident">file</span><span class="punct">.</span><span class="ident">read</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">trace</span><span class="punct">|</span>
+    <span class="ident">out</span><span class="punct">.</span><span class="ident">write</span> <span class="ident">trace</span>
+  <span class="keyword">end</span>
+<span class="keyword">end</span>
+</pre>
+
+
+<h2><a name="modifying_data"></a>Modifying Lists and Cycles</h2>
+
+<p>
+Traces read in with this library are immutable, but you can modify the
+associated list and cycle objects and write out modified versions to files.
+This ability to modify lists and cycles is supported primarily to enable
+easy re-organization of traces into a different set of files.
+</p>
+
+<p>
+We say <i>modify</i> as a simplifying fiction, because in truth, list and
+cycle objects are as equally immutable as traces.  To <i>modify</i> lists
+and cycles, you <b>derive</b> a new object with updated values from an
+existing object (the old object is unmodified).  Then you assign the new
+object to a trace, thereby replacing the association with the old object.
+For example, the following script changes the ID and hostname of cycles
+to <code>5</code> and <code>foo.bar.com</code>, respectivey, and updates
+traces to use the new cycle objects (note: cycle start and def objects will
+always be read in before any traces that use those cycle objects):
+</p>
+
+<!-- 17. modify ========================================================== -->
+<pre class="ruby snippet">
+<span class="ident">out</span> <span class="punct">=</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="ident">open</span> <span class="punct">&quot;</span><span class="string">out.warts</span><span class="punct">&quot;,</span> <span class="punct">&quot;</span><span class="string">w</span><span class="punct">&quot;</span>
+
+<span class="ident">cycle</span> <span class="punct">=</span> <span class="constant">nil</span>
+<span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">.</span><span class="ident">open</span><span class="punct">(</span><span class="constant">ARGV</span><span class="punct">[</span><span class="number">0</span><span class="punct">])</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">file</span><span class="punct">|</span>
+  <span class="ident">file</span><span class="punct">.</span><span class="ident">add_all_filters</span>
+  <span class="ident">file</span><span class="punct">.</span><span class="ident">read</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">element</span><span class="punct">|</span>
+    <span class="keyword">case</span> <span class="ident">element</span><span class="punct">.</span><span class="ident">element_type</span>
+    <span class="keyword">when</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">TRACE</span>
+      <span class="ident">element</span><span class="punct">.</span><span class="ident">cycle</span> <span class="punct">=</span> <span class="ident">cycle</span>
+
+    <span class="keyword">when</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">CYCLE_START</span><span class="punct">,</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">CYCLE_DEF</span><span class="punct">,</span>
+      <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">CYCLE_STOP</span>
+      <span class="ident">element</span> <span class="punct">=</span> <span class="ident">element</span><span class="punct">.</span><span class="ident">derive</span><span class="punct">(</span><span class="symbol">:id</span> <span class="punct">=&gt;</span> <span class="number">5</span><span class="punct">,</span> <span class="symbol">:hostname</span> <span class="punct">=&gt;</span> <span class="punct">&quot;</span><span class="string">foo.bar.com</span><span class="punct">&quot;)</span>
+      <span class="keyword">unless</span> <span class="ident">element</span><span class="punct">.</span><span class="ident">element_type</span> <span class="punct">==</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">CYCLE_STOP</span>
+        <span class="ident">cycle</span> <span class="punct">=</span> <span class="ident">element</span> 
+      <span class="keyword">end</span>
+    <span class="keyword">end</span>
+
+    <span class="ident">out</span><span class="punct">.</span><span class="ident">write</span> <span class="ident">element</span>
+  <span class="keyword">end</span>
+<span class="keyword">end</span>
+
+<span class="ident">out</span><span class="punct">.</span><span class="ident">close</span>
+</pre>
+
+
+<p>
+You would follow the same basic procedure to modify lists.  Note that you
+can't directly assign a list to a trace object; you must update the list in
+a cycle and then assign the cycle to a trace.  For example, the following
+script changes the name of lists to <code>dnssurvey</code> (and changes
+the ID of cycles to 5):
+</p>
+
+<!-- 18. modify2 ========================================================= -->
+<pre class="ruby snippet">
+<span class="ident">out</span> <span class="punct">=</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="ident">open</span> <span class="punct">&quot;</span><span class="string">out.warts</span><span class="punct">&quot;,</span> <span class="punct">&quot;</span><span class="string">w</span><span class="punct">&quot;</span>
+
+<span class="ident">cycle</span> <span class="punct">=</span> <span class="constant">nil</span>
+<span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">.</span><span class="ident">open</span><span class="punct">(</span><span class="constant">ARGV</span><span class="punct">[</span><span class="number">0</span><span class="punct">])</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">file</span><span class="punct">|</span>
+  <span class="ident">file</span><span class="punct">.</span><span class="ident">add_all_filters</span>
+  <span class="ident">file</span><span class="punct">.</span><span class="ident">read</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">element</span><span class="punct">|</span>
+    <span class="keyword">case</span> <span class="ident">element</span><span class="punct">.</span><span class="ident">element_type</span>
+    <span class="keyword">when</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">TRACE</span>
+      <span class="ident">element</span><span class="punct">.</span><span class="ident">cycle</span> <span class="punct">=</span> <span class="ident">cycle</span>
+
+    <span class="keyword">when</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">CYCLE_START</span><span class="punct">,</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">CYCLE_DEF</span><span class="punct">,</span>
+      <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">CYCLE_STOP</span>
+      <span class="ident">list</span> <span class="punct">=</span> <span class="ident">element</span><span class="punct">.</span><span class="ident">list</span><span class="punct">.</span><span class="ident">derive</span><span class="punct">(</span><span class="symbol">:name</span> <span class="punct">=&gt;</span> <span class="punct">&quot;</span><span class="string">dnssurvey</span><span class="punct">&quot;)</span>
+      <span class="ident">element</span> <span class="punct">=</span> <span class="ident">element</span><span class="punct">.</span><span class="ident">derive</span><span class="punct">(</span><span class="symbol">:id</span> <span class="punct">=&gt;</span> <span class="number">5</span><span class="punct">,</span> <span class="symbol">:list</span> <span class="punct">=&gt;</span> <span class="ident">list</span><span class="punct">)</span>
+      <span class="keyword">unless</span> <span class="ident">element</span><span class="punct">.</span><span class="ident">element_type</span> <span class="punct">==</span> <span class="constant">Warts</span><span class="punct">::</span><span class="constant">File</span><span class="punct">::</span><span class="constant">CYCLE_STOP</span>
+        <span class="ident">cycle</span> <span class="punct">=</span> <span class="ident">element</span> 
+      <span class="keyword">end</span>
+    <span class="keyword">end</span>
+
+    <span class="ident">out</span><span class="punct">.</span><span class="ident">write</span> <span class="ident">element</span>
+  <span class="keyword">end</span>
+<span class="keyword">end</span>
+
+<span class="ident">out</span><span class="punct">.</span><span class="ident">close</span>
+</pre>
+
+
+<h2>Further Reading</h2>
+
+<p>
+This concludes the tutorial.  There are more features in the library than
+described so far.  Browse the <a href="reference.html">class reference</a>
+and <a href="samples.html">sample scripts</a> for details.
+</p>
+
+<!---->
+</div></div>
+</body></html>