edu_draw 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4e69b855005aad0caf28a5744f23ec795726ee46
-  data.tar.gz: 2fdf15c6ccc60044879e4da397b1958c6d9150bf
+  metadata.gz: fd768abe04a69ab7b6157dfff3bcad5bb051464b
+  data.tar.gz: cfa2a99ee7eb1320b237ce207dd8d4c595cf3247
 SHA512:
-  metadata.gz: aea2b517f916a19d104c936e492abb5c34cad4dc6a693ef6ed855b980df4c9351374df6b3a4212c4aa2770d81e2c4497284cda0b7c83a657d2071eb06a7fbb08
-  data.tar.gz: 9b1357680876556026150810b66eee8724cbd24b8109e6de090a415c9de3b95901c14a22ee575dd2fbc3b28d408e50a598240d28d471d532f77c0c6ba41fea88
+  metadata.gz: ffca39137a42964697fb9bf6fe8de51caae460af6022f8cb3f3d90775ffa1c58949225743e1a6162929bc2c590fd240a0aef1a5bcff34ba14da2c80489def5ef
+  data.tar.gz: 1847a9ed2b554d930c2eab0da09aab7abcdeb7e4fb76106492558a6e24e6bbc0f87ee572fbe7e5f6da4bfafdbc053e9f79c1a1eabe0705f0ea1aa29542845506

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 AKnopf
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+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.
+

data/README.md

