minecraft 0.0.5 → 0.1.0

data/.gitignore

@@ -3,3 +3,6 @@ gem.sh
 .bundle
 Gemfile.lock
 pkg/*
+mc
+doc
+.yardoc

data/.yardopts

@@ -0,0 +1,5 @@
+--hide-void-return
+--title "Minecraft server wrapper and deployment solution."
+--readme README.md
+
+lib/**/*.rb

data/CHANGES.md

@@ -0,0 +1,54 @@
+0.0.5 (2011-08-17)
+------------------
+
+* Added `savefreq` and `welcome_message` CLI options.
+* Refactored `Minecraft` module, added a `Runtime` class.
+* Added `!printtime`, `!printtimer`, `!s`, `!shortcuts` commands.
+* Clarified console information/error messages.
+* Fixed kits.
+* Saves timers and shortcuts.
+* Displays welcome message to connecting users.
+* Major refactoring to server process handling.
+* `save_all` on exit works now, proper exit handling.  No longer used `Thread#join`
+* Toggling mob state (`--tempmob`) prints new state.
+
+0.0.4 (2011-08-14)
+------------------
+
+* Added the `!rules` command and associated `rules` CLI option.
+* Refactored `give` logic.
+* `!property`, `!uptime` commands added.
+* More intelligent quantifiers.
+* Monitors kicks and bans.
+
+0.0.3 (2011-08-13)
+------------------
+
+* Split command methods into the `Minecraft::Commands` module.
+* Validates `!kit` command.
+* Added `!list`, `!addtimer`, `!deltimer`, `!printtimer`, `!kitlist` commands.
+* Approximate item names implemented.
+* Fixed item naming bugs.
+* Major refactoring done to commands.
+* Logs user uptime.
+* Catches processing exceptions.
+
+0.0.2 (2011-08-13)
+------------------
+
+* Command line options added.
+* Trapped the interrupt signal for an exit hook.
+* `no_run`, `update`, `min_memory`, `max_memory`, `no_auto_save`, `tempmobs` CLI options implemented.
+* Fixed indentation.
+* `!giveall`, `!tpall`, `!help` commands implemented.
+* Meta checks in place (ops, join/part).
+* Privilege errors.
+* Refactored `Minecraft::Server`, added `Minecraft::Tools`.
+
+0.0.1 (2011-08-12)
+------------------
+
+* `:diamond`, `:garmour`, `:armour`, `:ranged`, `:nether`, `:portal` kits.
+* Data values hash in place.
+* Simple console processing in place.
+* `!give`, `!kit`, `!tp`, `!nom` commands implemented.

data/README.md

@@ -25,30 +25,55 @@ Usage
 Current Features
 ----------------
 
-- !give <item> <quantity>
-  - Give the user an item with a quantity of up to 2560 (by default Minecraft
-  will cap at 64).
-  - Use the item ID or item name. http://minecraftwiki.net/wiki/Data_values
-- !giveall <item> <quantity>
-- !tp <target_user>
-- !tpall
-- !nom
-- !nomall
-- !kit <group>
-  - Diamond
-  - Gold armour
-  - Armour
-  - Ranged
-  - Nether
-  - Portal
-- !kitall <group>
-- !addtimer <item> <frequency>
-- !deltimer <item>
-- !printtimer
-- !list
-
-TODO
-----
+Please refer to `Minecraft::Extensions#initialize`.
+
+    !give <item> <quantity>       # Gives the user an <item>, the <quantity> 
+                                  # upper bound is 2560 unlike the Minecraft 
+                                  # default of 64.  Items can be specified by
+                                  # approximate name.
+    !giveall <item> <quantity>    # Gives all connected users an <item>.
+    !tp <target_user>             # Teleports the user to the <target_user>.
+    !tpall                        # Teleports all connected user to the user.
+    !nom                          # Give a golden apple the user.
+    !nomall                       # Give a golden apple to every connected user.
+    !kit <group>                  # Gives a kit to the user.
+    !kitall <group>               # Give a kit to every connected user.
+    !kitlist                      # Lists the available kits.
+    !addtimer <item> <frequency>  # Adds a timer to give <item> to the user ever <frequency> seconds.
+    !deltimer <item>              # Delete a timer associated with <item>.
+    !printtimer                   # Print timers of the user.
+    !printtime                    # Print the current counter time.
+    !list                         # List the connected users, notes ops.
+    !property                     # Check a server property (!property spawn-monsters).
+    !s <label> <command>          # Associates a command to a shortcut label for the user.
+    !s <label>                    # Runs the command with the associated label.
+    !shortcuts                    # Lists the users shortcuts.
+    !rules                        # Prints the server rules.
+    !uptime <user>                # Prints the uptime of the given user.
+    !uptime                       # Prints the uptime of the current user.
+    !help                         # Outputs the help contents.
+
+Development Path
+----------------
+
+### Major Release Milestone
+
+- Complete test coverage
+- Complete documentation coverage
+- All feature requests closed
+- All bugs closed
+- Thorough testing done across multiple environments
+
+
+### Semantic Versioning
+
+- http://semver.org
+- Currently patch level releases are being made, nothing is stable yet.
+- Once tests and documentation has been written a stable minor release will be
+committed.
+- Once the repository is completely stable and I am satisified with the feature
+set, a major version will be released.  Any chances afterwards are backwards
+compatible until the major version is incremented.
 
 Contributors
 ------------

data/Rakefile

@@ -1 +1,8 @@
 require "bundler/gem_tasks"
+
+task :test do
+  $:.unshift "./test"
+  Dir.glob("test/*_test.rb").each { |test| require "./#{test}" }
+end
+
+task :default => :test

data/lib/minecraft/commands.rb

@@ -1,7 +1,19 @@
 module Minecraft
+  # Contains all the methods for console commands executed by a connected
+  # player.
   module Commands
     include Data
 
+    # Give command takes an item name or numeric id and a quantifier.  If a
+    # quantifier is not specified then the quantity defaults to 1.  Items will
+    # try to resolved if they are not an exact match.
+    #
+    # @param [String] user Target user of the command.
+    # @example
+    #   give("basicxman", "cobblestone")
+    #   give("basicxman", "cobblestone", "9m")
+    #   give("basicxman", "flint", "and", "steel", "1")
+    #   give("basicxman", "4")
     def give(user, *args)
       item, quantity = items_arg(1, args)
       item = resolve_item(item)
@@ -9,12 +21,21 @@ module Minecraft
       construct_give(user, item, quantity)
     end
 
+    # Validates a kit group, if the kit cannot be found it executes the
+    # !kitlist command.
     def validate_kit(group = "")
       return true if KITS.include? group.to_sym
       @server.puts "say #{group} is not a valid kit."
       kitlist
     end
 
+    # Kit command takes a group name and gives the contents of the kit to the
+    # target user.
+    #
+    # @param [String] user Target user of the command.
+    # @param [String] group Label of the kit.
+    # @example
+    #   give("basicxman", "diamond")
     def kit(user, group)
       KITS[group.to_sym].each do |item|
         if item.is_a? Array
@@ -25,22 +46,53 @@ module Minecraft
       end
     end
 
+    # Teleports the current user to the target user.
+    #
+    # @param [String] user Current user.
+    # @param [String] target User to teleport to.
+    # @example
+    #   tp("basicxman", "mike_n_7")
     def tp(user, target)
       @server.puts "tp #{user} #{target}"
     end
 
+    # Teleports all users to the target user.  Overrides !tpall.
+    #
+    # @param [String] user Current (target) user.
+    # @example
+    #   tp("basicxman")
     def tpall(user, *args)
       @users.each { |u| tp(u, user) }
     end
 
+    # Gives a golden apple to the specified user.
+    #
+    # @param [String] user Target user.
+    # @example
+    #   nom("basicxman")
     def nom(user)
       @server.puts "give #{user} 322 1"
     end
 
+    # Outputs the current value of a server property.
+    #
+    # @param [String] user The requesting user.
+    # @param [String] key The server property requested.
+    # @example
+    #   property("basicxman", "spawn-monsters")
     def property(user, key)
       @server.puts "say #{key} is currently #{@server_properties[key]}" if @server_properties.include? key
     end
 
+    # Checks the current uptime of the current or target user.  Prints their
+    # connected uptime and their total uptime.  If no target user is specified
+    # it will check the requesting user.
+    #
+    # @param [String] user The requesting user.
+    # @param [String] target_user The user to check.
+    # @example
+    #   uptime("basicxman")
+    #   uptime("basicxman", "mike_n_7")
     def uptime(user, target_user = nil)
       target_user ||= user
       time_spent = calculate_uptime(target_user)
@@ -50,10 +102,20 @@ module Minecraft
       @server.puts "say #{target_user} has been online for #{format_uptime(time_spent)} minutes.#{total}"
     end
 
+    # Will print the server rules to all connected players.
+    #
+    # @example
+    #   rules()
     def rules(*args)
       @server.puts "say #{@rules}"
     end
 
+    # Lists the currently connecting players, noting which is the requesting
+    # user and which users are ops.
+    #
+    # @param [String] user The requesting user.
+    # @example
+    #   list("basicxman")
     def list(user)
       l = @users.inject("") do |s, u|
         if u == user
@@ -66,6 +128,16 @@ module Minecraft
       @server.puts "say #{l}"
     end
 
+    # Adds a timer to the requesting users timers, the item and frequency in
+    # seconds of the timer should be specified.  If the timer already exists
+    # for that item, the frequency is re-assigned.  If the frequency is
+    # unspecified, it will default to 30.
+    #
+    # @param [String] user The requesting user.
+    # @param args item, frequency
+    # @example
+    #   addtimer("basicxman", "cobblestone")
+    #   addtimer("basicxman", "arrow", "10")
     def addtimer(user, *args)
       item, duration = items_arg(30, args)
       item = resolve_item(item)
@@ -74,12 +146,23 @@ module Minecraft
       @server.puts "say Timer added for #{user}.  Giving item id #{item} every #{duration} seconds."
     end
 
+    # Deletes a timer from the requesting user.
+    #
+    # @param [String] user The requesting user.
+    # @param args item
+    # @example
+    #   deltimer("basicxman", "cobblestone")
     def deltimer(user, *args)
       item = args.join(" ")
       item = resolve_item(item)
       @timers[user][item] = nil if @timers.has_key? user
     end
 
+    # Prints the requesting users current timers.
+    #
+    # @param [String] user The requesting user.
+    # @example
+    #   printtimer("basicxman")
     def printtimer(user)
       unless @timers.has_key? user || @timers[user].length == 0
         @server.puts "say No timers have been added for #{user}."
@@ -90,10 +173,24 @@ module Minecraft
       end
     end
 
+    # Prints the current value of the counter (seconds since server
+    # initialized).
+    #
+    # @example
+    #   printtimer("basicxman")
     def printtime(user)
       @server.puts "say Timer is at #{@counter}."
     end
 
+    # Adds a shortcut for the user with a given label.  Shortcuts can only be
+    # given for custom commands.  If only a label is given, the shortcut is
+    # executed.
+    #
+    # @param [String] user The requesting user.
+    # @param args label, command array
+    # @example
+    #   s("basicxman", "cobble", "give", "cobblestone", "64")
+    #   s("basicxman", "mike", "tp", "mike_n_7")
     def s(user, *args)
       return @server.puts "say You need to specify a shortcut silly!" if args.length == 0
 
@@ -109,11 +206,20 @@ module Minecraft
       @server.puts "say Shortcut labelled #{shortcut_name} for #{user} has been added."
     end
 
+    # Prints the requested users shortcuts.
+    #
+    # @param [String] user The requesting user.
+    # @example
+    #   shortcuts("basicxman")
     def shortcuts(user, *args)
       labels = @shortcuts[user].keys.join(", ") if @shortcuts.has_key? user
       @server.puts "say Shortcuts for #{user}: #{labels}."
     end
 
+    # Prints the help contents.
+    #
+    # @example
+    #   help()
     def help(*args)
       @server.puts <<-eof
 say !tp target_user
@@ -126,10 +232,24 @@ say !deltimer item
       eof
     end
 
+    # Prints the list of available kits to the connected players.
+    #
+    # @example
+    #   kitlist()
     def kitlist(*args)
       @server.puts "say Kits: #{KITS.keys.join(", ")}"
     end
 
+    # Helper method for printing the final give statements to the server.  If a
+    # quantity is above the default upper bound (64) it will print multiple
+    # statements.
+    #
+    # @param [String] user The requesting user.
+    # @param [Integer] item The item id.
+    # @param [Integer] quantity The quantity of the item to give.
+    # @example
+    #   construct_give("basicxman", 4, 64)
+    #   construct_give("basicxman", 4, 2560)
     def construct_give(user, item, quantity)
       if quantity <= 64
         @server.puts "give #{user} #{item} #{quantity}"
@@ -143,6 +263,16 @@ say !deltimer item
       @server.puts "give #{user} #{item} #{sub_quantity}" if sub_quantity > 0
     end
 
+    # Takes an array and decides if a quantifier is specified or not, returns
+    # the quantity and full item name.
+    #
+    # @param [Integer] default The default quantity to give if none is given.
+    # @return [Array] full_item_name, quantity
+    # @example
+    #   items_arg(1, ["flint", "and", "steel"])
+    #   items_arg(1, ["4"])
+    #   items_arg(1, ["4", "1"])
+    #   items_arg(1, ["flint", "and", "steel", "32"])
     def items_arg(default, args)
       if args.length == 1
         second = default
@@ -159,10 +289,29 @@ say !deltimer item
       return [first, second]
     end
 
+    # Resolves a full item name, checks if it is a numeric value and if not
+    # attempts an approximate match on the key and gets the value from the
+    # data value hash.
+    #
+    # @param [String] item The full item name.
+    # @return [String] The resolved item id.
+    # @example
+    #   resolve_item("4")
+    #   resolve_item("cobb")
+    #   resolve_item("cobblestone")
     def resolve_item(item)
-      item.to_i.to_s == item ? item.to_i : DATA_VALUE_HASH[resolve_key(item.downcase)]
+      item.to_i.to_s == item ? item : DATA_VALUE_HASH[resolve_key(item.downcase)]
     end
 
+    # Looks for an approximate match of a key, prints an error message to
+    # the player if the key does not exist.
+    #
+    # @param [String] key The approximate item name.
+    # @return [String] The proper item id.
+    # @example
+    #   resolve_key("cobb")
+    #   resolve_key("cobblestone")
+    #   resolve_key("torches")
     def resolve_key(key)
       bucket = key[0]
       return no_key(key) unless ITEM_BUCKETS.include? bucket
@@ -188,27 +337,50 @@ say !deltimer item
       return shortest_key
     end
 
+    # Prints a no key error the server.
     def no_key(key)
       @server.puts "say No item #{key} found."
     end
 
+    # Checks if a value is a valid quantifier or not.
+    #
+    # @param [String] quantity The potential quantifier.
+    # @return [Boolean]
+    # @example
+    #   is_quantifier? "x"
+    #   is_quantifier? "1m"
+    #   is_quantifier? "2d"
+    #   is_quantifier? "1s"
+    #   is_quantifier? "1"
+    #   is_quantifier? "steel"
     def is_quantifier?(quantity)
       quantity.index(/[0-9]+[a-z]?/) == 0
     end
 
+    # Compute a final quantity from a quantifier value.
+    #
+    # @param [String] value The quantifier.
+    # @return [Integer] The resulting quantity, upper bounded to 2560.
+    # @example
+    #   quantify("1m")
+    #   quantify("2d")
+    #   quantify("34s")
+    #   quantify("8m2d")
+    #   quantify("64")
     def quantify(value)
-      return value.scan(/[0-9]+[a-z]?/).inject(0) do |total, term|
+      quantity = value.scan(/[0-9]+[a-z]?/).inject(0) do |total, term|
         quantity, flag = term.match(/([0-9]+)([a-z]?)/)[1..2]
         quantity = quantity.to_i
         return total + quantity if flag.nil?
 
         total + case flag
-        when 'm' then [2560, quantity * 64].min
+        when 'm' then quantity * 64
         when 'd' then (64.0 / [1, quantity].max).round
         when 's' then [1, 64 - quantity].max
         else quantity
         end
       end
+      return [2560, quantity].min
     end
   end
 end

data/lib/minecraft/data.rb

@@ -1,5 +1,7 @@
 module Minecraft
+  # Contains kit and item hashes takes care of buckets for items.
   module Data
+    # Item kits.
     KITS = {
       :diamond    => [276, 277, 278, 279, 293],
       :goldarmour => [314, 315, 316, 317],
@@ -10,6 +12,7 @@ module Minecraft
       :redstone   => [[331, 256], [356, 64], [69, 64], [77, 64], [70, 64]]
     }
 
