word-search-puzzle 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9294041e86cf760a8de12fda97d4217675d7ba8bc424ea039d61411a1a62167e
+  data.tar.gz: 9eba51b91b9a55347eca122e07c81782877bdf16d4e2e2f966e8840d3ccbaa1a
+SHA512:
+  metadata.gz: 16f10a31d33c73f88d26ade1245ab20bf10eee17e58ba30e1858f0aba2fa5972e0a90809103180424b01a11756bd915f2d223845ce897dfa4ec2ec303fb9660f
+  data.tar.gz: 20281180b73200edf1b907e2a0a4201615abfa9d66a6f8e32763f7789b0579ec130e4947238f2b32e951493a8a5982f9734711ed272a48363603ff9825b26cc0

data/.ruby-version

@@ -0,0 +1 @@
+3.4.2

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/testdouble/standard
+ruby_version: 3.4

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-10-13
+
+- Initial release

data/Gemfile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in word-search-puzzle.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+gem "test-unit", "~> 3.0"
+gem "standard", "~> 1.3"
+
+# warning:
+#   <These gems> were loaded from the standard library,
+#   but will no longer be part of the default gems starting from Ruby 3.5.0.
+#   You can add irb to your Gemfile or gemspec to silence this warning.
+gem "rdoc", "~> 6.15"
+gem "irb", "~> 1.15"

data/Gemfile.lock

@@ -0,0 +1,98 @@
+PATH
+  remote: .
+  specs:
+    word-search-puzzle (0.1.0)
+      colorize (~> 1.1.0)
+      thor (~> 1.4.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.3)
+    colorize (1.1.0)
+    date (3.4.1)
+    erb (5.1.1)
+    io-console (0.8.1)
+    irb (1.15.2)
+      pp (>= 0.6.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    json (2.15.0)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    parallel (1.27.0)
+    parser (3.3.9.0)
+      ast (~> 2.4.1)
+      racc
+    power_assert (2.0.5)
+    pp (0.6.3)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.5.2)
+    psych (5.2.6)
+      date
+      stringio
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.3.0)
+    rdoc (6.15.0)
+      erb
+      psych (>= 4.0.0)
+      tsort
+    regexp_parser (2.11.3)
+    reline (0.6.2)
+      io-console (~> 0.5)
+    rubocop (1.80.2)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.46.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.47.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    rubocop-performance (1.25.0)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.38.0, < 2.0)
+    ruby-progressbar (1.13.0)
+    standard (1.51.1)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.80.2)
+      standard-custom (~> 1.0.0)
+      standard-performance (~> 1.8)
+    standard-custom (1.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.50)
+    standard-performance (1.8.0)
+      lint_roller (~> 1.1)
+      rubocop-performance (~> 1.25.0)
+    stringio (3.1.7)
+    test-unit (3.7.0)
+      power_assert
+    thor (1.4.0)
+    tsort (0.2.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.1.0)
+
+PLATFORMS
+  ruby
+  x86_64-linux
+
+DEPENDENCIES
+  irb (~> 1.15)
+  rake (~> 13.0)
+  rdoc (~> 6.15)
+  standard (~> 1.3)
+  test-unit (~> 3.0)
+  word-search-puzzle!
+
+BUNDLED WITH
+   2.7.2

data/README.md

@@ -0,0 +1,53 @@
+# Word Search Puzzle
+
+Ruby gem to create word search puzzles.
+
+## Installation
+
+Install the gem by executing:
+
+    $ gem install word-search-puzzle
+
+## Usage
+
+Execute `word-search-puzzle` from the command line.
+
+**Example**: create puzzle with default options.
+
+```
+$ word-search-puzzle create --words=JEDI,SITH,STARWARS
+```
+![](docs/images/puzzle-01.png)
+
+> Each execution builds a different puzzle.
+
+**Example**: Create a puzzle showing the final solution. 
+```
+$ word-search-puzzle create --words=VADER,OBIWAN,LUKE --padding='.' --size=6x6
+ . R . . . .
+ . . E . . .
+ . . . D . .
+ O B I W A N
+ . . . . . V
+ E K U L . .
+```
+
+**Example**: Create puzzle reading words from text file.
+```
+$ word-search-puzzle create --words=examples/starwars.txt                   
+```
+![](docs/images/puzzle-03.png)
+
+> **WARNING:**
+> Depending on the number and size of the words, the size of the grid, and the numbers of gaps, sometimes it will not be possible to find a solution.
+
+## Documentation
+
+* [Command line options and examples](docs/options.md)
+* [Examples using the Ruby library](examples/)
+* [Development](docs/development.md)
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/dvarrui/word-search-puzzle.
+

