sortviz 0.5.3 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7e30b9e51cccc9c3a759b30c48bd2ea23770181b
-  data.tar.gz: 846ec151c0cbf34fd73d3eca5a125d18b7b40ef0
+  metadata.gz: 3a26d73bfed67f35fc0932b25232780f66317e86
+  data.tar.gz: 37bf5941624feb66a49d2bce915f7b30aa791103
 SHA512:
-  metadata.gz: 096d616309245732d9e35b263b89b883332fb56b6b28f5c06130b59ff4231a21f08234c42db951cd4ca48cba55b3ebdeb1e0b05aad0ce0666290b66d2bce70ae
-  data.tar.gz: 4dbc3f8bb250a8cebdd6e5d89024476274d3c485aca2eb9d718bafae4df4bb14917e48c79ef4420e9aa4611404e36cd493e2e7b125f8426fc0f4dafe1fdbf23f
+  metadata.gz: a450eaafc8aa96da572fbbafe76def7f3d85969cdb666aa0f60eccd5537be860ed41b43a05cbf6e79f42dea64db842001841860fa6e26fe6bdda9f9816ca2b79
+  data.tar.gz: 954c10988e7585ea53c4a58392bf0c8f42fd38e318358c99137485d258605acb75fd7bfb2fce87d62cb3fbad5ab1ffaf00f00f15979a9379f97b020950b4da75

data/README.md

@@ -1,27 +1,27 @@
 # Sortviz
 
-Sortviz is a sorting algorithm visualizer. But here's the rub, it's terminal
-based. You guessed it! This sweet little tool will visualize sorting algorithms
-for your viewing pleasures, it's written in Ruby and uses Curses for the terminal work.
+Sortviz is a small terminal program written in Ruby and uses the Curses library
+It lets you visualize sorting algorithms, you can add more sorting algorithms
+at will but for the time being it can only load the ones bundled with itself.
 
-It also has a rather over simplified plugin architecture, more like a ruby 
-trick than anything. You can write your own sorting code and have it visualize
-that for you. You just need to follow a general principle.
+For pointers on the over simplified (Quite bad too) plugin system, check 
+[lib/sortviz/plugins.rb](lib/sortviz/plugins.rb) and check the plugins at
+[lib/algorithms](lib/algorithms).
 
 ## Looks like this
-![alt text][screenshot]
+![Screenshot][screenshot]
 
 ## Working with Sortviz
 
 Some sorting algorithms operate on single lists, swapping and sifting through
-it. Others operate on multiple lists, like merge sort. With any luck, you
+them. Others operate on multiple lists, like merge sort. With any luck, you
 might be able to get these kind of sorting algorithms working but until I officially test against them, you're on your own.
 
 __Generally speaking, the sorting algorithm (your code) has to yield a partially sorted list, with a current index on *every iteration*__.
 
-For examples, check the `algorithms` folder. 
+For examples, check the [lib/algorithms](lib/algorithms) directory. 
 
-Some implementations like the bubble sort one at `algorithms/bubblesort.rb` generate some visual artifacts. 
+Some implementations like the bubble sort one at [lib/algorithms/bubblesort.rb](lib/algorithms/bubblesort.rb) generate some visual artifacts. 
 If you look at it, you'd notice that the index we're yielding is +1.
 
 The reason for that is because otherwise, Sortviz will be selecting a column
@@ -44,23 +44,16 @@ $ sortviz -h      # Will display help
 $ sortviz -l      # Will give you a list of available sorting algorithms
 $ sortviz -s ALGO # Will start visualizing the sorting of 20 digits using that algorithm
 ```
-
-__Notice: I haven't yet added the ability to load algorithms from a folder of your choosing, but its pretty much the same concept as of loading them from the `algorithms` folder__
-
 ## Development
-
-*I'm using RVM to manage my Ruby and Gemset environments for the development of this Gem. So if you too are doing the same, careful cause I've checked in the following files `.ruby-gemset` and `.ruby-version`. If you don't know what I'm talking about, ignore this.*
-
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/l0gicpath/sortviz. (This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct) I Awe there, bundler is really sweet, isn't it?
+Bug reports and pull requests are welcome on GitHub at https://github.com/l0gicpath/sortviz. Please read [Contributor Covenant](http://contributor-covenant.org) and kindly attempt to adhere to it.
 
-Seriously now, PRs are welcome, bug reports too but don't make me do your
-job for you. It's OSS, be reasonable.
+And don't make me do your job for you. It's OSS, be reasonable.
 
 ## Why
 
@@ -75,19 +68,15 @@ bummer looking over everything I worked in, so this is my solution.
 
 Am I proud of it? Well yes, could be way better but I'm pressed on time.
 
-## Future
+*I also realized the notion of being proud of something is more of a process, after you've invested time and effort into something and grew it, you can't help but feel proud of it.*
 
-When I started this, I wanted something that's easy to use to learn more
-about sorting. So I might actually expand on that and allow a way to 
-write sorting algorithms using pseudocode instead of Ruby.
+## Future
 
+I want this to be a teaching tool, so I'll be expanding this to support writing sorting code using pseudocode instead of Ruby.
 Should be a fun little language design exercise.
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
-I wouldn't know why wouldn't you like MIT license but just in case you don't, 
-don't ping me saying it sucks. Ping bundler, they make it absurdly easy not to
-think about licensing when creating a new Gem.
 
 [screenshot]: screenshot.png "Mac OSX Terminal.app xterm-256color"

data/exe/sortviz

@@ -1,5 +1,12 @@
 #! /usr/bin/env ruby
 
+# Sortviz is a small terminal program written in Ruby and uses the Curses library
+# It lets you visualize sorting algorithms
+#
+# Author::    Hady Ahmed  (mailto:me@hadyahmed.com)
+# Copyright:: Copyright (c) 2016
+# License::   Distributes under MIT
+
 require 'optparse'
 require "sortviz"
 

data/lib/algorithms/selectionsort.rb

@@ -11,7 +11,7 @@ module Sortviz
 
       # then swap it
       list[j], list[iMin] = list[iMin], list[j]
-      yield list, iMin
+      yield list, j
     end
   end
 

data/lib/sortviz/canvas.rb

@@ -1,68 +1,69 @@
 module Sortviz
+  # Canvas is the portion of the screen that contains the sorting bar charts.
+  # It displays the partially sorted list of numbers and redraws on every iteration
+  # marking the currently selected bar (current index in the partially sorted list)
   class Canvas
     extend Forwardable
-    def_delegators :@window, 
-      :refresh, :clear, 
-      :getch, :close, :attron, :attroff
-    def_delegators :@cursor, :tprint
-
-    CANVAS_HEIGHT = 20  # That's our drawing area
-    CANVAS_GUTTER = 50  # We subtract this value from Curses.cols
-    GUTTER = 5
-    GRAY_COLOR = 8
-
+    def_delegators :@window, :refresh, :getch, :close, :attron, :attroff
+    MARGIN = 5
     attr_reader :window
 
+    # Initializes a new instance with a title to display, the current cursor
+    # object (+Sortviz::Cursor+) and the modified screen dimensions from the
+    # parent window/screen (standard screen created in +Sortviz::Visualizer+)
     def initialize(title, cursor, screen_dim)
       @screen_dim = screen_dim
       @cursor = cursor
       @title = title
-      # Cache red since we'll use it to highlight later, best do it now
-      @red_highlighter = Curses.color_pair(Curses.const_get("COLOR_RED"))
-      @gray_highlighter = Curses.color_pair(GRAY_COLOR)
-      @window = nil
+      @red_highlight = Curses.color_pair(Curses.const_get("COLOR_RED"))
     end
 
+    # Does the initial setup of creating an actual curses window, adding a 
+    # border to it and setting up non-blocking +Curses::Window#getch+
     def setup
-      @window = Curses::Window.new(
-        @cursor.y + CANVAS_HEIGHT, 
-        @screen_dim[:cols] - CANVAS_GUTTER,
+      @window ||= Curses::Window.new(
+        @screen_dim[:lines] - MARGIN, 
+        @screen_dim[:cols] - MARGIN,
         @cursor.y, @cursor.x)
       @window.box('|', '-')
-      # Update our y-position to reflect the addition of canvas and its height
-      @cursor.incr_y CANVAS_HEIGHT + 4
       @window.nodelay = 1 # Non-blocking mode for #getch
     end
 
+    # Draws the partially sorted list and highlights the current index
+    # It also attempts to center the graph in the display area, does well but
+    # not always, sometimes it'll be shifted to the right a bit.
     def redraw(partially_sorted, selected_indx)
       @window.clear
       @window.box('|', '-')
+      
       @cursor.move(0, 0)
       @cursor.tprint("Algorithm: #{@title}")
-      @cursor.move(CANVAS_HEIGHT + 2, GUTTER)
-      partially_sorted.each_with_index do |n, i|
-        
-        attron(@gray_highlighter)
-        tprint(("|%02d|" % n))
-        attroff(@gray_highlighter)
 
-        @cursor.decr_y
+      len = partially_sorted.join.center(4).length
+      @cursor.move(@window.maxy - 1, (@window.maxx - len) / MARGIN)
+      
+      partially_sorted.each_with_index do |number, i|
+        @cursor.tprint(("|%02d|" % number))
 
+        @cursor.decr_y
 
-        attron(@red_highlighter) if selected_indx == i
-        draw_bar(n)
-        attroff(@red_highlighter)
+        draw_bar(number, selected_indx == i)
 
-        @cursor.move_y(CANVAS_HEIGHT + 2)
-        @cursor.incr_x GUTTER
+        @cursor.move_y(@window.maxy - 1)
+        @cursor.incr_x MARGIN
       end
     end
+
     private
-    def draw_bar(height)
+    
+    def draw_bar(height, highlighted)
+      attr = highlighted ? @red_highlight : Curses::A_REVERSE
+      attron(attr)
       height.times do
-        tprint("|_ |")
+        @window.addstr(" ".center(4)) # 4 spaces
         @cursor.decr_y
       end
+      attroff(attr)
     end
   end
 end

data/lib/sortviz/cursor.rb

@@ -13,10 +13,9 @@ module Sortviz
     # => y      (Int)
     # => x      (Int)
     # @return instance of Sortviz::Cursor
-    def initialize(window, y, x)
+    def initialize(window, origin)
       @window = window
-      @cached = nil
-      move(y, x)
+      move(origin[:y], origin[:x])
     end
 
     # Move to positions y, x

data/lib/sortviz/plugins.rb

@@ -2,6 +2,17 @@ module Sortviz
   extend self
   ALGORITHMS = {}
 
+  # Defines a new algorithm for sorting by adding some meta data to
+  # +Sortviz::ALGORITHMS+ and turning the sorting algorithm method into a
+  # Module function of +Sortviz+.
+  #
+  # It's a bad design, should be fixed soon with a proper plugin system as this
+  # way pollutes the Sortviz namespace.
+  # Params:
+  # +name+:: +String+ Name of the sorting algorithm for display purposes
+  # +func_name+:: +Symbol+ A symbol representation of the actual method that does
+  # the actual sorting. It's important that both match or else +Sortviz::Visualizer+
+  # will not be able to find it and call it.
   def define_algorithm(name, func_name)
     ALGORITHMS[func_name] = name
     module_function func_name

data/lib/sortviz/version.rb

@@ -1,3 +1,3 @@
 module Sortviz
-  VERSION = "0.5.3"
+  VERSION = "0.6.0"
 end

data/lib/sortviz/visualizer.rb

@@ -1,37 +1,67 @@
 module Sortviz
-  # Visualizer is the entry point of our Terminal UI. That's where all the juice
-  # happens. It initializes the curses library, visualizes sorting, 
-  # cleans up after we're done and controls the event loop.
+  # Visualizer is the entry point of Sortviz, given an algorithm name it'll
+  # initialize Curses library, a +Sortviz::Canvas+ with proper screen dimensions
+  # and a +Sortviz::Cursor+.
+  #
+  # It also generates a shuffled list of numbers counting from 1 to n, n is 
+  # decided by Sortviz::Visualizer#generate_list which calculates the number
+  # of bar charts that can be drawn given the current screen size.
+  #
+  # _Notice_: Curses coordinates are treated in reverse, (y, x) and x represents
+  # the number of columns, y represents the number of lines so
+  # *(y, x)* is *(cols, lines)*. As a result of that we too, use _(y, x)_.
   class Visualizer
-    extend Forwardable
-    def_delegators :@cursor, :tprint, :newline 
-    # All our rendering kicks off from these two values, consider them
-    # our origin point instead of (0, 0)
-    GUTTER = 5          # We don't want to flirt too much with the terminal border
-    TOP_MARGIN = 1      # Same issue with the top border
-    SLEEP_INTERVAL = 0.3
+    # Origin starts at (1, 0) not 
+    ORIGIN = { y: 1, x: 5 }
+    SLEEP_INTERVAL = 0.05
 
-    def initialize(unsorted_list, algo)
+    # Initializes a new Visualizer for a sorting algorithm
+    # Params:
+    # +algo+:: +Symbol+ A symbol representing a sorting algorithm method
+    def initialize(algo)
       setup_curses
-      # Cache our dimensions, helpful in calculations
-      @screen_dim = { cols: Curses.cols, lines: Curses.lines }
-      # Take Reference for Curses initial standard window
+      @screen_dim = { cols: Curses.cols - ORIGIN[:x], lines: Curses.lines }
       @screen     = Curses.stdscr
-      @cursor     = Cursor.new(@screen, TOP_MARGIN, GUTTER)
+      @cursor     = Cursor.new(@screen, ORIGIN)
       @canvas     = Canvas.new(ALGORITHMS[algo], @cursor, @screen_dim)
 
       @algo       = algo
-      @unsorted_list = unsorted_list
+      @unsorted_list = generate_list
     end
 
+    # Starts the actual visualization
+    # * First prints the program's banner
+    # * Sets up the canvas (+Sortviz::Canvas+)
+    # * Caches the cursor location so we can return to our original location later
+    # * Refreshes the current standard screen first
+    # * Refreshes the canvas
+    # * Finally we switch input to the canvas through +Sortviz::Cursor#switch_window+
+    #
+    # The order is important because curses works in such a way that the last
+    # thing on display is the last thing refreshed, if we had refreshed canvas
+    # first, it would have been drawn normally, then we refresh the standard
+    # screen (in which the canvas is inside) it'll do just that refreshs and overrides the canvas.
+    #
+    # === The loop
+    # In order to draw every returned partially sorted list from the algorithm method
+    # we have to loop, clearing the canvas everytime and redrawing it then telling
+    # Curses to apply these drawn updates. This helps with flicker but I still
+    # seem to be getting some of it ever since I introduced the +Curses::A_REVERSE+
+    # attribute.
+    #
+    # Durring the loop, we're trapped inside the sorting method, as a block of code
+    # that gets yielded to on every iteration of the sorting algorithm. To exit that
+    # at anytime during the sorting run, we capture the keyboard and return if any key is pressed,
+    # the canvas has +Curses::Window#getch+ on non-block mode so it doesn't block waiting for a character.
+    #
+    # Finally, we make sure both the canvas and the standard screen are closed.
+    # It's important to note that we also poll on keyboard after we exit the sorting method.
+    # In order to allow the user a moment to see the final sorted graph.
     def visualize
       begin
         banner
-        # NOTICE: :caveat: It's important to setup the canvas AFTER displaying
-        # the banner, so the canvas would correctly calculate its offsets
-        # based on the current cursor position, as in, after printing banner
         @canvas.setup
-        @cursor.cache # Cache our location before the visualization mess kicks in
+        @cursor.cache
 
         @screen.refresh
         @canvas.refresh
@@ -41,51 +71,52 @@ module Sortviz
         loop do
            Sortviz.send(@algo, @unsorted_list) do |partially_sorted, selected_indx|
             @canvas.redraw(partially_sorted, selected_indx)
-            update
-            return if @canvas.getch == 'q'
+            Curses.doupdate
+            sleep SLEEP_INTERVAL
+            return if @canvas.getch
            end
-          @canvas.close
-
           @cursor.switch_window @screen # Switch back to our stdscr
           @cursor.restore # Restoring here, would place us right under the canvas box
-          newline
-          tprint("Press 'q' to exit")
-          break if Curses.getch == 'q'
+          @cursor.newline
+          @cursor.tprint("Press any key to exit")
+          break if Curses.getch
         end
       ensure
+        @canvas.close
         Curses.close_screen
       end
     end
 
     private
-    def update
-      # doupdate is much more efficient than multiple refreshes
-      # and after some testing, it seems to clear out the flicker
-      # caused by multiple rapid calls to refresh
-      Curses.doupdate
-      sleep SLEEP_INTERVAL
-    end
-
     def setup_curses
       Curses.init_screen
-      Curses.noecho       # As soon as we prep the terminal screen, stop echo
-      Curses.nonl         # Line feeds and carriage return as well
+      Curses.noecho
       Curses.curs_set(0)        # Hide cursor
       Curses.start_color        # Kick off colored output
       Curses.use_default_colors
 
-      # We need Red and Gray
-      Curses.init_pair(Curses::COLOR_RED, Curses::COLOR_RED, -1)
-      Curses.init_pair(8, 235, -1)
+      # We only need Red
+      Curses.init_pair(Curses::COLOR_RED, -1, Curses::COLOR_RED)
+    end
+
+    # We want to know how much can we draw depending on the window size
+    # To do that, we know that a single bar takes up 4 columns '|00|'' (bar_len)
+    # We also know that we add 5 columns between bars (Canvas::MARGIN)
+    # So we take cols/bar_len + CANVAS::MARGIN = n_bars
+    def generate_list
+      n = @screen_dim[:cols] / (4 + Canvas::MARGIN)
+      (1..n).to_a.shuffle
     end
 
     def banner
-      tprint("-----------------------------------------------------------------")
-      newline
-      tprint("SortViz: Sorting Algorithms Visualization, Ruby & Curses - v#{VERSION}")
-      newline
-      tprint("-----------------------------------------------------------------")
-      newline
+      @cursor.tap do |c|
+        c.tprint("-----------------------------------------------------------------")
+        c.newline
+        c.tprint("SortViz: Sorting Algorithms Visualization, Ruby & Curses - v#{VERSION}")
+        c.newline
+        c.tprint("-----------------------------------------------------------------")
+        c.newline
+      end
     end
 
   end

data/lib/sortviz.rb

@@ -12,8 +12,7 @@ Dir[libdir + '/algorithms/*.rb'].each {|file| require file }
 module Sortviz
   extend self
   def init(algo)
-    unsorted_list = (1..20).to_a.shuffle
-    visualizer = Visualizer.new unsorted_list, algo
+    visualizer = Visualizer.new algo
     visualizer.visualize
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sortviz
 version: !ruby/object:Gem::Version
-  version: 0.5.3
+  version: 0.6.0
 platform: ruby
 authors:
 - Hady Ahmed
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-06-18 00:00:00.000000000 Z
+date: 2016-06-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler