toy_robo_simulator 0.1.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8d36581000b8d9c29ed537e9dd0f387fb9916e76
-  data.tar.gz: dd370f74e8875bdd316da77319ca0272a3f1b2d9
+  metadata.gz: 62ae956554d56c2339ad12155828b718e5c43001
+  data.tar.gz: 4e821907248355bb259346bda33259f1859dd661
 SHA512:
-  metadata.gz: e9220146ac4c361c80413c1eecf03dbafb5b52f39101491fd2b4c660fb5957a6141d8ac77ad2dd0482bb9995219cfd5021f4f81b23ebb91bb0c9c461b836ec98
-  data.tar.gz: b5fce97d98b20109882deb14a82ea1f2d397c7e100422c038f475f669195c669b2a4a5dfff2cdad30160135b3b0fec7fbe537b5eecce3da628080dd0e4e3eb7f
+  metadata.gz: 185656aec074d6b64dc86c8e07081380232c7551683e66634ab78042c1307982ca4e05a1dff1f96b0592fbafba25d69e1079905eed2bda37cbfcd1d5adb947d3
+  data.tar.gz: b0aec3cc330d7290d00324f2a481d781a77867feda4e81db6aa565e28baf2cffe6b9125bc085a82308f8502fe59710b8962a5ebe9ce8a1d2d86abedfbc76304d

data/.gitignore

@@ -7,3 +7,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+*.gem

data/.yardopts

@@ -0,0 +1 @@
+--markup=markdown

data/Gemfile

@@ -2,3 +2,4 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in toy_robo_simulator.gemspec
 gemspec
+gem 'codeclimate-test-reporter', group: :test, require: nil

data/README.md

@@ -1,34 +1,101 @@
-# Toy Robot Simulator
+# Toy Robo Simulator
 
-## Installation
+[![Gem Version](https://badge.fury.io/rb/toy_robo_simulator.svg)](https://rubygems.org/gems/toy_robo_simulator) [![](https://travis-ci.org/adlerhsieh/toy_robo_simulator.svg)](https://travis-ci.org/adlerhsieh/toy_robo_simulator) [![Code Climate](https://codeclimate.com/github/adlerhsieh/toy_robo_simulator/badges/gpa.svg)](https://codeclimate.com/github/adlerhsieh/toy_robo_simulator) [![Test Coverage](https://codeclimate.com/github/adlerhsieh/toy_robo_simulator/badges/coverage.svg)](https://codeclimate.com/github/adlerhsieh/toy_robo_simulator/coverage)
+
+Toy Robo Simulator is a command line application that simulates the movement of a toy robot, or robo, on a square table. Entering an interactive console, you have several commands to control the robo including `PLACE`, `MOVE`, `LEFT`, and `RIGHT`. It's like moving a character in a PRG game. Feel free to roam around. 
 
-Run:
+## Installation
 
 ```
 gem install toy_robo_simulator
 ```
 
-## Usage
+Since this is a standalone program, there is no need to install with a `Gemfile`.
+
+## Initialize
+
+```
+robo
+```
+
+You should see a welcome message along with a command line prompt. Ready to move the robots!
+
+## Available Commands
+
+```ruby
+PLACE
+# Place a robo. Requires x, y, and orientation arguments. Arguments are separated by a white space.
+# e.g. PLACE 2 5 NORTH
+
+MOVE
+# Move forward one space. e.g. Facing north will move the robo one unit toward north.
 
-## Development Specs
+LEFT
+# Turn left.
 
-- [ ] Create a 5x5 tabletop when initated
-- [ ] The (0,0) is the south west corner
-- [ ] The robot cannot move out of range
-- [ ] Available Commands
-  - [ ] PLACE X, Y, F: Place the robot on a specific position with direction
-  - [ ] MOVE: move forward one space
-  - [ ] LEFT: turn left
-  - [ ] RIGHT: turn right
-  - [ ] REPORT: report current position and direction
-- [ ] PLACE should be the first command, otherwise ignored
-- [ ] Allow both CLI input and file input
+RIGHT
+# Turn right.
+
+REPORT
+# Report current position and orientation.
+
+HELP
+# Display all available commands.
+```
+
+The commands are not case-sensitive. Either `PLACE`, `Place` or `place` will work. 
+
+However, several rules to follow:
+
+- A robo must be placed on the table before any other commands.
+- The robo cannot be placed out of the table.
+- The robo is not allowed to move out the the table.
+
+## A Complete Example
+
+```
+Welcome to Toy Robo Simulator!
+
+Available Commands:
+- PLACE:  Place a robo. Requires x, y, and orientation arguments.
+          e.g. PLACE 2 5 NORTH
+- MOVE:   Move forward
+- LEFT:   Turn left
+- RIGHT:  Turn right
+- REPORT: Report current position and orientation
+- HELP:   Display all available commands
+Use PLACE first to start the simulation :)
+
+00 > PLACE 2 1 NORTH
+It is placed.
+01 > MOVE
+It moves forward.
+02 > LEFT
+It turns left.
+03 > REPORT
+Robo is now at (2,2) facing WEST
+04 > MOVE
+It moves forward.
+05 > RIGHT
+It turns right
+06 > MOVE
+It moves forward.
+07 > REPORT
+Robo is now at (1,3) facing NORTH
+08 > exit
+
+Thank You!
+```
+
+## Development Documentation
+
+Detailed documentations of every class, module, and method are on [RubyDoc](http://www.rubydoc.info/gems/toy_robo_simulator/1.0.0).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/toy_robo_simulator. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/adlerhsieh/toy_robo_simulator. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](contributor-covenant.org) code of conduct.
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
- 
+

data/lib/toy_robo_simulator.rb

@@ -1,5 +1,5 @@
 require_relative 'toy_robo_simulator/version'
-require_relative 'toy_robo_simulator/env'
+require_relative 'toy_robo_simulator/message'
 require_relative 'toy_robo_simulator/table'
 require_relative 'toy_robo_simulator/validator'
 require_relative 'toy_robo_simulator/robo'
@@ -7,11 +7,11 @@ require_relative 'toy_robo_simulator/console'
 
 # This module includes all other modules and classes in this program.
 # Basically it can be divided into:
-# 
+#
 # - Console: Offering a command line interface for input & output.
 # - Robo: A robot simulating the movement on a table.
 # - Validator: Validating the robo's actions and their prerequisities.
 # - Others
-#
 module ToyRoboSimulator
+  ORIENTATIONS = %i(north west south east).freeze
 end

data/lib/toy_robo_simulator/console.rb

@@ -1,46 +1,64 @@
 module ToyRoboSimulator
-  # The console is responsible for initaing a command line interface for 
+  # The console is responsible for initaing an interactive command line interface for
   # users to access the program.
   class Console
+    attr_accessor :robo
+    # Available uner-input commands
+    AVAILABLE_COMMANDS = %w(place move left right report help exit).freeze
+
+    # Initializes a CLI that includes a Robo instance.
     def initialize
-      puts ::MESSAGE
+      puts MESSAGE
       @n = 0
       @robo = Robo.new
       print "#{format('%02d', @n)} > "
     end
 
+    # Starts watching for user input.
     def watch
-      command = STDIN.gets
+      command = STDIN.gets.chomp
       while command
         run(command)
         print "#{format('%02d', @n += 1)} > "
-        command = STDIN.gets
+        command = STDIN.gets.chomp
       end
     end
 
+    # Analyzes if command is available, and process the command.
+    # The command should be separated either by white spaces or commas.
+    # However, only commands in AVAILABLE_COMMANDS are allowed.
+    #
+    # ```
+    # console = ToyRoboSimulator::Console.new
+    # console.run('hello world') # => 'unknown command.'
+    # console.run('foo, bar') # => 'unknown command.'
+    # console.run('exit') # => 'Thank You!'
+    # ```
     def run(command)
-      args   = command.split(' ')
-      action = args[0].gsub("\n", '').downcase
-      case
-      when ::AVAILABLE_COMMANDS.include?(action)
-        process(action, args)
-      when action == 'exit'
-        exit_program
-      when action == 'help'
-        help
+      args = to_args(command)
+      if AVAILABLE_COMMANDS.include?(args[0])
+        process(args[0], args[1..-1])
       else
-        puts ::WARNING
+        puts WARNING
       end
     end
 
     private
 
+    # Directly sends the command with arguments to the Robo instance.
     def process(action, args)
-      begin
-        @robo.send(action.to_sym, *args[1..-1])
-      rescue ArgumentError => e
-        tip if e.message.include? 'wrong number of arguments'
+      case action
+      when 'exit' then exit_program
+      when 'help' then help
+      else
+        @robo.send(action.to_sym, *args)
       end
+    rescue ArgumentError => e
+      tip if e.message.include? 'wrong number of arguments'
+    end
+
+    def to_args(command)
+      command.split(' ').map { |n| n.split(',') }.flatten.map(&:chomp).map(&:downcase)
     end
 
     def tip

data/lib/toy_robo_simulator/{env.rb → message.rb}

@@ -1,6 +1,8 @@
 require 'colorize'
 
-AVAILABLE_COMMANDS = %w(place move left right report)
+TIP = "#{'WARNING'.colorize(:red)}
+- PLACE should take 3 arguments: x, y, and orientation. e.g. PLACE 1 2 NORTH
+- Other commands take no argument.".freeze
 
 HELP = "Available Commands:
 - PLACE:  Place a robo. Requires x, y, and orientation arguments.
@@ -9,15 +11,9 @@ HELP = "Available Commands:
 - LEFT:   Turn left
 - RIGHT:  Turn right
 - REPORT: Report current position and orientation
-- HELP:   Display all available commands"
+- HELP:   Display all available commands".freeze
 
 MESSAGE = "\n#{'Welcome to Toy Robo Simulator!'.colorize(:green)}
-\n#{HELP}\nUse PLACE first to start the simulation :)\n\n"
-
-WARNING = "Command Not Found. See 'HELP'."
-
-TIP = "#{'WARNING'.colorize(:red)}
-- PLACE should take 3 arguments: x, y, and orientation. e.g. PLACE 1 2 NORTH
-- Other commands take no argument."
+\n#{HELP}\nUse PLACE first to start the simulation :)\n\n".freeze
 
-ORIENTATIONS = %i(north west south east)
+WARNING = "Command Not Found. See 'HELP'.".freeze

data/lib/toy_robo_simulator/robo.rb

@@ -1,50 +1,106 @@
 module ToyRoboSimulator
+  # Rubo is the character of this program. It serves to simulates the movement of a robot on a table.
+  # The available actions are place, move, left, right, and report. Each action is validated before execution
+  # and will respond with the result.
   class Robo
     include Validator
     attr_accessor :x, :y, :orientation
 
+    # Initializes a Robo instance with a table sizes 5x5.
     def initialize
       @table  = Table.new(5, 5)
       @errors = []
     end
 
+    # Places the robo on the table. The x and y arguments indicates its position.
+    # The positions shoule be within the range of the table.
+    # The orientation is limited to either north, south, west, and east.
+    # Any invalid argument will not set the Robo's attributes.
+    #
+    # ```
+    # robo = ToyRoboSimulator::Robo.new
+    # robo.place(1, 2, :north) # => 'It is placed.'
+    # robo.x # => 1
+    # robo.y # => 2
+    # robo.orientation # => :north
+    #
+    # robo.place("foo", "bar", :south)
+    # # => 'X must be a number'
+    # # => 'Y must be a number'
+    # robo.x # => nil
+    # robo.y # => nil
+    # ```
     def place(x, y, orientation)
       validate_placement(x, y, orientation)
       warning && return if @errors.any?
-      @x, @y = x.to_i, y.to_i
+      @x = x.to_i
+      @y = y.to_i
       @orientation = orientation.downcase.to_sym
       puts 'It is placed.'
     end
 
+    # Moves forward one space. This method is noly valid after the Robo is placed.
+    # Facing north will move the Robo one unit toward north.
+    # However, no further move is allowed if the Robo is at the edge of a table,
+    # which means, for example, its x coordinate is equal to the max value of
+    # a Table's width.
+    #
+    # ```
+    # robo = ToyRoboSimulator::Robo.new
+    # robo.move # => 'The Robo is not placed yet. Use PLACE command first.'
+    #
+    # robo.place(4, 2, :east) # => 'It is placed.'
+    # robo.x # => 4
+    # robo.move # => 'It moves forward.'
+    # robo.x # => 5
+    # robo.move # => 'The Robo is at edge. No further move is allowed.'
+    # robo.x # => 5
+    # ```
     def move
       validate_if_placed
       validate_movement
       warning && return if @errors.any?
-      case orientation
-      when :north then @y += 1
-      when :east  then @x += 1
-      when :south then @y -= 1
-      when :west  then @x -= 1
-      end
+      move_forward(1)
       puts 'It moves forward.'
     end
 
+    # Turns left. It changes the Robo's current orientation.
+    # This method is noly valid after the Robo is placed.
+    #
+    # ```
+    # robo = ToyRoboSimulator::Robo.new
+    # robo.left # => 'The Robo is not placed yet. Use PLACE command first.'
+    #
+    # robo.place(3, 3, :east) # => 'It is placed.'
+    # robo.orientation # => :east
+    # robo.left # => 'It turns left'
+    # robo.orientation # => :north
+    # ```
     def left
       validate_if_placed
       warning && return if @errors.any?
-      index = ::ORIENTATIONS.index(@orientation) + 1
-      @orientation = ::ORIENTATIONS[index] || :north
+      turn(:left)
       puts 'It turns left.'
     end
 
+    # Turns right. See `#left`.
     def right
       validate_if_placed
       warning && return if @errors.any?
-      index = ::ORIENTATIONS.index(@orientation) - 1
-      @orientation = ::ORIENTATIONS[index]
+      turn(:right)
       puts 'It turns right'
     end
 
+    # Reports current postion and orientation.
+    # This method is noly valid after the Robo is placed.
+    #
+    # ```
+    # robo = ToyRoboSimulator::Robo.new
+    # robo.report # => 'The Robo is not placed yet. Use PLACE command first.'
+    #
+    # robo.place(3, 3, :east) # => 'It is placed.'
+    # robo.report # => 'Robo is now at (3,3) facing EAST'
+    # ```
     def report
       validate_if_placed
       warning && return if @errors.any?
@@ -58,5 +114,19 @@ module ToyRoboSimulator
       @errors = []
     end
 
+    def turn(direction)
+      i = direction == :left ? 1 : -1
+      index = ORIENTATIONS.index(@orientation) + i
+      @orientation = ORIENTATIONS[index] || :north
+    end
+
+    def move_forward(unit)
+      case @orientation
+      when :north then @y += unit
+      when :east  then @x += unit
+      when :south then @y -= unit
+      when :west  then @x -= unit
+      end
+    end
   end
 end

data/lib/toy_robo_simulator/table.rb

@@ -1,6 +1,12 @@
 module ToyRoboSimulator
+  # Table is the environment in the program which decides
+  # the length and width of the table. The table will be used to
+  # validate the placement and movement of a Robo.
+  #
+  # The attributes x and y are the maximum values of length and width,
+  # while 0 is the minimum value.
   class Table
-    attr_accessor :x, :y
+    attr_reader :x, :y
     def initialize(x, y)
       @x = x
       @y = y

data/lib/toy_robo_simulator/validator.rb

@@ -1,5 +1,9 @@
 module ToyRoboSimulator
+  # Validator serves to validate operations performed by a Robo. It is a standalone module but
+  # takes arguments and attributes from a Robo.
   module Validator
+    # Ensures input values of Robo#place action is valid in type and range.
+    # Returns false if it is not valid.
     def validate_placement(x, y, orientation)
       @errors << 'X must be a number' unless int?(x)
       @errors << 'Y must be a number' unless int?(y)
@@ -8,21 +12,18 @@ module ToyRoboSimulator
       @errors << 'Orientation should be either NORTH, SOUTH, EAST, or WEST' unless orientation_valid?(orientation)
     end
 
+    # Prevents Robo#move from moving out of the table.
+    # Returns false if the Robo is at the edge of the table.
     def validate_movement
-      @errors << 'The Robo is at edge. No further move is allowed.' if at_table_edge?
+      @errors << 'The Robo is at edge. No further move is allowed.' if edge?
     end
 
+    # Ensures the Robo is placed before any other actions are performed.
+    # Returns false if no attributes are set for the Robo.
     def validate_if_placed
       @errors << 'The Robo is not placed yet. Use PLACE command first.' unless @x && @y && @orientation
     end
 
-    def at_table_edge?
-      (@orientation == :north && @y == @table.y) ||
-      (@orientation == :east  && @x == @table.x) ||
-      (@orientation == :south && @y == 0)        ||
-      (@orientation == :west  && @x == 0)
-    end
-
     private
 
     def int?(value)
@@ -34,7 +35,20 @@ module ToyRoboSimulator
     end
 
     def orientation_valid?(orientation)
-      ::ORIENTATIONS.include? orientation.downcase.to_sym
+      ORIENTATIONS.include? orientation.downcase.to_sym
+    end
+
+    def edge?
+      case @orientation
+      when :north
+        @y == @table.y
+      when :east
+        @x == @table.x
+      when :south
+        @y == 0
+      when :west
+        @x == 0
+      end
     end
   end
 end

data/lib/toy_robo_simulator/version.rb

@@ -1,3 +1,3 @@
 module ToyRoboSimulator
-  VERSION = '0.1.0'
+  VERSION = '1.0.1'
 end

data/toy_robo_simulator.gemspec

@@ -4,23 +4,23 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'toy_robo_simulator/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "toy_robo_simulator"
+  spec.name          = 'toy_robo_simulator'
   spec.version       = ToyRoboSimulator::VERSION
-  spec.authors       = ["Adler"]
-  spec.email         = ["nkj20932@hotmail.com"]
+  spec.authors       = ['Adler']
+  spec.email         = ['nkj20932@hotmail.com']
 
-  spec.summary       = %q{A toy robot simulator}
-  spec.description   = %q{A CLI that simulates the movement of a robot on a 5x5 table}
-  spec.homepage      = "http://github.com/adlerhsieh/toy_rubo_simulator"
-  spec.license       = "MIT"
+  spec.summary       = 'A toy robot simulator'
+  spec.description   = 'A CLI that simulates the movement of a robot on a 5x5 table'
+  spec.homepage      = 'http://github.com/adlerhsieh/toy_robo_simulator'
+  spec.license       = 'MIT'
 
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
-  spec.bindir        = "exe"
+  spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
 
-  spec.add_development_dependency "bundler", "~> 1.10"
-  spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_development_dependency "rspec"
-  spec.add_development_dependency "colorize"
+  spec.add_development_dependency 'bundler', '~> 1.10'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '3.4.0'
+  spec.add_development_dependency 'colorize', '0.7.7'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toy_robo_simulator
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Adler
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-03-10 00:00:00.000000000 Z
+date: 2016-03-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -42,30 +42,30 @@ dependencies:
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 3.4.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 3.4.0
 - !ruby/object:Gem::Dependency
   name: colorize
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.7.7
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.7.7
 description: A CLI that simulates the movement of a robot on a 5x5 table
 email:
 - nkj20932@hotmail.com
@@ -78,6 +78,7 @@ files:
 - ".rubocop.yml"
 - ".ruby-version"
 - ".travis.yml"
+- ".yardopts"
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
@@ -88,13 +89,13 @@ files:
 - bin/setup
 - lib/toy_robo_simulator.rb
 - lib/toy_robo_simulator/console.rb
-- lib/toy_robo_simulator/env.rb
+- lib/toy_robo_simulator/message.rb
 - lib/toy_robo_simulator/robo.rb
 - lib/toy_robo_simulator/table.rb
 - lib/toy_robo_simulator/validator.rb
 - lib/toy_robo_simulator/version.rb
 - toy_robo_simulator.gemspec
-homepage: http://github.com/adlerhsieh/toy_rubo_simulator
+homepage: http://github.com/adlerhsieh/toy_robo_simulator
 licenses:
 - MIT
 metadata: {}
@@ -119,3 +120,4 @@ signing_key:
 specification_version: 4
 summary: A toy robot simulator
 test_files: []
+has_rdoc: