acrosslite 0.2.0

data/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2010 Samuel Mullen
+ 
+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.rdoc

@@ -0,0 +1,88 @@
+= Acrosslite
+
+http://github.com/samullen/acrosslite
+
+A Ruby library for parsing Across Lite crossword puzzle (.puz) files.
+
+The Across Lite format is probably the most popular format for encoding
+crossword puzzles. This library in its current incarnation provides a means for
+retrieving the encoded crossword information from that format. In the future I
+may take a go at building an encoder, but there are some legal issues around
+doing such.
+
+For more information about acrosslite, go to http://litsoft.com.
+
+== Installation
+
+The acrosslite gem is hosted on RubyGems (http://rubygems.org).
+
+== Getting Started
+
+Instantiation of the library can be done in one of two ways: 1) passing in the full path to a file; 2) by passing in the puzzle blob.
+
+  require 'acrosslite'
+
+  ac = Acrosslite.new(:filepath => "/path/to/the/puzzle/file.puz")
+
+    -- Or --
+
+  blob = open("/path/to/the/puzzle/file.puz", "r").read
+  ac = Acrosslite.new(:content => blob)
+  
+Useful information about the puzzle can be retrieved with a handful of method
+calls.
+
+=== Puzzle Meta
+
+  ac.title         # -> Title of the puzzle
+  ac.author        # -> Author of the puzzle
+  ac.copyright     # -> Puzzle Copyright
+
+=== Puzzle Content
+
+  ac.diagram       # -> two-dimensional matrix of the diagram 
+  ac.solution      # -> two-dimensional matrix of the solution
+
+  ac.rows          # -> Array of Acrosslite::Entry objects
+  ac.columns       # -> Array of Acrosslite::Entry objects
+
+Acrosslite::Entry objects are broken down thusly:
+
+  ac.direction - The direction the answer goes (across, down)
+  ac.clue - The clue to provide an answer for
+  ac.clue_number - Clue number represented by the little number in a crossword cell
+  ac.row - What row the answer begins on (zero-based).
+  ac.column - What column the answer begins on (zero-based).
+  ac.length - The length of the answer
+  ac.cell_number - The "physical" cell the answer begins on
+  ac.answer - The answer
+
+== Other
+
+  US Crossword Rules: 
+  http://www.maa.org/editorial/mathgames/mathgames_05_10_04.html
+
+  The rules for American crosswords are as follows:
+
+  1. The pattern of black-and-white squares must be symmetrical.  Generally this rule means that if you turn the grid upside-down, the pattern will look the same as it does right-side-up.
+  2. Do not use too many black squares.  In the old days of puzzles, black squares were not allowed to occupy more than 16% of a grid.  Nowadays there is no strict limit, in order to allow maximum flexibility for the placement of theme entries.  Still, "cheater" black squares (ones that do not affect the number of words in the puzzle, but are added to make constructing easier) should be kept to a minimum, and large clumps of black squares anywhere in a grid are strongly discouraged.
+  3. Do not use unkeyed letters (letters that appear in only one word across or down).  In fairness to solvers, every letter has to be appear in both an Across and a Down word.
+  4. Do not use two-letter words.  The minimum word length is three letters.
+  5. The grid must have all-over interlock.  In other words, the black squares may not cut the grid up into separate pieces.  A solver, theoretically, should be able to able to proceed from any section of the grid to any other without having to stop and start over.
+  6. Long theme entries must be symmetrically placed.  If there is a major theme entry three rows down from the top of the grid, for instance, then there must be another theme entry in the same position three rows up from the bottom.  Also, as a general rule, no nontheme entry should be longer than any theme entry.
+  7. Do not repeat words in the grid.
+  8. Do not make up words and phrases.  Every answer must have a reference or else be in common use in everyday speech or writing.
+  9. (Modern rule) The vocabulary in a crossword must be lively and have very little obscurity.
+
+== Acknowledgements
+
+* Doug Sparling who created the perl Convert-AcrossLite library (http://cpansearch.perl.org/src/DSPARLING/Convert-AcrossLite-0.10/README). I also credit him with getting me into Ruby and getting me excited about programming again.
+* Bob Newell (http://www.gtoal.com/wordgames/gene/AcrossLite) who originally decyphered  the Acrosslite format to begin with.
+
+== Author
+
+Samuel Mullen <samullen@gmail.com>
+
+== Copyright
+
+Copyright(c) 2010 Samuel Mullen (samullen). See LICENSE for details

data/Rakefile

@@ -0,0 +1,56 @@
+$:.unshift File.expand_path("../lib", __FILE__)
+
+require 'rubygems'
+require 'rake/gempackagetask'
+require 'acrosslite'
+ 
+lib_dir = File.expand_path('lib')
+spec_dir = File.expand_path('spec')
+
+gem_spec = Gem::Specification.new do |s|
+  s.name = "acrosslite"
+  s.version = Acrosslite::VERSION
+  s.authors = ["Samuel Mullen"]
+  s.email = "samullen@gmail.com"
+  s.homepage = "http://github.com/samullen/acrosslite"
+  s.summary = "A Ruby library for parsing Across Lite puzzle (.puz) files"
+  s.description = false
+  s.test_files = Dir['spec/**/*']
+  s.add_development_dependency "rspec"
+  s.files = [
+    "LICENSE",
+    "README.rdoc",
+    "Rakefile",
+    "lib/acrosslite.rb",
+    "lib/entry.rb"
+  ] + s.test_files
+end
+
+begin
+  require 'spec/rake/spectask'
+rescue LoadError
+  task :spec do
+    $stderr.puts '`gem install rspec` to run specs'
+  end
+else
+  desc "Run specs"
+  Spec::Rake::SpecTask.new do |t|
+    t.spec_files = Dir['spec/**/*.rb']
+    t.spec_opts  = %w(-fs --color)
+  end
+end
+
+Rake::GemPackageTask.new(gem_spec) do |pkg|
+  pkg.need_zip = false
+  pkg.need_tar = false
+end
+
+desc "Install the gem locally"
+task :install => [:spec, :gem] do
+  sh %{gem install pkg/#{gem_spec.name}-#{gem_spec.version}}
+end
+
+desc "Remove the pkg directory and all of its contents."
+task :clean => :clobber_package
+
+task :default => [:spec, :gem]

data/lib/acrosslite.rb

@@ -0,0 +1,263 @@
+require 'stringio'
+
+require File.join(File.dirname(__FILE__), 'entry')
+
+class Acrosslite
+  attr_reader :across, :down, :solution, :diagram, :copyright, :title, :author,
+              :filepath
+
+  VERSION = '0.2.0'
+
+  ACROSSLITE = 2
+  ROWS       = 44
+  COLUMNS    = 45
+  SOLUTION   = 52
+
+  DEFAULT_OPTIONS = {
+    :filepath => nil,
+    :content  => nil,
+  }
+
+  def initialize(*args)
+    opts = {}
+
+    case
+    when args.length == 0 then
+    when args.length == 1 && args[0].class == Hash then
+      arg = args.shift
+
+      if arg.class == Hash
+        opts = arg
+      end
+    else
+      raise ArgumentError, "new() expects hash or hashref as argument"
+    end
+
+    opts = DEFAULT_OPTIONS.merge opts
+
+    @filepath   = opts[:filepath]
+    @content    = opts[:content] || content
+
+    @content_io = StringIO.new @content
+
+    @across     = Array.new
+    @down       = Array.new
+    @layout     = Array.new
+    @solution   = Array.new
+    @diagram    = Array.new
+  end
+
+  def content
+    @content ||= read_puzzle
+  end
+
+  def rows
+    unless @rows 
+      @content_io.seek(ROWS)
+      @rows = @content_io.read(1).unpack('C').first
+    end
+    @rows
+  end
+
+  def columns
+    unless @columns 
+      @content_io.seek(COLUMNS)
+      @columns = @content_io.read(1).unpack('C').first
+    end
+    @columns
+  end
+
+  def solution
+    width = columns
+
+#     if @solution.empty?
+    unless @solution.size == rows
+      @content_io.seek(SOLUTION)
+
+      rows.times do |r|
+        @solution << @content_io.read(width).unpack("C#{width}").map {|c| c.chr}
+      end
+    end
+    @solution
+  end
+
+  def diagram
+    width = columns
+
+    if @diagram.empty?
+      @content_io.seek(SOLUTION + rows * width)
+
+      rows.times do |r|
+        @diagram << @content_io.read(width).unpack("C#{width}").map {|c| c.chr}
+      end
+    end
+    @diagram
+  end
+
+  def area
+    rows * columns
+  end
+
+  def across
+    if @across.empty?
+      parse
+    end
+
+    @across
+  end
+
+  def down
+    if @down.empty?
+      parse
+    end
+
+    @down
+  end
+
+  def title
+    unless @title
+      parse
+    end
+
+    @title
+  end
+
+  def author
+    unless @author
+      parse
+    end
+
+    @author
+  end
+
+  def copyright
+    unless @copyright
+      parse
+    end
+
+    @copyright
+  end
+
+=begin rdoc
+If a filehandle or filepath were provided, open reads in the file's contents
+into the content attribute which is then used for parsing.
+
+open must be called prior to parsing if content has not already been provided.
+
+=end
+def read_puzzle(filepath=nil)
+  filepath ||= @filepath
+  raise unless filepath
+	@content = open(@filepath).read
+end
+
+private
+
+=begin rdoc
+=end
+def next_field
+	string = String.new
+
+	while (c = @content_io.getc.chr) != "\0"
+		string += c
+	end
+
+	return string
+end
+
+def content_io
+  @content_io ||= StringIO.new @content
+end
+
+=begin rdoc
+The parse method takes the puzzle loaded into content and breaks it out into the
+following attributes: rows, columns, solution, diagram, title, author, copyright, across, and down.
+=end
+
+  def parse
+    clues = Array.new
+
+    @content_io.seek(SOLUTION + area + area)
+
+    @title = next_field
+    @author = next_field
+    @copyright = next_field
+
+    #----- build clues array -----#
+    until @content_io.eof? do
+      clues << next_field
+    end
+
+    #----- determine answers -----#
+    across_clue = down_clue = 1 # clue_number: incremented only in "down" area
+
+    0.upto(rows - 1) do |r|
+      0.upto(columns - 1) do |c|
+        next if solution[r][c] =~ /[.:]/
+
+        if c - 1 < 0 || solution[r][c - 1] == "."
+          entry = Acrosslite::Entry.new
+          answer = ''
+
+          c.upto(columns - 1) do |cc|
+            char = solution[r][cc]
+
+            if char != '.'
+              answer += char
+            end
+
+            if char == "." || cc + 1 >= columns
+              entry.direction   = "across"
+              entry.clue        = clues.shift
+              entry.answer      = answer
+              entry.clue_number = across_clue
+              entry.row         = r
+              entry.column      = c
+              entry.length      = answer.size
+              entry.cell_number = r * columns + c + 1
+
+              @across << entry
+              across_clue += 1
+              break
+            end
+          end
+        end
+
+        if r - 1 < 0 || solution[r - 1][c] == "."
+          entry = Acrosslite::Entry.new
+          answer = ''
+
+          r.upto(rows - 1) do |rr|
+            char = solution[rr][c]
+
+            if char != '.'
+              answer += char
+            end
+
+            if char == "." || rr + 1 >= rows
+              entry.direction   = "down"
+              entry.clue        = clues.shift
+              entry.answer      = answer
+              entry.clue_number = down_clue
+              entry.row         = r
+              entry.column      = c
+              entry.length      = answer.size
+              entry.cell_number = r * columns + c + 1
+
+              @down << entry
+              down_clue += 1
+              break
+            end
+          end
+        end
+
+        if across_clue > down_clue
+          down_clue = across_clue
+        else
+          across_clue = down_clue
+        end
+      end
+    end
+  end
+
+end

data/lib/entry.rb

@@ -0,0 +1,9 @@
+class Acrosslite
+  class Entry
+    attr_accessor :direction, :clue, :clue_number, :row, :column, :length, 
+                  :cell_number, :answer
+
+    def initialize
+    end
+  end
+end

data/spec/acrosslite_spec.rb

@@ -0,0 +1,102 @@
+require File.join(File.dirname(__FILE__), '..', 'lib','acrosslite')
+
+describe Acrosslite do
+  before(:all) do
+    basedir        = File.dirname(__FILE__)
+    @example_files = Hash.new
+
+    @example_files[:halloween] = File.join(basedir, "files/halloween2009.puz")
+    @example_files[:crnet]     = File.join(basedir, "files/crnet100306.puz")
+    @example_files[:tmcal]     = File.join(basedir, "files/tmcal100306.puz")
+    @example_files[:xp]        = File.join(basedir, "files/xp100306.puz")
+    @example_files[:ydx]       = File.join(basedir, "files/ydx100515.puz")
+  end
+
+#   before(:each) do
+#   end
+# 
+#   after(:each) do
+#   end
+
+  #-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=#
+  # Builder Tests
+  #-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=#
+
+  it "should instantiate the puzzle with passing of file" do
+    ac = Acrosslite.new(:filepath => @example_files[:halloween])
+    ac.should be_an_instance_of Acrosslite
+    ac.filepath.should == @example_files[:halloween]
+    ac.content.should == File.open(@example_files[:halloween]).read
+  end
+
+  it "should instantiate the puzzle with passing of an acrosslite blob" do
+    ac = Acrosslite.new(:content => File.open(@example_files[:halloween]).read)
+    ac.should be_an_instance_of Acrosslite
+    ac.content.should == File.open(@example_files[:halloween]).read
+  end
+
+  it "should parse dimensions" do
+    ac = Acrosslite.new(:filepath => @example_files[:tmcal])
+    ac.rows.should == 15
+    ac.columns.should == 15
+    ac.area.should == 15 * 15
+  end
+
+  it "should parse solution and diagram" do
+    ac = Acrosslite.new(:filepath => @example_files[:crnet])
+    ac.solution.join.should == 'PASSED.MAMACASSLEANER.AMICABLYURBANA.FIGUREONCARRYWEIGHT.TVAKTEL.BLOAT.STEPYES.GLASS.COINS...KYOTO.TOWNIEMCENROE.RAREGASALLIED.RAKED...NESTS.HADES.PEWDAIS.REPOS.MUNIARN.FORINSTANCELOOKATME.IONIANAUREVOIR.CROSSESTEWARTS.KOSHER'
+    ac.diagram.join.should == '------.--------------.--------------.-------------------.-------.-----.-------.-----.-----...-----.-------------.-------------.-----...-----.-----.-------.-----.-------.-------------------.--------------.--------------.------'
+  end
+
+  it "should retrieve meta data about the puzzle" do
+    ac = Acrosslite.new(:filepath => @example_files[:tmcal])
+    ac.title.should == 'LA Times, Sat, Mar 6, 2010'
+    ac.author.should == 'Barry C. Silk / Ed. Rich Norris'
+#     ac.copyright.should == "© 2010 Tribune Media Services, Inc."
+
+    ac = Acrosslite.new(:filepath => @example_files[:crnet])
+    ac.title.should == '03/06/10 SATURDAY STUMPER'
+    ac.author.should == 'Merle Baker , edited by Stanley Newman'
+#     ac.copyright.should == "© Copyright 2010 Stanley Newman, Distributed by Creators Syndicate, Inc."
+
+    ac = Acrosslite.new(:filepath => @example_files[:xp])
+    ac.title.should == ''
+    ac.author.should == ''
+    ac.copyright.should == ''
+  end
+
+  it "should retrieve the data for each of the entries" do
+    ac = Acrosslite.new(:filepath => @example_files[:halloween])
+    ac.across.first.clue.should == "Item sought by kids in costumes"
+    ac.across.first.answer.should == "CANDY"
+    ac.across.first.clue_number.should == 1
+    ac.across.first.row.should == 0
+    ac.across.first.column.should == 0
+    ac.across.first.length.should == 5
+    ac.across.first.cell_number.should == 1
+
+    ac.across.last.clue.should == "Has to have"
+    ac.across.last.answer.should == "NEEDS"
+    ac.across.last.clue_number.should == 73
+    ac.across.last.row.should == 14
+    ac.across.last.column.should == 10
+    ac.across.last.length.should == 5
+    ac.across.last.cell_number.should == 221
+
+    ac.down.first.clue.should == "Slept under the stars"
+    ac.down.first.answer.should == "CAMPED"
+    ac.down.first.clue_number.should == 1
+    ac.down.first.row.should == 0
+    ac.down.first.column.should == 0
+    ac.down.first.length.should == 6
+    ac.down.first.cell_number.should == 1
+
+    ac.down.last.clue.should == "Take in slowly"
+    ac.down.last.answer.should == "SIP"
+    ac.down.last.clue_number.should == 66
+    ac.down.last.row.should == 12
+    ac.down.last.column.should == 6
+    ac.down.last.length.should == 3
+    ac.down.last.cell_number.should == 187
+  end
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification 
+name: acrosslite
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 2
+  - 0
+  version: 0.2.0
+platform: ruby
+authors: 
+- Samuel Mullen
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-03-25 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+description: "false"
+email: samullen@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- LICENSE
+- README.rdoc
+- Rakefile
+- lib/acrosslite.rb
+- lib/entry.rb
+- spec/acrosslite_spec.rb
+- spec/files/tmcal100306.puz
+- spec/files/crnet100306.puz
+- spec/files/halloween2009.puz
+- spec/files/ydx100515.puz
+- spec/files/xp100306.puz
+has_rdoc: true
+homepage: http://github.com/samullen/acrosslite
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: A Ruby library for parsing Across Lite puzzle (.puz) files
+test_files: 
+- spec/acrosslite_spec.rb
+- spec/files/tmcal100306.puz
+- spec/files/crnet100306.puz
+- spec/files/halloween2009.puz
+- spec/files/ydx100515.puz
+- spec/files/xp100306.puz