+    # All item keys.
     DATA_VALUE_HASH = {
       "glass"                   => "20",
       "purple wool"             => "35",
@@ -248,6 +251,7 @@ module Minecraft
       "cocoa beans"             => "351"
     }
 
+    # Alphabetical buckets for quicker approximate matching.  Filled on init.
     ITEM_BUCKETS = {}
     DATA_VALUE_HASH.each_key do |key|
       bucket = key[0]

data/lib/minecraft/extensions.rb

@@ -1,7 +1,14 @@
 module Minecraft
+  # An Extensions instance is meant to process pipes from a Server instance and
+  # manage custom functionality additional to default Notchian Minecraft
+  # behaviour.
   class Extensions
     include Commands
 
+    # New Extensions instance.
+    #
+    # @param [IO] server The standard input pipe of the server process.
+    # @param [Slop] opts Command line options from Slop.
     def initialize(server, opts)
       @ops = File.readlines("ops.txt").map { |s| s.chomp }
       @userlog = get_json("user.log")
@@ -38,6 +45,7 @@ module Minecraft
       add_command(:property,   :ops => true,  :all => false)
     end
 
+    # Gets a hash from a JSON file (or a blank one).
     def get_json(file)
       if File.exists? file
         JSON.parse(File.read(file))
@@ -46,23 +54,46 @@ module Minecraft
       end
     end
 
+    # Save the user timers and shortcuts hash to a data file.
     def save
       save_file :timers
       save_file :shortcuts
     end
 
+    # Save an instance hash to it's associated data file.
+    #
+    # @param [Symbol] var
+    # @example
+    #   save_file :timers
     def save_file(var)
       File.open("user_#{var}.json", "w") { |f| f.print instance_variable_get("@#{var}").to_json }
     end
 
+    # Writes the user uptime log to disk.
     def write_log
       File.open("user.log", "w") { |f| f.print @userlog.to_json }
     end
 
+    # Complicated method to decide the logic of calling a command.  Checks
+    # if the command requires op privileges and whether an `all` version is
+    # available and has been requested.
+    #
+    # Figures out the root portion of the command, checks if a validation
+    # method is available, if so it will be executed.  Then checks if op
+    # privileges are required, any `all` version of the command requires
+    # ops as it affects all users.  The corresponding method will be called,
+    # if an `all` command is used it will call the corresponding method if
+    # available or loop through the base command for each connected user.
+    #
+    # @param [String] user The requesting user.
+    # @param [String] command The requested command.
+    # @param args Arguments for the command.
+    # @example
+    #   call_command("basicxman", "give", "cobblestone", "64")
     def call_command(user, command, *args)
       is_all = command.to_s.end_with? "all"
       root   = command.to_s.chomp("all").to_sym
-      return invalid_command(command) unless @commands.include? root
+      return send(root, user, *args) unless @commands.include? root
 
       # Any `all` suffixed command requires ops.
       if @commands[root][:ops] or (is_all and @commands[root][:all])
@@ -85,10 +116,20 @@ module Minecraft
       end
     end
 
+    # Add a command to the commands instance hash
+    #
+    # @param [Symbol] command The command to add.
+    # @option opts [Boolean] :all
+    #   Whether or not an all version of the command should be made available.
+    # @option opts [Boolean] :ops
+    #   Whether or not the base command requires ops.
+    # @option opts [String] :all_message
+    #   The message to print when the all version is used.
     def add_command(command, opts)
       @commands[command] = opts
     end
 
+    # Processes a line from the console.
     def process(line)
       puts line
       return info_command(line) if line.index "INFO"
@@ -98,6 +139,8 @@ module Minecraft
       puts e.backtrace
     end
 
+    # Checks if the server needs to be saved and prints the save-all command if
+    # so.
     def check_save
       if @savefreq.nil?
         freq = 30
@@ -109,6 +152,8 @@ module Minecraft
       @server.puts "save-all" if @counter % freq == 0
     end
 
+    # Increments the counter and checks if any timers are needed to be
+    # executed.
     def periodic
       @counter += 1
       check_save
@@ -121,6 +166,11 @@ module Minecraft
       end
     end
 
+    # Removes the meta data (timestamp, INFO) from the line and then executes a
+    # series of checks on the line.  Grabs the user and command from the line
+    # and then calls the call_command method.
+    #
+    # @param [String] line The line from the console.
     def info_command(line)
       line.gsub! /^.*?\[INFO\]\s+/, ''
       return if meta_check(line)
@@ -132,17 +182,26 @@ module Minecraft
       call_command(user, args.slice!(0).to_sym, *args)
     end
 
+    # Executes the meta checks (kick/ban, ops, join/disconnect) and returns true
+    # if any of them were used (and thus no further processing required).
+    #
+    # @param [String] line The passed line from the console.
     def meta_check(line)
       return true if check_kick_ban(line)
       return true if check_ops(line)
       return true if check_join_part(line)
     end
 
+    # Removes the specified user as from the connected players array.
+    #
+    # @param [String] user The specified user.
+    # @return [Boolean] Always returns true.
     def remove_user(user)
       @users.reject! { |u| u.downcase == user.downcase }
       return true
     end
 
+    # Check if a console line has informed us about a ban or kick.
     def check_kick_ban(line)
       user = line.split(" ").last
       if line.index "Banning"
@@ -152,6 +211,7 @@ module Minecraft
       end
     end
 
+    # Check if a console line has informed us about a [de-]op privilege change.
     def check_ops(line)
       user = line.split(" ").last
       if line.index "De-opping"
@@ -163,6 +223,7 @@ module Minecraft
       end
     end
 
+    # Check if a console line has informed us about a player [dis]connecting.
     def check_join_part(line)
       user = line.split(" ").first
       if line.index "lost connection"
@@ -176,14 +237,20 @@ module Minecraft
       end
     end
 
+    # If a command method is called and is not specified, take in the arguments
+    # here and attempt to !give the player the item.  Otherwise print an error.
     def method_missing(sym, *args)
-      if DATA_VALUE_HASH.has_key? sym.downcase and is_op? args.first
-        give(args.first, sym, args.last)
+      item, quantity = items_arg(1, [sym.to_s.downcase, args.last])
+      item = resolve_item(item)
+      if item and is_op? args.first
+        give(args.first, item, quantity.to_s)
       else
-        puts "Invalid command given."
+        puts "#{item} is invalid."
       end
     end
 
+    # Calculate and print the time spent by a recently disconnected user.  Save
+    # the user uptime log.
     def log_time(user)
       time_spent = calculate_uptime(user)
       @userlog[user] ||= 0
@@ -192,27 +259,46 @@ module Minecraft
       write_log
     end
 
+    # Format an uptime for printing.  Should not be used for logging.
+    #
+    # @param [Integer] time Time difference in seconds.
+    # @return [Float] Returns the number of minutes rounded to two precision.
     def format_uptime(time)
       (time / 60.0).round(2)
     end
 
+    # Calculate a users current uptime.
+    #
+    # @param [String] user The specified user.
+    # @return [Integer] The uptime in seconds.
     def calculate_uptime(user)
       Time.now - @logon_time[user]
     end
 
+    # Check if a user has op privileges.
+    #
+    # @param [String] user The specified user.
+    # @return [Boolean]
     def is_op?(user)
       @ops.include? user.downcase
     end
 
+    # Check if a user is ops and print a privilege error if not.
+    #
+    # @param [String] user The specified user.
+    # @param [String] command The command they tried to use.
+    # @return [Boolean] Returns true if the user is an op.
     def validate_ops(user, command)
       return true if is_op? user
       @server.puts "say #{user} is not an op, cannot use !#{command}."
     end
 
+    # An error message for invalid commands.
     def invalid_command(command)
       @server.puts "say #{command} is invalid."
     end
 
+    # Load the server.properties file into a Ruby hash.
     def load_server_properties
       @server_properties = {}
       File.readlines("server.properties").each do |line|
@@ -222,6 +308,7 @@ module Minecraft
       end
     end
 
+    # Display a welcome message to a recently connected user.
     def display_welcome_message(user)
       @server.puts "say #{@welcome_message.gsub('%', user)}" unless @welcome_message.nil?
     end

data/lib/minecraft/runtime.rb

@@ -1,5 +1,15 @@
 module Minecraft
+  # An instance of the Runtime class will spool up the server and do any
+  # preliminary work.
   class Runtime
+    # New Runtime instance.
+    #
+    # @param [Slop] opts Command line options from slop.
+    # @example
+    #   opts = Slop.parse do
+    #     ...
+    #   end
+    #   runtime = Runtime.new(opts)
     def initialize(opts)
       @opts = opts
       pre_checks
@@ -13,6 +23,8 @@ module Minecraft
       end
     end
 
+    # Checks if Minecraft needs to be updated, checks if mobs are to be
+    # toggled.
     def pre_checks
       Minecraft::Tools.download_minecraft if @opts.update?
       puts "[+] Temporarily toggling mobs.  Setting to #{Minecraft::Tools.toggle_mobs}." if @opts.tempmobs?

data/lib/minecraft/server.rb

@@ -1,9 +1,21 @@
 require "open3"
 
 module Minecraft
+  # An instance of the server class will start a Java subprocess running the
+  # Minecraft server jarfile.  The interrupt signal will be trapped to run an
+  # exit hook and threads will be created to process all pipes.
   class Server
     attr_accessor :sin
 
+    # New Server instance.
+    #
+    # @param [String] command The command for the subprocess.
+    # @param [Slop] opts Command line options from Slop.
+    # @example
+    #   opts = Slop.new do
+    #     ...
+    #   end
+    #   server = Server.new("java -jar minecraft_server.jar", opts)
     def initialize(command, opts)
       @sin, @sout, @serr, @thr = Open3.popen3(command)
       @extensions = Extensions.new(@sin, opts)
@@ -20,6 +32,8 @@ module Minecraft
       exit!
     end
     
+    # An exit hook, checks if mobs need to be untoggled and saves the server.
+    # Server is stopped gracefully.
     def minecraft_exit
       puts "[+] Restoring previous mob state to #{Minecraft::Tools.toggle_mobs}." if @opts.tempmobs?
       puts "\n[+] Saving..."

data/lib/minecraft/tools.rb

@@ -1,27 +1,35 @@
 require "net/http"
 
 module Minecraft
+  # Methods for external manipulation of the current deployment.
   module Tools
+    # Checks if minecraft_server.jar and calls the download method if not.
     def self.check_jarfile
       download_minecraft unless File.exists? "minecraft_server.jar"
     end
 
+    # Downloads the minecraft server jarfile into the current directory.
     def self.download_minecraft
       url = get_minecraft_page
       puts "[+] Downloading Minecraft server..."
       `wget http://minecraft.net/#{url} -O minecraft_server.jar -q`
     end
 
+    # Parses the miencraft.net download page for the current jarfile URL.
     def self.get_minecraft_page
       page = Net::HTTP.get("www.minecraft.net", "/download.jsp")
       data = page.match /\"([0-9a-zA-Z_\/]*minecraft_server\.jar\?v=[0-9]+)/
       data[1]
     end
 
+    # Generates a command for running the server with default settings including memory.
+    #
+    # @param [Slop] opts Command line options from Slop, used for memory specification.
     def self.command(opts)
       "java -Xmx#{opts[:max_memory] || "1024M"} -Xms#{opts[:min_memory] || "1024M"} -jar minecraft_server.jar nogui"
     end
 
+    # Toggles mobs in server.properties and returns the new state.
     def self.toggle_mobs
       content = File.read("server.properties")
       state = content.match(/spawn\-monsters=(true|false)/)[1]

data/lib/minecraft/version.rb

@@ -1,3 +1,5 @@
+# Global Minecraft module.
 module Minecraft
-  VERSION = "0.0.5"
+  # Yay, keep these versions coming!
+  VERSION = "0.1.0"
 end

data/test/commands_test.rb

@@ -0,0 +1,80 @@
+require "helper"
+require "minecraft"
+
+class CommandsTest < Test
+  include Minecraft::Commands
+  test "should properly check quantifiers" do
+    assert is_quantifier? "1"
+    assert is_quantifier? "10"
+    assert is_quantifier? "9m"
+    assert is_quantifier? "9mm"
+    refute is_quantifier? "m"
+    refute is_quantifier? "steel"
+    refute is_quantifier? "!"
+  end
+
+  test "should propery quantify values" do
+    assert_equal 1,    quantify("1")
+    assert_equal 64,   quantify("1m")
+    assert_equal 63,   quantify("1s")
+    assert_equal 64,   quantify("1d")
+    assert_equal 1,    quantify("1i")
+    assert_equal 32,   quantify("2d")
+    assert_equal 160,  quantify("2d2m")
+    assert_equal 2560, quantify("41m")
+    assert_equal 2560, quantify("100000")
+    assert_equal 64,   quantify("0d")
+  end
+
+  test "should resolve keys" do
+    @server = StringIO.new
+    assert_equal "glass",       resolve_key("glass")
+    assert_equal "redstone",    resolve_key("redstone")
+    assert_equal "redstone",    resolve_key("reds")
+    assert_equal "cobblestone", resolve_key("cobb")
+    assert_equal "cobweb",      resolve_key("cob")
+    assert_nil resolve_key("asdf")
+  end
+
+  test "should properly distinguish items and quantities" do
+    assert_equal ["flint", 1], items_arg(1, ["flint"])
+    assert_equal ["flint and steel", 1], items_arg(1, ["flint", "and", "steel"])
+    assert_equal ["flint", 64], items_arg(1, ["flint", "64"])
+    assert_equal ["flint and steel", 64], items_arg(1, ["flint", "and", "steel", "64"])
+  end
+
+  test "should properly resolve an item id" do
+    @server = StringIO.new
+    assert_equal "5",  resolve_item("5")
+    assert_equal "81", resolve_item("cactus")
+    assert_nil resolve_item("asdf")
+  end
+
+  test "give command should give a single slot worth" do
+    @server = StringIO.new
+    give("foo", "cobblestone", "64")
+    result = <<eof
+give foo 4 64
+eof
+    assert_equal result, @server.string
+  end
+
+  test "give command should work for multiple slot spans" do
+    @server = StringIO.new
+    give("foo", "cobblestone", "2m")
+    result = <<eof
+give foo 4 64
+give foo 4 64
+eof
+    assert_equal result, @server.string
+  end
+
+  test "give command should give less than a single slot span" do
+    @server = StringIO.new
+    give("foo", "cobblestone", "32")
+    result = <<eof
+give foo 4 32
+eof
+    assert_equal result, @server.string
+  end
+end

data/test/helper.rb

@@ -0,0 +1,14 @@
+unless Object.const_defined? 'Minecraft'
+  $:.unshift File.expand_path("../../lib", __FILE__)
+  require "minecraft"
+end
+
+require "minitest/autorun"
+require "stringio"
+require "turn"
+
+class Test < MiniTest::Unit::TestCase
+  def self.test(name, &block)
+    define_method("test_#{name.gsub(/\W/, '_')}", block)
+  end
+end

data/test/tools_test.rb

@@ -0,0 +1,30 @@
+require "helper"
+require "minecraft/tools"
+
+class ToolsTest < Test
+  test "should get minecraft download url" do
+    url = Minecraft::Tools.get_minecraft_page
+    refute_nil url.index "minecraft_server.jar"
+  end
+
+  test "should generate a proper default command" do
+    command = Minecraft::Tools.command({})
+    assert_equal "java -Xmx1024M -Xms1024M -jar minecraft_server.jar nogui", command
+  end
+
+  test "should properly modify server properties when toggling mobs" do
+    File.open("server.properties", "w") do |f| f.print <<-eof
+#Minecraft server properties
+#Thu May 26 15:19:31 EDT 2011
+view-distance=10
+spawn-monsters=false
+online-mode=true
+eof
+    end
+    assert_equal "true", Minecraft::Tools.toggle_mobs
+    refute_nil File.read("server.properties").index("spawn-monsters=true")
+    assert_equal "false", Minecraft::Tools.toggle_mobs
+    refute_nil File.read("server.properties").index("spawn-monsters=false")
+    FileUtils.rm_f("server.properties")
+  end
+end

metadata

@@ -2,7 +2,7 @@
 name: minecraft
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.0.5
+  version: 0.1.0
 platform: ruby
 authors: 
 - Andrew Horsman
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-08-18 00:00:00 -04:00
+date: 2011-08-19 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -35,6 +35,8 @@ extra_rdoc_files: []
 
 files: 
 - .gitignore
+- .yardopts
+- CHANGES.md
 - Gemfile
 - README.md
 - Rakefile
@@ -48,6 +50,9 @@ files:
 - lib/minecraft/tools.rb
 - lib/minecraft/version.rb
 - minecraft.gemspec
+- test/commands_test.rb
+- test/helper.rb
+- test/tools_test.rb
 has_rdoc: true
 homepage: http://github.com/basicxman/minecraft
 licenses: []