data/Rakefile

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+require "standard/rake"
+
+task default: %i[test standard]
+
+task :help do
+  puts "Usage: rake --tasks or rake --help"
+end

data/docs/development.md

@@ -0,0 +1,19 @@
+[<< back](../README.md)
+
+# Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` 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 the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Installation
+
+Install the gem by executing:
+
+    $ gem install word-search-puzzle
+
+If bundler is being used to manage dependencies, install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add word-search-puzzle
+

data/docs/options.md

@@ -0,0 +1,157 @@
+[<< back](../README.md)
+
+# Command line options
+
+## Help
+
+* Show help: `word-search-puzzle help`
+* Show **create** action help: `word-search-puzzle help create`
+
+# Building options
+
+> Used to create different puzzles.
+
+* `--words`, Comma separated list of word or file name with de words.
+* `--size`, Grid size. Default value 10x10.
+
+## Words options
+
+**Example**: Create puzzle using these words: JEDO, SITH, STARWARS.
+```
+$ word-search-puzzle create --words=JEDI,SITH,STARWARS
+ D S O I D P O V W K
+ N J E D I D H P Q T
+ Q S T L M J Z N R M
+ L T O Y U B S B L P
+ N A K H W Q I K C K
+ G R Y D E I T R I N
+ N W E F H U H U F H
+ R A B S J U G M K U
+ U R V M A F H W D H
+ Q S O S L I V R O C
+```
+
+**Example**: Create puzzle reading words from TXT file.
+```
+$ word-search-puzzle create --words=examples/starwars.txt 
+ A W L U K E D W Y G
+ O P 3 C R C D G W Z
+ S R A W R A T S E S
+ T Y O D A D N U Q L
+ V R O D A R E P M E
+ A R Y O B I W A N C
+ D H 2 W D F L I G K
+ E Y S D X S N E D N
+ R V H U 2 E B V I W
+ R J F S I T H G S A
+```
+
+## Size option
+
+**Example**: Create default size puzzle (10 rows and 10 cols).
+```
+$ word-search-puzzle create --words=examples/starwars.txt        
+ X U B R E D A V O B
+ R N S A D O Y B E T
+ 2 A R R F M I Z M Z
+ D X A I L W Q J P D
+ 2 H W F A U D E E N
+ C T R N L M K S R X
+ H J A B H A S E A U
+ G V T W H I I O D N
+ E R S T S E T S O X
+ Q C 3 P O L H W R M
+```
+
+**Example**: Create 8x20 puzzle (8 rows and 20 cols).
+```
+$ word-search-puzzle create --words=examples/starwars.txt --size=8x20
+ C E K U L K W S S I Y I G O B I W A N X
+ L E F A T F S L W O C Y R 2 D 2 I Z P P
+ E Y V S J R N U D O Y L R H X Q O Q N O
+ Y H W T I C H A T V V J F G K R E O M Z
+ P N V Y P S P G J J R I J O P 3 C I S O
+ K Z K X T R O D A R E P M E T L E I A N
+ S R A W R A T S X Z E L O B A W T P Y O
+ D S L L G M N C A V A D E R O H C L L G
+```
+
+*+Example**: Create 9x9 puzzle (rows and 9 cols).
+```
+$ word-search-puzzle create --words=examples/starwars.txt --size=9
+ X R I Y O Y S V B
+ T O O Q B L R H Z
+ J D C V I U A T T
+ A A K A W K W I O
+ O R L D A E R S P
+ N E E E N 2 A I 3
+ M P I R D J T K C
+ L M A 2 K Z S V T
+ R E R G I P N Z W
+```
+# Rendering options
+
+> Used to display the puzzle in different ways.
+
+* `--color`, Indicates whether to display the output with color. Default value false.
+* `--padding=LIST`, comma.separated list of characters to fill in the gaps in the puzzle. Default value A-Z.
+* `--gaps=FILEPATH`, Filename with list of gaps coordinates. List of `row,col` integers.
+
+## Color option
+
+The `color` option, highlights the list of words within the puzzle, so we can easily identify their location.
+
+```
+$ word-search-puzzle create --words=DEATH,STAR --color
+```
+![](images/color-option.png)
+
+## Padding option
+
+In the puzzle creation process, we first place the word list inside the grid and then fill in the blanks with random letters until the grid is completely filled.
+
+During this step, the letters A through Z will be used by default as random values.
+
+However, in some cases, the words in our puzzle may use other characters set (for example, Japanese characters), so we use `padding` option set custom random character fill list
+
+**Example**: Using `padding` option to custom random padding values.
+
+```
+$ word-search-puzzle create --words=DEATH,STAR --padding='+,*,x' 
+ * x * + x x * * x x
+ * x x + x * * * * x
+ + x * * + x * * + +
+ + + x x + x + * x +
+ * * * + * + + + + x
+ + * x + * + H x * x
+ + * + + x T + + x *
+ + x + x A * + + + +
+ x x x E * + R A T S
+ x x D * x + * * x x
+```
+
+## Gaps option
+
+The grid is a group of cell into square or a rectangle shape. However, this program offers us to customize the grid shape.
+
+To do this, first we start with a square grid and gradually remove the cells defined by `gaps` option to customize the shape.
+
+**Example**: Using `gaps` to customize grid shape.
+
+```
+$ word-search-puzzle create --words=DEATH,STAR --gaps=examples/ball-shape.txt
+                    
+       N L P T      
+     O R P S P O    
+   V E A S T D P Q  
+   Y O B B A H C X  
+   O P B M R T W K  
+   V O I P K A F T  
+     H H J N E X    
+       U J D D  
+
+```
+
+We can define gaps in two ways:
+1. Using a [TXT file](../examples/ball-shape.txt), where the dot (`.`) character represents a gap and `@` represents an available cell.
+2. Using a [CSV file](../examples/ball-gaps.csv), where each line contains the coordinates (row, column) of a gap.

data/examples/01-default.rb

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+# Create puzzle with default options
+
+require_relative "../lib/word-search-puzzle"
+
+# 1. Initialize your words list
+words = %w[STARWARS OBIWAN LUKE VADER R2D2 C3PO LEIA YODA EMPERADOR SITH]
+
+# 2. Create puzzle (Default size 10x10)
+puzzle = WordSearchPuzzle.create(words: words)
+
+# 3. Show puzzle on screen
+puts puzzle.render

data/examples/02-read_words_file.rb

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+# Create your puzzle reading words from external txt file
+
+require_relative "../lib/word-search-puzzle"
+
+# 1. Create puzzle (default size 10x10) reading words from text file
+FILEPATH = File.join(File.dirname(__FILE__), "starwars.txt")
+puzzle = WordSearchPuzzle.create(words: FILEPATH)
+
+# 2. Check if exits solution
+if puzzle.nil?
+  puts "I'm sorry! Can't create the puzzle!"
+  puts "Revise filepath, please! (#{filename})"
+  exit 1
+end
+
+# 3. Show puzzle on screen
+puts puzzle.render

data/examples/03-render_options.rb

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+require_relative "../lib/word-search-puzzle"
+
+# 1. Define your word list
+words = %w[STARWARS OBIWAN LUKE VADER R2D2 C3PO LEIA YODA EMPERADOR SITH]
+
+# 2. Create your puzzle (10x20 size)
+puzzle = WordSearchPuzzle.create(
+  words: words,
+  size: "10x20"
+)
+
+# 3. Show puzzle on screen:
+# - color: Use colors to highlight the words
+# - padding: define the characters set used to fill the grid
+puts puzzle.render(color: true, padding: ["."])

data/examples/04-custom_shape.rb

@@ -0,0 +1,43 @@
+#!/usr/bin/env ruby
+require_relative "../lib/word-search-puzzle"
+
+# 1. First desing your own grid shape and create the gaps
+#
+#      9x9 Grid example
+#
+#     0 1 2 3 4 5 6 7 8
+# 0 | . @ @ . . . @ @ .
+# 1 | @ @ @ @ . @ @ @ @
+# 2 | @ @ @ @ @ @ @ @ @
+# 3 | @ @ @ @ @ @ @ @ @
+# 4 | . @ @ @ @ @ @ @ .
+# 5 | . . @ @ @ @ @ . .
+# 6 | . . . @ @ @ . . .
+# 7 | . . . . @ . . . .
+# 8 | . . . . . . . . .
+#
+# gaps:
+# - Define gaps within the grid (row, col).
+# - Gaps are positions within the grid that cannot be used for the puzzle.
+gaps = [
+  [0, 0], [0, 3], [0, 4], [0, 5], [0, 8],
+  [1, 4],
+  [4, 0], [4, 8],
+  [5, 0], [5, 1], [5, 7], [5, 8],
+  [6, 0], [6, 1], [6, 2], [6, 6], [6, 7], [6, 8],
+  [7, 0], [7, 1], [7, 2], [7, 3], [7, 5], [7, 6], [7, 7], [7, 8],
+  [8, 0], [8, 1], [8, 2], [8, 3], [8, 4], [8, 5], [8, 6], [8, 7], [8, 8]
+]
+
+# 2. Define words list
+words = %w[DEATH STAR RETURN JEDI]
+
+# 3. Create a puzzle with custom words, size and gaps
+puzzle = WordSearchPuzzle.create(
+  words: words,
+  size: 9,
+  gaps: gaps
+)
+
+# 4. Render puzzle on screen
+puts puzzle.render(color: true, padding: ["@"])

data/examples/05-read_gaps_file.rb

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+require_relative "../lib/word-search-puzzle"
+
+# 1. Read a CSV file with your gaps definition.
+#    Gaps positions within the grid that cannot be used for the puzzle.
+FILEPATH = File.join(File.dirname(__FILE__), "ball-gaps.csv")
+
+# 2. Define words list
+words = %w[DEATH STAR RETURN JEDI]
+
+# 3. Create puzzle with custom words, default size (10x10), and custom gaps
+puzzle = WordSearchPuzzle.create(
+  words: words,
+  gaps: FILEPATH
+)
+
+# 4. Render puzzle on screen
+puts puzzle.render(color: true, padding: ["@"])

data/examples/ball-gaps.csv

@@ -0,0 +1,48 @@
+0,0
+0,1
+0,2
+0,3
+0,4
+0,5
+0,6
+0,7
+0,8
+0,9
+1,0
+1,1
+1,2
+1,7
+1,8
+1,9
+2,0
+2,1
+2,8
+2,9
+3,0
+3,9
+4,0
+4,9
+5,0
+5,9
+6,0
+6,9
+7,0
+7,1
+7,8
+7,9
+8,0
+8,1
+8,2
+8,7
+8,8
+8,9
+9,0
+9,1
+9,2
+9,3
+9,4
+9,5
+9,6
+9,7
+9,8
+9,9

data/examples/ball-shape.txt

@@ -0,0 +1,10 @@
+..........
+...@@@@...
+..@@@@@@..
+.@@@@@@@@.
+.@@@@@@@@.
+.@@@@@@@@.
+.@@@@@@@@.
+..@@@@@@..
+...@@@@...
+..........

data/examples/starwars.txt

@@ -0,0 +1,10 @@
+STARWARS
+OBIWAN
+LUKE
+VADER
+R2D2
+C3PO
+LEIA
+YODA
+EMPERADOR
+SITH

data/lib/word-search-puzzle/cell.rb

@@ -0,0 +1,44 @@
+module WordSearchPuzzle
+  class Cell
+    attr_reader :data, :count
+
+    def initialize
+      @count = 0
+      @data = :empty
+    end
+
+    def empty?
+      @data == :empty
+    end
+
+    def gap?
+      @data == :gap
+    end
+
+    def gap!
+      @data = :gap
+    end
+
+    def in_use?
+      @count > 0
+    end
+
+    def push(data)
+      if empty? || @data == data
+        @data = data
+        @count += 1
+      else
+        raise "Cell.push: new data(#{data}) is not equal to current data(#{@data})!"
+      end
+    end
+
+    def pop
+      raise "Cell.pop: No data!" unless in_use?
+
+      @count -= 1
+      current_data = @data
+      @data = :empty if @count.zero?
+      current_data
+    end
+  end
+end

data/lib/word-search-puzzle/cli/user_actions.rb

@@ -0,0 +1,22 @@
+require_relative "../../word-search-puzzle"
+
+module WordSearchPuzzle
+  class UserActions
+    def create(options)
+      puzzle = WordSearchPuzzle.create(
+        words: options["words"],
+        size: options["size"],
+        gaps: options["gaps"]
+      )
+
+      if puzzle.nil?
+        warn "Unable to create puzzle!"
+        exit 1
+      end
+
+      color = options["color"] || false
+      padding = options["padding"] ? options["padding"].split(",") : ("A".."Z").to_a
+      puts puzzle.render(color: color, padding: padding)
+    end
+  end
+end

data/lib/word-search-puzzle/cli.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "thor"
+require_relative "version"
+require_relative "../word-search-puzzle"
+require_relative "cli/user_actions"
+
+##
+# Command Line User Interface
+class CLI < Thor
+  map ["h", "-h", "--help"] => "help"
+
+  map ["v", "-v", "--version"] => "version"
+  desc "version", "Show the program version"
+  def version
+    puts "#{WordSearchPuzzle::NAME} version #{WordSearchPuzzle::VERSION}"
+    exit 0
+  end
+
+  map ["c", "-c", "--create"] => "create"
+  option :words, required: true
+  option :size
+  option :color, type: :boolean
+  option :padding
+  option :gaps
+  desc "create [--size=SIZE][--color]", "Create puzzle"
+  long_desc <<-LONGDESC
+
+  - [--words=LIST], comma-separated list of words or file name with the words
+
+  - [--size=SIZE], Grid size. Default value 10x10.
+  Examples 5:, sets rows=5 and cols=5.
+  Example 10x20: sets rows=10 and col=20.
+
+  - [--color], Indicates whether to display the output with color. Default value false
+
+  - [--padding=LIST], comma.separated list of characters to fill puzzle. Default value A-Z.
+
+  - [--gaps=FILEPATH], TEXT file with grid shape, or CSV file with gaps coordinates.
+  
+  LONGDESC
+  def create
+    WordSearchPuzzle::UserActions.new.create(options)
+  end
+
+  def respond_to_missing?(_method_name)
+    true
+  end
+
+  ##
+  # Thor stop and show messages on screen on failure
+  def self.exit_on_failure?
+    true
+  end
+end

data/lib/word-search-puzzle/grid.rb

@@ -0,0 +1,91 @@
+require_relative "cell"
+require "colorize"
+
+module WordSearchPuzzle
+  class Grid
+    def self.directions
+      {
+        n: {row: -1, col: 0},
+        ne: {row: -1, col: 1},
+        e: {row: 0, col: 1},
+        se: {row: 1, col: 1},
+        s: {row: 1, col: 0},
+        sw: {row: 1, col: -1},
+        w: {row: 0, col: -1},
+        nw: {row: -1, col: -1}
+      }
+    end
+    Coord = Data.define(:row, :col, :data)
+    attr_reader :rows, :cols
+
+    def initialize(rows, cols, gaps = [])
+      @rows = rows
+      @cols = cols
+      @matrix = []
+      (0...rows).each do |row|
+        data = []
+        (0...cols).each { |col| data << Cell.new }
+        @matrix[row] = data
+      end
+      gaps.each { |x, y| @matrix[x][y].gap! }
+    end
+
+    def cell(row, col)
+      @matrix[row][col]
+    end
+
+    def find_sequence(word, first_row, first_col, direction)
+      step = Grid.directions[direction]
+      row = first_row
+      col = first_col
+      coords = []
+      word.chars.each do |letter|
+        return [] if row >= @rows || col >= @cols || row < 0 || col < 0
+
+        cell = @matrix[row][col]
+        if cell.empty? || cell.data == letter
+          coords << Coord.new(row: row, col: col, data: letter)
+          row += step[:row]
+          col += step[:col]
+        else
+          return []
+        end
+      end
+      coords
+    end
+
+    def set_sequence(coords)
+      coords.each { @matrix[it.row][it.col].push(it.data) }
+    end
+
+    def unset_sequence(coords)
+      coords.each { @matrix[it.row][it.col].pop }
+    end
+
+    def render(color: false, padding: :default)
+      padding ||= ["."]
+      padding = ("A".."Z").to_a if padding == :default
+
+      lines = @matrix.map do |row|
+        row.map { render_cell(it, color, padding) }.join
+      end
+      lines.join("\n")
+    end
+
+    private
+
+    def render_cell(cell, color, padding)
+      return "  " if cell.gap?
+      data = cell.data.to_s
+      data = padding.sample if cell.count.zero?
+
+      if color && cell.count.zero?
+        data = data.colorize(:gray)
+      elsif color
+        data = data.colorize(:ligth_white)
+      end
+
+      " " + data
+    end
+  end
+end

