lib/nmap/xml.rb in ruby-nmap-0.6.0 vs lib/nmap/xml.rb in ruby-nmap-0.7.0

@@ -1,9 +1,10 @@
 require 'nmap/scanner'
 require 'nmap/scan_task'
 require 'nmap/scan'
 require 'nmap/host'
+require 'nmap/run_stat'
 
 require 'nokogiri'
 
 module Nmap
   #
@@ -17,27 +18,70 @@
     attr_reader :path
 
     #
     # Creates a new XML object.
     #
-    # @param [String] path
-    #   The path to the Nmap XML scan file.
+    # @param [Nokogiri::XML::Document, IO, String] document
+    #   The path to the Nmap XML scan file or Nokogiri::XML::Document.
     #
     # @yield [xml]
     #   If a block is given, it will be passed the new XML object.
     #
     # @yieldparam [XML] xml
     #   The newly created XML object.
     #
-    def initialize(path)
-      @path = File.expand_path(path)
-      @doc = Nokogiri::XML(open(@path))
+    def initialize(document)
+      case document
+      when Nokogiri::XML::Document
+        @doc = document
+      when IO, StringIO
+        @doc = Nokogiri::XML(document)
+      else
+        @path = File.expand_path(document)
+        @doc  = Nokogiri::XML(open(@path))
+      end
 
       yield self if block_given?
     end
 
     #
+    # Creates a new XML object from XML text.
+    #
+    # @param [String] text
+    #   XML text of the scan file
+    #
+    # @yield [xml]
+    #   If a block is given, it will be passed the new XML object.
+    #
+    # @yieldparam [XML] xml
+    #   The newly created XML object.
+    #
+    # @since 0.7.0
+    #
+    def self.load(text,&block)
+      new(Nokogiri::XML(text), &block)
+    end
+
+    #
+    # Creates a new XML object from the file.
+    #
+    # @param [String] path
+    #   The path to the XML file.
+    #
+    # @yield [xml]
+    #   If a block is given, it will be passed the new XML object.
+    #
+    # @yieldparam [XML] xml
+    #   The newly created XML object.
+    #
+    # @since 0.7.0
+    #
+    def self.open(path,&block)
+      new(path,&block)
+    end
+
+    #
     # Parses the scanner information.
     #
     # @return [Scanner]
     #   The scanner that was used and generated the scan file.
     #
@@ -81,10 +125,51 @@
         )
       end
     end
 
     #
+    # Parses the essential runstats information.
+    #
+    # @yield [run_stat]
+    #   The given block will be passed each runstat.
+    #
+    # @yieldparam [RunStat] run_stat
+    #   A runstat.
+    #
+    # @return [Enumerator]
+    #   If no block is given, an enumerator will be returned.
+    #
+    # @since 0.7.0
+    #
+    def each_run_stat
+      return enum_for(__method__) unless block_given?
+
+      @doc.xpath('/nmaprun/runstats/finished').each do |run_stat|
+        yield RunStat.new(
+          Time.at(run_stat['time'].to_i),
+          run_stat['elapsed'],
+          run_stat['summary'],
+          run_stat['exit']
+        )
+      end
+
+      return self
+    end
+
+    #
+    # Parses the essential runstats information.
+    #
+    # @return [Array<RunStat>]
+    #   The runstats.
+    #
+    # @since 0.7.0
+    #
+    def run_stats
+      each_run_stat.to_a
+    end
+
+    #
     # Parses the verbose level.
     #
     # @return [Integer]
     #   The verbose level.
     #
@@ -103,29 +188,51 @@
     end
 
     #
     # Parses the tasks of the scan.
     #
-    # @return [Array<ScanTask>]
-    #   The tasks of the scan.
+    # @yield [task]
+    #   The given block will be passed each scan task.
     #
-    # @since 0.1.2
+    # @yieldparam [ScanTask] task
+    #   A task from the scan.
     #
-    def tasks
-      @doc.xpath('/nmaprun/taskbegin').map do |task_begin|
+    # @return [Enumerator]
+    #   If no block is given, an enumerator will be returned.
+    #
+    # @since 0.7.0
+    #
+    def each_task
+      return enum_for(__method__) unless block_given?
+
+      @doc.xpath('/nmaprun/taskbegin').each do |task_begin|
         task_end = task_begin.xpath('following-sibling::taskend').first
 
-        ScanTask.new(
+        yield ScanTask.new(
           task_begin['task'],
           Time.at(task_begin['time'].to_i),
           Time.at(task_end['time'].to_i),
           task_end['extrainfo']
         )
       end
+
+      return self
     end
 
     #
+    # Parses the tasks of the scan.
+    #
+    # @return [Array<ScanTask>]
+    #   The tasks of the scan.
+    #
+    # @since 0.1.2
+    #
+    def tasks
+      each_task.to_a
+    end
+
+    #
     # Parses the hosts in the scan.
     #
     # @yield [host]
     #   Each host will be passed to a given block.
     #
@@ -134,15 +241,15 @@
     #
     # @return [XML, Enumerator]
     #   The XML object. If no block was given, an enumerator object will
     #   be returned.
     #
-    def each_host(&block)
-      return enum_for(__method__) unless block
+    def each_host
+      return enum_for(__method__) unless block_given?
 
       @doc.xpath('/nmaprun/host').each do |host|
-        Host.new(host,&block)
+        yield Host.new(host)
       end
 
       return self
     end
 
@@ -167,15 +274,15 @@
     #
     # @return [XML, Enumerator]
     #   The XML parser. If no block was given, an enumerator object will
     #   be returned.
     #
-    def each_up_host(&block)
-      return enum_for(__method__) unless block
+    def each_up_host
+      return enum_for(__method__) unless block_given?
 
       @doc.xpath("/nmaprun/host[status[@state='up']]").each do |host|
-        Host.new(host,&block)
+        yield Host.new(host)
       end
 
       return self
     end
 
@@ -204,9 +311,19 @@
     # @return [String]
     #   The path of the XML scan file.
     #
     def to_s
       @path.to_s
+    end
+
+    #
+    # Inspects the XML file.
+    #
+    # @return [String]
+    #   The inspected XML file.
+    #
+    def inspect
+      "#<#{self.class}: #{self}>"
     end
 
   end
 end