toy-robot-simulator 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3ed853290dbb977c1c2b342805da404cc67a2a6100f87595b575619aa31f647
-  data.tar.gz: ab21ed69da38c44c7bd494a88ba07c00be6fc2146782e77a4ab1d94c45450096
+  metadata.gz: 45d7af2744c4d7fe285025d8a6777f1e55a81d3ec9bfc71c75a4492405642c4a
+  data.tar.gz: 427275d04889e285ed1869bcc97e60957ff0e8b57166b087bda91c720e135b64
 SHA512:
-  metadata.gz: 8f7080dcaf8309609f5dd61ae4e75428abdbba355d0d0a6a1bb228c7d653eb8c0fa0fdc90cb094ac59494b149e0276c02ff8c6ab1b929800a2e154639b3c4356
-  data.tar.gz: 19b7d35b3cc6c0c02297e2964d78e201d981dbc877a97b7d6923288b56eee02e98139eb720ef59cb58fbeb8544870b736a403c13426c3c92aa7d54037241ac51
+  metadata.gz: 437ddd7ff5990ac97f339c46ec4a5d47b30d7f9b4c4d260d224be29298be147829e5603d607a8a9384c5422b52376eb200665e747638ff192461839212264378
+  data.tar.gz: b1bdd09d3e4b79e0c29a62306acd441fbf74eb4af88849e9b752305d7ab68c931ead274b9f6688802b279645484882971c63bb8c6c20a0be9d3511e2f8392c0a

data/README.md

@@ -4,13 +4,13 @@ _version: 0.0.1_
 
 The Ruby gem let the toy robot move a table painlessly, easily, and most importantly, **it does not fall from the table** 
 
