viewworkbook 0.2 → 1.0

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,75 +59,87 @@ 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
     <michael.uplawski@uplawski.eu>
 
+This document
+-------------
+.. _CC By-ND 4.0: https://creativecommons.org/licenses/by-nd/4.0/
+.. |date| date::
+
+©Michael Uplawski <michael.uplawski@uplawski.eu>
+
+License: `CC BY-ND 4.0`_
+
+Date: |date|
+
 **Ω**

data/lib/action.rb

@@ -26,13 +26,13 @@ class Action
 
   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)
-
     @name = options[:name]
     @key = options[:key]
     @proc = b if b
@@ -40,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')
@@ -47,3 +48,4 @@ class Action
     @proc.call(*args) 
   end
 end
+# Ω

data/lib/cell.rb

@@ -26,6 +26,7 @@ class Cell
 
   include BasicLogging
 
+  # create a cell in co:row and enter a value
   def initialize(row = nil, col = nil, value = nil)
     @row = row if row
     @col = col if col
@@ -38,18 +39,22 @@ class Cell
     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
@@ -57,6 +62,7 @@ class Cell
     @row.resize
   end
 
+  # set the value of the cell
   def value=(value)
     @@split_pattern = nil
     @value = value
@@ -64,10 +70,12 @@ class Cell
     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
@@ -76,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...
@@ -100,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/column.rb

@@ -31,7 +31,8 @@ class Column
     @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,29 +49,32 @@ 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
-    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
     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
@@ -80,6 +84,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

data/lib/menu.rb

@@ -22,7 +22,6 @@ require_relative 'user_input'
 
 # Shows options that the user can choose from.
 # Options may be associated with sub-menus.
-
 class Menu 
   include BasicLogging
 
@@ -33,6 +32,7 @@ class Menu
   @@global_elements = []
   @@hidden_elements = []
 
+  # create the menu
   def initialize(options = {})
     @elements = [] 
     if(options && !options.respond_to?(:to_hash) )
@@ -42,10 +42,12 @@ class Menu
     @key = options[:key] if options[:key]
   end
 
+  # display menu
   def call(*args)
     show()
   end
 
+  # add an action or sub menu to the menu
   def add(element, pos = nil)
     if(element.respond_to?(:call))
       if(pos)
@@ -67,6 +69,7 @@ class Menu
   end
 
   private
+  # display menu and react to user input.
   def show()
     @elements.each do |ele|
       name = ele.name.downcase

data/lib/row.rb

@@ -28,6 +28,7 @@ class Row
     @height = 1
   end
 
+  # add a cell to the row
   def add(cell)
     n_cell = nil
     if cell.respond_to?(:to_cell)
@@ -44,12 +45,15 @@ class Row
     resize()
   end
 
+  # execute block on each cell in the row
   def each(&b)
     @cells.each do |c|
       yield(c) 
     end
   end
 
+  # adapt the height of the row to the ideal height of the
+  # highest cell 
   def resize()
     if(@cells && ! @cells.empty? )
       if(@cells.length == 1 )
@@ -62,6 +66,7 @@ class Row
     @height ||= @@DEF_HEIGHT
   end
 
+  # returns a string representation of the row
   def to_s
     '#<' << self.class.name << ':' << object_id.to_s << "{number=%s height=%s cells.length=%s}" %[@number.to_s, @height.to_s, @cells.length.to_s] 
   end

data/lib/sheetdata.rb

