poefy 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c669c795f0aa86b7641c6b0246bf7af4c70a044c
-  data.tar.gz: 1d6b45c4c036677c7dcffa769576eac72e997d7c
+  metadata.gz: 2836cb70692fce83aa7c647d66d5165b786c2a4c
+  data.tar.gz: 359f87bf030ca881585f696d6bad29cf442e143d
 SHA512:
-  metadata.gz: 83b5d17cea7d870b77cd04ee06120f24ccd7b09fc4184472c1c9a893e0c9aeea64b9d255b9585515689ff06e19a1d9fe3cd841c1eda89d124a2807ff9b25a5c3
-  data.tar.gz: 58e698d002d74198bbd10fbea4a66f402a664e8d182a6c1c4ee2455b3829ad068b3de81437f03d8ad5d9ab76585ce79357de5179c795f356b539f8d543b9fea1
+  metadata.gz: 19f4e4e13177e712efce9919ad4f524a008c6cb257d81d39e3e43ad24b8397107d6265b06ed55da22ed7dafa8b010f4947a2e05251976f6206ff7c5c186be063
+  data.tar.gz: 9ef68d0b24110653b8d496be8f17618a5558697e426a024a78bb747b8943f2b137935fd1d456de81acd801b16c309166c0b935b917e4feb06e986dedb82bcffb

data/.gitignore

@@ -67,9 +67,6 @@ desktop.ini
 work*.rb
 /~/
 
-# Config files
-settings.yml
-
 # Data files
 /data/
 

data/README.md

@@ -1,11 +1,3 @@
-__Warning: This project is undergoing serious revision at the moment, and parts of this readme are invalid.__
-
-__For the correct documentation for the most recent gem version (0.6.1), please see the revision here:
-[README.md](https://github.com/nossidge/poefy/blob/fb4e39a88296074075a8ad1708e60747f3323baf/README.md)__
-
-__Version 1.0.0 is coming soon, with Postgres support as the major feature.__
-
-
 # Poefy
 
 by [Paul Thompson](https://tilde.town/~nossidge) - nossidge@gmail.com
@@ -17,6 +9,20 @@ Poems are created using a template to select lines from the database, according
 I wrote this because I was banging my head against a wall trying to use [Tracery](https://github.com/galaxykate/tracery) to generate villanelles. Then I remembered that I know how to program computers. Lucky!
 
 
+## Table of Contents
+* [Installation](#installation)
+  * [Install the base gem](#install-the-base-gem)
+  * [Install a database gem](#install-a-database-gem)
+    * [PostgreSQL](#postgresql)
+    * [SQLite](#sqlite)
+  * [Set up some example corpora](#set-up-some-example-corpora)
+* [Usage](#usage)
+  * [From the Command Line](#from-the-command-line)
+  * [As a Ruby Gem](#as-a-ruby-gem)
+* [Some tips](#some-tips)
+* [Sample output](#sample-output)
+
+
 ## Installation
 
 ### Install the base gem
@@ -33,11 +39,12 @@ You have two options when it comes to databases.
 
 Install [PostgreSQL 9.0+](https://www.postgresql.org/download/)
 
-Install the below gem.
+Install the gem, and let poefy know that you will be using 'pg'.
 
     $ gem install poefy-pg
+    $ poefy -D pg
 
-Create a new user:
+In your Postgres instance, create a new user:
 
     username: 'poefy'
     password: 'poefy'
@@ -53,9 +60,12 @@ Everything is called 'poefy'. Nice and easy.
 
 Install [SQLite 3.0+](https://sqlite.org/download.html)
 
-Just install the below gem. There is no further setup needed.
+Install the gem, and let poefy know that you will be using 'sqlite3'.
 
     $ gem install poefy-sqlite3
+    $ poefy -D sqlite3
+
+There is no further setup needed.
 
 
 ### Set up some example corpora
@@ -64,13 +74,6 @@ The repo comes with some initial text files included. To generate corpora for th
 
     $ poefy_make
 
-This command will also setup a `settings.yml` file in the gem root. By default it will be set to 'pg' or 'sqlite3', depending on which gem you installed. If you need to change that setting you can run either of the below:
-
-    $ poefy -D pg
-    $ poefy -D sqlite3
-
-You can use the `-D` option by itself without the argument to see the current database setting.
-
 
 ## Usage
 
@@ -107,7 +110,7 @@ You then need to use the `-l` option when generating poems:
     $ cd path/to
     $ poefy -l eliot.db ballata
 
-Note that using this option, you *do* need to specify the '.db' file extension of the chosen corpus.
+Note that using this option you must use the whole file name, i.e. "coleridge.db" and not just "coleridge".
 
 
 #### Option `-f` or `--form`
@@ -148,8 +151,8 @@ To view and amend these definitions, the code is in `lib/poefy/poetic_forms.rb`.
   double_dactyl: {
     rhyme:    'abcd efgd',
     indent:   '',
-    syllable: '[6,6,6,4,0,6,6,6,4]',
-    regex:    '{7=>/^\S+$/}'
+    syllable: '{0:6, 4m0:4}',
+    regex:    '{7: ^\S+$}'
   }
 }
 ```
@@ -197,30 +200,64 @@ If the string is comma delimited, all lines will be any of those numbers of syll
 
     $ poefy whitman sonnet -s'9,10,11'
 
+The above can also be written to use a range format:
+
+    $ poefy whitman sonnet -s'9-11'
+
 If the string is an array, each element corresponds to a line in the output. This will skip blank lines.
 
-Both of the below will generate limericks, with the second more permissive than the first.
+All of the below will generate limericks, with the latter ones more permissive than the first.
 
     $ poefy whitman -r'aabba' -s'[8,8,5,5,8]'
     $ poefy whitman -r'aabba' -s'[[8,9],[8,9],[4,5,6],[4,5,6],[8,9]]'
+    $ poefy whitman -r'aabba' -s'[8-9,8-9,4-6,4-6,8-9]'
 
-If the string is a hash, the key will be used to match the line number.
+If the string is a hash, the key will be used to match the line number. The underlying code that reads this uses YAML, but because the values will only be numbers we can be kinder with regards to key identifiers. So you can use `=>` or `:`, and they will be replaced with YAML's default `: ` (colon + space).
 
     $ poefy whitman -r'aabba' -s'{1:8,2:8,3:5,4:5,5:8}'
     $ poefy whitman -r'aabba' -s'{1:[8,9],2:[8,9],3:[4,5,6],4:[4,5,6],5:[8,9]}'
-    $ poefy whitman -r'aabba' -s'{0: [8,9],3: [4,5,6],4: [4,5,6]}'
-    $ poefy whitman -r'aabba' -s'{0=>[8,9],3=>[4,5,6],4=>[4,5,6]}'
-
-In the hash form, any lines not explicitly specified will use the value of the '0' key. If there is no '0' key, the lines will be ignored.
+    $ poefy whitman -r'aabba' -s'{1:[8,9],2:[8,9],3:4-6,4:4-6,5:[8,9]}'
+    $ poefy whitman -r'aabba' -s'{0: [8,9],3: [4,5,6],4: 4-6}'
+    $ poefy whitman -r'aabba' -s'{0=>[8,9],3=>[4,5,6],4=>4-6}'
 
-The below example will have 8 syllables for the first and fifth lines, but any number for the rest.
+The below example will have 8 syllables for the 1st and 5th lines, but any number for the rest.
 
     $ poefy whitman -r'aabba' -s'{1:8,5:8}'
 
+Any lines not explicitly specified will use the value of the '0' key (zero). If there is no '0' key, the lines will follow no constraints.
+
+The below example will have 8 syllables for the 1st and 5th lines, and 6 syllables for the rest.
+
+    $ poefy whitman -r'aabba' -s'{0:6,1:8,5:8}'
+
 The key of the hash can take the form of negative numbers. In that case, they will refer to lines from the end of the poem. Any duplicated keys will be overwritten by the latest one.
 
     $ poefy whitman -r'aabba' -s'{1:8,2:8,3:5,-2:5,-1:8}'
 
+You can use the special keys 'o' and 'e' to specify odd or even lines. This will ignore empty lines between stanzas (spaces in the rhyme string). The below example will have 8 syllables for the 1st and 3rd lines, 6 syllables for the 2nd and 4th, 6 syllables for the 5th, and 4 syllables for the 6th.
+
+    $ poefy whitman -r'ad bd cd' -s'{o:8,e:6,-2:6,-1:4}'
+
+A more advanced version of the above, you can use the letter 'm' to perform a [modulo operation][0] on the line number. This key takes the format `[divider]m[remainder]`. There's a few examples here, but it's not as complicated as it might at first seem.
+
+[0]: https://en.wikipedia.org/wiki/Modulo_operation
+
+If you have stanzas of 6 lines, to match the last line in each you can use the key `6m0`. This is because the line has a number of 6, 12, or 18, and those divide by 6 cleanly, leaving 0 as the remainder:
+
+    $ poefy whitman -r'abcdef abcdef abcdef' -s'{6m0:4}'
+
+To match the first two lines, use `6m1` and `6m2`:
+
+    $ poefy whitman -r'abcdef abcdef abcdef' -s'{6m1:4, 6m2:8}'
+
+This will give you stanzas of three lines, and longer syllable counts for the first line of each stanza:
+
+    $ poefy whitman -r'abb abb cdd cdd' -s'{0:4, 3m1:8}'
+
+This will create a [double dactyl](https://en.wikipedia.org/wiki/Double_dactyl):
+
+    $ poefy whitman -r'abcd efgd' -s'{0:6, 4m0:4}' -x'{7: ^\S+$}'
+
 Use zero `-s0` to specify no syllable matching.
 
 
@@ -230,14 +267,16 @@ Specify a regular expression for lines to follow.
 
 If the string is just one regex, all lines will be forced to match that regex.
 
-    $ poefy whitman sonnet -x'^[A-Z].*$'
-    $ poefy whitman sonnet -x'^[^e]*$' -s0
+    $ poefy whitman sonnet -x'^[A-Z]'
+    $ poefy whitman sonnet -x'^[^e]*$'
 
-If the string is a hash, the key will be used to match the line number. Unlike in the `syllable` string, you must use ruby's `=>` key identifier, and not `:` as in JSON. Also, you must put the regex inside `/slashes/`.
+If the string is a hash, you can use the same key types as with `syllable` string. Again, it will be parsed as YAML, but here we are more concerned about string substitution messing up the regex. So you have to use `: ` as the key identifier. Also, you must put the regex inside `'single'` or `"double"` quotes.
 
 Example, to ensure the first line always starts with capitalisation:
 
-    $ poefy whitman sonnet -x'{1=>/^[A-Z].*$/}'
+    $ poefy whitman sonnet -x'{1: "^[A-Z]"}'
+
+Unlike with the syllable option, you cannot use an array. You must use a single value or a hash. This is because the use of `[]` symbols in regular expressions confuses the parser, and I didn't want to forbid these common regex symbols. You can use hashes, but because of this you cannot use `{}` repetition matching in Poefy command line expressions. It's a pretty niche regex use though. You'll be fine without it.
 
 Use a space `-x' '` to specify no regex matching.
 
@@ -431,8 +470,8 @@ puts poefy.poem ({ rhyme: 'abab cdcd efef gg', indent: '0101 0101 0011 01' })
 puts poefy.poem ({ form: 'sonnet' })
 puts poefy.poem ({ form: :sonnet, syllable: 0 })
 puts poefy.poem ({ form: :sonnet, syllable: 10 })
-puts poefy.poem ({ form: :sonnet, regex: /^[A-Z].*$/ })
-puts poefy.poem ({ form: :sonnet, regex: '^[A-Z].*$' })
+puts poefy.poem ({ form: :sonnet, regex: /^[A-Z]/ })
+puts poefy.poem ({ form: :sonnet, regex: '^[A-Z]' })
 puts poefy.poem ({ form: :sonnet, acrostic: 'pauldpthompson' })
 puts poefy.poem ({ form: 'sonnet', indent: '01010101001101' })
 puts poefy.poem ({ form: 'sonnet', proper: false })

data/bin/poefy

@@ -23,6 +23,14 @@ def corpora
   end
 end
 
+# Create a new Poefy::Poem object, and catch any exceptions thrown.
+def poefy_new corpus, options = nil
+  Poefy::Poem.new corpus, options
+rescue Poefy::DatabaseError => e
+  STDERR.puts e.console_msg
+  exit 1
+end
+
 ################################################################################
 
 def parse_options
@@ -60,6 +68,7 @@ def parse_options
       poefy therese -r 'abab cdcd efef gg' -i '0101 0101 0011 01'
       poefy whitman -r 'A1bA2 abA1 abA2 abA1 abA2 abA1A2'
       poefy -Lc
+      poefy -f
     ].gsub('      ','       ')
 
     list = 'Corpora: ' + corpora.join("\n         ")
@@ -67,11 +76,15 @@ def parse_options
     opts.banner = program_info + "\n" + usage + "\n" + list + "\n\n"
 
     # These will be further validated within the class.
-    opts.on('-f', '--form STRING',
+    opts.on('-f', '--form [STRING]',
             "A named poetic form for the output\n" +
             ' ' * 37 + "Specifies rhyme, indent and syllable\n" +
             ' ' * 37 + "One of:\n" +
             ' ' * 39 + forms_by_4.join("\n" + ' ' * 39)) do |s|
+      if s.nil?
+        puts forms
+        exit 0
+      end
       options[:form] = s
     end
     opts.on('-r', '--rhyme STRING', "(See 'Description of rhyme string' below)") do |s|
@@ -107,8 +120,12 @@ def parse_options
             ' ' * 39 + "Defaults to ON -- Use this option to DISABLE") do
       options[:proper] = false
     end
+    opts.on('-c', '--capital',
+            "Capitalise the first letter of each line") do
+      options[:transform] = proc { |line| line.capitalize }
+    end
 
-    # Repeat options.
+    # Poem output options.
     opts.separator nil
     opts.on('-n', '--number INTEGER',
             "Number of poems to generate") do |n|
@@ -212,7 +229,14 @@ options[:form] = second_arg if second_arg != ''
 # If we need to make a corpus.
 # Exit the program after corpus is generated.
 if options[:make_corpus]
-  poefy = Poefy::Poem.new first_arg
+
+  # It's okay if there's an error with an existing database, because
+  # we're creating a new one. So we can swallow any errors here.
+  begin
+    poefy = Poefy::Poem.new first_arg
+  rescue Poefy::DatabaseError
+  end
+
   if data
     poefy.make_database data, options[:corpus_desc], true
     poefy.close
@@ -227,7 +251,7 @@ end
 # If we need to update a corpus description.
 # Exit the program after corpus is generated.
 if options[:corpus_desc]
-  poefy = Poefy::Poem.new first_arg
+  poefy = poefy_new first_arg
   begin
     poefy.corpus.desc = options[:corpus_desc]
     poefy.close
@@ -241,7 +265,7 @@ end
 # If the second argument is 'rhyme', then output all
 #   lines that rhyme with the word.
 if second_arg == 'rhyme'
-  poefy = Poefy::Poem.new first_arg
+  poefy = poefy_new first_arg
   third_arg  = (ARGV.length > 2) ? ARGV[2] : nil
   fourth_arg = (ARGV.length > 3) ? ARGV[3] : nil
   puts poefy.corpus.rhymes(third_arg, fourth_arg)
@@ -255,12 +279,25 @@ if data or File.exists?(second_arg)
 end
 
 # Create poefy object using the options.
-poefy = Poefy::Poem.new first_arg, options
+begin
+  poefy = poefy_new first_arg, options
+rescue Poefy::DatabaseError => e
+  STDERR.puts e.console_msg
+  exit 1
+end
 
 # Make the correct number of poems, and output them.
 number = options[:number] || 1
 number.times do |i|
-  poem = poefy.poem
+
+  # Exit the program if a Poefy error is raised.
+  begin
+    poem = poefy.poem
+  rescue Poefy::Error => e
+    STDERR.puts e.console_msg
+    exit 1
+  end
+
   if poem
     puts poem
     puts nil if i < number - 1

data/bin/poefy_make

@@ -15,6 +15,8 @@ Poefy.console = true
 # Determine which database interface to use, based on the gems installed.
 # Attempt to load exactly one of the below files.
 # Array is ordered by priority, so use PostgreSQL before SQLite.
+# (This code shouldn't really be necessary, unless the user has explicitly
+#   deleted their settings file.)
 def determine_database_interface
   loaded_file = nil
   [
@@ -22,21 +24,17 @@ def determine_database_interface
     'poefy/sqlite3'
   ].each do |file|
     begin
-      require_relative file
+      require file
       loaded_file = File.basename(file)
       break
     rescue LoadError
     end
   end
 
-  # Exit and send error to the console if no file loaded.
+  # Exit the program if no file loaded.
   if loaded_file.nil?
-    msg = "ERROR: Please specify the type of database to use." +
-        "\n       The 'poefy' gem does not implement a database interface" +
-        "\n       by default; you must install one of the below gems:" +
-        "\n         gem install poefy-sqlite3" +
-        "\n         gem install poefy-pg"
-    STDERR.puts msg
+    e = Poefy::MissingDBInterface.new
+    STDERR.puts e.console_msg
     exit 1
   end
 

data/lib/poefy/core_extensions/array.rb

@@ -13,6 +13,8 @@ module Poefy
     module Array
       module SortByDistance
       end
+      module ModuloIndex
+      end
     end
   end
 end
@@ -93,11 +95,27 @@ module Poefy::CoreExtensions::Array::SortByDistance
   end
 end
 
+#--
+# Define module methods.
+#++
+module Poefy::CoreExtensions::Array::ModuloIndex
+
+  ##
+  # Return elements located at specific index periods.
+  #
+  def modulo_index(divider, remainder = 0, start_index = 0)
+    self.values_at(* self.each_index.select do |i|
+      (i + start_index) % divider == remainder
+    end)
+  end
+end
+
 #--
 # Extend Array class.
 #++
 class Array
   include Poefy::CoreExtensions::Array::SortByDistance
+  include Poefy::CoreExtensions::Array::ModuloIndex
 end
 
 ################################################################################

data/lib/poefy/database.rb

@@ -7,7 +7,6 @@
 ################################################################################
 
 require_relative 'string_manipulation.rb'
-require_relative 'handle_error.rb'
 
 ################################################################################
 
@@ -16,7 +15,6 @@ module Poefy
   class Database
 
     include Poefy::StringManipulation
-    include Poefy::HandleError
 
     attr_reader :name, :local
 
@@ -49,7 +47,7 @@ module Poefy
           create_sprocs
         rescue
           @db = nil
-          return handle_error 'ERROR: Database contains invalid structure'
+          raise Poefy::StructureInvalid
         end
       end
       @db

data/lib/poefy/db_type.rb

@@ -27,35 +27,28 @@ module Poefy
       hsh = {'database' => db_name}
       file.write hsh.to_yaml
     end
+    @@database_type = nil
   end
   def self.database_type create_file = true
+    @@database_type ||= nil
+    return @@database_type if @@database_type
     settings_file = Poefy.root + '/settings.yml'
     if not File.exists?(settings_file)
       return nil if !create_file
       Poefy.database_type = 'pg'
     end
-    YAML::load_file(settings_file)['database']
+    @@database_type = YAML::load_file(settings_file)['database']
   end
 
   # Requires the chosen database interface gem.
   def self.require_db db_interface_gem = nil
     begin
+      @@database_type = db_interface_gem if db_interface_gem
       require 'poefy/' + (db_interface_gem || Poefy.database_type)
 
-    # Exit and send error to the console if no file loaded.
+    # Replace with custom exception.
     rescue LoadError
-      if loaded_file.nil?
-        msg = "ERROR: Please specify the type of database to use." +
-            "\n       The 'poefy' gem does not implement a database interface" +
-            "\n       by default; you must install one of the below gems:" +
-            "\n         gem install poefy-sqlite3" +
-            "\n         gem install poefy-pg"
-        if Poefy.console
-          STDERR.puts msg
-          exit 1
-        end
-        raise msg
-      end
+      raise Poefy::MissingDBInterface
     end
   end
 

data/lib/poefy/exceptions.rb

@@ -0,0 +1,123 @@
+#!/usr/bin/env ruby
+# Encoding: UTF-8
+
+################################################################################
+# Poefy exception hierarchy.
+# These errors have short messages for developers using the gem, and longer
+#   messages for end users who will be using the bin through the console.
+# If accessing through a console, all these errors are cause to exit.
+################################################################################
+
+module Poefy
+
+  class Error < StandardError
+    def console_msg
+      "ERROR: " + msg
+    end
+    def initialize short_message, console_message = nil
+      super short_message
+    end
+  end
+
+  ##############################################################################
+
+  class InputError < Error
+  end
+
+  class MissingFormOrRhyme < InputError
+    def msg
+      "No valid rhyme or form input specified"
+    end
+    def console_msg
+        "ERROR: No valid rhyme or form option specified." +
+      "\n       Try again using the -f or -r option." +
+      "\n       Use -h or --help to view valid forms."
+    end
+    def initialize
+      super msg, console_msg
+    end
+  end
+
+  class RhymeError < InputError
+    def msg
+      "Rhyme input is not valid"
+    end
+    def initialize
+      super msg
+    end
+  end
+
+  class SyllableError < InputError
+    def msg
+      "Syllable input is not valid"
+    end
+    def initialize short_message = msg
+      super short_message
+    end
+  end
+
+  class RegexError < InputError
+    def msg
+      "Regular expression input is not valid"
+    end
+    def initialize short_message = msg
+      super short_message
+    end
+  end
+
+  ##############################################################################
+
+  class GenerationError < Error
+  end
+
+  class NotEnoughData < GenerationError
+    def msg
+      "Not enough rhyming lines in the input"
+    end
+    def initialize console_message = nil
+      super msg, console_message
+    end
+  end
+
+  ##############################################################################
+
+  class DatabaseError < Error
+  end
+
+  class MissingDatabase < DatabaseError
+    def msg
+      "Database does not exist"
+    end
+    def initialize
+      super msg
+    end
+  end
+
+  class StructureInvalid < DatabaseError
+    def msg
+      "Database contains invalid structure"
+    end
+    def initialize console_message = nil
+      super msg, console_message
+    end
+  end
+
+  class MissingDBInterface < DatabaseError
+    def msg
+      "Database interface not specified"
+    end
+    def console_msg
+        "ERROR: Please specify the type of database to use." +
+      "\n       poefy does not implement a database interface by" +
+      "\n       default; you must install one of the below gems:" +
+      "\n         gem install poefy-sqlite3" +
+      "\n         gem install poefy-pg"
+    end
+    def initialize
+      super msg, console_msg
+    end
+  end
+
+end
+
+################################################################################