-- [Full gem documentation (version 0.0.1)](https://www.rubydoc.info/gems/toy-robot-simulator/0.0.1/)
+- [Full gem documentation (version 0.0.3)](https://www.rubydoc.info/gems/toy-robot-simulator/0.0.3/)
 # Installation
 ```
 gem install toy-robot-simulator
 ```
 ```ruby
-gem "toy-robot-simulator", "~> 0.0.1"
+gem "toy-robot-simulator", "~> 0.0.3"
 ```
 ```
 bundle install
@@ -33,11 +33,7 @@ examples:
 ```ruby
 ToyRobotController.init(['PLACE 0,0,NORTH', 'MOVE'])
 ```
-**3. Execute the commands**
-```ruby
-ToyRobotController.execute_commands
-```
-**4. Report**
+**3. Report**
 ```ruby
 ToyRobotController.report
 ```
@@ -47,7 +43,6 @@ ToyRobotController.report
 
 ```ruby
 require  'helpers/command_set_loader'
-include CommandSetLoader
 ```
 ```ruby
 commands = CommandSetLoader.read_commands('./test_data/test1.txt')
@@ -57,7 +52,7 @@ commands = CommandSetLoader.read_commands('./test_data/test1.txt')
 ToyRobotController.init(commands)
 ```
 
-## Things to considered
+## Things to consider
 
  **init** method of ToyRobotController expects array of commands where all the commands should be type of **string**
  
@@ -68,6 +63,11 @@ MOVE
 REPORT
 ```
 
+## Change Log
+- Updated documentation
+- Added more readable comments in the code
+- Updated the CommandSetLoader
+
 ## TODO
 
 - Add configuration option 
@@ -77,3 +77,4 @@ REPORT
 - **CommandSetLoader** is reading file locally, would be a good idea to add the option to read the file remotely
 - Add obstructions on the table
 - Non square table 
+- Robot reports in multiple formats such as JSON, HTML, XML etc

data/lib/errors/command.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# contains commands related error classes
 module Command
   class InvalidOrEmptyCommands < StandardError; end
   class InvalidCommandStreamType < StandardError; end

data/lib/errors/robot.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# contains ToyRobot related error classes
 module ToyRobot
   class InvalidFacing < StandardError; end
   class RobotIsNotPlaced < StandardError; end

data/lib/errors/table.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# contains Table related error classes
 module Surface
   class TableOutOfBound < StandardError; end
   class TableIsNotSet < StandardError; end

data/lib/helpers/command_helper.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
 require_relative '../constants/application_constants'
-# CommandHelper module
+
+# CommandHelper contains all the helper methods to valid integrity and type of a command
 module CommandHelper
+  # it will validate the provided command against the PLACE_COMMAND_PATTERN set in the application_contants
+  # @retrun [Boolean]
   def a_valid_place_command?(command)
     return false if command.match(PLACE_COMMAND_PATTERN).nil?
 
@@ -14,16 +17,22 @@ module CommandHelper
     result&.captures
   end
 
+  # it will return type of command such as PLACE, MOVE, LEFT, RIGHT, REPORT
+  # @return [String]
   def command_type(command)
     return if command.nil?
     return PLACE if command.include? PLACE
     return command if COMMANDS.include? command
   end
 
+  # return all directions array [NORTH EAST SOUTH WEST]
+  # @return [Array]
   def directions
     DIRECTIONS
   end
 
+  # return all valid commands array [MOVE LEFT RIGHT REPORT PLACE]
+  # @return [Array]
   def commands
     COMMANDS
   end

data/lib/helpers/command_parser_helper.rb

@@ -2,10 +2,21 @@
 
 require_relative '../constants/application_constants'
 require_relative 'command_helper'
-# CommandParserHelper module
+
+# CommandParserHelper is just parsing the command and return a command Struct
 module CommandParserHelper
   include CommandHelper
 
+  # it the provided command is valid, it will return a Struct with
+  # with type, value, status, error attributes
+  #
+  # type represents the type of command such as PLACE, MOVE, REPORT, LEFT, RIGHT
+  #
+  # value represents the value it holds such value will be X,Y,F for PLACE command
+  #
+  # status and error attributes are set to empty in the start
+  # @param command [String]
+  # @return [Struct]
   def parse_command(command)
     type_of_command = command_type(command)
     return if type_of_command.nil?
@@ -16,16 +27,19 @@ module CommandParserHelper
 
   private
 
+  # returns the value of a comamnd
   def command_value(command)
     return split_place_command(command) if place_command_and_valid?(command)
 
     command
   end
 
+  # return command Struct
   def command_object(type, value, status = '', error = '')
     Struct.new(:type, :value, :status, :error).new(type, value, status, error)
   end
 
+  # check if it is a PLACE command and valid also
   def place_command_and_valid?(command)
     command_type(command) == PLACE && a_valid_place_command?(command)
   end

data/lib/helpers/command_set_loader.rb

@@ -1,22 +1,32 @@
 # frozen_string_literal: true
 
 require_relative '../errors/command'
-# CommandSetLoader module
+# CommandSetLoader is there to read commands from file locally for now
 module CommandSetLoader
-  def read_commands(location = '', source = 'file', format = 'text')
-    raise Command::FormatNotSupported, 'Only text format is supported' unless format == 'text'
-    raise Command::SourceNotSupported, 'Only file as a source is supported' unless source == 'file'
-    raise Command::EmptyLocationProvided if location.strip == ''
+  class << self
+    # @todo Add support to load file remotely and support for different formats such as JSON
+    # @param location [String] location of the file containig commands
+    # @param source [String]
+    # @param format [String]
+    # @raise [Command::FormatNotSupported] if format is not set to text
+    # @raise [Command::SourceNotSupported] if source is not set to file
+    # @raise [Command::EmptyLocationProvided] location is empty
+    def read_commands(location = '', source = 'file', format = 'text')
+      raise Command::FormatNotSupported, 'Only text format is supported' unless format == 'text'
+      raise Command::SourceNotSupported, 'Only file as a source is supported' unless source == 'file'
+      raise Command::EmptyLocationProvided if location.strip == ''
 
-    @location = location
-    read_from_file
-  end
+      @location = location
+      read_from_file
+    end
 
-  private
+    private
 
-  def read_from_file
-    commands = []
-    File.readlines(@location).each { |line| commands << line.strip }
-    commands
+    # reading commands from file and return Array of commands
+    def read_from_file
+      commands = []
+      File.readlines(@location).each { |line| commands << line.strip }
+      commands
+    end
   end
 end

data/lib/surface/table.rb

@@ -3,17 +3,24 @@
 require_relative 'table_interface'
 require_relative '../errors/table'
 module Surface
-  # Table class
+  # Table class represents a square table of 5x5 by default
+  # @todo Add functionality to add Obsturctions on Table
   class Table
     include TableInterface
     attr_accessor :rows, :columns, :grid
 
+    # @param rows [Integer]
+    # @param columns [Integer]
     def initialize(rows = 5, columns = 5)
       @grid = Array.new(rows) { Array.new(columns) { 0 } }
       @rows = rows
       @columns = columns
     end
 
+    # validates if the x, y can be placed on to the table
+    # @param x [Integer]
+    # @param y [Integer]
+    # @return [Boolean]
     def can_be_placed?(x, y)
       return false unless (0..(rows - 1)).include?(x)
       return false unless (0..(columns - 1)).include?(y)

data/lib/surface/table_interface.rb

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
-# module Surface
+# Surface module is trying to set the rules interfaces type of surfaces such as TableInterface.
+#
+# in a nutshell a Table should include the *Surface:TableInterface* and override the can_be_placed? method
+#
+# if we want to add any other surface such as Benchtop, it will be a good
+# practice to create a BenchtopInterface module with the method(s) represents it rules
 module Surface
   # TableInterface to valid can_be_placed?(_x, _y) implemented by Table
   module TableInterface

data/lib/toy_robot/robot.rb

@@ -3,10 +3,12 @@
 require_relative '../errors/command'
 require_relative '../errors/robot'
 module ToyRobot
-  # Robot class
+  # Robot class represents our ToyRobot which be moving on to the table
   class Robot
     attr_accessor :x, :y, :facing, :placed, :table
 
+    # this method will set the instance methods such as table, placed, x, y and facing of robot
+    # @param table [Surface::Table]
     def initialize(table = nil)
       @placed = false
       @table = table
@@ -15,6 +17,17 @@ module ToyRobot
       @facing = nil
     end
 
+    # This method will place the robot on the table as per provided coordinates
+    # and direction it should be facing
+    # @param x [Integer]
+    # @param y [Integer]
+    # @param facing [String]
+    # @raise [Surface::TableIsNotSet] if the table is not set
+    #
+    # @raise [Surface::TableOutOfBound] if x or y will make the robot fall from the table
+    #
+    # @raise [Surface::InvalidFacing] if the facing value is other than [NORTH SOUTH EAST WEST]
+    #
     def place(x, y, facing)
       return if @placed
       raise Surface::TableIsNotSet if @table.nil?
@@ -27,16 +40,31 @@ module ToyRobot
       @placed = true
     end
 
+    # move the robot 90 degress counter clock wise
+    #
+    # example: if the robot was facing NORTH, it will be facing WEST after this method call
+    # @raise [Surface::TableIsNotSet] if the table is not set
+    # @raise [ToyRobot::RobotIsNotPlaced] if the robot is not placed
     def left
       check_pre_conditions
       @facing = next_facing('left')
     end
 
+    # move the robot 90 degress  clock wise
+    #
+    # example: if the robot was facing EAST, it will be facing SOUTH after this method call
+    # @raise [Surface::TableIsNotSet] if the table is not set
+    # @raise [ToyRobot::RobotIsNotPlaced] if the robot is not placed
     def right
       check_pre_conditions
       @facing = next_facing('right')
     end
 
+    # move the robot in the direct it is facing if possible
+    #
+    # @raise [Surface::TableOutOfBound] if the potential x or y will make the robot fall from the table
+    # @raise [Surface::TableIsNotSet] if the table is not set
+    # @raise [ToyRobot::RobotIsNotPlaced] if the robot is not placed
     def move
       check_pre_conditions
       result = calculate_potential_movement(facing)
@@ -50,6 +78,9 @@ module ToyRobot
       @y = y_should_be
     end
 
+    # @todo Add suppor for other formats such as JSON, XML, HTML etc
+    # @param format [String] default value is console
+    # @raise [ToyRobot::RobotIsNotPlaced] if the robot is not placed on to the table
     def report(format = 'console')
       raise ToyRobot::RobotIsNotPlaced unless @placed
 
@@ -61,6 +92,9 @@ module ToyRobot
       end
     end
 
+    # based on provided facing direction, which x or y coordinates should mutate
+    #
+    # *this method does not validate if the robot will fall from the table*
     def calculate_potential_movement(facing)
       case facing
       when 'NORTH'
@@ -80,6 +114,8 @@ module ToyRobot
       "#{@x},#{@y},#{@facing}"
     end
 
+    # based on provided arrow value left/right
+    # it determines the next direction of robot facing
     def next_facing(arrow)
       return DIRECTIONS.last if @facing == DIRECTIONS.first && arrow == 'left'
       return DIRECTIONS.first if @facing == DIRECTIONS.last && arrow == 'right'

data/lib/toy_robot_controller.rb

@@ -8,12 +8,21 @@ require_relative 'errors/command'
 # ToyRobotController module which sets up the Robot, Table and execute commands provided
 module ToyRobotController
   class << self
-    attr_accessor :robot, :commands
     include CommandParserHelper
 
     # This method is expecting [Array<String>] of commands such as ['PLACE 0,0,NORTH', 'MOVE', 'REPORT']
     # @param commands_stream [Array<String>]
     # @param table_size [Integer]
+    #
+    # @raise [Command::InvalidCommandStreamType] if the commands_stream is not of type Array
+    #
+    # @raise [Command::InvalidOrEmptyCommands] if the commands_stream array length is 0
+    #
+    # @raise [Command::InvalidCommandType] if the any of commands_stream element is not type String
+    #
+    # @raise [Command::NoValidCommandsFound] if the commands_stream array length is 0 or contains all invalid commands
+    #
+    # @raise [Command::PlaceCommandNotFound] if the commands_stream array does not contain a valid PLACE command
     def init(commands_stream, table_size = 5)
       validate_command_stream(commands_stream)
 
@@ -22,20 +31,22 @@ module ToyRobotController
       @robot = ToyRobot::Robot.new(@table)
       @commands = []
       populate_commands
+      execute_commands
     end
 
-    # This method return the coordinates of Robot on the table and the direction it is facing
-    def report(format = 'console')
-      @robot.report(format)
-    end
+    # return [ToyRobot::Robot] if present
+    # @return [ToyRobot::Robot]
+    attr_reader :robot
 
-    # Simply executes the commands array.
-    #
-    # considerations:
+    # return Array of commands if present
     #
-    # @raise [Command::NoValidCommandsFound] if the commands array length is 0
-    #
-    # @raise [Command::PlaceCommandNotFound] if the commands array does not contain a valid PLACE command
+    # example: <struct type="PLACE", value=["0", "0", "NORTH"], status="", error="">
+    # @return [Array<Struct>]
+    attr_reader :commands
+
+    private
+
+    # validate the populated commands and send each to the send_command_to_robot method
     def execute_commands
       raise Command::NoValidCommandsFound if @commands.size.zero?
       raise Command::PlaceCommandNotFound if @commands.select { |c| c.type == 'PLACE' }.size.zero?
@@ -43,8 +54,9 @@ module ToyRobotController
       @commands.each { |command| send_command_to_robot(command) }
     end
 
-    private
-
+    # based on command type, it call the appropriate method of Robot
+    # if the command can not be executed by the Robot, it will update the status and error attributes
+    # of command struct
     def send_command_to_robot(command)
       case command.type
       when 'PLACE'
@@ -57,12 +69,14 @@ module ToyRobotController
       command.error = e.to_s
     end
 
+    # checks the integrity of commands_stream Array
     def validate_command_stream(commands_stream)
       raise Command::InvalidCommandStreamType unless commands_stream.is_a?(Array)
       raise Command::InvalidOrEmptyCommands if commands_stream.size.zero?
       raise Command::InvalidCommandType unless commands_stream.all? { |i| i.is_a? String }
     end
 
+    # filling the commands array with all the valid commands by parse_command method
     def populate_commands
       @commands_stream.each do |command|
         current_command = parse_command(command)

data/spec/command_set_loader_spec.rb

@@ -1,33 +1,33 @@
 # frozen_string_literal: true
 
 describe CommandSetLoader do
-  include CommandSetLoader
+  let(:loader) { described_class }
 
-  describe '#read_commands' do
+  describe '.read_commands' do
     it 'will load the commands from test1.txt file and return array of commands' do
-      commands = read_commands('./test_data/test1.txt')
+      commands = loader.read_commands('./test_data/test1.txt')
       expect(commands).to match_array(['PLACE 0,0,NORTH', 'MOVE', 'REPORT'])
     end
 
     it 'will load the commands from test2.txt file and return array of commands' do
-      commands = read_commands('./test_data/test2.txt')
+      commands = loader.read_commands('./test_data/test2.txt')
       expect(commands).to match_array(['PLACE 0,0,NORTH', 'LEFT', 'REPORT'])
     end
 
     it 'will load the commands from test3.txt file and return array of commands' do
-      commands = read_commands('./test_data/test3.txt')
+      commands = loader.read_commands('./test_data/test3.txt')
       expect(commands).to match_array(['PLACE 1,2,EAST', 'MOVE', 'MOVE', 'LEFT', 'MOVE', 'REPORT'])
     end
 
     it 'will return SourceNotSupported exception if source is not file' do
       expect do
-        read_commands('./test_data/test3.txt', 'remote')
+        loader.read_commands('./test_data/test3.txt', 'remote')
       end.to raise_error(Command::SourceNotSupported)
     end
 
     it 'will return FormatNotSupported exception if source is not text' do
       expect do
-        read_commands('./test_data/test3.txt', 'file', 'json')
+        loader.read_commands('./test_data/test3.txt', 'file', 'json')
       end.to raise_error(Command::FormatNotSupported)
     end
   end

data/spec/spec_helper.rb

@@ -22,6 +22,9 @@ require_relative '../lib/helpers/command_helper'
 require_relative '../lib/helpers/command_parser_helper'
 require_relative '../lib/helpers/command_set_loader'
 require 'byebug'
+require 'simplecov'
+SimpleCov.start
+
 # require 'byebug'
 RSpec.configure do |config|
   # rspec-expectations config goes here. You can use an alternate

data/spec/toy_robot_controller_spec.rb

@@ -33,31 +33,24 @@ describe ToyRobotController do
         expect { controller.init(comamnds_stream) }.to raise_error(Command::InvalidCommandType)
       end
     end
-  end
-
-  describe '.execute_commands' do
     context 'when all commands are invalid' do
       it 'will raise NoValidCommandsFound exception' do
         comamnds_stream = ['RANDOM Command', 'adfadfadf', 'adfrtrett']
-        controller.init(comamnds_stream)
-        expect { controller.execute_commands }.to raise_error(Command::NoValidCommandsFound)
+        expect { controller.init(comamnds_stream) }.to raise_error(Command::NoValidCommandsFound)
       end
     end
 
     it 'will ignore all commands before PLACE' do
       controller.init(['MOVE', 'REPORT', 'PLACE 1,1,NORTH', 'MOVE', 'REPORT'])
-      controller.execute_commands
       expect(controller.commands.select { |c| c.status == 'ignored' }.size).to eq(2)
     end
 
     context 'when PLACE command is not provided' do
       it 'will raise PlaceCommandNotFound exception' do
-        controller.init(%w[MOVE MOVE LEFT MOVE REPORT])
-        expect { controller.execute_commands }.to raise_error(Command::PlaceCommandNotFound)
+        expect { controller.init(%w[MOVE MOVE LEFT MOVE REPORT]) }.to raise_error(Command::PlaceCommandNotFound)
       end
       it 'will raise PlaceCommandNotFound exception with a PLACE command without X,Y,Facing' do
-        controller.init(%w[PLACE MOVE MOVE LEFT MOVE REPORT])
-        expect { controller.execute_commands }.to raise_error(Command::PlaceCommandNotFound)
+        expect { controller.init(%w[PLACE MOVE MOVE LEFT MOVE REPORT]) }.to raise_error(Command::PlaceCommandNotFound)
       end
     end
   end
@@ -66,37 +59,27 @@ describe ToyRobotController do
     context 'when command sequence is PLACE 0,0,NORTH MOVE REPORT ' do
       it 'will move the robot to 0,1,NORTH' do
         controller.init(['PLACE 0,0,NORTH', 'MOVE', 'REPORT'])
-        controller.execute_commands
-        expect(controller.report).to eq('0,1,NORTH')
+        expect(controller.robot.report).to eq('0,1,NORTH')
       end
     end
 
     context 'when command sequence is PLACE 1,2,EAST MOVE MOVE LEFT MOVE REPORT' do
       it 'will move the robot to 3,3,NORTH' do
         controller.init(['PLACE 1,2,EAST', 'MOVE', 'MOVE', 'LEFT', 'MOVE', 'REPORT'])
-        controller.execute_commands
-        expect(controller.report).to eq('3,3,NORTH')
+        expect(controller.robot.report).to eq('3,3,NORTH')
       end
     end
     context 'when command sequence is PLACE 1,2,WEST MOVE MOVE LEFT MOVE REPORT' do
       it 'will move the robot to 0,1,SOUTH' do
         controller.init(['PLACE 1,2,WEST', 'MOVE', 'MOVE', 'LEFT', 'MOVE', 'REPORT'])
-        controller.execute_commands
-        expect(controller.report).to eq('0,1,SOUTH')
+        expect(controller.robot.report).to eq('0,1,SOUTH')
       end
     end
 
     context 'when command sequence contains only PLACE command' do
       it 'will report where the robot was PLACED' do
         controller.init(['PLACE 0,0,SOUTH'])
-        controller.execute_commands
-        expect(controller.report).to eq('0,0,SOUTH')
-      end
-    end
-    context 'when PLACE command is not provided' do
-      it 'will raise RobotIsNotPlaced exception' do
-        controller.init(%w[MOVE MOVE LEFT MOVE REPORT])
-        expect { controller.report }.to raise_error(ToyRobot::RobotIsNotPlaced)
+        expect(controller.robot.report).to eq('0,0,SOUTH')
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: toy-robot-simulator
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Salman Sohail