@@ -2,7 +2,7 @@
 
 =begin
 /***************************************************************************
- *   ©2016-2024, Michael Uplawski <michael.uplawski@uplawski.eu>           *
+ *   ©2016-2025, 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                     * 
@@ -21,7 +21,6 @@ require 'roo-xls'
 
 require_relative 'basic_logging'
 
-# Transforms a file into a Roo spreadsheet instance.
 
 ODS_Magic  = "OpenDocument Spreadsheet"
 XLS_Magic  = "Composite Document File V2 Document"
@@ -36,6 +35,9 @@ CSV_MIME  = "text/plain"
 # SoftMaker Office
 PMDX_MIME = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
 
+=begin
+Transforms a file into a Roo spreadsheet instance.
+=end
 class SheetData
   # logs on class level
   self.extend BasicLogging
@@ -43,6 +45,7 @@ class SheetData
   @@file = nil		
   @@workbook = nil
 
+  # returns a new workbook
   def self::workbook(file)
     @@file = file
     if !@@workbook

data/lib/sheetinterface.rb

@@ -53,6 +53,7 @@ class SheetInterface
   end
 
   def initialize(wb, num)
+    # set_level('debug')
     @workbook = wb.sheet(num)
     @menu = nil
     @status = Status.new
@@ -60,6 +61,16 @@ class SheetInterface
   end
 
   private
+=begin
+  Interrupts the screen refresh to display a debug message,
+  if the log level is BasicLogging::DEBUG.
+=end
+  def pause_debug(text)
+    if @@log_level == BasicLogging::DEBUG
+      debug(text)
+      wait_for_user    
+    end
+  end
 =begin
         returns [width, height] in columns and lines of the current
         terminal-window. 
@@ -68,7 +79,7 @@ class SheetInterface
     size = `stty size`.split.map { |x| x.to_i }.reverse
     return size
   end 
-  # Asks the user to enter a number, then verifies ageinst eventual
+  # Asks the user to enter a number, then verifies against eventual
   # constraints.
   def ask_number(question, &constraint)
     num = nil
@@ -190,8 +201,8 @@ class SheetInterface
     end
 
     if sn && !sn.to_s.empty?
-      debug('calling workbook.sheet with ' << sn.to_s)
-      debug('@workbook is of type ' << @workbook.class.name)
+      pause_debug('calling workbook.sheet with ' << sn.to_s)
+      pause_debug('@workbook is of type ' << @workbook.class.name)
       set_sheet(sn)
     end
     construct
@@ -208,10 +219,24 @@ class SheetInterface
     save_Menu.add_action(Action.new(:name => 'current sheet', :key => 'c') do 
       file = new_file()
       if(file)
-        File::open(file, 'w+') {|out| draw(out) }
-        @status.message = green('... done')
+        num = 0
+        begin
+          content = draw(false)
+          pause_debug(__LINE__.to_s << 'have content – writing to ' << file)
+          num = File::write(file, content )
+          pause_debug(__LINE__.to_s << 'wrote ' << num.to_s << ' bytes')
+        rescue Exception => ex
+          @status.message = red( 'cannot write to ' << file << ': ' << ex.message)
+          # raise ex
+        end
+        if num > 0
+          @status.message = green('... done (' << num.to_s << ' bytes written)')
+        else
+          @status.message = red('Cannot write to ' << file << ' (' << num.to_s << ' bytes written)')
+        end
+        construct
       end
-      construct
+      # end action - close parenthesis
     end)	
 
     save_Menu.add_action(Action.new(:name => 'all sheets', :key => 'a') do 
@@ -223,12 +248,15 @@ class SheetInterface
         begin
           File::open(file, 'w+') do |out| 
             @workbook.sheets.each do |s|
-              debug('writing sheet ' << s)
               set_sheet(s)
               construct(false)
-              draw(out) 
+              debug(__LINE__.to_s << 'writing sheet ' << s.to_s)
+              wait_for_user if @@log_level == BasicLogging::DEBUG
+              out.write draw(false) 
             end
           end
+        rescue Errno => ex
+          @status.message = red(__LINE__.dup << 'cannot write to ' << file << ':' << ex.message   )
         rescue Interrupt
           puts bold(red("Interrupted by user. Bye!"))
           exit true
@@ -237,6 +265,7 @@ class SheetInterface
       end
       set_sheet(current_sheet)
       construct
+      # end action - close parenthesis
     end)	
 
     col_Menu = Menu.new(:name=>'column', :key => 'c')
@@ -255,7 +284,7 @@ class SheetInterface
         if(@rows[row] && @columns[col])
           cell = @rows[row].cells.detect {|c| c.col == col} 
           if(cell)
-            @status.message = "#{cell_coord[0].upcase}:#{cell_coord[1]} is \"" << cell.value.to_s << "\" (%d)" %cell.value.to_s.length
+            @status.message = yellow("value in #{cell_coord[0].upcase}:#{cell_coord[1]} is \"" << cell.value.to_s << "\" (%d)" %cell.value.to_s.length)
           else
             @status.message = red('invalid cell')
           end
@@ -280,10 +309,12 @@ class SheetInterface
   end
   # This is hard to describe. 
   # The function basically draws a table on screen. 
-  def draw(out = STDOUT)
+  def draw(on_screen = true)
     if(@rows && !@rows.empty?)
       # Welcome to hell.
-      on_screen = STDOUT == out
+      debug 'drawing on screen' if on_screen 
+      wait_for_user if on_screen && @@log_level == BasicLogging::DEBUG
+      
       col_w = Column::col_width
       num_c = @rows[0].cells.length()
       num_r = @rows.length
@@ -294,46 +325,33 @@ class SheetInterface
       #-----
 
       table_view << @workbook.default_sheet << "\n"
-      #out.puts @workbook.default_sheet
       table_view << ('┌' << '─' * num_r.to_s.length << '┬' << (('─' * col_w) << '┬' ) * (num_c -1) ) << (('─' * col_w) << '┐' ) << "\n"
-      # out.puts ('┌' << '─' * num_r.to_s.length << '┬' << (('─' * col_w) << '┬' ) * (num_c -1) ) << (('─' * col_w) << '┐' )
       lh = 0
       @rows.each do |row|
 
         if(row == @rows.first)
           ch = 'A'
           table_view << "│%#{num_r.to_s.length}s" %" " 
-          #out.print "│%#{num_r.to_s.length}s" %" " 
           table_view << '│'
-          # out.print '│'
           row.each do |c|
             head = "%#{col_w}s" %ch 
             head = bold(head) if(on_screen)
-            # out.print(head << "|")
             table_view << (head << "│")
             ch = ch.next
           end
-          # out.puts
           table_view << "\n"
           hline = ('├' << ('─' * (num_r.to_s.length) ) <<'┼' << (('─' * col_w) << '┼' ) * (num_c - 1) ) <<  (('─' * col_w) << '┤')if !hline
           table_view << hline << "\n"
-          # out.puts hline
         end
         lh += 1
         table_view << "│" 
-        # out.print "│" 
         line_head = "%#{num_r.to_s.length}s" %lh.to_s
         line_head = bold(line_head) if on_screen 
         table_view << line_head
-        # out.print line_head
-
-        #      out.print "│" << bold("%#{num_r.to_s.length}s" %line_head)
 
         row.height.times do |li|
           table_view << "│%#{num_r.to_s.length}s" %" " if li > 0
-          # out.print "│%#{num_r.to_s.length}s" %" " if li > 0
           table_view << '│'
-          # out.print '│'
           row.each do |cell|
             line = cell.line(li)
             content = "%#{col_w}s│" %line 
@@ -341,15 +359,12 @@ class SheetInterface
               content = red(content)
             end
             table_view << content
-            # out.print content
           end
           table_view << "\n"
-          # out.puts
         end
         hlline = ('│' << (('─' * col_w) << '│' ) * num_c  ) if !hline
 
         table_view << hline << "\n"
-        # out.puts hline
 
         # Some of the following code may go to a function as it repeats the
         # procedure from the beginning of the table.  I am currently unwilling to
@@ -359,26 +374,20 @@ class SheetInterface
         if(row == @rows.last)
           ch = 'A'
           table_view << "│%#{num_r.to_s.length}s" %" " 
-          # out.print "│%#{num_r.to_s.length}s" %" " 
           table_view << '│'
-          # out.print '│'
           row.each do |c|
             head = "%#{col_w}s" %ch
             head = bold(head) if on_screen
             table_view << ( head << '│')
-            # out.print( head << '│')
             ch = ch.next
           end
           table_view << "\n"
-          # out.puts
           hline = ('└' << ('─' * (num_r.to_s.length) ) << '┴' << (('─' * col_w) << '┴' ) * (num_c - 1) ) << (('─' * col_w) << '┘' )
 
           table_view << hline << "\n"
-          # out.puts hline
         end
 
       end
-
       return table_view
     else
       return nil