ppp 0.1.6.alpha → 1.0.0

data/lib/ppp.rb

@@ -17,6 +17,7 @@ module Ppp
       Generator.new key, opts
     end
 
+    # @param [String] str some string to create a SHA-256 digest of
     # @return a SHA-256 digest of the given string
     def key_from_string str
       Digest::SHA256.new.update( str ).to_s
@@ -27,8 +28,11 @@ module Ppp
       Cppp.random_key
     end
 
-    def printer style, *args
-      case style
+    # @param [Symbol] type the type of card to return
+    # @param [Array] args parameters to pass to the card's constructor
+    # @return a +Card+ of the given type
+    def card type, *args
+      case type
       when :html  then return Card::Html.new  *args
       when :xml   then return Card::Xml.new   *args
       when :plain then return Card::Plain.new *args
@@ -36,6 +40,7 @@ module Ppp
       raise ArgumentError.new( "%s is not a valid printer style." % style )
     end
 
+   # @return [Hash{Symbol => String}] the default alphabets
     def default_alphabets
       @@ALPHABETS
     end

data/lib/ppp/card/base.rb

@@ -2,6 +2,7 @@ require 'ppp/generator'
 
 module Ppp
   module Card
+    # @abstract Subclass and override {#to_s} to implement a custom Card class.
     class Base
       attr_reader :card_number, :row_count, :title
 
@@ -13,6 +14,11 @@ module Ppp
       @@ERROR_LONG_CODES     = %[Passcodes longer than 16 characters are too long for printing]
       @@ERROR_WRONG_NUM_ARGS = %[Wrong number of arguments. Expected %s, got %d]
 
+      # @param [Generator] generator the generator this card will get passcodes from
+      # @param [Hash] opts options to create the card with
+      # @option opts [Fixnum] :row_count (10) the number of rows in the card
+      # @option opts [String] :card_title ('PPP Passcard') the title of the card
+      # @option opts [Fixnum] :first_card_number (1) the number of the first card to create
       def initialize generator, opts={}
         @generator = generator
         raise ArgumentError.new( @@ERROR_LONG_CODES ) if code_length > 16
@@ -26,23 +32,31 @@ module Ppp
         @card_number = options[ :first_card_number ]
       end
 
+      # @return [Fixnum] the number of characters in each passcode in the card
       def code_length
         @generator.length
       end
 
+      # @param [Fixnum] number the new card number. Must be +1+ or more. The card number determines which passcodes
+      #   will be printed on the card. For example, if the card has 10 rows, and each row has five passcodes, then
+      #   Card #1 will retrieve passcodes 0-49 from the generator. If +card_number == 2+, then passcodes 50-99 will
+      #   be printed from the generator.
       def card_number= number
         raise ArgumentError.new( "card number must be a positive integer" ) if number < 1
         @card_number = number
       end
 
+      # @return [Fixnum] the number of passcodes to be printed on each line
       def passcodes_per_line
         @passcodes_per_line ||= ( (@@CHARS_PER_LINE+1) / (code_length + 1) ).to_i
       end
 
+      # @return [Fixnum] the number of passcodes to be printed on the card
       def passcodes_per_card
         passcodes_per_line * row_count
       end
 
+      # @return [Array(Array(String))] the passcodes on the current card
       def codes
         (1..row_count).collect do |row|
           offset = card_offset + ((row-1) * passcodes_per_line)
@@ -51,6 +65,13 @@ module Ppp
         end
       end
 
+      # @overload passcode(cell)
+      #   @return [String] the passcode in the given cell
+      #   @param [String] cell A cell ID. example: +10B+
+      # @overload passcode(row, column)
+      #   @return [String] the passcode in the given row and column
+      #   @param [Fixnum] row the row of the passcode to return
+      #   @param [String] column the column of the passcode to return
       def passcode *args
         case args.size
         when 1
@@ -72,21 +93,37 @@ module Ppp
         @generator.passcode offset
       end
 
+      # @overload verify(cell, given_passcode)
+      #   @return [Boolean] +true+ if the given passcode matches the passcode in the given cell
+      #   @param [String] cell A cell ID. example: +10B+
+      #   @param [String] given_passcode the passcode to verify
+      # @overload verify(row, column, given_passcode)
+      #   @return [Boolean] +true+ if the given passcode matches the passcode in the given row and column
+      #   @param [Fixnum] row the row of the passcode to return
+      #   @param [String] column the column of the passcode to return
+      #   @param [String] given_passcode the passcode to verify
       def verify *args
         given_code = args.pop
         given_code == passcode( *args )
       end
 