data/lib/word-search-puzzle/input.rb

@@ -0,0 +1,96 @@
+module WordSearchPuzzle
+  class Input
+    DEFAULT_GRID_SIZE = 10
+
+    def self.read_words(words)
+      if words.is_a? Array
+        if words.empty?
+          warn "Input: empty parameter! (words)"
+          exit 1
+        end
+        return words
+      elsif File.exist?(words)
+        lines = File.readlines(words)
+        lines.map! { it.strip }
+        lines.delete("")
+        if lines.empty?
+          warn "Input: empty file! (#{words})!"
+          exit 1
+        end
+        return lines
+      end
+
+      if words.nil? || words.empty?
+        warn "Input: empty parameter! (words)"
+        exit 1
+      end
+
+      words.split(",").map { it.strip }
+    end
+
+    def self.read_size(size)
+      if size.nil?
+        rows = cols = DEFAULT_GRID_SIZE
+      elsif size.is_a? Integer
+        rows = cols = size
+      else
+        values = size.split("x")
+        rows = values[0].to_i
+        rows = (rows < 1) ? DEFAULT_GRID_SIZE : rows
+        cols = (values.size == 2) ? values[1].to_i : rows
+      end
+      [rows, cols]
+    end
+
+    def self.read_gaps(gaps)
+      return gaps if gaps.is_a? Array
+      return [] if gaps.nil?
+
+      if File.exist?(gaps)
+        lines = File.readlines(gaps)
+        lines.delete("")
+
+        if gaps.end_with?(".csv")
+          data = lines.map do |line|
+            items = line.split(",")
+            [items[0].to_i, items[1].to_i]
+          end
+        else
+          data = []
+          lines.each_with_index do |line, row|
+            line.chars.each_with_index do |char, col|
+              data << [row, col] if char == "."
+            end
+          end
+        end
+        return data
+      end
+
+      []
+    end
+
+    def self.validate(words, rows, cols, gaps)
+      msg = []
+
+      words.each do |word|
+        msg << "E01: The word <#{word}> does not fit in the grid." if word.length > [rows, cols].max
+      end
+
+      if words.size == 1 && msg.size == 1
+        msg << "E02: If <#{words.first}> is a filepath then it was not found."
+      end
+
+      total_words_size = words.sum { it.length }
+      if total_words_size > (rows * cols - gaps.length)
+        msg << "E03: The grid is not large enough to contain all the words."
+      end
+
+      gaps.each do |y, x|
+        if y >= rows || x >= cols
+          msg << "E04: Gap [#{y}, #{x}] outside the grid size."
+        end
+      end
+      msg
+    end
+  end
+end

data/lib/word-search-puzzle/strategy.rb

@@ -0,0 +1,63 @@
+require_relative "grid"
+
+module WordSearchPuzzle
+  class Strategy
+    def initialize(words, grid)
+      # Sort words from longest to smallest
+      @words = words.sort_by { it.length }.reverse
+      @initial_grid = grid
+      @final_grid = nil
+    end
+
+    def grid
+      @final_grid
+    end
+
+    def calculate
+      @final_grid = find_solution(@words.clone, @initial_grid.clone)
+    end
+
+    private
+
+    def find_solution(words, grid)
+      # Take the first word
+      word = words.delete_at(0)
+      available_word_locations = get_available_locations(word, grid)
+      return nil if available_word_locations.empty? # No solution
+
+      available_word_locations.shuffle!
+      available_word_locations.each do |sequence|
+        grid.set_sequence(sequence) # Push word into grid location
+        return grid if words.empty? # Solved puzzle. No more words to push
+
+        resolved_grid = find_solution(words.clone, grid.clone) # Find solution recursively
+        if resolved_grid
+          return resolved_grid # <new_grid> contains the solved puzzle
+        else
+          # The selected <sequence> of the word does not help to solve the puzzle.
+          # 1. Restore <grid> content
+          # 2. And try other sequence
+          grid.unset_sequence(sequence)
+        end
+      end
+      if words.empty?
+        grid # All the words has been placed
+      else
+        nil # All possibilities have been tried and there are still words left unplaced.
+      end
+    end
+
+    def get_available_locations(word, grid)
+      locations = []
+      (0...grid.rows).each do |row|
+        (0...grid.cols).each do |col|
+          Grid.directions.keys.each do |direction|
+            location = grid.find_sequence(word, row, col, direction)
+            locations << location unless location.empty?
+          end
+        end
+      end
+      locations
+    end
+  end
+end

data/lib/word-search-puzzle/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module WordSearchPuzzle
+  NAME = "word-search-puzzle"
+  VERSION = "0.1.0"
+end

data/lib/word-search-puzzle.rb

@@ -0,0 +1,26 @@
+require_relative "word-search-puzzle/grid"
+require_relative "word-search-puzzle/input"
+require_relative "word-search-puzzle/strategy"
+
+module WordSearchPuzzle
+  def self.create(words: [], size: "10x10", gaps: [])
+    # Read input values
+    words = WordSearchPuzzle::Input.read_words(words)
+    rows, cols = WordSearchPuzzle::Input.read_size(size)
+    gaps = WordSearchPuzzle::Input.read_gaps(gaps)
+
+    # Validate input values
+    errors = WordSearchPuzzle::Input.validate(words, rows, cols, gaps)
+    unless errors.empty?
+      puts "Unable to create puzzle:"
+      errors.each_with_index { |message, index| puts "#{index + 1}. #{message}" }
+      exit 1
+    end
+
+    # Create the grid ant try to find a puzzle
+    grid = Grid.new(rows, cols, gaps)
+    strategy = Strategy.new(words, grid)
+    strategy.calculate
+    strategy.grid
+  end
+end

data/sig/word-search-puzzle/cell.rbs

@@ -0,0 +1,4 @@
+class Cell
+    attr_reader data: Char
+    attr_reader count: Integer
+end

data/sig/word-search-puzzle/version.rbs

@@ -0,0 +1,8 @@
+module Word
+  module Search
+    module Puzzle
+      VERSION: String
+      # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+    end
+  end
+end

data/word-search-puzzle

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require_relative "lib/word-search-puzzle/cli"
+require "debug"
+
+# Start command line interface
+CLI.start(ARGV)

data/word-search-puzzle.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "lib/word-search-puzzle/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "word-search-puzzle"
+  spec.version = WordSearchPuzzle::VERSION
+  spec.authors = ["David Vargas Ruiz"]
+  spec.email = ["dvarrui@proton.me"]
+
+  spec.summary = "Create word search puzzles"
+  # spec.description = "TODO: Write a longer description or delete this line."
+  spec.homepage = "https://github.com/dvarrui/word-search-puzzle"
+  spec.required_ruby_version = ">= 3.4.0"
+
+  # spec.metadata["allowed_push_host"] = "TODO: Set to your gem server 'https://example.com'"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "https://github.com/dvarrui/word-search-puzzle/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "colorize", "~> 1.1.0"
+  spec.add_dependency "thor", "~> 1.4.0"
+end

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification
+name: word-search-puzzle
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- David Vargas Ruiz
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: colorize
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.1.0
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.4.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.4.0
+email:
+- dvarrui@proton.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".ruby-version"
+- ".standard.yml"
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- docs/development.md
+- docs/images/color-option.png
+- docs/images/puzzle-01.png
+- docs/images/puzzle-03.png
+- docs/options.md
+- examples/01-default.rb
+- examples/02-read_words_file.rb
+- examples/03-render_options.rb
+- examples/04-custom_shape.rb
+- examples/05-read_gaps_file.rb
+- examples/ball-gaps.csv
+- examples/ball-shape.txt
+- examples/starwars.txt
+- lib/word-search-puzzle.rb
+- lib/word-search-puzzle/cell.rb
+- lib/word-search-puzzle/cli.rb
+- lib/word-search-puzzle/cli/user_actions.rb
+- lib/word-search-puzzle/grid.rb
+- lib/word-search-puzzle/input.rb
+- lib/word-search-puzzle/strategy.rb
+- lib/word-search-puzzle/version.rb
+- sig/word-search-puzzle/cell.rbs
+- sig/word-search-puzzle/version.rbs
+- word-search-puzzle
+- word-search-puzzle.gemspec
+homepage: https://github.com/dvarrui/word-search-puzzle
+licenses: []
+metadata:
+  homepage_uri: https://github.com/dvarrui/word-search-puzzle
+  source_code_uri: https://github.com/dvarrui/word-search-puzzle
+  changelog_uri: https://github.com/dvarrui/word-search-puzzle/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Create word search puzzles
+test_files: []