viewworkbook 0.1.3 → 0.3

data/doc/rst/viewworkbook.rst

@@ -11,28 +11,35 @@ viewworkbook <spreadsheet>
 
 DESCRIPTION
 =============
-Viewworkbook lets you read spreadsheet-files in text-mode, in a terminal
-window. It reproduces the tables which are contained in a spreadsheet file and
+ViewWorkbook allows you to read spreadsheet files in text mode in a terminal
+window. It reproduces the tables contained in a spreadsheet file and It also
 lets you navigate through the sheets. The visible part of a sheet is limited
-laterally and horizontally by the terminal-size but can be scrolled. You can
-adapt the width of table-columns, to render the table more readable and
-finally, if you wish, save tables to a text-file.  To the author of the
-program, the utility serves to take a quick glance at spreadsheets that are
-received via email, in the Mutt mail-client, which is itself a terminal
+laterally and horizontally by the size of the terminal, but you can scroll
+through it. You can adapt the width of table columns to make the table more
+readable.  Finally, you can save tables to a text file if you wish.  For the
+author of the program, the utility serves to quickly glance at spreadsheets
+that are received via email in the Mutt mail client, which is a terminal
 application.
 
-The supported spreadsheet formats are those which are handled by the Ruby-gem
-"**roo**" (February 2017):
+Supported spreadsheet formats are those handled by the Ruby gem "**roo**"
+(2024, roo 2.10.1):
   
-- Microsoft™'s **xls** and **xlsx**, 
+- Microsoft™  Excel 2007 - 2013 formats (**xlsx**, **xlsm**)
 
-- the OpenDocument spreadsheet **ods**
+- LibreOffice / OpenOffice.org formats (**ods**)
 
-- and the SoftMaker™ spreadsheet formats **pmd** and **pmdx**.
+- CSV
+
+- Microsoft™ Excel 97, Excel 2002 XML, and Excel 2003 XML formats (**xls**,
+  **xml**)
+
+Additionally also 
+
+- The SoftMaker™ spreadsheet formats **pmd** and **pmdx**.
 
 Options
 =============
-Other than the path to the spreadsheet file, viewworkbook does currently not
+Other than the path to the spreadsheet file, viewworkbook does not currently 
 interpret any command line arguments.
 
 Menu commands
@@ -52,72 +59,73 @@ below the current table:
 
 **value (v) * save to file (f) * sheet (s) * column (c) * up(i) * down(k) * left(j) * right(l) * quit (q) ***
 
-When you enter one of the hotkeys, a command can be executed directly (like "q"
-to terminate the program), a sub-menu may be shown (like with "c" which shall
-give you control on column properties) or you are confronted with an input
-invitation (like with "v", where you have to enter a cell-reference).  Read on
-for an explanation of each menu command.  
+When you press one of the hotkeys, you can execute a command directly (like "q"
+to terminate the program) or a submenu may appear (like with "c" which gives
+you control over column properties) or you may be prompted for input (like with
+"v", where you have to enter a cell reference).  Read on for an explanation of
+each menu command.  
 
   value (v) 
      display the value from a cell. This is useful, when columns are not wide
-     enough to show complete values.  After entering "**v**", you are
+     enough to show the full value.  After entering "**v**", you are
      immediately invited to enter a cell reference.  Cells are referenced in
-     the format "Column:Row", e.g. D:12 for the cell in column "D" and row
+     the format "column:row", e.g. D:12 for the cell in column "D" and row
      "12".
 
   save to file (f)
-     Save the current or all tables to a text file. The command does initially
-     show two alternative sub-commands:
+     Save the current table or all tables to a text file. Initially, the command 
+     shows two alternative sub-commands:
 
   Current sheet (c) * all sheets (a)
-     Independently of your choice, in the next step you will have to enter the
-     path to the output file.  You will be warned, if the file already exists
-     and may choose to either overwrite the existing file or name a different
-     one.
+     Regardless of your choice, you will be prompted to enter the output file
+     path in the next step. You will receive a warning, if the file already
+     exists at which point you can choose to either overwrite the existing file
+     or give it a different name.
 
   sheet (s) 
-     Navigate to a different sheet in the current workbook. You may choose
-     between a sheet-number and the name of a sheet. If you want to indicate
-     the next sheet **by name**, the list of all available names is first
-     shown. You just type right away the one that you want.
+     Navigate to a different sheet whthin the current workbook. You can choose
+     a sheet by its number or by its name. If you want to select the next sheet
+     **by name**, a list of available names will first be shown. You just type
+     the name you want.
 
   column (c)
-     Alter the properties of the table-columns.  At the time of this writing
-     (February 2017) the only property that can be changed, is the width of all
-     columns.  When you enter "**c**" the subcommand column width (w) is shown.
-     After entering "**w**" you can enter the desired width in characters.
+     Alter the properties of the table columns. As of February 2017 the only
+     property that can be changed, is the width of all columns.  When you enter
+     "**c**" the subcommand column width (w) is shown.  After entering "**w**"
+     you can enter the desired width in characters.
 
   Arrows(i, j, k, l) 
-     Navigate in a sheet that is too big to be displayed entirely at once.
-     These hotkeys correspond to the default navigation keys in the vi editor.
-
+     Use these hotkeys to navigate a sheet that is too big to be displayed
+     entirely at once. These hotkeys correspond to the default navigation keys
+     in the Vi editor.
+     
   quit (q) 
      Enter "**q**" to quit the program at any moment except when an input
      invitation is shown.
 
-Hidden (menu-)commands
-------------------------
-There is currently only one such command available:
-The **Escape-key** will interrupt an unfinished action and refresh the display.
+Hidden menu commands
+---------------------
+Currently, there is only one such command available. Pressing the **Escape
+key** will interrupt an unfinished action and refresh the display.
   
 Other Information
 =================
 
   Development and source code 
-   Viewworkbook 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**. 
+   Viewworkbook has been written in Ruby. Since Ruby is an interpreted programming
+   language, the executable file and all files to which it refers at any given time
+   are the source files of the current program version. You can open these
+   files in any text editor to examine 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 
-    Negative values are not always displayed, when very long (like 15 ciphers).
-    Enlarging the column-width further does not have an effect.
+    Negative values are not always displayed, when they are very long (like 15
+    ciphers). Increasing the column width further does not help.
 
   License 
-    Viewworkbook is distributed under the conditions of the GNU General Public
-    License, version 3.
+    Viewworkbook is distributed under the conditions of the WTFPL 2.0 or later,
+    see http://www.wtfpl.net/about/ for details
 
   Author 
     Viewworkbook has been developed by Michael Uplawski

data/lib/action.rb

@@ -1,46 +1,38 @@
 #encoding: UTF-8
-
 =begin
 /***************************************************************************
- *   Copyright © 2014, Michael Uplawski <michael.uplawski@uplawski.eu>     *
+ *   ©2016-2024, 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.                                   *
+ *   it under the terms of the WTFPL 2.0 or later, see                     * 
+ *   http://www.wtfpl.net/about/                                           *
  *                                                                         *
  *   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.                          *
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                  *
  *                                                                         *
- *   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 'logging'
+require_relative 'basic_logging'
 
 # An Action is executed on a user's request.
 # It has a name, an associated closure and hotkey.
 class Action
-  include Logging
+  include BasicLogging
 
   class ActionError < StandardError
   end
 
   attr_accessor :name, :key, :proc, :global, :hidden
 
+  # return a string representation of the action
   def to_s
     "[#<" << classname << ':' << hash << '@name="' << name << '", @key="' << key << '">'
   end
 
-
+  # create an action
   def initialize(options = {}, &b)
-    init_logger(STDOUT, Logger::INFO)
-
     @name = options[:name]
     @key = options[:key]
     @proc = b if b
@@ -48,6 +40,7 @@ class Action
     @hidden = options[:hidden]
   end
 
+  # execute te action
   def call(*args)
     unless @proc
       raise ActionError.new((@name ? '' : 'Unnamed ') << 'action' << (@name ? (' ' << @name) : '') << ' called before a command was defined')
@@ -55,3 +48,4 @@ class Action
     @proc.call(*args) 
   end
 end
+# Ω

data/lib/basic_logging.rb

@@ -0,0 +1,178 @@
+#!/bin/env ruby
+#encoding: UTF-8
+=begin
+/***************************************************************************
+ *   ©2023-2024, Michael Uplawski <michael.uplawski@uplawski.eu>           *
+ *                                                                         *
+ *   This program is free software; you can redistribute it and/or modify  *
+ *   it under the terms of the WTFPL 2.0 or later, see                     * 
+ *   http://www.wtfpl.net/about/                                           *
+ *                                                                         *
+ *   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.                  *
+ *                                                                         *
+ ***************************************************************************/
+=end
+
+#
+# Simplified logging. 
+# See example code at the bottom of this file.
+# Execute this file to see the output.
+#
+
+#require 'time'
+
+module BasicLogging
+
+  DEBUG = 0
+  INFO =  1
+  WARN =  2
+  ERROR = 3
+  FATAL = 4
+  UNKNOWN = nil
+  
+  # this is mainly for the translation of method calls into log levels
+  Levels = {:debug => DEBUG, :info => INFO, :warn => WARN, :error => ERROR,
+            :fatal => FATAL, :unknown => UNKNOWN}
+
+  @@log_level = UNKNOWN
+  @@target = STDOUT
+  @@muted = []
+
+  # do not log, if caller is obj (class or instance)
+  def self.mute(obj)
+    name = obj.class == Class ? obj.name.dup : obj.class.name
+    @@muted << name
+  end
+
+  def self.is_muted?(obj)
+    name = obj.class == Class ? obj.name.dup : obj.class.name
+    @@muted.include?(name)  
+  end
+
+  # set the log level 
+  def self::set_level(lv)
+    if lv.respond_to?(:to_str)
+      lv = Levels[lv.to_sym]
+    end
+    if(!lv || (lv.respond_to?(:to_int) && lv >= DEBUG && lv <= FATAL) )
+      @@log_level = lv
+    else
+      STDERR.puts __FILE__.dup << ": ERROR : invalid log level \"" << lv.to_s << "\""
+      STDERR.puts "Keepinng old log level " << Levels.keys.detect {| k| Levels[k] == @@log_level}.to_s
+    end
+  end
+
+  def set_level(lv)
+    BasicLogging::set_level(lv)
+  end
+
+  # set the log target 
+  def self::set_target(tg)
+    if tg.respond_to?(:to_io) 
+      @@target = tg
+    elsif(!File::exist?(tg) || ( File.file?(tg) && File.writable?(tg) ) )
+      @@target = File.open(tg, 'w+')  
+    else
+      STDERR.puts __FILE__.dup << ': ERROR : target ' << tg << ' cannot be set'
+      STDERR.puts "Keeping old target " << @@target.inspect
+      return
+    end
+  end
+
+  def set_target(tg)
+    BasicLogging::set_target(tg)
+  end
+
+  # Output of log messages, depending on the log level set for the calling class
+  # and the name of the alias method which is actually called.
+  def log(message)
+    if !BasicLogging.is_muted?(self)
+      # how has this method been called?
+      mlevel = __callee__
+      if Levels.has_key?(mlevel) && Levels[mlevel] <=  FATAL
+        # output only for levels equal or above the value that corresponds to
+        # the calling alias.
+        format_log( message, mlevel) if @@log_level && Levels[mlevel] >= @@log_level 
+      else
+        STDERR.puts __FILE__.dup << ": ERROR : invalid log level \"" << mlevel.to_s << "\""
+      end
+    end
+  end
+
+  alias :debug :log
+  alias :info :log
+  alias :warn :log
+  alias :error :log
+  alias :fatal :log
+
+  attr_reader :target, :log_level
+
+  private 
+
+  # 1 format_log for all loggers.
+  def format_log(message, mlevel)
+    # indicate if a registered class or the registered object of a class is calling.
+    name = self.class == Class ? self.name.dup << ' [class]' : self.class.name
+    @@target.puts '' << name << ' ' << mlevel.to_s << ' ' << Time.now.strftime("%H:%M:%S:%6N")  << ': ' << message
+  end
+end
+#---------test: execute file----------
+if $0 == __FILE__
+  Array.extend(BasicLogging)
+  Array.set_level(BasicLogging::INFO)
+  Array.info('TEST')
+  ar = Array.new
+  ar.extend(BasicLogging)
+  # --- no output : 
+  l = __LINE__
+  ar.debug(l.next.to_s << ': debug-test 0')
+  # output
+  ar.set_level(BasicLogging::DEBUG)
+  l = __LINE__
+  ar.debug(l.next.to_s << ': debug-test 1')
+
+  obj = Object.new
+  obj.extend(BasicLogging)
+  obj.set_level(BasicLogging::DEBUG)
+  puts "--------debug-----------"
+  obj.debug('debug')
+  obj.info('info')
+  obj.warn('warn')
+  obj.error('error')
+  obj.fatal('fatal')
+  puts "--------info-----------"
+  obj.set_level("info")
+  obj.debug('debug')
+  obj.info('info')
+  obj.warn('warn')
+  obj.error('error')
+  obj.fatal('fatal')
+  puts "--------fatal-----------"
+  obj.set_level("fatal")
+  obj.debug('debug')
+  obj.info('info')
+  obj.warn('warn')
+  obj.error('error')
+  obj.fatal('fatal')
+  puts "--------UNKNOWN-----------"
+  obj.set_level(nil)
+  obj.debug('debug')
+  obj.info('info')
+  obj.warn('warn')
+  obj.error('error')
+  obj.fatal('fatal')
+  puts " ------ Output into file ----"
+  obj.set_target "/tmp/test_log.log"
+  puts " ------ INFO -----------"
+  obj.set_level BasicLogging::INFO
+  obj.info('info output')
+
+  obj.info('info output 2') 
+  puts "---------- invalid -------"
+  obj.set_target "/dev/sr0"
+  obj.set_level "power"
+end
+
+# EOF 

data/lib/cell.rb

@@ -1,27 +1,19 @@
 #encoding: UTF-8
-
 =begin
 /***************************************************************************
- *   Copyright ©2016-2016, Michael Uplawski <michael.uplawski@uplawski.eu> *
+ *   ©2016-2024, 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.                                   *
+ *   it under the terms of the WTFPL 2.0 or later, see                     * 
+ *   http://www.wtfpl.net/about/                                           *
  *                                                                         *
  *   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.                          *
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                  *
  *                                                                         *
- *   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 'logging'
+require_relative 'basic_logging'
 require_relative 'row'
 require_relative 'column'
 
@@ -32,33 +24,37 @@ class Cell
   @@DEF_TYPE=Integer
   @@split_pattern = nil
 
-  self.extend(Logging)
-  @@log = self.init_logger
+  include BasicLogging
 
+  # create a cell in co:row and enter a value
   def initialize(row = nil, col = nil, value = nil)
-    @log = @@log
     @row = row if row
     @col = col if col
+    @debinfo = '(' << @col.number.to_s << ':' << @row.number.to_s << ') '
     @type_class = @@DEF_TYPE
     @value = value
     split_value
     set_limits
     @row.resize
-    @log.debug("cell.initialize, lines is #{@lines}, value is #{value}, ideal_width is #{@ideal_width}")
+    debug(@debinfo << "cell.initialize, lines is #{@lines}, value is #{value}, ideal_width is #{@ideal_width}")
   end
 
+  # returns self
   def to_cell()
     self
   end
 
+  # return a line from the cell
   def line(num = nil)
     num && num < @lines.length ? @lines[num].to_s : ' ' if @lines && !@lines.empty?
   end
 
+  # returns a string representation of the cell
   def to_s
     object_id.to_s << "{" << @row.number.to_s << ":" << @col.number.to_s << ", " << @lines.to_s << ", " << @ideal_height.to_s << ", " << @ideal_width.to_s << " }"
   end
 
+  # resizes the cell to its ideal value.
   def resize
     @@split_pattern = nil
     split_value
@@ -66,17 +62,20 @@ class Cell
     @row.resize
   end
 
+  # set the value of the cell
   def value=(value)
     @@split_pattern = nil
     @value = value
     split_value
-    @log.debug('after split_value, lines is ' <<  @lines.to_s)
+    debug(@debinfo << 'after split_value, lines is ' <<  @lines.to_s)
   end
 
+  # returns the column number of the cell
   def col
     @col.number
   end
-
+  
+  # returns the row number of the cell
   def row
     @row.number
   end
@@ -85,6 +84,9 @@ class Cell
 
   private
 
+  # handle long values in a way to make part of them
+  # visible, hide the remainder, if the cell ist too
+  # small.
   def split_value()
     # The regex may be used in many cells. Define on class-level.
     # And...
@@ -109,6 +111,7 @@ class Cell
     @row.resize
   end
 
+  # Determines the ideal height and width of the cell
   def set_limits
     if @lines && !@lines.empty?
       @ideal_height = @lines.length

data/lib/color_output.rb

@@ -1,5 +1,21 @@
 #encoding 'UTF-8'
 
+=begin
+/***************************************************************************
+ *   ©2016-2024, Michael Uplawski <michael.uplawski@uplawski.eu>           *
+ *                                                                         *
+ *   This program is free software; you can redistribute it and/or modify  *
+ *   it under the terms of the WTFPL 2.0 or later, see                     * 
+ *   http://www.wtfpl.net/about/                                           *
+ *                                                                         *
+ *   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.                  *
+ *                                                                         *
+ ***************************************************************************/
+=end
+
+
 # functions to apply colors to terminal output
 
 COLORS = {:default => 9, :black => 0, :red => 1, :green => 2, :yellow => 3, :blue => 4, :purple => 5, :cyan => 6, :white => 7 }

