logigram 0.1.0.pre

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1873a940545e833150f3eb22b6208ec10bc122a62c38619e733b90f44b64d3c8
+  data.tar.gz: 11ecd0546c63ce5564abcafd1e381673b9ef0d4c593579d49cded2fa87f9ce2b
+SHA512:
+  metadata.gz: fdad315c96239708eac672fd6b269653d19ba897b9fd388c872377c8d1cf8fc3fd861ca37bd632378cbc942a4099ffaff3ffc4792cc92b4d9d7101dd42e66f36
+  data.tar.gz: e9242ac2766a70d47d838a07bd4658ea94b3c12b1a3d1f6ee941a8046c746e3187d6e748fba307103551c0c5bca4a85871dc9573b74331384fac656e5fb1d4cd

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/.vscode/
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.3.3
+before_install: gem install bundler -v 1.14.6

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in logigram.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Fred Snyder
+
+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,33 @@
+# Logigram
+
+A library for generating [logic puzzles](https://en.wikipedia.org/wiki/Logic_puzzle).
+
+A Logigram puzzle is a form of *syllogism*. The puzzle provides a collection of facts (or *premises*) and asks a question. The answer can be construed from the facts through deductive reasoning.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'logigram'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install logigram
+
+## Usage
+
+See [example.rb](example.rb) for a simple demonstration.
+
+## TODO:
+
+- Dynamically generate constraints and pieces from objects with existing properties.
+    - Example: Three objects have existing properties `:hair_color` and `:eye_color`. The logigram uses the existing constraints
+      and values.
+    - The logigram will need to verify that the resulting challenge has exactly one discoverable solution.
+    - The process for generating the logigram will need a mechanism to accept constraint properties (e.g., `predicate`)

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "logigram"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/example.rb

@@ -0,0 +1,35 @@
+# A simple example of a Logigram puzzle
+
+require 'logigram'
+
+class Puzzle < Logigram::Base
+  # Create a formatter that refers to pieces as "animals" instead of "things"
+  formatter = Logigram::Formatter.new(subject: 'the %<value>s animal')
+
+  # Apply constraints that will be used to generate the puzzle's premises
+  constrain 'color', ['red', 'green', 'blue'], formatter: formatter
+  constrain 'size', ['small', 'medium', 'large'], formatter: formatter
+end
+
+# Create a new puzzle with three pieces. If a `solution` is not specified, the
+# puzzle will select one at random
+puzzle = Puzzle.new(['the dog', 'the cat', 'the pig'])
+
+# The challenge holds the clues the player can use to solve the puzzle
+challenge = Logigram::Challenge.new(puzzle)
+
+puts "The animals are #{puzzle.pieces.join(', ')}"
+puzzle.constraints.each do |c|
+  puts "One of each is #{c.values.join(', ')}"
+end
+puts "Which animal #{puzzle.solution_predicate}?"
+
+puts 'Known facts:'
+challenge.clues.each do |c|
+  puts "* #{c.to_s.capitalize}"
+end
+
+print 'Press enter for the solution....'
+$stdin.gets
+
+puts "#{puzzle.solution.to_s.capitalize} #{puzzle.solution_predicate}."

data/lib/logigram/base.rb

@@ -0,0 +1,273 @@
+module Logigram
+  # A base class for creating logic puzzles. Authors should not instantiate
+  # this class directly, but extend it with their own puzzle implementations.
+  #
+  # @example
+  #   class Puzzle < Logigram::Base
+  #     constrain 'color', ['red', 'green', 'blue']
+  #     constrain 'size', ['small', 'medium', 'large']
+  #   end
+  #
+  class Base
+    # The piece that represents the solution. The puzzle's premises should be
+    # clues from which this solution can be deduced.
+    #
+    # @return [Piece]
+    attr_reader :solution
+
+    class << self
+      # An array of the puzzle's constraints.
+      #
+      # Constraints specify attributes that get assigned to puzzle pieces.
+      # When a puzzle gets instantiated, each piece is assigned a value from
+      # each constraint, and the puzzle uses them to generate premises.
+      #
+      # @return [Array<Constraint>]
+      def constraints
+        constraint_map.values
+      end
+
+      # Get a constraint by name.
+      #
+      # @param name [String]
+      # @return [Constraint, nil]
+      def constraint(name)
+        constraint_map[name]
+      end
+
+      protected
+
+      # Add a constraint to the puzzle.
+      #
+      # @example The pieces in the instantiated puzzle will each be assigned a unique color and size.
+      #
+      #   class MyPuzzle < Logigram::Base
+      #     constrain 'color', ['red', 'green', 'blue']
+      #     constrain 'size', ['small', 'medium', 'large']
+      #   end
+      #   puzzle = MyPuzzle.new ['dog', 'cat', 'rat']
+      #
+      # @param name [String]
+      # @param values [Array<Object>]
+      # @param reserve [Object, Array<Object>, nil] Require the solution to be one of these values
+      # @param formatter [Formatter] Formatting rules for generated premises
+      # @return [Logigram::Constraint] The newly created constraint
+      def constrain(name, values, reserve: nil, formatter: Formatter::DEFAULT)
+        constraint_map[name] = Constraint.new(name, values, reserve: reserve, formatter: formatter)
+      end
+
+      private
+
+      # @return [Hash<String, Constraint>]
+      def constraint_map
+        @constraint_map ||= {}
+      end
+    end
+
+    # Generate a puzzle with the provided configuration.
+    #
+    # The `objects` array is required. If `solution` and `terms` are not provided, they'll be randomly generated.
+    #
+    # @param objects [Array<Object>] The piece identifiers
+    # @param solution [Object] Which object to use as the solution
+    # @param terms [String, Array<String>, nil] The solution term(s)
+    # @param recur [String, Array<String>, nil] Recurring constraints (uniqueness never enforced)
+    def initialize(objects, solution: objects.sample, terms: nil, recur: nil)
+      @object_pieces = {}
+      @solution_terms = terms ? [terms].flatten : [constraints.map(&:name).sample]
+      @recur = recur ? [recur].flatten : []
+      objects.push solution unless objects.include?(solution)
+      generate_pieces objects, solution
+    end
+
+    # @return [Array<Premise>]
+    def premises
+      @premises ||= generate_all_premises
+    end
+
+    # @return [Array<Constraint>]
+    def constraints
+      self.class.constraints
+    end
+
+    # @param name [String]
+    # @return [Constraint, nil]
+    def constraint(name)
+      self.class.constraint name
+    end
+
+    # Get an array of values for a constraint.
+    # This method will only include values that are currently assigned to pieces.
+    #
+    # @return [Array<Object>]
+    def term_values(key)
+      # Use an intersection to retain the order in which the values were
+      # assigned to the constraint
+      constraint(key).values & pieces.map { |piece| piece.value(key) }
+    end
+
+    # The terms that should be used to identify the solution.
+    #
+    # @return [Array<String>]
+    attr_reader :solution_terms
+
+    def solution_term
+      raise 'Use `solution_terms` when there is more than one term' unless @solution_terms.one?
+
+      @solution_terms.first
+    end
+
+    # Shortcut to get the solution terms' values, e.g., "red"
+    #
+    # @return [Array<String>]
+    def solution_values
+      @solution_terms.map { |t| @solution.value(t) }
+    end
+
+    # Shortcut to get the solution term's value, e.g., "red"
+    #
+    # @raise [RuntimeError] if there is more than one solution term
+    # @return [String]
+    def solution_value
+      raise 'Use `solution_values` when there is more than one term' unless @solution_terms.one?
+
+      @solution.value(@solution_terms.first)
+    end
+
+    # Shortcut to get the solution terms' predicates, e.g., "is red"
+    #
+    # @return [Array<String>]
+    def solution_predicates
+      @solution_terms.map { |t| constraint(t).predicate(@solution.value(t)) }
+    end
+
+    # Shortcut to get the solution term's predicate, e.g., "is red"
+    #
+    # @return [String]
+    def solution_predicate
+      raise 'Use `solution_predicates` when there is more than one term' unless @solution_terms.one?
+
+      constraint(@solution_terms.first).predicate(@solution.value(@solution_terms.first))
+    end
+
+    # @return [Array<Logigram::Piece>]
+    def pieces
+      @object_pieces.values
+    end
+
+    # Get the piece associated with an object.
+    #
+    # @param object [Object] The object used to generate the piece
+    # @return [Logigram::Piece]
+    def piece_for(object)
+      @object_pieces[object]
+    end
+
+    private
+
+    # Generate the puzzle pieces.
+    #
+    # @param objects [Array<Object>]
+    # @param solution [Object]
+    # @return [void]
+    def generate_pieces(objects, solution)
+      selected_values = {}
+      solution_terms.each do |term|
+        selected_values[term] = constraint(term).reserves.sample
+      end
+      @solution = generate_piece(solution, selected_values, true)
+      objects.each do |o|
+        @object_pieces[o] = if o == solution
+                              @solution
+                            else
+                              generate_piece(o, selected_values, false)
+                            end
+      end
+    end
+
+    # @param object [Object]
+    # @param selected_values [Hash]
+    # @param selected [Boolean]
+    # @return [Piece]
+    def generate_piece(object, selected_values, selected)
+      constraint_repo = generate_constraint_repo(selected_values, selected)
+      terms = {}
+      constraint_repo.each_pair do |key, values|
+        raise "Unable to select value for constraint '#{key}'" if values.empty?
+
+        terms[key] = values.sample
+      end
+      Piece.new(object, terms)
+    end
+
+    # @param selected_values [Hash]
+    # @param selected [Boolean]
+    # @return [Hash]
+    def generate_constraint_repo(selected_values, selected)
+      repo = {}
+      # Setting a fixed term ensures that at least one solution term will not
+      # be duplicated by another piece
+      fixed_term = selected_values.keys.sample
+      constraints.each do |c|
+        repo[c.name] = if selected_values.key?(c.name)
+                         if selected
+                           [selected_values[c.name]]
+                         elsif c.name == fixed_term
+                           limit_available_values(c, selected_values[fixed_term], selected)
+                         else
+                           limit_available_values(c, nil, false)
+                         end
+                       else
+                         limit_available_values(c, nil, selected)
+                       end
+      end
+      repo
+    end
+
+    # @param constraint [Constraint]
+    # @param exception [String]
+    # @param selected [Boolean]
+    # @return [Array<String>]
+    def limit_available_values(constraint, exception, selected)
+      available = (selected ? constraint.reserves : constraint.values) - [exception]
+      filtered = available -
+                 [@solution&.value(constraint.name)] -
+                 (@recur.include?(constraint.name) ? [] : pieces.map { |p| p.value(constraint.name) })
+      filtered.empty? ? available : filtered
+    end
+
+    # Create an array of all possible premises for the puzzle.
+    #
+    # @return [Array<Logigram::Premise>]
+    def generate_all_premises
+      pieces.map { |pc| generate_piece_premises pc }.flatten
+    end
+
+    # Create an array of all possible premises for the specified piece.
+    #
+    # @param piece [Logigram::Piece]
+    # @return [Array<Logigram::Premise>]
+    def generate_piece_premises(piece)
+      result = []
+      piece.terms.each do |t|
+        # Positive specific
+        result.push Premise.new(piece, constraint(t), piece.value(t))
+        # Positive generic
+        (constraints - [constraint(t)]).each do |o|
+          result.push Premise.new(piece, constraint(t), piece.value(t), o)
+        end
+        # Negative specific
+        (term_values(t) - [piece.value(t)]).each do |o|
+          result.push Premise.new(piece, constraint(t), o)
+        end
+        # Negative generic
+        (term_values(t) - [piece.value(t)]).each do |o|
+          (constraints - [constraint(t)]).each do |id|
+            result.push Premise.new(piece, constraint(t), o, id)
+          end
+        end
+      end
+      result
+    end
+  end
+end

data/lib/logigram/challenge.rb

@@ -0,0 +1,132 @@
+module Logigram
+  # Use the Logigram::Challenge class to generate a list of clues from a
+  # puzzle.
+  #
+  # Challenges have three degrees of difficulty.
+  # - easy: all affirmative premises
+  # - medium: mixture of affirmative and negative premises
+  # - hard: one affirmative premise per constraint
+  #
+  class Challenge
+    # @return [Array<Logigram::Premise>]
+    attr_reader :clues
+
+    attr_reader :puzzle
+
+    # @param puzzle [Logigram::Base]
+    # @param difficulty [Symbol] :easy, :medium, :hard
+    def initialize(puzzle, difficulty: :medium)
+      @puzzle = puzzle
+      @clues = []
+      @term_values = {}
+      @difficulty = difficulty
+      generate_premises
+    end
+
+    private
+
+    def solution_constraints
+      @solution_constraints ||= @puzzle.solution_terms.map { |t| @puzzle.constraint(t) }
+    end
+
+    # @return [Array<Constraint>]
+    def unique_constraints
+      @unique_constraints ||= solution_constraints.select do |con|
+        value = @puzzle.solution.value(con.name)
+        @puzzle.pieces.select { |p| p.value(con.name) == value }.one?
+      end
+    end
+
+    # @return [Array<Constraint>]
+    def sorted_constraints
+      @sorted_constraints ||= begin
+        fixed_constraints = unique_constraints || [solution_constraints.sample]
+        other = (@puzzle.constraints - fixed_constraints).shuffle
+        first = other.shift
+        (first ? [first] : []) + other + fixed_constraints
+      end
+    end
+
+    # Remove a value from a term's availability list.
+    #
+    # @param term [String]
+    # @param value [String]
+    # @return [void]
+    def remove_value(term, value)
+      @term_values[term] ||= @puzzle.term_values(term)
+      @term_values[term].delete value
+    end
+
+    # Get a random value from a term's availability list.
+    #
+    # @param term [String]
+    # @param except [String, nil]
+    def sample_value(term, except: nil)
+      @term_values[term] ||= @puzzle.term_values(term)
+      # Try to eliminate the exception but allow it if it's the only option
+      (@term_values[term] - [except]).sample || @term_values[term].sample
+    end
+
+    # @return [void]
+    def generate_premises
+      last_constraint = nil
+      sorted_constraints[0..-2].each do |constraint|
+        shuffled_pieces = @puzzle.pieces.shuffle
+        shuffled_pieces[0..-2].each_with_index do |piece, index|
+          @clues.push generate_premise(piece, constraint, last_constraint, affirmation_at(index))
+        end
+        last_constraint = constraint
+      end
+      (@puzzle.pieces - [@puzzle.solution]).shuffle.each_with_index do |piece, index|
+        @clues.push generate_premise(piece, sorted_constraints.last, last_constraint, affirmation_at(index))
+      end
+      @clues = [@clues[0]] + @clues[1..-1].shuffle
+    end
+
+    # @param index [Integer]
+    # @return [Symbol]
+    def affirmation_at(index)
+      if @difficulty == :easy
+        :affirmative
+      elsif @difficulty == :medium
+        if index < @puzzle.pieces.length - 2
+          :affirmative
+        else
+          :random
+        end
+      elsif @difficulty == :hard
+        if index == 0
+          :affirmative
+        else
+          :negative
+        end
+      end
+    end
+
+    # @param piece [Logigram::Piece]
+    # @param constraint [Logigram::Constraint]
+    # @param identifier [Logigram::Constraint]
+    # @param affirm [Symbol] :affirmative, :negative, :random
+    def generate_premise(piece, constraint, identifier, affirm)
+      value = case affirm
+              when :affirmative
+                piece.value(constraint.name)
+              when :negative
+                sample_value(constraint.name, except: piece.value(constraint.name))
+              else
+                sample_value(constraint.name)
+              end
+      remove_value constraint.name, value
+      Logigram::Premise.new(piece, constraint, value, clarify(piece, identifier))
+    end
+
+    # @param piece [Piece]
+    # @param identifier [Constraint, nil]
+    def clarify(piece, identifier)
+      return nil unless identifier
+
+      total = @puzzle.pieces.select { |p| p.value(identifier.name) == piece.value(identifier.name) }
+      total.length == 1 ? identifier : nil
+    end
+  end
+end

data/lib/logigram/constraint.rb

@@ -0,0 +1,74 @@
+module Logigram
+  # Constraints describe features that puzzle pieces can possess. They are
+  # identified by name and have a finite set of possible values. When a puzzle
+  # is generated, its pieces are assigned a unique random value for each
+  # constraint.
+  #
+  class Constraint
+    # @return [String]
+    attr_reader :name
+
+    # All possible values for the constraint
+    #
+    # @return [Array<String>]
+    attr_reader :values
+
+    # The subset of values that can be applied to solutions. When a puzzle
+    # generates a solution, its value for the constraint should be one of the
+    # reserves. (By default, reserves are all possible values.)
+    #
+    # @return [Array<String>]
+    attr_reader :reserves
+
+    attr_reader :formatter
+
+    # @param name [String]
+    # @param values [Array] All possible values for the constraint
+    # @param reserve [Object, Array<Object>, nil] Values to reserve for solutions
+    # @param formatter [Formatter] Formatting rules
+    def initialize name, values, reserve: nil, formatter: Formatter::DEFAULT
+      @name = name
+      @values = values
+      @reserves = configure_reserves(reserve)
+      @formatter = formatter
+    end
+
+    # A noun form for the value, e.g., "the red thing"
+    #
+    # @return [String]
+    def subject value
+      validate value
+      formatter.subject(value)
+    end
+
+    # A verbal predicate for the value, e.g., "is red"
+    #
+    # @return [String]
+    def predicate value, quantity = 1
+      validate value
+      formatter.predicate(value, quantity)
+    end
+
+    # A negative verbal predicate form for the value, e.g., "is not red"
+    def negative value, quantity = 1
+      validate value
+      formatter.negative(value, quantity)
+    end
+
+    private
+
+    # @raise [ArgumentError] if the value is not valid
+    # @param value [String]
+    # @return [String]
+    def validate value
+      return value if values.include?(value)
+      raise ArgumentError, "Constraint for #{name} received invalid value #{value}"
+    end
+
+    # @param reserve [String, Array<Sting>, nil]
+    def configure_reserves(reserve)
+      return values unless reserve
+      [reserve].flatten.map { |v| validate(v) }
+    end
+  end
+end

data/lib/logigram/formatter/conjugations.rb

@@ -0,0 +1,15 @@
+module Logigram
+  class Formatter
+    CONJUGATIONS = {
+      be: ['is', 'are', 'is not', 'are not'],
+      drink: ['drinks', 'drink', 'does not drink', 'do not drink'],
+      eat: ['eats', 'eat', 'does not eat', 'do not eat'],
+      have: ['has', 'have', 'does not have', 'do not have'],
+      like: ['likes', 'like', 'does not like', 'do not like'],
+      live_in: ['lives in', 'live in', 'does not live in', 'do not live in'],
+      own: ['owns', 'own', 'does not own', 'do not own'],
+      play: ['plays', 'play', 'does not play', 'do not play'],
+      work_as: ['works as', 'work as', 'does not work as', 'do not work as']
+    }
+  end
+end

data/lib/logigram/formatter.rb

@@ -0,0 +1,67 @@
+require 'logigram/formatter/conjugations'
+
+module Logigram
+  # Rules for generating premise statements.
+  #
+  # @example Use the default rules, but refer to pieces as "objects" instead of "things"
+  #   Formatter.new(subject: 'the %{value} object')
+  #   # Example premise: "the green object is large"
+  #
+  # @example Use the default rules, except make the "be" conjugations past tense
+  #   Formatter.new(verb: ['was', 'were', 'was not', 'were not'])
+  #   # Example premise: "the red thing was small"
+  #
+  class Formatter
+    # @param subject [String]
+    # @param plural [String]
+    # @param verb [Symbol, Array<String>]
+    # @param descriptor [String]
+    def initialize subject: 'the %{value} thing', plural: "#{subject}s", verb: :be, descriptor: '%{value}'
+      @conjugations = validate_verb(verb)
+      @subject = subject
+      @plural = plural
+      @descriptor = descriptor
+    end
+
+    def subject value, amount = 1
+      (amount == 1 ? @subject : @plural) % {value: fix_article(value)}
+    end
+
+    def predicate value, amount = 1
+      "#{predicate_verb(amount)} #{@descriptor % {value: value}}"
+    end
+
+    def negative value, amount = 1
+      "#{negative_verb(amount)} #{@descriptor % {value: value}}"
+    end
+
+    private
+
+    def predicate_verb amount
+      amount == 1 ? @conjugations[0] : @conjugations[1]
+    end
+
+    def negative_verb amount
+      amount == 1 ? @conjugations[2] : @conjugations[3]
+    end
+
+    def fix_article(value)
+      return value unless @subject.include?('the %{value}')
+      value.to_s.sub(/^(a|an) /, '')
+    end
+
+    # @return [Array<String>]
+    def validate_verb verb
+      CONJUGATIONS[verb] ||
+        validate_conjugation(verb) ||
+        raise(ArgumentError, 'Verb must be a predefined infinitive or an array of verb forms')
+    end
+
+    # @return [Array<String>]
+    def validate_conjugation verb
+      return verb if verb.is_a?(Array) && verb.length == 4
+    end
+  end
+
+  Formatter::DEFAULT = Formatter.new
+end

data/lib/logigram/piece.rb

@@ -0,0 +1,38 @@
+module Logigram
+  class Piece
+    # @return [Object]
+    attr_reader :object
+
+    # @param object [Object]
+    # @param terms [Hash]
+    # @param name [String]
+    def initialize object, terms, name: nil
+      @object = object
+      @terms = terms
+      @name = name
+    end
+
+    def name
+      @name || object.to_s
+    end
+
+    # Get the value assigned to this piece for the specified term.
+    #
+    # @param term [String] The name of a constraint
+    # @return [Object]
+    def value term
+      @terms[term]
+    end
+
+    # The names of all the constraints associated with this piece.
+    #
+    # @return [Array<String>]
+    def terms
+      @terms.keys
+    end
+
+    def to_s
+      name
+    end
+  end
+end

data/lib/logigram/premise.rb

@@ -0,0 +1,111 @@
+module Logigram
+  # A premise is a fact about a puzzle piece. Puzzles use premises to provide
+  # clues.
+  #
+  # Examples of premises:
+  #
+  #   "Bob is short."
+  #   "Mary is not tall."
+  #   "The short person has red hair."
+  #
+  class Premise
+    # @return [Piece]
+    attr_reader :piece
+
+    # @return [Constraint]
+    attr_reader :constraint
+
+    # @return [String]
+    attr_reader :value
+
+    # @return [Constraint, nil]
+    attr_reader :identifier
+
+    # @param piece [Piece]
+    # @param constraint [Constraint]
+    # @param value [String]
+    # @param identifier [Constraint, nil]
+    def initialize(piece, constraint, value, identifier = nil)
+      @piece = piece
+      @constraint = constraint
+      @identifier = identifier
+      @value = value
+    end
+
+    # Determine if this premise refers to its piece specifically or uses an
+    # alternate identifier.
+    # A specific premise uses the piece's name for the subject, e.g., "Bob."
+    # The subject of an alternate premise is typically a description, e.g.,
+    # "The gray cat" or "The person with brown hair."
+    #
+    # @return [Boolean]
+    def specific?
+      identifier.nil?
+    end
+
+    # Determine if this is a generic premise.
+    # @see #specific?
+    def generic?
+      !specific?
+    end
+
+    # Determine if this is an affirmative premise.
+    # An affirmative premise is a fact, e.g., "The dog is red."
+    # A negative premise is a reduction, e.g., "The dog is not blue."
+    #
+    # @return [Boolean]
+    def affirmative?
+      piece.value(constraint.name) == value
+    end
+
+    # Determine if this is a negative premise.
+    # @see #affirmative?
+    #
+    # @return [Boolean]
+    def negative?
+      !affirmative?
+    end
+
+    # The name of the constraint for which this premise provides a fact.
+    # Example: for the premise `the dog is red`, the term is `color`.
+    #
+    # @return [String]
+    def term
+      constraint.name
+    end
+
+    # The subject is the puzzle piece for which this premise provides a fact.
+    # If the premise is `specific`, the subject is the piece's name. Otherwise
+    # the subject is a description of the piece based on the constraint being
+    # used as an `identifier`.
+    #
+    # Example: The premise's piece is named Bob. The puzzle's constraints
+    # include hair color. Bob's hair is red. If this premise is specific, the
+    # subject would be `Bob`. If the premise is not specific and its identifier
+    # is hair color, the subject would be `the person with red hair`.
+    #
+    # @return [String]
+    def subject
+      @subject ||= if identifier.nil?
+                     piece.name
+                   else
+                     identifier.subject(piece.value(identifier.name))
+                   end
+    end
+
+    # A human-readable representation of the premise, e.g., "The dog is red."
+    #
+    # @return [String]
+    def text
+      @text ||= if affirmative?
+                  "#{subject} #{constraint.predicate(value)}"
+                else
+                  "#{subject} #{constraint.negative(value)}"
+                end
+    end
+
+    def to_s
+      text
+    end
+  end
+end

data/lib/logigram/statistics.rb

@@ -0,0 +1,54 @@
+module Logigram
+  # A data summary about the pieces and premises of a puzzle.
+  #
+  # @param puzzle [Logigram::Base]
+  # @param subject [String]
+  # @param plural [String]
+  class Statistics
+    def initialize puzzle, subject: 'thing', plural: "#{subject}s"
+      @puzzle = puzzle
+      @subject = subject
+      @plural = plural
+    end
+
+    # @return [Hash]
+    def raw_data
+      @raw_data ||= generate_statistics
+    end
+
+    # @return [Array<String>]
+    def statements
+      @statements ||= generate_statements
+    end
+
+    private
+
+    def noun qty
+      qty == 1 ? @subject : @plural
+    end
+
+    def generate_statistics
+      stats = {}
+      @puzzle.constraints.each do |con|
+        values = {}
+        @puzzle.pieces.each do |pc|
+          values[pc.value(con.name)] ||= 0
+          values[pc.value(con.name)] += 1
+        end
+        stats[con.name] = values
+      end
+      stats
+    end
+
+    def generate_statements
+      lines = []
+      raw_data.each_pair do |key, values|
+        con = @puzzle.constraint(key)
+        values.each_pair do |val, qty|
+          lines.push "#{qty} #{noun(qty)} #{con.predicate(val, qty)}"
+        end
+      end
+      lines
+    end
+  end
+end

data/lib/logigram/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Logigram
+  VERSION = '0.1.0.pre'
+end

data/lib/logigram.rb

@@ -0,0 +1,8 @@
+require "logigram/version"
+require 'logigram/constraint'
+require 'logigram/piece'
+require 'logigram/formatter'
+require 'logigram/premise'
+require 'logigram/base'
+require 'logigram/challenge'
+require 'logigram/statistics'

data/logigram.gemspec

@@ -0,0 +1,36 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'logigram/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "logigram"
+  spec.version       = Logigram::VERSION
+  spec.authors       = ["Fred Snyder"]
+  spec.email         = ["fsnyder@castwide.com"]
+
+  spec.summary       = "A library for generating logic puzzles"
+  #spec.description   = %q{TODO: Write a longer description or delete this line.}
+  spec.homepage      = "http://castwide.com"
+  spec.license       = "MIT"
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  # if spec.respond_to?(:metadata)
+  #   spec.metadata['allowed_push_host'] = "TODO: Set to 'http://mygemserver.com'"
+  # else
+  #   raise "RubyGems 2.0 or newer is required to protect against " \
+  #     "public gem pushes."
+  # end
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency 'simplecov'
+end

data/test.rb

@@ -0,0 +1,42 @@
+require 'logigram'
+
+class Murder < Logigram::Base
+  constrain 'alibi', ['true alibi', 'false alibi', 'no alibi'], reserve: ['false alibi', 'no alibi']
+  constrain 'weapon', ['with weapon', 'without weapon'], reserve: ['with weapon']
+  constrain 'motive', ['motivated', 'motiveless'], reserve: ['motivated']
+  constrain 'proof', ['with proof', 'without proof'], reserve: ['with proof']
+  constrain 'knows', ['knows suspect', 'knows address', 'knows motive', 'knows nothing']
+end
+
+class Entity
+  attr_reader :name
+
+  def initialize(name)
+    @name = name
+  end
+
+  def to_s
+    name
+  end
+end
+
+characters = [
+  Entity.new('Bob'),
+  Entity.new('Joe'),
+  Entity.new('Tim'),
+  Entity.new('Dan'),
+  Entity.new('Hal')
+]
+
+puzzle = Murder.new(characters, recur: true, terms: %w[alibi weapon])
+
+# challenge = Logigram::Challenge.new(puzzle, difficulty: :easy)
+# challenge.clues.each do |clue|
+#   puts "#{clue.piece.name}, #{clue.value}"
+# end
+# puts challenge.puzzle.solution
+
+puzzle.premises.select(&:affirmative?).select(&:specific?).each do |premise|
+  puts "#{premise.piece}, #{premise.value}"
+end
+puts puzzle.solution

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: logigram
+version: !ruby/object:Gem::Version
+  version: 0.1.0.pre
+platform: ruby
+authors:
+- Fred Snyder
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-05-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description:
+email:
+- fsnyder@castwide.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- example.rb
+- lib/logigram.rb
+- lib/logigram/base.rb
+- lib/logigram/challenge.rb
+- lib/logigram/constraint.rb
+- lib/logigram/formatter.rb
+- lib/logigram/formatter/conjugations.rb
+- lib/logigram/piece.rb
+- lib/logigram/premise.rb
+- lib/logigram/statistics.rb
+- lib/logigram/version.rb
+- logigram.gemspec
+- test.rb
+homepage: http://castwide.com
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubygems_version: 3.3.7
+signing_key:
+specification_version: 4
+summary: A library for generating logic puzzles
+test_files: []