-      def row_label row_number
-        "#{row_number + 1}:"
+      def to_s
+        raise "unimplemented"
+      end
+
+      protected
+
+      def row_label row_index
+        "#{row_index + 1}:"
       end
 
       def column_label column_number
         (@@FIRST_COLUMN.ord + (column_number - 1)).chr
       end
-  
-      protected
-  
+
+      # @return [Fixnum] the offset of passcodes to request from the generator for the given card. For example, if this
+      #   card contains 50 passcodes, and we are currently on card 3, we want to request passcodes 100-149 from the
+      #   generator.
       def card_offset
         (card_number-1) * passcodes_per_card
       end

data/lib/ppp/card/plain.rb

@@ -15,35 +15,37 @@ class Ppp::Card::Plain < Ppp::Card::Base
     line( split_bar )
   end
 
-  def card_number= number
-    super
-  end
-
   private
 
+  # @return [String] a horizontal rule
   def bar
     '-' * (width + 2)
   end
 
+  # @return [Fixnum] the width of the table
   def width
     return rows.first.join( ' ' ).size if rows.size >= 1
     header.size
   end
 
+  # @return [Array(Array(String))] The cells of the table, with the first column containing the row labels
   def rows
     codes.each_with_index.collect { |row, i| [ first_column( i ) ] + row }
   end
 
+  # @return [String] the column labels
   def header
     header_cells.join ' '
   end
 
+  # @return [Array(String)] a list of the column headers
   def header_cells
     cells = passcodes_per_line.times.collect { |i| column_label(i+1).center code_length }
 
     [' ' * first_column_width ] + cells
   end
 
+  # @return [String] a line containing the title and card number
   def title_str
     title = @title[0, width - card_label.size] # trim title if it's too long to fit
 
@@ -51,31 +53,40 @@ class Ppp::Card::Plain < Ppp::Card::Base
     title = title + (' ' * blank_space) + card_label
   end
 
+  # @return [String] a label containing the card number
   def card_label
     "[#{card_number}]"
   end
 
+  # @return [String] a horizontal rule with notches in it to deliniate the columns
   def split_bar
     parts = ['-' * first_column_width] + (1..passcodes_per_line).collect { '-' * code_length }
     "-#{parts.join '+'}-"
   end
 
+  # @return [Array(String)] a list of rows, each element containing the string of passcodes for that rows
   def row_lines
     rows.collect{ |r| line :pad, r.join( ' ' ) }
   end
 
+  # @return [String] a line with the table's left and right border
+  # @param [String] str the content of the line
+  # @param [Symbol] +:pad+ if borders should have a one-space padding
   def line pad=:nopad, str
     return "| #{str} |\n" if pad == :pad
 
     "|#{str}|\n"
   end
 
+  # @return [String] the content of the first cell of the given row. The row's label
+  # @param [Fixnum] The index of the given row.
   def first_column row_index
     label = row_label row_index
     padding = ' ' * (first_column_width - label.size)
     padding + label
   end
 
+  # @return [Fixnum] the required number of characters needed to fit the row label of each row
   def first_column_width
     @row_count.to_s.size + 1
   end

data/lib/ppp/generator.rb

@@ -8,10 +8,10 @@ class Ppp::Generator
 
   # @param [String] sha256_key a 64 hex-digit string representation of a
   #   SHA-256 hash. This hash will seed all the generated passcodes.
-  # @param [Fixnum] length the number of characters in each generated passcode
-  # @param [String] alphabet a string containing the characters passcodes will
-  #   be comprised of. Cannot contain null characters and duplicate characters
-  #   will be removed.
+  # @param [Hash] opts the options to create the generator with.
+  # @option opts [Fixnum] :length (4) the number of characters in each generated passcode
+  # @option opts [String] :alphabet (:conservative) a string containing the characters passcodes will
+  #   be comprised of. Cannot contain null characters and duplicate characters will be removed.
   def initialize sha256_key, opts={}
     raise NotHexKey.new( sha256_key ) if @@HEX_PATTERN.match( sha256_key ).nil?
 

data/lib/ppp/version.rb

@@ -1,3 +1,3 @@
 module Ppp
-  VERSION = '0.1.6.alpha'
+  VERSION = '1.0.0'
 end

metadata

@@ -1,8 +1,8 @@
 --- !ruby/object:Gem::Specification
 name: ppp
 version: !ruby/object:Gem::Version
-  version: 0.1.6.alpha
-  prerelease: 6
+  version: 1.0.0
+  prerelease: 
 platform: ruby
 authors:
 - Jon Sangster
@@ -52,9 +52,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>'
+  - - ! '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: ppp
 rubygems_version: 1.8.15
@@ -63,3 +63,4 @@ specification_version: 3
 summary: Ruby bindings for John Graham-Cumming's implementation of GRC's Perfect Paper
   Passwords
 test_files: []
+has_rdoc: