timequiz 0.1.3

data/doc/rst/timequiz.rst

@@ -0,0 +1,156 @@
+=======================
+ TIMEQUIZ
+=======================
+----------------------------------------
+ play a history quiz game
+----------------------------------------
+
+SYNOPSIS
+=======================
+timequiz [options]
+
+Called without any option, the game is started with the events that are included
+in the installed program package. There are not many.
+
+DESCRIPTION
+=======================
+The general idea is to put historical events in the right order. In the
+beginning, a limited number of events (3 at the time of this writing) is
+presented and you have to indicate the right order of these events. All the
+following rounds will confront you with just 1 additional event and you must
+find for the new event the right spot in the previously ordered list, i.e.
+after one of the listed events or earlier than any of the known events. After
+each round, the first one inclusive, your performance is evaluated. You can
+then choose to continue with a new event or, if you like, read a short
+description of any of the events, already in the list.
+
+The game continues in this way until you push the 'q' button to quit or until
+all the events that are known to the game, are listed.
+
+You do not need to know it all
+--------------------------------
+Beware that to win a round, it is oftentimes not necessary to really know the
+date of an event. Pure logic and reasonable guesses may be sufficient to find
+the right spot within a historical context or to exclude events as too far in
+the past or future of the currently handled event. Reading the descriptive
+comments to an event may later help you get different events into context.
+
+OPTIONS
+=======================
+**-a, --add**                       Add a new event
+
+**-e, --event** [EVENT]             Name of the new event
+
+**-y, --year** [YEAR]               Year of the new event
+
+**-b, --background** [INFO]         Background information for the new event
+
+**-f, --file** [FILE]               The file, where events are read from or written to
+
+**-d, --debug**                     Be verbose
+
+**-v, --version**                   Show program version
+
+**-h, --help**                      Show a help text
+
+The Options in detail:
+----------------------
+-a --add
+  This option imposes that -e, -y, and -f be given, too. In consequence, it
+  will be considered superfluous and removed in future versions of the program.
+
+-e --event
+  Name the event to add to the events-file. For this option to take effect, -a,
+  -y and -f are needed, too. Beware to enclose the value with quotes, like in, e.g.
+  --event "Some guy was born and something broke"
+
+-y --year
+  Is followed by a year, like -y 1244
+
+-b --background
+  Should be used to provide background-information to an event. While this
+  option is ... optional, the information will help solving quizzes and may be
+  educative to the player... do not abuse, though.
+  Example: -b "The phenomenon was bearing no significance whatsoever"
+
+-f --file
+  Name the “events-file” which will be used for either creating the quizzes
+  randomly or adding events to an existing list of events. The file must be
+  readable to serve for a quiz and writable to accept new events. If it does
+  not exist, it is created and some exemplary events are included on top.
+  Example: --file ~/my_history_quiz
+
+-d --debug
+  Be verbose. This switches on the output of debug-messages that have been left
+  in the program code. Probably useless.
+
+-v --version
+  Shows the program version
+
+-h --help
+  Shows the option-summary.
+  
+  
+GAME EXAMPLE
+=======================
+Calling timequiz without arguments on the command-line, you are confronted with
+three arbitrary, historical events, like in the following screen:
+
++---------------------------------------------------------------------------+
+|Put the following events into the right chronological order (e.g.: 2 3 1). |
+|                                                                           |
+|1) The Roman emperor Diocletian devides the empire in two                  |
+|2) End of the "War of the mercenaries"                                     |
+|3) Destruction of Nimrod and Ninive by the Medians and Neo-Babylonians     |
+|                                                                           | 
+|Available: 1, 2, 3)                                                        |
++---------------------------------------------------------------------------+
+
+You type in the three numbers in the order that you consider chronologically
+correct, like "321" (you do not have to push return after each number). The
+game will respond by showing you the correct order of events with the
+corresponding years and an evaluation of your input. You are also prompted to
+decide if you want to play with a new arbitrary event or first be shown some
+information about the listed events:
+
++------------------------------------------------------------------------------------------------------+
+|Enter number for more information about an event, 'a' to play with one new, random event, 'q' to quit.|
++------------------------------------------------------------------------------------------------------+
+
+If you push 'a', a new event is shown:
+
++----------------------------------------------------------------------------------------------------------+
+|Indicate the event from the previous list, which precedes the following, or '0' (zero) to put it in front:|
+|                                                                                                          |
+|The Italian painter Lorenzo Lotto dies.                                                                   |
++----------------------------------------------------------------------------------------------------------+
+
+You can now decide, which of the three previous events precedes the death of
+the Italian painter and either put in the (current) number of that previous
+event or the number 0 (zero) if you consider that Lorenzo Lotto died well
+before any of the other events (which would, of course, be false in the
+example).  You have to push the return-button after your input, as it can
+contain an arbitrary number of ciphers, later in the game.
+ 
+Other Information
+====================
+Development and source code
+  timequiz has been written in Ruby. As Ruby is an interpreted programming
+  language, the executable file and all those that it may refer to at one point
+  in time, are themselves the source-files of the current program-version. You
+  can open them in any text-editor to scrutinize the source-code. If you have
+  received the program as a Ruby-gem, you can also decompress a copy of the
+  gem-file with *tar -x*, then *tar -xzf*. 
+
+Bugs
+  At one time during the game, the list of already known events is incorrectly
+  wrapped and continues to be.
+
+License
+  timequiz is distributed under the conditions of the GNU General Public
+  License, version 3.
+
+Author
+  timequiz has been developed by Michael Uplawski
+  <michael.uplawski@uplawski.eu>
+

data/lib/adder.rb

@@ -0,0 +1,74 @@
+#!/usr/bin/env ruby 
+#encoding: UTF-8
+
+=begin
+/******************************************************************************
+ *   Copyright © 2017-2017, Michael Uplawski <michael.uplawski@uplawski.eu>   *
+ *                                                                            *
+ *   This program is free software; you can redistribute it and/or modify     *
+ *   it under the terms of the GNU General Public License as published by     *
+ *   the Free Software Foundation; either version 3 of the License, or        *
+ *   (at your option) any later version.                                      *
+ *                                                                            *
+ *   This program is distributed in the hope that it will be useful,          *
+ *   but WITHOUT ANY WARRANTY; without even the implied warranty of           *
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the            *
+ *   GNU General Public License for more details.                             *
+ *                                                                            *
+ *   You should have received a copy of the GNU General Public License        *
+ *   along with this program; if not, write to the                            *
+ *   Free Software Foundation, Inc.,                                          *
+ *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.                *
+ ******************************************************************************/
+=end
+
+require_relative 'constants'
+require_relative 'logging'
+
+class Adder
+  #@@events_file = File.dirname(__FILE__) << File::Separator << 'events.rb'
+  #@@events_backup = File.dirname(__FILE__) << File::Separator << 'bak_events.rb'
+  self::extend(Logging)
+  @@log = self::init_logger
+  # Do not present as 'Adder' on the command-line
+  self::log_label=$APPNAME
+
+  def self::add(options) 
+    @log.debug('options are ' << options.to_s)
+    if options.file
+      @@events_file = options.file
+      @@events_backup = File.dirname(@@events_file) << File::Separator << 'bak_' << File.basename(@@events_file)
+    else
+      @log.error('To add events, you must name a file on the command-line. Aborting')
+      exit false
+    end
+    if(!options.event || !options.year)
+      @log.error("To add events, you must provide them on the command-line.\n\tPSE start the program with option -h or --help to see an option-overview.")
+      exit false
+    end
+
+    @@log.level = $LOG_LEVEL if $LOG_LEVEL 
+    fields = [:event, :year, :background]
+    @log.debug('options are ' << options.to_s)
+    if options[:event] && options[:year]
+      if !options[:background]
+        @log.warn('Optional background information is missing')
+        bg = ''
+      else
+        bg = options.background
+      end
+
+      ev_def = "$events << [\"" << options.event << "\", " << options.year << ", \"" << bg << "\"]" 
+      @log.debug('writing events-backup to ' << @@events_backup)
+      File.open(@@events_backup, 'w+') {|bak| bak.write( File.read(@@events_file))}
+      @log.debug('adding new event to the list: ' << ev_def)
+      File.open(@@events_file, 'a') {|evf| evf.puts(ev_def)}
+      @log.info('A new event has been added to ' << @@events_file << '.')
+    else
+      opts = options.to_h.keys
+      @log.error('Option missing: ' << fields.each {|f| opts.delete(f) }.join(', '))
+      exit false
+    end
+  end
+end
+

data/lib/argparser.rb

@@ -0,0 +1,85 @@
+#encoding: UTF-8 
+=begin
+/***************************************************************************
+ *   ©2016-2017 Michael Uplawski <michael.uplawski@uplawski.eu>            *
+ *                                                                         *
+ *   This program is free software; you can redistribute it and/or modify  *
+ *   it under the terms of the GNU General Public License as published by  *
+ *   the Free Software Foundation; either version 3 of the License, or     *
+ *   (at your option) any later version.                                   *
+ *                                                                         *
+ *   This program is distributed in the hope that it will be useful,       *
+ *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
+ *   GNU General Public License for more details.                          *
+ *                                                                         *
+ *   You should have received a copy of the GNU General Public License     *
+ *   along with this program; if not, write to the                         *
+ *   Free Software Foundation, Inc.,                                       *
+ *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
+ ***************************************************************************/
+=end
+
+
+require 'optparse'
+require 'optparse/time'
+require 'ostruct'
+require_relative 'logging'
+# require_relative 'translating'
+require_relative 'constants'
+
+class ArgParser 
+  # Class level logger. This is a static class. 
+  self.extend(Logging)
+  # self.extend(Translating)
+  @@log = init_logger()
+
+  # Returns a structure describing the options.
+  #
+  def self.parse(args)
+    # The options specified on the command line will be collected in
+    # <b>options</b>.  No defaults. Most options are optional and do not
+    # have to be set at all.
+    # The others must be named for each transformation or be set in the
+    # configuration-file.
+    options = OpenStruct.new
+
+    op = OptionParser.new do |opts|
+     opts.on("-a", "--add", 'Add new event') do  
+        options.add = 'add'
+      end
+
+      opts.on("-eEVENT", "--event=EVENT", 'Name of the event') do |ev|
+        options.event = ev
+      end
+      opts.on("-yYEAR", "--year=YEAR", 'Year of the event') do |year|
+        options.year = year
+      end
+      opts.on("-bINFO", "--background=INFO", 'Background information') do  |info|
+        options.background = info
+      end
+      opts.on("-fFILE", "--file=FILE", 'The file, where events are read from') do  |file|
+        options.file = file
+      end
+        opts.on("-d", "--debug", 'Be verbose') do  
+        options.debug = 'debug'
+      end
+      opts.on("-v", "--version", 'Show program version') do  
+        puts $APPNAME.dup << ", version " << $VERSION
+        exit true
+      end
+   end
+    begin
+      op.parse!(args)
+    rescue OptionParser::ParseError => er
+      msg = "ERROR! Unsuitable or incomplete program-arguments" << ": %s" %er.message	
+      puts msg
+      puts "Start this program with parameter -h or --help to see the usage-message."
+      exit false
+    end
+
+    options
+  end  # parse()
+
+end  
+

data/lib/busy_indicator.rb

@@ -0,0 +1,104 @@
+#encoding: UTF-8
+
+=begin
+/******************************************************************************
+ *   Copyright © 2014-2017, Michael Uplawski <michael.uplawski@uplawski.eu>   *
+ *                                                                            *
+ *   This program is free software; you can redistribute it and/or modify     *
+ *   it under the terms of the GNU General Public License as published by     *
+ *   the Free Software Foundation; either version 3 of the License, or        *
+ *   (at your option) any later version.                                      *
+ *                                                                            *
+ *   This program is distributed in the hope that it will be useful,          *
+ *   but WITHOUT ANY WARRANTY; without even the implied warranty of           *
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the            *
+ *   GNU General Public License for more details.                             *
+ *                                                                            *
+ *   You should have received a copy of the GNU General Public License        *
+ *   along with this program; if not, write to the                            *
+ *   Free Software Foundation, Inc.,                                          *
+ *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.                *
+ ******************************************************************************/
+=end
+
+# BusyIndicator provides a way to show 'activity' in a terminal-window, while
+# the main thread does something else. For a usage example see the test-code at
+# the bottom of this file and execute the file (e.g. ruby ./busy_indicator.rb)
+class BusyIndicator
+  attr_writer :width
+  def initialize(start = true, width = nil)
+    # defaults
+    @width = width && width >= 3 ? width : 3
+    @sequence = %w"OOO ooo ___ ooo"
+    run if start
+  end
+
+  # change sequence for the following run().
+  def sequence=(seq)
+    @sequence = seq
+    @width = seq[0].length
+  end
+
+  # start busy-indicator with the current settings for width and sequence.
+  def run() 
+    @thr = busy_indicator(@width) if !@thr || !@thr.alive?
+  end
+
+  # stop busy-indicator and show comment-string if given.
+  def stop(comment = nil)
+    @thr.terminate
+    @thr.join(0.1)
+    print ("\b" * @width)
+    print ("%+#{@width}s\n" %comment) if comment
+  end
+
+  # returns true or false, so that !stopped? == running?.
+  def running?
+    @thr.alive?
+  end
+
+  # returns true or false, so that !stopped? == running?.
+  def stopped?
+    !running?
+  end
+
+  private
+  
+  # does it.
+  def busy_indicator(width)
+    tobj = Thread.new() do
+      loop do 
+        @sequence.each do |s|
+          print "%+#{width}s" %s
+          sleep 0.1
+          print ("\b" * width)
+        end
+      end
+    end
+  end
+end
+
+# ========== TEST =============
+if($0 == __FILE__)
+  width = 20
+  2.times do |i|
+    puts "I am busy, pse wait..."
+    thr = BusyIndicator.new(true, width)
+    sleep 3
+    # effect of comment != nil and comment == nil
+    thr.stop("Okay") if i == 0
+    thr.stop() if i != 0
+  end
+  bi = BusyIndicator.new(false)
+  # change sequence
+  bi.sequence = %w"E [ ( | ¦ ; , . o O D P F"
+  bi.run
+  sleep 3
+  bi.stop("Stopped")
+  # change width
+  bi.width = 8
+  bi.run
+  sleep 3
+  bi.stop("stopped again")
+end
+

data/lib/color_output.rb

@@ -0,0 +1,73 @@
+#encoding: UTF-8
+
+=begin
+/******************************************************************************
+ *   Copyright © 2014-2017, Michael Uplawski <michael.uplawski@uplawski.eu>   *
+ *                                                                            *
+ *   This program is free software; you can redistribute it and/or modify     *
+ *   it under the terms of the GNU General Public License as published by     *
+ *   the Free Software Foundation; either version 3 of the License, or        *
+ *   (at your option) any later version.                                      *
+ *                                                                            *
+ *   This program is distributed in the hope that it will be useful,          *
+ *   but WITHOUT ANY WARRANTY; without even the implied warranty of           *
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the            *
+ *   GNU General Public License for more details.                             *
+ *                                                                            *
+ *   You should have received a copy of the GNU General Public License        *
+ *   along with this program; if not, write to the                            *
+ *   Free Software Foundation, Inc.,                                          *
+ *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.                *
+ ******************************************************************************/
+=end
+
+# Functions to apply colors to terminal output.
+# This is stolen from the Internet and I have lost track of my own additions
+# and modifications.
+
+COLORS = {:default => 9, :black => 0, :red => 1, :green => 2, :yellow => 3, :blue => 4, :purple => 5, :cyan => 6, :white => 7 }
+
+BG = 4
+FG = 3
+REGULAR = 0
+BOLD = 1
+UNDERLINE = 4
+BLINK = 5
+SWAP = 7
+NEUTRAL = 0
+
+STYLES = {:regular => REGULAR, :bold => BOLD, :underline => UNDERLINE, :blink => BLINK, :swap => SWAP, :neutral => NEUTRAL}
+
+# Colorizes the given text. Color-code is either an escape-sequence or one of
+# the symbols representing color-names in the COLORS hash.
+def colorize(text, color_code)
+  if (COLORS.keys.include?(color_code) )
+    "\033[3#{COLORS[color_code]}m#{text}\033[0m"
+  else
+    "#{color_code}#{text}\033[0m"
+  end
+end
+
+def style(text, style_code)
+  "#{style_code}#{text}\033[0m"
+end
+# a function which allows to manipulate every known aspect of the ansi-output.
+def colored_output(output_text, fg_color = :default, bg_color = :default, style = :regular , mode = :neutral )
+  "\033[%i;%i;%i%i;%i%im%s\033[0m" %[STYLES[mode.to_sym], STYLES[style.to_sym], FG, COLORS[fg_color.to_sym], BG, COLORS[bg_color.to_sym], output_text]
+end
+
+# convenience functions
+def red(text); colorize(text, "\033[31m"); end
+def green(text); colorize(text, "\033[32m"); end
+def yellow(text); colorize(text, "\033[33m"); end
+def purple(text); colorize(text, "\033[35m"); end
+def cyan(text); colorize(text, "\033[36m"); end
+def blue(text); colorize(text, "\033[34m"); end
+def white(text); colorize(text, "\033[37m"); end
+
+def black_on_white(text); colorize(colorize(text, "\033[30m"), "\033[47m");end
+def white_on_black(text); colorize(colorize(text, "\033[37m"), "\033[40m");end
+
+def bold(text); style(text, "\033[01m");end
+def underline(text); style(text, "\033[04m");end
+