roebe 0.5.191 → 0.6.3

data/lib/roebe/classes/make_gem.rb

@@ -154,7 +154,7 @@ class MakeGem < Base # === Roebe::MakeGem
       # ===================================================================== #
       # (4) We will also publish the gem at once next.
       # ===================================================================== #
-      e 'We will also automatically publish this gem at once.'
+      e "#{rev}We will also automatically publish this gem at once."
       e "#{rev}This is "+orange('necessary')+rev+' so that we can '\
         'restore the old file called'
       e "#{sfile('lecture_information')} #{rev}again."
@@ -209,32 +209,6 @@ class MakeGem < Base # === Roebe::MakeGem
     esystem 'gem build *.gemspec'
   end
 
-  # ========================================================================= #
-  # === prepare_the_gem_for_the_rbt_project
-  #
-  # This method will publish the rbt project.
-  # ========================================================================= #
-  def prepare_the_gem_for_the_rbt_project
-    return unless @may_we_prepare_the_gem_for_the_rbt_project
-    if is_on_roebe?
-      require 'rbt/version/version.rb'
-      rename_kde_konsole_tab(
-        "Updating RBT to Version #{RBT.version?}",
-        :be_quiet
-      )
-    end
-    require 'rbt'
-    e orange('(1) RBT.save_the_available_programs_versions:')
-    if RBT.respond_to? :save_the_available_programs_versions
-      RBT.save_the_available_programs_versions
-    else
-      e "#{rev}RBT.save_the_available_programs_versions does not work."
-    end
-    if is_on_roebe?
-     rename_kde_konsole_tab('', :be_quiet)
-    end
-  end
-
   # ========================================================================= #
   # === check_for_readme_gen
   #
@@ -262,6 +236,34 @@ class MakeGem < Base # === Roebe::MakeGem
     end
   end
 
+  # ========================================================================= #
+  # === prepare_the_gem_for_the_rbt_project
+  #
+  # This method will publish the rbt project.
+  # ========================================================================= #
+  def prepare_the_gem_for_the_rbt_project
+    return unless @may_we_prepare_the_gem_for_the_rbt_project
+    if is_on_roebe?
+      require 'rbt/requires/require_actions.rb'
+      require 'rbt/version/version.rb'
+      rename_kde_konsole_tab(
+        "Updating RBT to Version #{RBT.version?}",
+        :be_quiet
+      )
+    end
+    require 'rbt'
+    RBT.action(:save_available_programs)
+    e orange('(1) RBT.save_the_available_programs_versions:')
+    if RBT.respond_to? :save_the_available_programs_versions
+      RBT.save_the_available_programs_versions
+    else
+      e "#{rev}RBT.save_the_available_programs_versions does not work."
+    end
+    if is_on_roebe?
+     rename_kde_konsole_tab('', :be_quiet)
+    end
+  end
+
   # ========================================================================= #
   # === run                                                         (run tag)
   # ========================================================================= #

data/lib/roebe/classes/readme_generator/readme_generator.rb

@@ -2,9 +2,605 @@
 # Encoding: UTF-8
 # frozen_string_literal: true
 # =========================================================================== #
+# === Roebe::ReadmeGenerator
+#
+# This class can be used to generate a README.md file. Input-templates
+# can also be used, such as README.gen. From such a template file, we
+# can autogenerate a README file.
+#
+# Usage example:
+#
+#   Roebe::ReadmeGenerator.new(ARGV)
+#
+# =========================================================================== #
 # require 'roebe/classes/readme_generator/readme_generator.rb'
 # =========================================================================== #
-require 'roebe/classes/readme_generator/misc.rb'
+require 'roebe/base/base.rb'
+
+module Roebe
+
+class ReadmeGenerator < Base # === Roebe::ReadmeGenerator
+
+  # ========================================================================= #
+  # === FILE_DOC_README_GEN
+  # ========================================================================= #
+  FILE_DOC_README_GEN = 'doc/README.gen'
+
+  # ========================================================================= #
+  # === NAME_OF_THE_FILE_THAT_IS_AUTOGENERATED
+  # ========================================================================= #
+  NAME_OF_THE_FILE_THAT_IS_AUTOGENERATED = 'README.md'
+
+  # ========================================================================= #
+  # === initialize
+  # ========================================================================= #
+  def initialize(
+      input_gen_file = FILE_DOC_README_GEN,
+      run_already    = true
+    )
+    reset
+    set_input_gen_file(input_gen_file)
+    # ======================================================================= #
+    # === Handle blocks next
+    # ======================================================================= #
+    if block_given?
+      yielded = yield
+      case yielded
+      # ===================================================================== #
+      # === :do_not_open_in_the_browser
+      # ===================================================================== #
+      when :do_not_open_in_the_browser
+        @internal_hash[:open_in_browser] = false
+      end
+    end
+    run if run_already
+  end
+
+  # ========================================================================= #
+  # === reset                                                     (reset tag)
+  # ========================================================================= #
+  def reset
+    super()
+    infer_the_namespace
+    try_to_require_the_open_gem
+    # ======================================================================= #
+    # === :open_in_browser
+    # ======================================================================= #
+    @internal_hash[:open_in_browser] = true
+    # ======================================================================= #
+    # === @_
+    # ======================================================================= #
+    @_ = ''.dup
+  end
+
+  # ========================================================================= #
+  # === main_file?
+  # ========================================================================= #
+  def main_file?
+    NAME_OF_THE_FILE_THAT_IS_AUTOGENERATED
+  end
+
+  # ========================================================================= #
+  # === set_input_gen_file
+  # ========================================================================= #
+  def set_input_gen_file(
+      i = FILE_DOC_README_GEN
+    )
+    i = i.first if i.is_a? Array
+    i = i.to_s.dup
+    if i.empty?
+      i = FILE_DOC_README_GEN
+    end
+    # ======================================================================= #
+    # Next, quickly see whether a file called "README.gen" exists in
+    # the current directory but not at e. g. doc/README.gen. In this
+    # case we will use that file instead.
+    # ======================================================================= #
+    if File.exist?('README.gen') and !File.exist?(i)
+      i = 'README.gen'
+    end
+    @input_gen_file = i
+  end
+
+  # ========================================================================= #
+  # === input_gen_file?
+  # ========================================================================= #
+  def input_gen_file?
+    @input_gen_file
+  end; alias gen_file? input_gen_file? # === gen_file?
+
+  # ========================================================================= #
+  # === try_to_embed_this_file
+  # ========================================================================= #
+  def try_to_embed_this_file(this_file)
+    # ======================================================================= #
+    # Turn it into an absolute path for now.
+    # ======================================================================= #
+    this_file = File.absolute_path(this_file)
+    if File.exist? this_file
+      # ===================================================================== #
+      # Read in the file then.
+      # ===================================================================== #
+      opne "Reading in the content of the file `#{sfile(this_file)}`."
+      add(
+        N+'<pre>'+N+File.read(this_file)+N+'</pre>'+N
+      )
+    else
+      opne "No file called #{sfile(this_file)} exists."
+    end
+  end
+
+  # ========================================================================= #
+  # === add_text_for_the_donate_macro
+  #
+  # This is the text that will be added for the donation-macro in a
+  # README.gen file.
+  # ========================================================================= #
+  def add_text_for_the_donate_macro
+    add('Currently this project does not accept donations, but')
+    add('in the future this may be subject to change, including')
+    add('more information in how folks could support the project,')
+    add('if they would like to.')
+    add
+    add('Of course **documentation**, **patches**, **bug fixes** and so')
+    add('forth are **always** appreciated.')
+  end
+
+  # ========================================================================= #
+  # === open_in_browser
+  # ========================================================================= #
+  def open_in_browser(i)
+    if File.exist?(i) and !(File.size(i) == 0)
+      Open.in_browser(i) if Object.const_defined? :Open
+    else
+      opne "No file exists at `#{sfile(i)}` - or "\
+           "has a file size larger than 0."
+    end
+  end
+
+  # ========================================================================= #
+  # === store_the_string
+  # ========================================================================= #
+  def store_the_string
+    what = @_
+    into = main_file?
+    opne 'Storing the dataset into the file `'+sfile(into)+'`.'
+    write_what_into(what, into)
+  end
+
+  # ========================================================================= #
+  # === return_name_of_the_project
+  #
+  # This method will return the name of the project at hand. Note that
+  # this functionality depends on guessing the directory name, so
+  # we need to have cd-ed to the correct directory prior to making
+  # use of this method here.
+  # ========================================================================= #
+  def return_name_of_the_project
+    File.basename(Dir.pwd)
+  end
+
+  # ========================================================================= #
+  # === try_to_add_the_content_of_this_file
+  #
+  # This method will try to add the file-content of an existing file,
+  # into the newly generated README.md file.
+  # ========================================================================= #
+  def try_to_add_the_content_of_this_file(this_file)
+    if File.exist? this_file
+      # ===================================================================== #
+      # Read in the file then.
+      # ===================================================================== #
+      opne "Reading in the content of the file `#{sfile(this_file)}`."
+      add(File.read(this_file))
+    else
+      e
+      opne crimson("No file called #{sfile(this_file)} exists.")
+      e
+      if is_on_roebe?
+        e 'Please fix the above error first.'
+        # =================================================================== #
+        # And using zenity to fix that, too.
+        # =================================================================== #
+        esystem "zenity --list --column='#{this_file}'"
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === generate_html_file_via_kramdown
+  # ========================================================================= #
+  def generate_html_file_via_kramdown
+    store_here = '/Depot/Information/foobar.html'
+    if File.exist? main_file?
+      _ = "kramdown #{main_file?} > #{store_here}"
+      esystem _ 
+      if File.exist? store_here
+        open_in_browser(store_here) if open_in_browser?
+      end
+    else
+      opne "No file exists at #{sfile(main_file?)}#{rev} "\
+           "- thus, kramdown can not be used."
+      if is_on_roebe?
+        opne 'This is a problem on my home system, as I tend to generate'
+        opne 'readme files. Hence, we will now exit, and hope that the'
+        opne 'problem will be corrected by roebe.'
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === open_in_browser?
+  # ========================================================================= #
+  def open_in_browser?
+    @internal_hash[:open_in_browser]
+  end
+
+  # ========================================================================= #
+  # === add_string_showing_the_last_updated_programs
+  #
+  # Note that we will modify this String by replacing all
+  # newlines via HTML <br> tags.
+  # ========================================================================= #
+  def add_string_showing_the_last_updated_programs
+    require 'rbt/toplevel_methods/toplevel_methods.rb'
+    begin
+      add(
+        RBT.return_string_showing_the_last_updated_programs.
+            gsub("\n","<br>\n")
+      )
+    rescue Exception => error
+      pp error
+    end
+    if is_on_roebe?
+      # ===================================================================== #
+      # Also remove the file if it exists.
+      # ===================================================================== #
+      begin
+        require 'rbt/toplevel_methods/files_and_directories_related_methods.rb'
+      rescue LoadError => error; pp error; end
+      this_file = "#{RBT.log_dir?}these_programs_were_updated_copy.yml"
+      if File.exist? this_file
+        remove_file(this_file)
+        this_file = "/home/x/programming/ruby/src/rbt/lib/rbt/yaml/these_programs_were_updated_copy.yml"
+        if File.exist?(this_file)
+          remove_file(this_file)
+        end
+      else
+        e rev+'Can not remove file '+sfile(this_file)+
+          rev+' because it does not exist.'
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === add                                                         (add tag)
+  # ========================================================================= #
+  def add(i = '')
+    i = i.join(N) if i.is_a? Array
+    @_ << "#{i}#{N}"
+  end
+
+  # ========================================================================= #
+  # === add_badge                                                 (badge tag)
+  #
+  # This will add the two main badges that I usually use in ruby projects.
+  #
+  # The first badge, to the left, is a link to the distribution called
+  # GoboLinux; the second badge, to the right of it, is a link to the
+  # official ruby-lang site.
+  #
+  # Note that since as of August 2019, a third badge will be shown -
+  # the badge that tags the gem-version onto the markdown file. This
+  # badge is special in that we need to attach the name of the project
+  # at hand.
+  # ========================================================================= #
+  def add_badge
+    homepage2 = 'https://www.ruby-lang.org/en/'.dup
+    name_of_the_project = return_name_of_the_project
+    add_gobolinux_badge
+    @_ << "[![forthebadge](https://forthebadge.com/images/badges/made-with-ruby.svg)](#{homepage2})#{N}"
+    # ======================================================================= #
+    # Next add the gem-version to the ruby-project at hand:
+    # ======================================================================= #
+    @_ << '[![Gem Version](https://badge.fury.io/rb/'+name_of_the_project+'.svg)](https://badge.fury.io/rb/'+name_of_the_project+')'+N
+  end; alias add_ruby_badge add_badge # === add_ruby_badge
+
+  # ========================================================================= #
+  # === add_gobolinux_badge
+  # ========================================================================= #
+  def add_gobolinux_badge(
+      homepage = 'https://www.gobolinux.org/'
+    )
+    @_ << "[![forthebadge](https://forthebadge.com/images/badges/built-with-love.svg)](#{homepage})#{N}"
+  end; alias add_gobolinux_logo add_gobolinux_badge # === add_gobolinux_logo
+
+  # ========================================================================= #
+  # === add_environment_information_properly_formatted_array
+  # ========================================================================= #
+  def add_environment_information_properly_formatted_array
+    require 'environment_information/constants/array_tracked_components.rb'
+    EnvironmentInformation::ARRAY_TRACKED_PROGRAMS.each {|entry|
+      @_ << "    #{entry}\n"
+    }
+    @_ << "\n"
+  end
+
+  # ========================================================================= #
+  # === add_time_stamp
+  #
+  # Add information to the README when this gem was last updated.
+  # ========================================================================= #
+  def add_time_stamp
+    add(
+      "\nThis gem was <b>last updated</b> on the "\
+      "<span style=\"color: darkblue; font-weight: bold\">#{dd_mm_yyyy}</span> "\
+      "(dd.mm.yyyy notation), at "\
+      "<span style=\"color: steelblue; font-weight: bold\">#{hh_mm_ss}</span> o'clock."
+    )
+  end
+
+  # ========================================================================= #
+  # === read_dataset_from_gen_file
+  # ========================================================================= #
+  def read_dataset_from_gen_file
+    _ = gen_file?
+    if File.exist? _
+      readlines_with_proper_encoding(_).each {|line|
+        line.chomp!
+        # =================================================================== #
+        # Process each line next.
+        # =================================================================== #
+        case line # case tag
+        # =================================================================== #
+        # === Handle files that begin with MACRO
+        #
+        # Several "aliases" exist to this entry point, such as
+        # INCLUDE_THIS_FILE or EMBED_THIS_FILE.
+        #
+        # Keep in mind that the file at hand should, ideally, exist. :)
+        # =================================================================== #
+        when /^MACRO read_file_as_pre_tag (.+)$/,
+             /^INCLUDE_THIS_FILE (.+)$/,
+             /^EMBED_THIS_FILE (.+)$/,
+             /^READ_AND_DISPLAY_THIS_FILE (.+)$/,
+             /^DISPLAY_THIS_FILE (.+)$/
+          this_file = $1.to_s.dup
+          try_to_embed_this_file(this_file)
+        # =================================================================== #
+        # === Add the default ruby header
+        # =================================================================== #
+        when /^RUBY_BADGE_AND_TIME_STAMP$/i,
+             /^DEFAULT_HEADER$/i
+          add_ruby_badge # <- This method will also invoke the method add_gobolinux_badge().
+          add_time_stamp
+        # =================================================================== #
+        # === ADD_CONTEXTFREE_ART_DISCLAIMER
+        #
+        # This entry point was specifically added in order to be used
+        # for linking to the fine contextfreedesign project (cfdg).
+        # =================================================================== #
+        when /ADD(_|-)?CONTEXTFREE(_|-)?ART(_|-)?DISCLAIMER$/
+          add_contextfree_art_disclaimer
+        # =================================================================== #
+        # === ADD_TIME_STAMP
+        #
+        # Add a time stamp, aka the current time, in combination with a
+        # "This gem was last updated on xyz." notification.
+        # =================================================================== #
+        when /^ADD_TIME_STAMP$/,
+             /^ADD_LAST_UPDATE$/,
+             /^ADD_MAIN_TIMESTAMP$/,
+             /^ADD_LAST_UPDATED_WHEN$/
+          add_time_stamp
+        # =================================================================== #
+        # === LICENCE_IS_MIT
+        # =================================================================== #
+        when /LICENCE_?IS_?MIT/,
+             /USE_?THE_?MIT_?LICENCE/
+          add_licence_is_MIT
+        # =================================================================== #
+        # === ADD_CONTACT_INFORMATION
+        #
+        # Add the default email address in use.
+        # =================================================================== #
+        when /ADD_?CONTACT_?INFORMATION/,
+             /ADD_?CONTACT_?DETAILS/,
+             /ADD_?EMAIL/,
+             /ADD_?MY_?EMAIL/,
+             /CONTACT_?INFORMATION/
+          add_contact_information
+        # =================================================================== #
+        # === ADD_GOBOLINUX_LINK
+        # =================================================================== #
+        when /^ADD_GOBOLINUX_LINK$/,
+             /^GOBOLINUX_IS_AWESOME$/
+          add_gobolinux_badge
+        # =================================================================== #
+        # === ADD_RUBY_LOGO_AND_TIMESTAMP
+        #
+        # This entry point combines two method-calls. This is the correct
+        # combination and order, too.
+        # =================================================================== #
+        when /^ADD_RUBY_LOGO_AND_TIMESTAMP$/,
+             /^MY_MAIN_HEADER$/,
+             /^ADD_DEFAULT_HEADER$/
+          add_badge
+          add_time_stamp
+        # =================================================================== #
+        # === ADD_BADGE
+        #
+        # Add a ruby badge to the autogenerated README.md file.
+        # =================================================================== #
+        when 'ADD_BADGE',
+             'DEFAULT_RUBY_HEADER',
+             'ADD_RUBY_HEADER',
+             'ADD_RUBY_BADGE',
+             /ADD_?RUBY_?BADGES/,
+             /ADD_?GOBOLINUX_?AND_?RUBY_?HEADER/,
+             /ADD_?DEFAULT_?HEADER/,
+             /RUBY_?HEADER/,
+             /ADD_?RUBY_?HEAD/,
+             /GOBOLINUX_?IS_?GREAT/,
+             /ADD(_|-)?MAIN(_|-)?HEADER/i
+          add_badge
+        # =================================================================== #
+        # === This will tap into RBT, to show which programs were last
+        #     updated.
+        # =================================================================== #
+        when /^INSERT_THE_LAST_UPDATED_PROGRAMS_HERE$/
+          add_string_showing_the_last_updated_programs
+        # =================================================================== #
+        # === Handle files that begin with MACRO or INCLUDE_FILE
+        # =================================================================== #
+        when /^MACRO read_file (.+)$/,
+             /^INCLUDE_FILE (.+)$/,
+             /^embed_this_file (.+)$/
+          this_file = $1.to_s.dup
+          try_to_add_the_content_of_this_file(this_file)
+        # =================================================================== #
+        # === Handle the donate-macro next
+        # =================================================================== #
+        when /^DONATE_MACRO$/
+          add_text_for_the_donate_macro
+        # =================================================================== #
+        # === ADD_ENVIRONMENT_INFORMATION_PROPERLY_FORMATTED_ARRAY
+        # =================================================================== #
+        when /^ADD_?ENVIRONMENT_?INFORMATION_?PROPERLY_?FORMATTED_?ARRAY$/i
+          add_environment_information_properly_formatted_array
+        # =================================================================== #
+        # === Handle RBT-specific macros next
+        # =================================================================== #
+        when /^MACRO RBT\.(.+)$/
+          require 'rbt' # In this case, just load the whole RBT project.
+          # ================================================================= #
+          # The next line of code is equivalent to:
+          #   RBT.will_install_which_binaries?
+          # ================================================================= #
+          if RBT.respond_to? $1.to_s.to_sym 
+            result = RBT.send($1.to_s.to_sym)
+            if result.is_a? Array # ← should always be an Array, but still, if check seems fine
+              result = result.map {|entry| entry.prepend('    ') }.join(N)
+            end
+            add(result) # ← Add it here.
+          else
+            e 'RBT does not respond to '+$1.to_s.to_sym.to_s+'().'
+          end
+        else
+          add(line)
+        end
+      }
+    else
+      opne "No file called #{sfile(_)} could be found."
+    end
+  end
+
+  # ========================================================================= #
+  # === add_contextfree_art_disclaimer
+  # ========================================================================= #
+  def add_contextfree_art_disclaimer
+    @_ << "(The <b>above image</b> was <b>partially autogenerated</b> "\
+          "using <b>cfdg rules</b>. See this fine project here for "\
+          "more information pertaining to the <b>autogeneration</b> of "\
+          "such - or similar - images: "\
+          "**https://www.contextfreeart.org/gallery/**)\n"
+  end
+
+  # ========================================================================= #
+  # === add_licence_is_MIT                                          (MIT tag)
+  #
+  # This will add the MIT licence to the readme.
+  # ========================================================================= #
+  def add_licence_is_MIT
+    @_ << "
+## Licence
+
+The licence for this gem is the MIT licence.
+
+Basically the most important part of the MIT licence is that, aside
+from you being able to use the project as you see fit, is the no
+warranty disclaimer to avoid any potential misuse from the use
+of the software at hand.
+
+You can read up on this licence here:
+
+https://opensource.org/licenses/MIT
+
+The usual copyright assignment is:
+
+Copyright #{current_year?} Robert Heiler
+
+"
+  end; alias use_the_mit_licence add_licence_is_MIT # === use_the_mit_licence
+
+  # ========================================================================= #
+  # === add_contact_information
+  # ========================================================================= #
+  def add_contact_information
+    @_ << "
+## Contact information and mandatory 2FA (no longer) coming up in 2022 / 2023
+
+If your creative mind has ideas and specific suggestions to make this gem
+more useful in general, feel free to drop me an email at any time, via:
+
+    shevy@inbox.lt
+
+Before that email I used an email account at Google gmail, but in **2021** I
+decided to slowly abandon gmail, for various reasons. In order to limit the
+explanation here, allow me to just briefly state that I do not feel as if I
+want to promote any Google service anymore when the user becomes the end
+product (such as via data collection by upstream services, including other
+proxy-services). My feeling is that this is a hugely flawed business model
+to begin with, and I no longer wish to support this in any way, even if
+only indirectly so, such as by using services of companies that try to
+promote this flawed model.
+
+In regards to responding to emails: please keep in mind that responding 
+may take some time, depending on the amount of work I may have at that
+moment. So it is not that emails are ignored; it is more that I have not
+(yet) found the time to read and reply. This means there may be a delay
+of days, weeks and in some instances also months. There is, unfortunately,
+not much I can do when I need to prioritise my time investment, but I try
+to consider <b>all</b> feedback as an opportunity to improve my projects
+nonetheless.
+
+In <b>2022</b> rubygems.org decided to make 2FA mandatory for every
+gem owner eventually:
+
+see
+https://blog.rubygems.org/2022/06/13/making-packages-more-secure.html
+
+However had, that has been reverted again, so I decided to shorten
+this paragraph. Mandatory 2FA may exclude users who do not have a 
+smartphone device or other means to 'identify'. I do not feel it is
+a fair assumption by others to be made that non-identified people may
+not contribute code, which is why I reject it. Mandatory 2FA would mean
+an end to all my projects on rubygems.org, so let's hope it will never
+happen. (Keep in mind that I refer to mandatory 2FA; I have no qualms
+for people who use 2FA on their own, but this carrot-and-stick strategy
+by those who control the rubygems infrastructure is a very bad one to
+pursue.
+
+"
+  end
+
+  # ========================================================================= #
+  # === run                                                         (run tag)
+  # ========================================================================= #
+  def run
+    read_dataset_from_gen_file
+    store_the_string
+    generate_html_file_via_kramdown
+  end
+
+  # ========================================================================= #
+  # === Roebe::ReadmeGenerator[]
+  # ========================================================================= #
+  def self.[](i = ARGV)
+    new(i)
+  end
+
+end; end
 
 if __FILE__ == $PROGRAM_NAME
   Roebe::ReadmeGenerator.new(ARGV)