data/lib/column.rb

@@ -2,44 +2,37 @@
 
 =begin
 /***************************************************************************
- *   Copyright ©2016-2016, Michael Uplawski <michael.uplawski@uplawski.eu> *
+ *   ©2016-2024, 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.                                   *
+ *   it under the terms of the WTFPL 2.0 or later, see                     * 
+ *   http://www.wtfpl.net/about/                                           *
  *                                                                         *
  *   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.                          *
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                  *
  *                                                                         *
- *   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 'logging'
+require_relative 'basic_logging'
 
 # Objects of this class represent columns in a spreadsheet table
 
 class Column
-  self.extend(Logging)
-  @@log = self.init_logger
+  include BasicLogging
   @@DEF_WIDTH=15
   @@col_width=@@DEF_WIDTH
   @@columns = Array.new
   def initialize(number = nil)
-    @log = @@log
     @number = number
     @cells = Array.new
     @width = @@col_width
     @@columns << self
   end
-
+  
+  # add a cell to the column
   def add(cell)
     n_cell = nil
     if cell.respond_to?(:to_cell)
@@ -48,7 +41,7 @@ class Column
       n_cell = Cell.new( cell, @number) 
     else
       msg = 'For a new cell, a row-number must be specified'
-      @log.error(yellow(msg))
+      error(yellow(msg))
       raise StandardError(msg)
     end
     @cells.insert(n_cell.row, n_cell) 
@@ -56,29 +49,34 @@ class Column
     set_limits
   end
 
+  #  execute the block for each cell in the column
   def each(&b)
     @cells.each do |c|
       yield(c) 
     end
   end
 
+  # return the width of the column
   def self::col_width
     @@col_width
   end
 
+  # set the column width to w
   def self::col_width=(w)
     @@col_width = w
-    @log.debug("self::col_width=(#{w}), calling resize")
+    debug(@number.to_s << ' ' <<"self::col_width=(#{w}), calling resize")
 
     @@columns.each {|col| col.resize(w)}
   end
 
+  # resize the column to width
   def resize(width)
     @width = width
-    @log.debug('calling resize')
+    debug(@number.to_s << ' ' <<'calling resize')
     @cells.each {|cell| cell.resize}
   end
 
+  # returns a string representation of the column
   def to_s
     '<' << self.class.name.dup << ':' << object_id.to_s << "{number=%s width=%s cells.length=}>" %[@number, @cells.length]
   end
@@ -88,6 +86,7 @@ class Column
 
   private
 
+  # determine ideal width of the column
   def set_limits
     @ideal_width = @cells.max{|c1, c2| c1.ideal_width <=> c2.ideal_width}.ideal_width 
     @ideal_width ||= @@DEF_WIDTH