@@ -0,0 +1,65 @@
+# edu_draw
+Simple ruby drawing API based on gosu meant for educational purposes.
+
+## Install
+`gem install edu_draw`
+
+If you run into any problems its most likely because of [gosu](https://github.com/jlnr/gosu/wiki/Ruby-Tutorial), as this is the only runtime dependency of edu_draw.
+
+## Usage
+There are only two classes: A sheet to draw on and a pen to draw with. The sheet is also the window. Unfortunately, the underlying engine only supports really one window, so you should only create one sheet per program. This is done as follows:
+First, load edu_draw into your program
+
+`require "edu_draw"`
+
+Then, create the sheet
+
+`sheet = EduDraw::Sheet.new x: 500, y: 600, title: "It works"`
+
+Now that you have a sheet, that is 500 pixels wide and 600 pixels high, you can create pens for this sheet to draw on.
+
+`green_pen = sheet.new_pen x: 100, y: 20`
+
+Green is the default color for pens but you can have any color using the `color` parameter.
+
+Now it's time to draw a rectangle!
+
+```
+green_pen.move 100
+green_pen.turn_right 90
+green_pen.move 80
+green_pen.turn_right 90
+green_pen.move 100
+green_pen.turn_right 90
+green_pen.move 80
+```
+
+
+When you are done drawing, you have to make one final call to the sheet, to actually display the window with your drawings.
+
+`sheet.show`
+
+The whole program looks like this:
+
+```
+require "edu_draw"
+
+sheet = EduDraw::Sheet.new x: 500, y: 600, title: "It works"
+green_pen = sheet.new_pen(x: 100, y: 20)
+
+green_pen.move 100
+green_pen.turn_right 90
+green_pen.move 80
+green_pen.turn_right 90
+green_pen.move 100
+green_pen.turn_right 90
+green_pen.move 80
+
+sheet.show
+```
+
+## Contributing
+Feel free to contribute anything, may it be better tests, better documentation or more features. As you can see, I tried to keep the code tidy so it is appreciated if you'd do the same. Just add a pull request and we will make it work. Oh, and don't forget to have fun ;)
+
+## Kudos
+Kudos to the wonderful people behind [Gosu](http://www.libgosu.org/). You do some great work.

data/Rakefile

@@ -0,0 +1,7 @@
+require 'rake/testtask'
+
+task default: :test
+
+Rake::TestTask.new do |t|
+  t.pattern = "test/**/*_test.rb"
+end

data/{example.rb → examples/lines.rb}

@@ -1,21 +1,29 @@
-require_relative 'edu_draw'
+require "edu_draw"
 
+# Create a new Sheet. That's your window.
 sheet = EduDraw::Sheet.new x: 500, y: 600, title: "It works"
+
+# Create a new pen for this sheet at the position 100 pixel from the left and 20 pixel from the top
 pen = sheet.new_pen(x: 100, y: 20)
+
+# Draw a decagon
 10.times do
 	pen.move 40
 	pen.turn_right 36
 end
 
+# Move to the right without drawing a line
 pen.up!
 pen.move 150
 pen.down!
 
-10.times do
+# Draw a octagon
+8.times do
 	pen.move 40
-	pen.turn_right 36
+	pen.turn_right 45
 end
 
+# Move to the middle bottom of the sheet without drawing lines
 pen.up!
 pen.move -55
 pen.turn_right 90
@@ -24,6 +32,7 @@ pen.turn_left 180
 pen.down!
 pen.move 10
 
+# Define how to draw a tree recursively
 def draw_tree(pen, length)
 	angle = 20
 	min_length = 4
@@ -38,9 +47,13 @@ def draw_tree(pen, length)
 	pen.move -length
 end
 
+# Draw 8 trees in a circle
 8.times do
 	draw_tree pen, 40
 	pen.turn_left 45
 end
 
-sheet.show
+# After all drawing is done, #show has to be called on the window to actually display everything
+sheet.show
+
+# Press Escape to close the window again

data/lib/edu_draw/pen.rb

@@ -1,12 +1,25 @@
 module EduDraw
-	# A Pen is a drawing tool that provides basic drawing functionalities on a 2d sheet.
-	# It has a certain position (x,y) in pixel where (0,0) is the top-left corner.
-	# It has an angel in degree, where 0 points to the right.
-	# It also has a certain color in which it draws.
+	# A Pen is a drawing tool that provides basic drawing functionalities on a 2d {Sheet}.
 	class Pen
 
-		attr_reader :x, :y, :angle, :color
+		# @return [Fixnum] x-coordinate of position in pixel where left is 0
+		attr_reader :x
 
+		# @return [Fixnum] y-coordinate of position in pixel where top is 0
+		attr_reader :y
+
+		# @return [Fixnum] Direction of the pen in degree where 0 points to the right
+		attr_reader :angle
+
+		# @return [Gosu::Color] Color of the pen
+		attr_reader :color
+
+		# Creates a new Sheet
+		#
+		# @param x [Fixnum] initial value of {#x}
+		# @param y [Fixnum] initial value of {#y}
+		# @param angle [Fixnum] initial value of {#angle}
+		# @param color [Gosu::Color] initial value of {#color}
 		def initialize(sheet, x: 0, y: 0, angle: 0, color: Gosu::Color::GREEN)
 			@x = x
 			@y = y
@@ -17,30 +30,53 @@ module EduDraw
 			down!
 		end
 
+		# Changes the direction of self to be turned to the left
+		# The {#angle} stays within 0..364
+		#
+		# @param degree [Fixnum] Amount of degree to be turned
 		def turn_left(degree)
 			@angle -= degree
+			@angle = (@angle + 360) % 360 # Make sure angle is always in 0..359
 		end
 
+		# Changes the direction of self to be turned to the right
+		# The {#angle} stays within 0..364
+		#
+		# @param degree [Fixnum] Amount of degree to be turned
 		def turn_right(degree)
 			turn_left -degree
 		end
 
+		# If the pen is up, it does not touch the {Sheet} and is not drawing. It can still be moved.
 		def up?
 			@up
 		end
 
+		# If the pen is up, it touches the {Sheet} and is drawing when moved.
 		def down?
 			!up?
 		end
 
+		# Lifts the pen from the {Sheet}
+		#
+		# @see {#up?}
+		# @see {#down?}
 		def up!
 			@up = true
 		end
 
+		# Sticks the pen to the {Sheet}
+		#
+		# @see {#up?}
+		# @see {#down?}
 		def down!
 			@up = false
 		end
 
+		# Moves the stick an amount of pixel into its direction.
+		# Draws when it is {#down?}
+		#
+		# @param length [Fixnum] Amount of pixels moved
 		def move(length)
 			target_x = x + Math.cos(angle_in_rad) * length
 			target_y = y + Math.sin(angle_in_rad) * length
@@ -51,6 +87,7 @@ module EduDraw
 			@y = target_y
 		end
 
+		# @return [Fixnum] angle in radians instead of degree
 		def angle_in_rad
 			angle * Math::PI / 180.0
 		end

data/lib/edu_draw/sheet.rb

@@ -1,17 +1,39 @@
 module EduDraw
-	# A Sheet is a 2D-Canvas that can be drawn on using Pen
+	# A Sheet is a 2D-Canvas that can be drawn on using {Pen}
 	class Sheet < Gosu::Window
+
+		# @private
 		attr_reader :shapes
+
+		# Creates a new Sheet
+		#
+		# @param x [Fixnum] width in pixels
+		# @param y [Fixnum] height in pixels
+		# @param title [String] Caption of the window
 		def initialize(x: 100, y: 100, title: "A blank sheet")
 			super x, y, false
 			self.caption = title
 			@shapes = []
 		end
 
+		# @private
+		def needs_cursor?
+			true
+		end
+
+		# Creates a new {Pen} that draws on self
+		#
+		# @see {Pen}
+		#
+		# @param x [Fixnum] x-coordinate of starting position. Left is 0.
+		# @param y [Fixnum] y-coordinate of starting position. Top is 0.
+		# @param angle [Fixnum] Direction of pen in degree. 0 points to the right.
+		# @param color [Gosu::Color] Color of the pen
 		def new_pen(x: 0, y: 0, angle: 0, color: Gosu::Color::GREEN)
 			Pen.new(self, x: x, y: y, angle: angle, color: color)
 		end
 
+		# @private
 		def draw
 			shapes.each do |shape|
 				method,*args = shape
@@ -19,6 +41,7 @@ module EduDraw
 			end
 		end
 
+		# @private
 		def update
 			if button_down? Gosu::KbEscape
 				close

data/test/edu_draw/pen_test.rb

@@ -0,0 +1,62 @@
+require_relative "../test_helper"
+module EduDraw
+	class PenTest < Minitest::Unit::TestCase
+		def setup
+			@sheet_stub = stub shapes: []
+			@pen = Pen.new(@sheet_stub, x: 10, y: 20, angle: 25, color: Gosu::Color::BLACK)
+		end
+
+		def test_initialize
+			assert_equal 10, @pen.x
+			assert_equal 20, @pen.y
+			assert_equal 25, @pen.angle
+			assert_equal Gosu::Color::BLACK, @pen.color
+		end
+
+		def test_move
+			@pen.move 100
+			expected_x = 10 + Math.cos(25 * Math::PI / 180.0) * 100
+			expected_y = 20 + Math.sin(25 * Math::PI / 180.0) * 100
+			assert_equal expected_x, @pen.x 						# x changed
+			assert_equal expected_y, @pen.y 						# y changed
+			assert_equal 25, @pen.angle 							  # angle unchanged
+			assert_equal Gosu::Color::BLACK, @pen.color # color unchanged
+		end
+
+		def test_doesnt_draws_when_up
+			@sheet_stub.expects(:shapes).times(0)
+			@pen.up!
+			@pen.move 100
+		end
+
+		def test_up_and_down
+			assert @pen.down?
+			refute @pen.up?
+
+			@pen.up!
+			assert @pen.up?
+			refute @pen.down?
+
+			@pen.down!
+			assert @pen.down?
+			refute @pen.up?
+		end
+
+		def test_turning
+			assert_equal 25, @pen.angle
+
+			@pen.turn_left 25
+			assert_equal 0, @pen.angle
+
+			@pen.turn_left 10
+			assert_equal 350, @pen.angle
+
+			@pen.turn_right 20
+			assert_equal 10, @pen.angle
+		end
+
+		def test_angle_in_rad
+			assert_equal 25 * Math::PI / 180.0, @pen.angle_in_rad
+		end
+	end
+end

data/test/edu_draw/sheet_test.rb

@@ -0,0 +1,33 @@
+require_relative "../test_helper"
+module EduDraw
+	class SheetTest < Minitest::Unit::TestCase
+		def setup
+			@sheet = Sheet.new(x: 10, y: 20, title: "test")
+		end
+
+		def test_initialize
+			assert_equal 10, @sheet.width
+			assert_equal 20, @sheet.height
+			assert_equal "test", @sheet.caption
+		end
+
+		def test_cursor_visible
+			assert @sheet.needs_cursor?
+		end
+
+		def test_window
+			assert_kind_of Gosu::Window, @sheet
+		end
+
+		def test_new_pen_creates_pen
+			assert_respond_to @sheet, :new_pen
+			assert_kind_of Pen, @sheet.new_pen
+		end
+
+		def test_new_pen_creates_new_instance
+			Pen.expects(:new).once
+			@sheet.new_pen
+		end
+
+	end
+end

data/test/test_helper.rb

@@ -0,0 +1,5 @@
+require "minitest/autorun"
+require "minitest/mock"
+require "mocha"
+require "mocha/mini_test"
+require_relative "../lib/edu_draw"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: edu_draw
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Marvin Ede
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
 description: Simple object oriented API for opening a window and drawing in it. Based
   on gosu. It's meant to teach beginners programming as a visualization of code can
   help.
@@ -32,11 +46,17 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- example.rb
+- LICENSE
+- README.md
+- Rakefile
+- examples/lines.rb
 - lib/edu_draw.rb
 - lib/edu_draw/pen.rb
 - lib/edu_draw/sheet.rb
-homepage: http://rubygems.org/gems/edu_draw
+- test/edu_draw/pen_test.rb
+- test/edu_draw/sheet_test.rb
+- test/test_helper.rb
+homepage: https://github.com/AKnopf/edu_draw
 licenses:
 - MIT
 metadata: {}
@@ -61,3 +81,4 @@ signing_key:
 specification_version: 4
 summary: Offers a simple API to open a window and draw in it
 test_files: []
+has_rdoc: