class_docu_shower 1.0.3 → 1.0.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 706a06d9164f89d3cf5a600bdbc0e1eb65bb839f
-  data.tar.gz: 6c58b78d9404c2e5e0983a983befcd6fe1196a96
+SHA256:
+  metadata.gz: 403b52dadc7d2d0c9434d9af218b1892c3674110af0c9ebf7c1d1e8ef2edb2c1
+  data.tar.gz: d193d3d8192fb50a8dfee4a0a600bc2275d1e2679e13836953d4f3ca340ca7b0
 SHA512:
-  metadata.gz: a85869271e95c374ecdc4cf39cf2d9c19f141068d92c47d9e0da93930452682c46041b73fc487541af2da247293c8e8fa193c649cfb270130b0db08f3cd489c5
-  data.tar.gz: 445e7ac50e3b53e8413835c35413b87f145aabc6814404bb1b7125a5562cb8d8c32d2e29107292876f7f7223a009606d5b77d0e11699ac778bbee66e29441758
+  metadata.gz: a3f955a6c65c0e77558c7dd6cc0c4a6b952be51559f38e279270157726f661a3c38f3946d7aa8ae795348fc6ec6192b1f3fb2e140e3629710a7944c04f33bc54
+  data.tar.gz: a84f1458d1a4e2ed166e4fff0ef6a5c2fdea4a67d09fd52a1d7ccc9b276a0882a68e9f478384e44d3c505c89a18b6936778e6db8219ef5f90bcbe3b643d94098

data/README.md

@@ -0,0 +1,20 @@
+## Why was this class necessary?
+
+I found that I wrote a lot of ruby .rb files over the various
+years. When the file is of some importance, I would usually
+also document in the header what this class does. Since I
+was already doing so, I figured that it may be useful to
+display this explanation on the commandline too, via a
+unified interface, invocable such as via "--info". 
+
+That way I can note down what the respective class is doing
+and have this output on the commandline.
+
+## Contact information
+
+If you have specific suggestions to make this gem more
+useful for others, please drop me an email at:
+
+  shevegen@gmail.com
+
+Thank you.

data/USAGE.md

@@ -7,4 +7,10 @@
 == Using it in a project
 
   ClassDocuShower.new("some_file_here.rb")
+  ClassDocuShower['some_file_here.rb']
 
+== Commandline
+
+  You can run the executable called
+  
+    class_docu_shower

data/bin/class_docu_shower

@@ -0,0 +1,7 @@
+#!/System/Index/bin/ruby -w
+# Encoding: ISO-8859-1
+# frozen_string_literal: true
+# =========================================================================== #
+require 'class_docu_shower'
+
+ClassDocuShower[ARGV]

data/class_docu_shower.gemspec

@@ -1,64 +1,56 @@
 # =========================================================================== #
 # Gemspec for Project ClassDocuShower.
 # =========================================================================== #
+require 'class_docu_shower/version/version.rb'
+
 Gem::Specification.new { |s|
 
-  s.name        = 'class_docu_shower'
-  s.version     = '1.0.3'
-  s.date        = Time.now.strftime('%Y-%m-%d')
+  s.name    = 'class_docu_shower'
+  s.version = ClassDocuShower::VERSION
+  s.date    = Time.now.strftime('%Y-%m-%d')
   
-  s.summary = <<-EOF
+  DESCRIPTION = <<-EOF
   
-    It will display the header of a .rb file in question.
-    For this to properly function, you should use 3 =
-    followed by the name of the class, and delimited
-    in # ===== entries.
-    
-    Example:
-    
-    === Menu
+This library is called class_docu_shower.
 
-    If you have specific suggestions to make this gem more
-    useful for others, please drop me an email at:
-      shevegen@gmail.com
-    Thank you.
+It will display the header of a .rb file in question.
 
-  EOF
-  
-  s.description = <<-EOF
+For this to properly function, you should use 3 '=' characters,
+followed by the name of the class, and delimited via '# ====='
+entries.
+
+Example:
+
+'=== Menu'
 
-    This library is called class_docu_shower.
-    
-    It will display the header of a .rb file in question.
-    For this to properly function, you should use 3 =
-    followed by the name of the class, and delimited
-    in # ===== entries.
-    
-    Example:
-    
-    === Menu
+Without the '' quotes.
 
-    If you have specific suggestions to make this gem more
-    useful for others, please drop me an email at:
-      shevegen@gmail.com
-    Thank you.
+There also is an executable at bin/class_docu_shower.
+
+Pass it the path to a .rb file and it will output the
+top header comment.
 
   EOF
   
+  s.summary     = DESCRIPTION
+  s.description = DESCRIPTION
+  
   s.extra_rdoc_files = %w( USAGE.md )
   
-  s.authors     = ['Robert A. Heiler']
-  s.email       = 'shevegen@gmail.com'
-  s.files       = Dir['**/*']
-  s.files      << 'USAGE.md'
-  s.license     = 'GPL 2'
-  s.required_ruby_version = '>= 1.9.2'
-  s.homepage    = 'http://rubygems.org/gems/class_docu_shower'
-
-  s.rubygems_version = '2.1.11'
-
-  s.add_dependency 'colours', '>= 0.0.12'
-  s.add_dependency 'opn', '>= 1.0.0'
-  s.add_dependency 'usher', '>= 0.0.6'
-
-}
+  s.authors    = ['Robert A. Heiler']
+  s.email      = 'shevegen@gmail.com'
+  s.files      = Dir['**/*']
+  s.files     << 'USAGE.md'
+  s.license    = 'GPL-2.0'
+  s.homepage   = 'http://rubygems.org/gems/class_docu_shower'
+
+  s.required_ruby_version     = '>= '+RUBY_VERSION
+  s.required_rubygems_version = '>= '+Gem::VERSION
+  s.rubygems_version          = '>= '+Gem::VERSION
+
+  s.add_dependency 'colours'
+  s.add_dependency 'opn'
+  # s.add_dependency 'usher'
+  # ^^^ The variant on rubygems.org is not the one we need.
+
+}

data/doc/README.gen

@@ -0,0 +1,20 @@
+## Why was this class necessary?
+
+I found that I wrote a lot of ruby .rb files over the various
+years. When the file is of some importance, I would usually
+also document in the header what this class does. Since I
+was already doing so, I figured that it may be useful to
+display this explanation on the commandline too, via a
+unified interface, invocable such as via "--info". 
+
+That way I can note down what the respective class is doing
+and have this output on the commandline.
+
+## Contact information
+
+If you have specific suggestions to make this gem more
+useful for others, please drop me an email at:
+
+  shevegen@gmail.com
+
+Thank you.

data/lib/class_docu_shower/class_docu_shower.rb

@@ -1,31 +1,60 @@
-#!/System/Executables/ruby -w
-# Encoding: ASCII-8BIT
+#!/System/Index/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
 # =========================================================================== #
 # === ClassDocuShower
 #
-# This file will extract the comment from a class and return a
-# string about the docu. That comment must be padded inside lines 
-# with '# ====' lines, like this file here.
+# This file will extract the comment from a class and return a string about
+# the docu. That comment must be padded inside lines with '# ====' lines,
+# like this file here.
 #
 # Usage example:
 #   ClassDocuShower.new('file_location_comes_in_here')
 # =========================================================================== #
-require 'pp'
-require 'colours'
+# require 'class_docu_shower.rb'
+# =========================================================================== #
 require 'opn'
-require 'usher'
+begin
+  require 'usher'
+rescue LoadError; end
+begin
+  require 'colours'
+rescue LoadError; end
+require 'class_docu_shower/version/version.rb'
+require 'class_docu_shower/colours.rb'
 
-class ClassDocuShower # require 'class_docu_shower'; ClassDocuShower.new
+class ClassDocuShower # === ClassDocuShower.new
 
   include Colours
 
-  attr_reader :files
+  N = "\n"
+
+  # ========================================================================= #
+  # === DEFAULT_FILE
+  # ========================================================================= #
+  DEFAULT_FILE =
+    '/Users/x/DATA/PROGRAMMING_LANGUAGES/RUBY/src/tools/show_available_users.rb'
 
-  DEFAULT_FILE = '/Users/x/DATA/PROGRAMMING_LANGUAGES/RUBY/SRC/TOOLS/show_available_users.rb'
+  # ========================================================================= #
+  # === FORBIDDEN_CHARACTERS
+  # ========================================================================= #
   FORBIDDEN_CHARACTERS = '# ===='
 
+  # ========================================================================= #
+  # === ENCODING_TO_USE
+  # ========================================================================= #
+  ENCODING_TO_USE = 'ISO-8859-1' # Which Encoding to consistently use for this class.
+
+  # ========================================================================= #
+  # === initialize
+  #
+  # The first argument should be a .rb file.
+  #
+  # The second argument can be :silent, in which case we will be silent
+  # rather than verbose.
+  # ========================================================================= #
   def initialize(
-      i = nil,
+      i           = nil,
       run_already = true
     )
     be_silent
@@ -36,65 +65,146 @@ class ClassDocuShower # require 'class_docu_shower'; ClassDocuShower.new
         @be_verbose = run_already[:verbose]
         run_already = true
       end
-    elsif run_already == :silent
-      be_silent
-      run_already = true
+    else
+      case run_already
+      when :silent
+        be_silent
+        run_already = true
+      when :no_colours
+        @use_colours = false
+        run_already = true
+      end
+    end
+    if block_given?
+      yielded = yield
+      case yielded
+      when :do_not_report_the_filename
+        @report_the_filename = false
+      end
     end
     run if run_already
   end
-  def reset # (reset tag)
-    @data  = nil
-    @usher = Usher.new
+
+  # ========================================================================= #
+  # === reset                                                     (reset tag)
+  # ========================================================================= #
+  def reset
+    @data   = nil
+    if Object.const_defined? :Usher
+      @usher = Usher.new
+    else
+      @usher = nil
+    end
+    @result = nil
+    @use_colours = true
+    @report_the_filename = true
   end
+
+  # ========================================================================= #
+  # === reset_usher_object
+  # ========================================================================= #
   def reset_usher_object
-    @usher.reset
-    @usher.allow_n_changes = 1
+    if @usher
+      @usher.reset
+      @usher.allow_n_changes = 1
+    end
   end
-  def be_verbose; @be_verbose = true; end
-  def be_silent;  @be_verbose = false; end
-  def set_files(i = DEFAULT_FILE)
-    # i = i[0] if i.is_a? Array
-    i = DEFAULT_FILE if i.nil?
-    # i = i.to_s.dup if i
-    i = [i] unless i.is_a? Array # Must always be an Array.
-    i = i.flatten # But keep it flattened.
-    @files = i
+
+  # ========================================================================= #
+  # === be_verbose
+  # ========================================================================= #
+  def be_verbose
+    @be_verbose = true
+  end
+
+  # ========================================================================= #
+  # === be_silent
+  # ========================================================================= #
+  def be_silent
+    @be_verbose = false
+  end
+
+  # ========================================================================= #
+  # === file?
+  # ========================================================================= #
+  def file?
+    @file.to_s
   end
+
+  # ========================================================================= #
+  # === show_the_result
+  # ========================================================================= #
+  def show_the_result
+    e @result if result?
+  end
+
+  # ========================================================================= #
+  # === use_colours?
+  # ========================================================================= #
+  def use_colours?
+    @use_colours
+  end
+
+  # ========================================================================= #
+  # === read_in_file
+  #
+  # We determine @data here.
+  # ========================================================================= #
   def read_in_file(this_file = @file)
     if File.exist? this_file
-      @data = File.readlines(this_file)
+      @data = File.readlines(this_file, :encoding => ENCODING_TO_USE)
     else # We should report.
-      opn; e 'We could not find a file at '+sfile(this_file)+','
-      opn; e 'thus can not check whether it has an documentation.'
+      result = 'We could not find a file at '+sfile(this_file)+','
+      result = Colours.remove_colours(result) unless use_colours?
+      opn; e result
+      result = 'thus can not check whether it has an documentation.'
+      result = Colours.remove_colours(result) unless use_colours?
+      opn; e result
     end
   end
+
+  # ========================================================================= #
+  # === result?
+  # ========================================================================= #
+  def result?
+    @result
+  end
+
+  # ========================================================================= #
+  # === show_result
+  # ========================================================================= #
   def show_result
-    if @be_verbose # We will be chatty here.
-      opn; e 'From the file '+sfile(@file)+' we '
-      opn; e 'can show this result:'
+    if @be_verbose # We will be chatty here, aka, verbose.
+      result = 'From the file '+sfile(file?)+' we '
+      result = Colours.remove_colours(result) unless use_colours?
+      opn; e result
+      result = 'can show this result:'
+      result = Colours.remove_colours(result) unless use_colours?
+      opn; e result
     end 
     show_the_result
   end
-  def show_the_result
-    e @result
-  end
-  def process_dataset
-    reset_usher_object
-    @data.each {|entry| # @data is an Array.
-      if entry.include? FORBIDDEN_CHARACTERS
-        @usher.toggle
-      else
-        # Else add the entry. We should not use .lstrip
-        # on it because that way we can preserve
-        # indent.
-        @usher << entry.delete('#') # .lstrip
-      end
-    }
-    @result = @usher._
-  end
-  def show_file_header(i)
-    e 'From file '+sfile(i)+':'+N+N
+
+  # ========================================================================= #
+  # === files?
+  # ========================================================================= #
+  def files?
+    @files
+  end; alias files files? # === files
+
+  # ========================================================================= #
+  # === sfile
+  # ========================================================================= #
+  def sfile(i = '')
+    i = Colours.sfile(i) if use_colours?
+    return i
   end
+
+  # ========================================================================= #
+  # === process
+  #
+  # This method contains the in-class logic.
+  # ========================================================================= #
   def process
     @files.each {|file|
       show_file_header(file)
@@ -104,12 +214,78 @@ class ClassDocuShower # require 'class_docu_shower'; ClassDocuShower.new
       e
     }
   end
-  def run # (run tag)
+
+  # ========================================================================= #
+  # === process_dataset
+  # ========================================================================= #
+  def process_dataset
+    reset_usher_object
+    if @data
+      @data.each {|entry| # @data is an Array.
+        if entry.include? FORBIDDEN_CHARACTERS # Reject leading '# ===' parts.
+          @usher.toggle if @usher
+        else
+          # ================================================================= #
+          # Else add the entry. We should not use .lstrip on it because
+          # that way we can preserve the original indent.
+          # ================================================================= #
+          entry.delete!('#') # .lstrip
+          if use_colours? and Object.const_defined?(:Colours)
+            if entry.start_with? ' ==='
+              entry = orange(entry)
+            elsif entry.include? 'Usage examples:'
+              entry = lightblue(entry)
+            end
+          end
+          @usher << entry if @usher
+        end
+      }
+      @result = @usher._ if @usher
+    end
+  end
+
+  # ========================================================================= #
+  # === set_files
+  # ========================================================================= #
+  def set_files(i = DEFAULT_FILE)
+    i = DEFAULT_FILE if i.nil?
+    # i = i.to_s.dup if i
+    i = [i] unless i.is_a? Array # Must always be an Array.
+    i.flatten! # But keep it flattened.
+    @files = i
+  end
+
+  # ========================================================================= #
+  # === show_file_header
+  #
+  # This method will show the header, with an introduction like
+  # "From file bla".
+  # ========================================================================= #
+  def show_file_header(i)
+    if @report_the_filename#
+      result = 'From file '+sfile(i)+':'+N+N
+      result = Colours.remove_colours(result) unless use_colours?
+      e result
+    end
+  end
+
+  # ========================================================================= #
+  # === run                                                         (run tag)
+  # ========================================================================= #
+  def run
     process
   end
 
+  # ========================================================================= #
+  # === ClassDocuShower[]
+  # ========================================================================= #
+  def self.[](i)
+    ClassDocuShower.new(i)
+  end
+
 end
 
 if __FILE__ == $PROGRAM_NAME
-  ClassDocuShower.new(ARGV, :silent)
-end # cdocu
+  _ = ClassDocuShower.new(ARGV, :silent)
+  # pp _.result? # This here for debug.
+end # rdocu

data/lib/class_docu_shower/colours.rb

@@ -0,0 +1,30 @@
+#!/System/Index/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# Colour-related code will be stored here.
+# =========================================================================== #
+class ClassDocuShower
+
+  # ========================================================================= #
+  # === orange
+  # ========================================================================= #
+  def orange(i)
+    ::Colours.orange(i)
+  end
+
+  # ========================================================================= #
+  # === slateblue
+  # ========================================================================= #
+  def slateblue(i)
+    ::Colours.slateblue(i)
+  end
+
+  # ========================================================================= #
+  # === lightblue
+  # ========================================================================= #
+  def lightblue(i)
+    ::Colours.lightblue(i)
+  end
+
+end

data/lib/class_docu_shower/version/version.rb

@@ -0,0 +1,14 @@
+#!/System/Index/bin/ruby -w
+# Encoding: ISO-8859-1
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'class_docu_shower/version/version.rb'
+# =========================================================================== #
+class ClassDocuShower
+
+  # ========================================================================= #
+  # === ClassDocuShower::VERSION
+  # ========================================================================= #
+  VERSION = '1.0.21'
+
+end

data/test/testing_class_docu_shower.rb

@@ -0,0 +1,14 @@
+#!/System/Index/bin/ruby -w
+# Encoding: ISO-8859-1
+# frozen_string_literal: true
+# =========================================================================== #
+require 'colour_e/autoinclude'
+require 'class_docu_shower'
+
+i = '/Users/x/DATA/PROGRAMMING_LANGUAGES/RUBY/SRC/cookbooks/lib/cookbooks/utility_scripts/registered_libraries.rb' # The class comes here.
+e 'Using colour-codes next.'
+e
+ClassDocuShower.new(i)
+e 'Getting rid of all colour-codes.'
+e
+ClassDocuShower.new(i, :no_colours)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: class_docu_shower
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.0.21
 platform: ruby
 authors:
 - Robert A. Heiler
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-16 00:00:00.000000000 Z
+date: 2019-05-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: colours
@@ -16,61 +16,52 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.0.12
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.0.12
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: opn
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.0
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.0
-- !ruby/object:Gem::Dependency
-  name: usher
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.0.6
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.0.6
-description: "\n    This library is called class_docu_shower.\n    \n    It will display
-  the header of a .rb file in question.\n    For this to properly function, you should
-  use 3 =\n    followed by the name of the class, and delimited\n    in # ===== entries.\n
-  \   \n    Example:\n    \n    === Menu\n\n    If you have specific suggestions to
-  make this gem more\n    useful for others, please drop me an email at:\n      shevegen@gmail.com\n
-  \   Thank you.\n\n"
+        version: '0'
+description: "  \nThis library is called class_docu_shower.\n\nIt will display the
+  header of a .rb file in question.\n\nFor this to properly function, you should use
+  3 '=' characters,\nfollowed by the name of the class, and delimited via '# ====='\nentries.\n\nExample:\n\n'===
+  Menu'\n\nWithout the '' quotes.\n\nThere also is an executable at bin/class_docu_shower.\n\nPass
+  it the path to a .rb file and it will output the\ntop header comment.\n\n"
 email: shevegen@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files:
 - USAGE.md
 files:
+- README.md
 - USAGE.md
+- bin/class_docu_shower
 - class_docu_shower.gemspec
+- doc/README.gen
 - lib/class_docu_shower.rb
 - lib/class_docu_shower/class_docu_shower.rb
+- lib/class_docu_shower/colours.rb
+- lib/class_docu_shower/version/version.rb
+- test/testing_class_docu_shower.rb
 homepage: http://rubygems.org/gems/class_docu_shower
 licenses:
-- GPL 2
+- GPL-2.0
 metadata: {}
 post_install_message: 
 rdoc_options: []
@@ -80,21 +71,19 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 1.9.2
+      version: 2.6.3
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 3.0.3
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
-summary: 'It will display the header of a .rb file in question. For this to properly
-  function, you should use 3 = followed by the name of the class, and delimited in
-  # ===== entries.  Example:  === Menu  If you have specific suggestions to make this
-  gem more useful for others, please drop me an email at: shevegen@gmail.com Thank
-  you.'
+summary: 'This library is called class_docu_shower.  It will display the header of
+  a .rb file in question.  For this to properly function, you should use 3 ''='' characters,
+  followed by the name of the class, and delimited via ''# ====='' entries.  Example:  ''===
+  Menu''  Without the '''' quotes.  There also is an executable at bin/class_docu_shower.  Pass
+  it the path to a .rb file and it will output the top header comment.'
 test_files: []
-has_rdoc: