rmuh 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2afa8d700e33ca03886586afae8cb833e30e6848
-  data.tar.gz: 1812d02b9537370a22db998fcee1f6936e5b39c8
+  metadata.gz: ee6d35d0861a94192af934236bc6f749b43bf1ae
+  data.tar.gz: aae69a679fff65aa138f6f9328894f3403d444c0
 SHA512:
-  metadata.gz: 6956e30ee23bc0d415276f263e5bac85d629781e272e082dd694f3af23bf3f2ba0deeb2a7fe6749dfcae8a398b572d9d540276575956bbe6a996bfd0cd0b7d05
-  data.tar.gz: 5c3ce06cd77a60f70045da346fb340df5b4455290d5f92d07cbd6ca1f4969358801b20436fa4e143d459ee23a993918117bb5b8ff0ca551ee2e0ad1ef31e1635
+  metadata.gz: 55e40a5069510f01a0f6b5957596184ff994b0f33a0b78a9666194f521e7520e7200689bd04d06ccb357f3e627622295be480a6a95e7d7dd0bc213604ceb79a7
+  data.tar.gz: d3e196a3bd246975d82fea8b7bfe08bff3ab947dd106fb5cf9ae6ba3f6b0a8390c54c68bd12ef318f848a3cff85d03d02250d4aa633f534cd2f728c183b0658f

data/README.md

@@ -1,8 +1,8 @@
 RMuh
 ====
 [![Build Status](https://img.shields.io/travis/theckman/rmuh/master.svg)](https://travis-ci.org/theckman/rpt-ruby)
-[![MIT Licensed](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://tldrlegal.com/license/mit-license)
-[![RubyGems](http://img.shields.io/gem/v/rmuh.svg)](https://rubygems.org/gems/rmuh)
+[![MIT License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://tldrlegal.com/license/mit-license)
+[![RubyGems :: RMuh Gem Version](http://img.shields.io/gem/v/rmuh.svg)](https://rubygems.org/gems/rmuh)
 [![Coveralls Coverage](https://img.shields.io/coveralls/theckman/rmuh/master.svg)](https://coveralls.io/r/theckman/rmuh)
 [![Code Climate](https://img.shields.io/codeclimate/github/theckman/rmuh.svg)](https://codeclimate.com/github/theckman/rmuh)
 [![Gemnasium](https://img.shields.io/gemnasium/theckman/rmuh.svg)](https://gemnasium.com/theckman/rmuh)
@@ -11,11 +11,146 @@ RMuh
 interacting with ArmA 2 servers (specifically tested against Operation
 Arrowhead servers).
 
-In short, this `README` file usless right now. It is a work in progress.
-Please refer to it in the future for more information as it should be helpful
-then...
-
 LICENSE
 -------
-**RMuh** is released under The MIT License. The full text of the license can be
-found in the `LICENSE` file
+**RMuh** is released under the
+[The MIT License](http://opensource.org/licenses/MIT) The full text of the
+license can be found in the `LICENSE` file
+
+CONTRIBUTING
+------------
+I know different communities may have slightly different RPT/Server log files.
+Want to contribute changes/additions to the project? Just for the project to
+your own repo, make your changes and write corresponding RSpec tests, and then
+submit a PR.
+
+INSTALLATION
+------------
+This is packaged on the [RubyGems](https://rubygems.org/) site and can be
+installed via the `gem` command:
+
+```Ruby
+$ gem install rmuh
+```
+
+If you have a `Gemfile` or a `Gemspec` file for your project you can add
+these entires to these files and use `bundle install` to install the gem:
+
+**Gemfile**:
+
+```Ruby
+gem 'rmuh'
+```
+
+**Gemspec**:
+
+```Ruby
+g.add_runtime_dependency 'rmuh'
+```
+
+**Note:** If you want to do version pinning within your `Gemfile` or `Gemspec`
+file visit [RubyGems :: RMuh](https://rubygems.org/gems/rmuh) to see the
+specific versions available.
+
+USAGE
+-----
+This is just an overview of how to use the specific features of `RMuh`. For
+full documentation please view the `README.md` files within the `lib` dir,
+look in the `examples` dir, or visit the docs on
+[RubyDoc](http://rubydoc.info/gems/rmuh).
+
+So here are some examples of how to use the different classes.
+
+Log Fetching
+------------
+There is a built in log fetcher that uses `httparty` to pull the log files.
+
+Here is an example of how to just fetch the full log and print it:
+
+```Ruby
+require 'rmuh/rpt/log/fetch'
+URL = 'http://arma2.unitedoperations.net/dump/SRV1/SRV1_RPT.txt'
+f = RMuh::RPT::Log::Fetch.new(URL)
+puts f.log
+```
+In this case `f.log` returns a `StringIO` object which will be used by the
+parsers to parse the log files.
+
+If you want to specify a
+[byte range](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35.2):
+
+```Ruby
+f = RMuh::RPT::Log::Fetch.new(URL, byte_start: 100, byte_end: 200)
+```
+This can be used to pull the log in smaller sizes if you are doing incremental
+updates. To compound the byte range ability, you can get the log file size as
+well as update the byte range after initializing the object:
+
+```Ruby
+f.size            # prints Fixnum
+f.byte_start = 10 # Sets the first byte to 10
+f.byte_end = 40   # Sets the last byte to 40
+```
+
+Log Parsing
+-----------
+Included with this module is a default log parser. The default parser does
+nothing but return each line as a Hash within an Array. There is no metadata
+extracted, it's a literal copy and paste of the provided log line. This default
+parser is primarily used as an example class to be used for subclassing of your
+own parser.
+
+```Ruby
+require 'rmuh/rpt/log/fetch'
+require 'rmuh/rpt/parsers/base
+URL = 'http://arma2.unitedoperations.net/dump/SRV1/SRV1_RPT.txt'
+f = RMuh::RPT::Log::Fetch.new(URL)
+p = RMuh::RPT::Log::Parsers::Base.new
+l = p.parse(f.log)
+```
+At this specific moment `l` would contain an Array of Hashes corresponding to
+the log lines.
+
+Server Stats
+------------
+The `RMuh` gem also wraps the
+[GamespyQuery](https://rubygems.org/gems/gamespy_query) Rubygem for pulling
+live statistics from the server. This includes current map, mission, play list,
+and others. Deep down this just uses the GameSpy protocol to get the
+information directly from the server.
+
+Here is a quick overview of how to use this functionality:
+
+```
+require 'rmuh/serverstats/base
+UO_IP = '70.42.74.59'
+s = RMuh::ServerStats::Base.new(host: UO_IP)
+s.update_cache
+puts s.stats
+```
+By default the `ServerStats::Base` class caches the information so you need to
+explicitly update the cache. This is not done automatically as it is a blocking
+operation, this allow you to block somewhere other than where you instantiate
+the object.
+
+If you want to avoid using the cache:
+
+```
+s = RMuh::ServerStats::Base.new(host: UO_IP, cache: false)
+```
+If you want to be able to pull each part of the returned data set using
+dot-notation, you can use the `Advanced` class:
+
+```
+require 'rmuh/serverstats/base
+s = RMuh::ServerStats::Advanced.new(host: UO_IP)
+s.update_cache
+puts s.players
+```
+In this case, `players` is an Array. If you specify a key that doesn't exist
+you will get a NoMethodError exception.
+
+SUPPORT
+-------
+Having some problems understanding something? Just open an issue and I'll get
+back to you as soon as I can.

data/lib/rmuh/rpt/log/fetch.rb

@@ -5,43 +5,54 @@ require 'ostruct'
 module RMuh
   module RPT
     module Log
-      # TODO: Fetch Class documentation
+      # This is the RPT Log fetcher class. It allows fetching a specific URL,
+      # only pulling a specific byte range, as well as getting the size of the
+      # external file
       #
       class Fetch
         include HTTParty
-        attr_accessor :cfg
-
-        def initialize(log_url, byte_start = 0, byte_end = nil)
-          @cfg = OpenStruct.new(
-            log_url: log_url,
-            byte_start: byte_start,
-            byte_end: byte_end
-          )
+        attr_accessor :log_url, :byte_start, :byte_end
+
+        def self.validate_opts(opts)
+          if opts.key?(:byte_start) &&
+             (!opts[:byte_start].is_a?(Fixnum) || opts[:byte_start] < 0)
+            fail(ArgumentError, ':byte_start must be a Fixnum >= 0')
+          end
+          if opts.key?(:byte_end) &&
+             ![Fixnum, NilClass].include?(opts[:byte_end].class)
+            fail(ArgumentError, ':byte_end must be nil or Fixnum')
+          end
+        end
+
+        # New Fetch class. This is used for fetching the ArmA 2 log files
+        # Required param (#1): (String) The log file URL
+        # Optional param (#2): (Hash):
+        # * :byte_start - what byte to start the log file from
+        # * :byte_end - the last byte that we want from the log file
+        #
+        def initialize(log_url, opts = {})
+          @log_url = log_url
+          @byte_start = opts.key?(:byte_start) ? opts[:byte_start] : 0
+          @byte_end = opts.key?(:byte_end) ? opts[:byte_end] : nil
         end
 
         def byte_start=(bytes)
-          if bytes.is_a?(Integer)
-            @cfg.byte_start = bytes
-          else
-            fail ArgumentError, 'argument 1 must be an integer'
-          end
+          self.class.validate_opts(byte_start: bytes)
+          @byte_start = bytes
         end
 
         def byte_end=(bytes)
-          if bytes.nil? || bytes.is_a?(Integer)
-            @cfg.byte_end = bytes
-          else
-            fail ArgumentError, 'argument 1 must be nil or an integer'
-          end
+          self.class.validate_opts(byte_end: bytes)
+          @byte_end = bytes
         end
 
         def size
-          self.class.head(@cfg.log_url).headers['content-length'].to_i
+          self.class.head(@log_url).headers['content-length'].to_i
         end
 
         def log
-          headers = { 'Range' => "bytes=#{@cfg.byte_start}-#{@cfg.byte_end}" }
-          response = self.class.get(@cfg.log_url, headers: headers)
+          headers = { 'Range' => "bytes=#{@byte_start}-#{@byte_end}" }
+          response = self.class.get(@log_url, headers: headers)
           StringIO.new(response.lines.map { |l| dos2unix(l) }.join)
         end
 

data/lib/rmuh/rpt/log/parsers/base.rb

@@ -16,11 +16,9 @@ module RMuh
           def parse(loglines)
             fail(
               ArgumentError, 'argument 1 must be a StringIO object'
-            ) unless loglines.is_a? StringIO
+            ) unless loglines.is_a?(StringIO)
 
-            loglines.map do |line|
-              { type: :log, message: line }
-            end
+            loglines.map { |line| { type: :log, message: line } }
           end
         end
       end

data/lib/rmuh/rpt/log/parsers/unitedoperationslog.rb

@@ -10,7 +10,12 @@ module RMuh
   module RPT
     module Log
       module Parsers
-        # TODO: UnitedOperationsLog Class Documentation
+        # This is the UnitedOperations Log parser class. It separates the log
+        # in to an array of Hashes, one for each log line.
+        #
+        # This can be used to rebuild the log file, from metadata alone.
+        #
+        # It extends RMuh::RPT::Log::Parsers::Base
         #
         class UnitedOperationsLog < RMuh::RPT::Log::Parsers::Base
           include RMuh::RPT::Log::Util::UnitedOperations
@@ -18,6 +23,11 @@ module RMuh
           include RMuh::RPT::Log::Util::UnitedOperationsLog # Regexp Constants
           extend RMuh::RPT::Log::Util::UnitedOperationsLog
 
+          # Validate the options that are passed in as arg 1 to the new()
+          # function
+          #
+          # This raises ArgumentError if something doesn't pass
+          #
           def self.validate_opts(opts)
             fail(
               ArgumentError, 'arg 1 should be an instance of Hash'
@@ -27,6 +37,13 @@ module RMuh
             validate_bool_opt(opts, :chat)
           end
 
+          # This builds the object. There are three optional args for the Hash:
+          # * :chat -- should chat lines be included?
+          # * :to_zulu -- convert timestamp to zulu
+          # * :timezone -- specify the server timezone
+          # --
+          # TODO: Make this use an auto hash to instance variable function
+          # ++
           def initialize(opts = {})
             self.class.validate_opts(opts)
             @include_chat = opts[:chat].nil? ? false : opts[:chat]

data/lib/rmuh/rpt/log/parsers/unitedoperationsrpt.rb

@@ -10,13 +10,20 @@ module RMuh
   module RPT
     module Log
       module Parsers
-        # TODO: UnitedOperationsRPT Class Documentation
+        # This is the UnitedOperations parser class. This separates the
+        # UnitedOperations log lines in to their respective Hashes
+        #
+        # This can be used to rebuild the log file, from metadata alone.
+        #
+        # It extends RMuh::RPT::Log::Parsers::Base
         #
         class UnitedOperationsRPT < RMuh::RPT::Log::Parsers::Base
           include RMuh::RPT::Log::Util::UnitedOperations
           extend RMuh::RPT::Log::Util::UnitedOperations
           include RMuh::RPT::Log::Util::UnitedOperationsRPT # Regexp Constants
 
+          # This is used to validate the options passed in to new()
+          # Will throw ArgumentError if things aren't right.
           def self.validate_opts(opts)
             fail ArgumentError,
                  'argument 1 should be a Hash' unless opts.class == Hash
@@ -24,6 +31,15 @@ module RMuh
             validate_timezone(opts)
           end
 
+          # This is the initializer for the whole object. There are two
+          # valid options for this class:
+          # :to_zulu -- convert the timestamp to zulu and add iso8601 and dtg
+          #             timestamp -- this defaults to true
+          # :timezone -- specifies the server's timezone from the tz database
+          #              this defaults to the UO timezone
+          # --
+          # TODO: Convert this to use an auto hash to instance variable
+          # ++
           def initialize(opts = {})
             self.class.validate_opts(opts)
 
@@ -31,6 +47,9 @@ module RMuh
             @timezone = opts[:timezone].nil? ? UO_TZ : opts[:timezone]
           end
 
+          # Parse the StringIO object which is the lines from the log.
+          # This expects arg 1 to be a StringIO object, otherwise it will
+          # throw an ArgumentError exception
           def parse(loglines)
             unless loglines.is_a?(StringIO)
               fail ArgumentError, 'argument 1 must be a StringIO object'

data/lib/rmuh/rpt/log/util/unitedoperations.rb

@@ -6,7 +6,8 @@ module RMuh
   module RPT
     module Log
       module Util
-        # TODO: Module documentation
+        # UnitedOperations module. This has a constant and some shared
+        # functions. This is shared amongst the two UO logs
         #
         module UnitedOperations
           UO_TZ ||= TZInfo::Timezone.get('America/Los_Angeles')

data/lib/rmuh/rpt.rb

@@ -0,0 +1,11 @@
+# -*- coding: UTF-8 -*-
+
+# RMuh::RPT
+# Released under the MIT License
+# Copyright (c) 2014 Tim Heckman
+
+path = File.expand_path('..', __FILE__)
+require File.join(path, 'rpt/log/fetch')
+require File.join(path, 'rpt/log/parsers/base')
+require File.join(path, 'rpt/log/parsers/unitedoperationsrpt')
+require File.join(path, 'rpt/log/parsers/unitedoperationslog')

data/lib/rmuh/serverstats/advanced.rb

@@ -4,7 +4,10 @@ require 'rmuh/serverstats/base'
 
 module RMuh
   module ServerStats
-    # TODO: Documentation
+    # This is an advanced extension of the Base class. This adds the ability to
+    # access the top level keys returned from the server using dot notation
+    #
+    # No additions / alterations exist to the methods from the Base class
     #
     class Advanced < RMuh::ServerStats::Base
       def method_missing(method, *args, &block)

data/lib/rmuh/serverstats/base.rb

@@ -3,10 +3,19 @@
 require 'gamespy_query'
 
 module RMuh
-  # TODO: Documentation
+  # This is the namespace for the Gamespy Query Server Statistics.
+  # It has no methods.
   #
   module ServerStats
-    # TODO: Documentation
+    # This is the Base server stats class. It wraps GamespyQuery::Socket and
+    # adds a simpler interface for the usage of querying the server.
+    #
+    # The required parameter within the Hash is ':host'. Optional params are:
+    # port and cache
+    #
+    # * port: the GamespyQuery port of the server (usually game port)
+    # * cache: whether the data will cache on request, or pull new data each
+    #          stats request
     #
     class Base
       DEFAULT_PORT = 2_302

data/lib/rmuh/version.rb

@@ -1,10 +1,12 @@
 # -*- coding: UTF-8 -*-
 # RMuh : the ArmA 2 Ruby library
 #
+# This is just the version file.
+#
 module RMuh
   VERSION_MAJ ||= 0
   VERSION_MIN ||= 2
-  VERSION_REV ||= 0
+  VERSION_REV ||= 1
 
   VERSION ||= "#{VERSION_MAJ}.#{VERSION_MIN}.#{VERSION_REV}"
 end

data/lib/rmuh.rb

@@ -20,3 +20,8 @@
 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
+
+path = File.expand_path('../rmuh', __FILE__)
+require File.join(path, 'rpt')
+require File.join(path, 'serverstats/base')
+require File.join(path, 'serverstats/advanced')

data/spec/rmuh_rpt_log_fetch_spec.rb

@@ -15,18 +15,18 @@ describe RMuh::RPT::Log::Fetch do
       fetch.should be_an_instance_of RMuh::RPT::Log::Fetch
     end
 
-    it 'should have a @cfg object which is an instance of OpenStruct' do
-      fetch.cfg.should be_an_instance_of OpenStruct
+    it 'should have a @log_url object which is an instance of String' do
+      fetch.log_url.should be_an_instance_of String
     end
 
-    it 'should set the "byte_start" config item if specified as arg:1' do
-      rlfetch = RMuh::RPT::Log::Fetch.new(url, 10)
-      rlfetch.cfg.byte_start.should eql 10
+    it 'should set the "byte_start" config item if specified' do
+      rlfetch = RMuh::RPT::Log::Fetch.new(url, byte_start: 10)
+      rlfetch.byte_start.should eql 10
     end
 
-    it 'should set the "byte_end" config item if specified as arg:3' do
-      rlfetch = RMuh::RPT::Log::Fetch.new(url, 10, 42)
-      rlfetch.cfg.byte_end.should eql 42
+    it 'should set the "byte_end" config item if specified' do
+      rlfetch = RMuh::RPT::Log::Fetch.new(url, byte_end: 42)
+      rlfetch.byte_end.should eql 42
     end
   end
 
@@ -49,7 +49,7 @@ describe RMuh::RPT::Log::Fetch do
 
     it 'should update the @cfg.byte_start value' do
       fetch.byte_start = 10
-      fetch.cfg.byte_start.should eql 10
+      fetch.byte_start.should eql 10
     end
   end
 
@@ -72,7 +72,7 @@ describe RMuh::RPT::Log::Fetch do
 
     it 'should update the @cfg.byte_end value' do
       fetch.byte_end = 42
-      fetch.cfg.byte_end.should eql 42
+      fetch.byte_end.should eql 42
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rmuh
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Tim Heckman
@@ -224,6 +224,7 @@ files:
 - README.md
 - Rakefile
 - lib/rmuh.rb
+- lib/rmuh/rpt.rb
 - lib/rmuh/rpt/log/fetch.rb
 - lib/rmuh/rpt/log/parsers/base.rb
 - lib/rmuh/rpt/log/parsers/unitedoperationslog.rb