vnstat-ruby 1.0.0

data/lib/vnstat/result/hour.rb

@@ -0,0 +1,56 @@
+module Vnstat
+  class Result
+    ##
+    # A class representing a tracking result for a specific hour.
+    #
+    # @attr_reader [Date] date The date the result was captured on.
+    # @attr_reader [Integer] hour The hour the result was captured at.
+    class Hour < Result
+      include DateDelegation
+      include TimeComparable
+
+      attr_reader :date, :hour
+
+      ##
+      # Initializes the {Hour}.
+      #
+      # @param [Date] date The date the result was captured on.
+      # @param [Integer] hour The hour the result was captured at.
+      # @param [Integer] bytes_received The received bytes.
+      # @param [Integer] bytes_sent The sent bytes.
+      def initialize(date, hour, bytes_received, bytes_sent)
+        @date = date
+        @hour = hour
+        super(bytes_received, bytes_sent)
+      end
+
+      ##
+      # Initializes a {Hour} using the the data contained in the given XML
+      # element.
+      #
+      # @param [Nokogiri::XML::Element] element The XML element.
+      # @return [Hour]
+      def self.extract_from_xml_element(element)
+        date = Parser.extract_date_from_xml_element(element)
+        hour = Integer(element.attr('id').to_s)
+        new(date, hour, *Parser.extract_transmitted_bytes_from_xml_element(element))
+      end
+
+      ##
+      # @return [Integer, nil]
+      def <=>(other)
+        return nil unless other.respond_to?(:bytes_transmitted)
+        return nil unless other.respond_to?(:time)
+        [time, bytes_transmitted] <=> [other.time, other.bytes_transmitted]
+      end
+
+      ##
+      # The time the result was captured.
+      #
+      # @return [DateTime]
+      def time
+        DateTime.new(year, month, day, hour)
+      end
+    end
+  end
+end

data/lib/vnstat/result/minute.rb

@@ -0,0 +1,62 @@
+module Vnstat
+  class Result
+    ##
+    # A class representing a tracking result for a specific minute.
+    #
+    # @attr_reader [DateTime] time The time the result was captured at.
+    class Minute < Result
+      include DateDelegation
+      include TimeComparable
+
+      attr_reader :time
+
+      ##
+      # Initializes the {Minute}.
+      #
+      # @param [DateTime] time The time the result was captured at.
+      # @param [Integer] bytes_received The received bytes.
+      # @param [Integer] bytes_sent The sent bytes.
+      def initialize(time, bytes_received, bytes_sent)
+        @time = time
+        super(bytes_received, bytes_sent)
+      end
+
+      ##
+      # Initializes a {Minute} using the the data contained in the given XML
+      # element.
+      #
+      # @param [Nokogiri::XML::Element] element The XML element.
+      # @return [Minute]
+      def self.extract_from_xml_element(element)
+        new(
+          Parser.extract_datetime_from_xml_element(element),
+          *Parser.extract_transmitted_bytes_from_xml_element(element)
+        )
+      end
+
+      ##
+      # The date the result was captured.
+      #
+      # @return [Date]
+      def date
+        time.to_date
+      end
+
+      ##
+      # The hour the result was captured.
+      #
+      # @return [Integer]
+      def hour
+        time.hour
+      end
+
+      ##
+      # The minute the result was captured.
+      #
+      # @return [Integer]
+      def minute
+        time.minute
+      end
+    end
+  end
+end

data/lib/vnstat/result/month.rb

@@ -0,0 +1,47 @@
+module Vnstat
+  class Result
+    ##
+    # A class representing a tracking result for a specific month.
+    #
+    # @attr_reader [Integer] year The year the result was captured in.
+    # @attr_reader [Integer] month The month the result was captured in.
+    class Month < Result
+      attr_reader :year, :month
+
+      ##
+      # Initializes the {Month}.
+      #
+      # @param [Integer] year The year the result was captured in.
+      # @param [Integer] month The month the result was captured in.
+      # @param [Integer] bytes_received The received bytes.
+      # @param [Integer] bytes_sent The sent bytes.
+      def initialize(year, month, bytes_received, bytes_sent)
+        @year = year
+        @month = month
+        super(bytes_received, bytes_sent)
+      end
+
+      ##
+      # Initializes a {Month} using the the data contained in the given XML
+      # element.
+      #
+      # @param [Nokogiri::XML::Element] element The XML element.
+      # @return [Month]
+      def self.extract_from_xml_element(element)
+        new(
+          *Parser.extract_month_from_xml_element(element),
+          *Parser.extract_transmitted_bytes_from_xml_element(element)
+        )
+      end
+
+      ##
+      # @return [Integer, nil]
+      def <=>(other)
+        return nil unless other.respond_to?(:bytes_transmitted)
+        return nil if !other.respond_to?(:year) || !other.respond_to?(:month)
+        [year, month, bytes_transmitted] <=>
+          [other.year, other.month, other.bytes_transmitted]
+      end
+    end
+  end
+end

data/lib/vnstat/result/time_comparable.rb

@@ -0,0 +1,16 @@
+module Vnstat
+  class Result
+    ##
+    # A module that is included by result types that can be compared based
+    # on their particular time information.
+    module TimeComparable
+      ##
+      # @return [Integer, nil]
+      def <=>(other)
+        return nil unless other.respond_to?(:bytes_transmitted)
+        return nil unless other.respond_to?(:time)
+        [time, bytes_transmitted] <=> [other.time, other.bytes_transmitted]
+      end
+    end
+  end
+end

data/lib/vnstat/system_call.rb

@@ -0,0 +1,90 @@
+require 'open3'
+
+module Vnstat
+  ##
+  # A class responsible for communication with command line interfaces.
+  #
+  # @attr_reader [Array] args
+  # @attr_reader [String, nil] success_result The STDOUT output of the called
+  #   command.
+  # @attr_reader [String, nil] error_result The STDERR output of the called
+  #   command.
+  # @attr_reader [Process::Status, nil] exit_status The exit status of the
+  #   called command.
+  class SystemCall
+    attr_reader :args, :success_result, :error_result, :exit_status
+
+    ##
+    # Initializes the {SystemCall}.
+    #
+    # @param [Array] args The command line arguments.
+    def initialize(*args)
+      @args = args.flatten
+    end
+
+    ##
+    # Initializes and calls the {SystemCall}.
+    #
+    # @param [Array] args The command line arguments.
+    # @return [SystemCall]
+    def self.call(*args)
+      new(*args).call
+    end
+
+    ##
+    # Calls the command.
+    #
+    # @return [SystemCall]
+    def call
+      Open3.popen3(*args) do |_, stdout, stderr, wait_thr|
+        @success_result = readlines(stdout)
+        @error_result = readlines(stderr)
+        @exit_status = wait_thr.value
+      end
+      self
+    end
+
+    ##
+    # Determines whether the command has been called.
+    #
+    # @return [true, false]
+    def called?
+      !exit_status.nil?
+    end
+
+    ##
+    # Returns the command result.
+    #
+    # @return [String] Returns result from {#success_result} when command exited
+    #   successfully. Otherwise returns result from {#error_result}.
+    # @raise [RuntimeError] Raises when the command has not yet been called.
+    def result
+      success? ? success_result : error_result
+    end
+
+    ##
+    # Indicates whether the command has been executed successfully.
+    #
+    # @raise [RuntimeError] Raises when the command has not yet been called.
+    # @return [true, false]
+    def success?
+      fail 'Command not invoked' unless called?
+      exit_status.success?
+    end
+
+    ##
+    # Indicates whether the command has not been executed successfully.
+    #
+    # @raise [RuntimeError] Raises when the command has not yet been called.
+    # @return [true, false]
+    def error?
+      !success?
+    end
+
+    private
+
+    def readlines(io)
+      io.readlines.join.chomp
+    end
+  end
+end

data/lib/vnstat/traffic.rb

@@ -0,0 +1,11 @@
+module Vnstat
+  ##
+  # A namespace incorporating all kinds of traffic collections.
+  module Traffic
+    autoload :Base, 'vnstat/traffic/base'
+    autoload :Daily, 'vnstat/traffic/daily'
+    autoload :Hourly, 'vnstat/traffic/hourly'
+    autoload :Monthly, 'vnstat/traffic/monthly'
+    autoload :Tops, 'vnstat/traffic/tops'
+  end
+end

data/lib/vnstat/traffic/base.rb

@@ -0,0 +1,46 @@
+module Vnstat
+  module Traffic
+    ##
+    # An abstract implementation for a traffic collection.
+    #
+    # @attr_reader [Interface] interface The tracked interface.
+    class Base
+      include Enumerable
+
+      attr_reader :interface
+
+      ##
+      # Initializes the traffic collection.
+      #
+      # @param [Interface] interface The tracked interface.
+      def initialize(interface)
+        @interface = interface
+      end
+
+      ##
+      # Iterates over all results in the collection.
+      #
+      # @overload each
+      #   @return [Enumerator]
+      #
+      # @overload each(&block)
+      #   @yield [result]
+      #   @yieldparam [Result] result
+      #   @return [Base]
+      def each(&block)
+        entries_hash.values.each(&block)
+      end
+
+      private
+
+      def traffic_data
+        interface.data.xpath('//traffic')
+      end
+
+      def entries_hash
+        fail NotImplementedError,
+             "Please override #{self.class.name}##{__method__}"
+      end
+    end
+  end
+end

data/lib/vnstat/traffic/daily.rb

@@ -0,0 +1,40 @@
+module Vnstat
+  module Traffic
+    ##
+    # A class encapsulating daily tracking information.
+    class Daily < Base
+      ##
+      # Fetches a single {Result::Day} from the collection.
+      #
+      # @return [Result::Day]
+      #
+      # @overload [](date)
+      #   @param [Date] date
+      #
+      # @overload [](year, month, day)
+      #   @param [Integer] year
+      #   @param [Integer] month
+      #   @param [Integer] day
+      def [](*args)
+        date = case args.count
+               when 1 then args.first
+               when 3 then Date.new(*args)
+               else
+                 fail ArgumentError, 'wrong number of arguments ' \
+                                     "(#{args.count} for 1 or 3)"
+               end
+        entries_hash[date]
+      end
+
+      private
+
+      def entries_hash
+        elements = traffic_data.xpath('days/day')
+        elements.each_with_object({}) do |element, hash|
+          result = Result::Day.extract_from_xml_element(element)
+          hash[result.date] = result
+        end
+      end
+    end
+  end
+end

data/lib/vnstat/traffic/hourly.rb

@@ -0,0 +1,44 @@
+module Vnstat
+  module Traffic
+    ##
+    # A class encapsulating hourly tracking information.
+    class Hourly < Base
+      ##
+      # Fetches a single {Result::Hour} from the collection.
+      #
+      # @return [Result::Hour]
+      #
+      # @overload [](date, hour)
+      #   @param [Date] date
+      #   @param [Integer] hour
+      #
+      # @overload [](year, month, day, hour)
+      #   @param [Integer] year
+      #   @param [Integer] month
+      #   @param [Integer] day
+      #   @param [Integer] hour
+      def [](*args)
+        args_count = args.count
+        hour = args.pop
+        date = case args_count
+               when 2 then args.first
+               when 4 then Date.new(*args)
+               else
+                 fail ArgumentError, 'wrong number of arguments ' \
+                                     "(#{args_count} for 2 or 4)"
+               end
+        entries_hash[[date, hour]]
+      end
+
+      private
+
+      def entries_hash
+        elements = traffic_data.xpath('hours/hour')
+        elements.each_with_object({}) do |element, hash|
+          result = Result::Hour.extract_from_xml_element(element)
+          hash[[result.date, result.hour]] = result
+        end
+      end
+    end
+  end
+end

data/lib/vnstat/traffic/monthly.rb

@@ -0,0 +1,27 @@
+module Vnstat
+  module Traffic
+    ##
+    # A class encapsulating monthly tracking information.
+    class Monthly < Base
+      ##
+      # Fetches a single {Result::Month} from the collection.
+      #
+      # @param [Integer] year
+      # @param [Integer] month
+      # @return [Result::Month]
+      def [](year, month)
+        entries_hash[[year, month]]
+      end
+
+      private
+
+      def entries_hash
+        elements = traffic_data.xpath('months/month')
+        elements.each_with_object({}) do |element, hash|
+          result = Result::Month.extract_from_xml_element(element)
+          hash[[result.year, result.month]] = result
+        end
+      end
+    end
+  end
+end