program_information 1.1.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ca607b1d436ccedea84032d281b1611f2d38dbdef363fc39f25d9b97603f29cb
+  data.tar.gz: 783469f7383a5ca7608308065ba0f91c750dae7221c4156a90e332f052463cc2
+SHA512:
+  metadata.gz: b6869ce061838966f6963022fa9ba5976e5ee2d93f5ffff477359b13b37e71c4626737d5f32020c910e35ebfc586b12a4105401571c74a69d4b5919959422eb2
+  data.tar.gz: 75937f68f7fc398f47f7b98a91001999041fd45c8c8024b0fdb231080da66791031713cd66ef1e85c2fc59058083ee11b294d2b3716b33bcf9f6b55e6176a7b2

data/README.md

@@ -0,0 +1,9 @@
+## .first and .last
+
+You can obtain the name of the program at hand, and the associated
+version, like so:
+
+    require 'program_information'
+    x = ProgramInformation.new('ruby-2.5.0')
+    puts x.first
+    puts x.last

data/bin/program_information

@@ -0,0 +1,14 @@
+#!/System/Index/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+require 'program_information'
+
+if ARGV.first
+  ProgramInformation::ProgramInformation.new(ARGV).report(:be_verbose)
+else # "Normal" tests here.
+  _ = ProgramInformation.parse 'http://downloads.sourceforge.net/boost/boost_1_54_0.tar.bz2'
+  p ProgramInformation.parse('http://downloads.sourceforge.net/boost/boost_1_54_0.tar.bz2', false)
+end
+# p _.original_program_name
+# pii

data/doc/CONVENTIONS.md

@@ -0,0 +1,22 @@
+Any given input can have three components:
+
+   (1) real_short_name
+   (2) short_name
+   (3) program_version
+
+real_short_name depends on short_name. It simply is short_name with all
+instances of the '_' character removed. It is thus a dependent variable.
+
+The three numbers above also correspond to respective @instance_variables,
+so in other words we have @real_short_name, @short_name and
+@program_version.
+
+The input passed to the main class may be "unclean". The class will try
+# to get the "best" result out of any given input that was supplied, no
+matter how unclean this input was.
+
+It is recommended to use this class when wanting to determine the
+short_name and the program version of any given program.
+
+Note that short_name is allowed to include '-' characters whereas
+real_short_name will strip '-' characters.

data/doc/README.gen

@@ -0,0 +1,9 @@
+## .first and .last
+
+You can obtain the name of the program at hand, and the associated
+version, like so:
+
+    require 'program_information'
+    x = ProgramInformation.new('ruby-2.5.0')
+    puts x.first
+    puts x.last

data/lib/program_information.rb

@@ -0,0 +1,2 @@
+require 'program_information/toplevel_methods.rb'
+require 'program_information/constants/array_test_with_this_as_input.rb'

data/lib/program_information/constants/array_test_with_this_as_input.rb

@@ -0,0 +1,120 @@
+#!/System/Index/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# This is the input that can be used by the testing file.
+# =========================================================================== #
+# require 'program_information/constants/array_test_with_this_as_input.rb'
+# =========================================================================== #
+require 'program_information/constants/regex.rb'
+require 'program_information/toplevel_methods/return_proper_pipe_token_to_this_input.rb'
+
+module ProgramInformation
+
+  # ========================================================================= #
+  # === ProgramInformation::ARRAY_TEST_THIS_AS_INPUT
+  #
+  # The character '|' is not allowed to be part of any program name,
+  # so we wil use this as special token.
+  #
+  # We will insert it at the boundary level.
+  # ========================================================================= #
+  ARRAY_TEST_THIS_AS_INPUT = %w(
+    unieject-6
+    acl_2.2.47-1
+    ncbi_cxx-12_0_0
+    lynx-2.8.8-rel2
+    subtle-0.11.3224-xi
+    font-bitstream-75dpi-1.0.3
+    xf86-input-elographics-1.4.1
+    zope.interface-4.2.0
+    CrownCutlass-Alpha1.4
+    gobject-introspection-1.53.4
+    dvd+rw-tools-7.1
+    font-xfree86-type1-1.0.4
+    lshw-B.02.08.01
+    e_dbus-1.7.10
+    xf86-video-omap-0.4.2
+    at-spi2-core-2.19.2
+    xfce4-dev-tools-4.8.0
+    WebKit-r174650
+    akonadi-calendar-tools-17.08.1
+    Archive-Zip-1.46
+    did_you_mean-1.1.2
+    artemis_v16.0.11
+    chunky_png-1.3.8
+    libedit-20170329-3.1
+    font-adobe-utopia-type1-1.0.4
+    wpa_supplicant-2.6
+    dpkg_1.18.22
+    ncbi-blast-2.6.0+
+    ntfs-3g_ntfsprogs-2017.3.23
+    b43-fwcutter-015
+    wcd-6.0.1-beta3
+    xf86-video-i810-1.7.4
+    gnome-internet-radio-locator-0.9.0
+    SDL2_gfx-1.0.1
+    boost-1_54_0
+    boost_1_65_1.tar.bz2
+    boost_1_65_1
+    oxygen-icons5-5.37.0
+    artemis_v16.0.11.jar
+    mod_python_3.3.1
+    xfce4-statusnotifier-plugin-0.2.0
+    p7zip_16.02_src_all.tar.bz2
+    mime-types-data-3.2016.0521.gem
+    domain_name-0.5.20170404.gem
+    ftp://ftp.alsa-project.org/pub/plugins/alsa-plugins-1.0.29.tar.bz2
+    alsa-plugins-1.0.29.tar.bz2
+    alsa-plugins-1.0.29
+    libquvi-scripts-0.9.20131130
+    btrfs-progs-v4.13.2.tar.xz
+    btrfs-progs-v4.13.2
+    ImageMagick-7.0.7-7
+    Archive-Zip-1.46
+    loop-AES-v3.7d
+    boost-build-2014-10
+    openobex-1.7.1-Source
+    /Users/x/SRC/zope.interface/zope.interface-4.4.2.tar.gz
+    libatomic_ops-7.4.2.tar.gz
+    mod_python-11.10.2017
+    expect5.45.3
+    http://search.cpan.org/CPAN/authors/id/M/MA/MARKOV/XML-LibXML-Simple-0.98.tar.gz
+    https://rubygems.org/downloads/mini_portile2-2.3.0.gem
+    kismet-2016-07-R1.tar.xz
+    nana%201.5.4.zip
+    http://download.icu-project.org/files/icu4c/61.1/icu4c-61_1-src.tgz
+    XML-NamespaceSupport-1.09.tar.xz
+    XML-NamespaceSupport-1.09
+    icu4c-62_1
+    polkit-kde-agent-1-5.15.2
+    polkit-kde-agent-1-5.10.95
+    polkit-qt-1-0.112.0
+    xf86-video-amd-2.7.7.7
+    NVIDIA-Linux-x86-352.63.run
+    xf86-video-s3virge-1.11.0
+    youtube-dl-2019.06.27
+    dvd+rw-tools-7.1
+  )
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  require 'colours/autoinclude'
+  # ========================================================================= #
+  # This is colourized in more detail because it makes it easier to
+  # visualize what is going on, on the commandline.
+  # ========================================================================= #
+  ProgramInformation::ARRAY_TEST_THIS_AS_INPUT.each {|entry|
+    original_entry = entry.dup
+    entry = File.basename(entry)
+    entry = ProgramInformation.return_proper_pipe_token_to_this_input(entry)
+    use_sfancy_colour = Colours.colour_methods_to_specific_colour?[:sfancy]
+    e "#{simp(original_entry.ljust(36))}"\
+      "  ->  "\
+      "#{sfancy(
+        entry.sub(/\|/, Colours.orange('|')+
+        Colours.send(use_sfancy_colour))
+      )}"
+  }
+end

data/lib/program_information/constants/colours.rb

@@ -0,0 +1,42 @@
+#!/System/Index/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+module ProgramInformation
+
+class ProgramInformation
+
+  begin
+    require 'colours'
+  rescue LoadErrors; end
+
+  # ========================================================================= #
+  # === rev
+  # ========================================================================= #
+  def rev
+    Colours.rev
+  end
+
+  # ========================================================================= #
+  # === COLOUR_FOR_REVERT
+  # ========================================================================= #
+  COLOUR_FOR_REVERT = Colours::WHITE # WHITE is defined in the colours project.
+
+  # ========================================================================= #
+  # === APOSTROPH
+  # ========================================================================= #
+  APOSTROPH = Colours::TEAL+'`'+COLOUR_FOR_REVERT # +Colours.rev
+
+  # ========================================================================= #
+  # === NAME_OF_CLASS
+  # ========================================================================= #
+  NAME_OF_CLASS = Colours::CGREY+'ProgramInformation:'+COLOUR_FOR_REVERT
+
+  # ========================================================================= #
+  # === yellow?
+  # ========================================================================= #
+  def yellow?
+    Colours::BOLD_YELLOW
+  end
+
+end; end

data/lib/program_information/constants/constants.rb

@@ -0,0 +1,55 @@
+#!/System/Index/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'program_information/constants/constants.rb'
+# =========================================================================== #
+require 'program_information/constants/regex.rb'
+require 'program_information/constants/colours.rb'
+
+module ProgramInformation
+
+class ProgramInformation
+
+  # ========================================================================= #
+  # === SHALL_WE_DOWNCASE
+  #
+  # So that input such as "Libgnome" can become "libgnome".
+  # ========================================================================= #
+  SHALL_WE_DOWNCASE = false
+
+  # ========================================================================= #
+  # === REMOVE_PLUS_AND_MINUS
+  #
+  # If true then we will remove plus '+' and minus '-' from the program name.
+  # ========================================================================= #
+  REMOVE_PLUS_AND_MINUS = false
+
+  # ========================================================================= #
+  # === REPLACE_PLUS_WITH_LONG_NAME
+  #
+  # If this constant is true then we will replace all '+' with the
+  # string 'plus' as part of the issued name. Note that remove-actions
+  # are stronger, so if the constant REMOVE_PLUS_AND_MINUS was also
+  # set to true, then the constant here will not be honoured at all.
+  # ========================================================================= #
+  REPLACE_PLUS_WITH_LONG_NAME = false
+
+  # ========================================================================= #
+  # === REMOVE_PLUS_TOKEN
+  #
+  # If this constant is true then we will eliminate '+' in the input.
+  #
+  # This overrules the replace-constant called REPLACE_PLUS_WITH_LONG_NAME.
+  #
+  # Also note that if the constant REMOVE_PLUS_AND_MINUS is set to true
+  # then this setting here will always be set to false.
+  # ========================================================================= #
+  REMOVE_PLUS_TOKEN = false
+
+  # ========================================================================= #
+  # === BE_VERBOSE
+  # ========================================================================= #
+  BE_VERBOSE = false
+
+end; end

data/lib/program_information/constants/regex.rb

@@ -0,0 +1,85 @@
+#!/System/Index/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'program_information/constants/regex.rb'
+# =========================================================================== #
+module ProgramInformation
+
+  # ========================================================================= #
+  # === REGEX_FOR_TWO_HYPHENS
+  #
+  # This is valid for input such as 'lynx-2.8.8-rel2' or
+  # 'gobject-introspection-1.53.4' or 'subtle-0.11.3224-xi' or
+  # 'dvd+rw-tools-7.1' or 'Archive-Zip-1.46' or 'btrfs-progs-v4.12.1'
+  # or 'color-tools-1.3.0' or 'libedit-20170329-3.1' or
+  # 'ncbi-blast-2.6.0+' or 'b43-fwcutter-015' or 'wcd-6.0.1-beta3'
+  # or 'oxygen-icons5-5.37.0' or 'btrfs-progs-v4.13.2' or
+  # 'Archive-Zip-1.46' or 'wcd-6.0.1-beta3' or 'openobex-1.7.1-Source'
+  # or 'youtube-dl-2019.06.27'.
+  #
+  # See:
+  #
+  #   https://rubular.com/r/u9Yy3qcxrlp5uG
+  #
+  # ========================================================================= #
+  REGEX_FOR_TWO_HYPHENS = 
+    /([A-Za-z+]{0,12}-?[a-z0-9]{0,9}-?[A-Za-z]{0,14}\d{0,4}-?[A-Za-z0-9]{0,12})-(\d{0,2}\.?[a-z]{0,1}\d{0,2}\.?[a-z]{0,1}\d{0,4}[.|-]?\d{0,8}[A-Za-z]{0,9}\d?\+?)$/
+
+  # ========================================================================= #
+  # === REGEX_FOR_THREE_OR_MORE_HYPHENS
+  #
+  # This is for input such as 'akonadi-calendar-tools-17.08.1' or
+  # 'boost-build-2014-10' or 'xf86-video-i810-1.7.4' or
+  # or 'xfce4-statusnotifier-plugin-0.2.0' or 'mime-types-data-3.2016.0521'
+  # or 'XML-LibXML-Simple-0.98' or 'kismet-2016-07-R1.tar.xz' or
+  # 'polkit-kde-agent-1-5.15.2' or 'xf86-video-amd-2.7.7.7'
+  # or 'xf86-video-s3virge-1.11.0'.
+  #
+  # See: https://rubular.com/r/lCrdU01HE7MRV4
+  # ========================================================================= #
+  REGEX_FOR_THREE_OR_MORE_HYPHENS =
+    /^([A-Za-z]{0,9}\d{0,2}-?[A-Za-z]{0,12}\d{0,2}-?[a-z]{0,9}\d{0,1}-?[A-Za-z]{0,8}-?1?\d{0,3}[a-z]{0,3})-(\d{0,4}\.?\d{0,4}\.?-?[A-Z]{0,1}\d{0,4}\.?\d{0,4})$/
+
+  # ========================================================================= #
+  # === REGEX_FOR_INPUT_HAVING_ONLY_DOTS
+  #
+  # This is valid for strange input such as 'expect5.45.3' or
+  # 'sendmail.8.15.2'. These have no '-' and no '_'.
+  # ========================================================================= #
+  REGEX_FOR_INPUT_HAVING_ONLY_DOTS = # See: http://rubular.com/r/KVePR7ShX3
+    /([a-z]{1,10})\.?(\d+\.?\d{1,2}\.?\d{0,2})/
+
+  # ========================================================================= #
+  # === REGEX_FOR_BOOST_LIKE_INPUT
+  #
+  # Valid input should be 'ncbi_cxx-12_0_0' or 'icu4c-61_1'.
+  #
+  # See: http://rubular.com/r/CyNqJbCMR2
+  # ========================================================================= #
+  REGEX_FOR_BOOST_LIKE_INPUT =
+    /([a-z]{0,3}\d{0,1}[a-z]{0,5}_?[a-z]{0,3})([-|_]{1})(\d{1,2}_\d{1,2}_?\d*)/
+
+  # ========================================================================= #
+  # === REGEX_FOR_ACL_LIKE_INPUT
+  #
+  # Valid input should be 'acl_2.2.47-1' or 'e_dbus-1.7.10' or
+  # 'wpa_supplicant-2.6' or 'SDL2_gfx-1.0.1' or 'libatomic_ops-7.4.2'
+  # or 'mod_python-11.10.2017' or 'mini_portile2-2.3.0.gem'.
+  #
+  # See: http://rubular.com/r/XDdBNWxipp
+  # ========================================================================= #
+  REGEX_FOR_ACL_LIKE_INPUT =
+    /([A-Za-z]{0,10}[0-9]{0,1}_?[0-9]{0,1}[a-z]{1,10}[0-9]{0,1})(_|-)([0-9]{0,2}\.?[0-9]{0,2}\.?[0-9]{0,2}-?[0-9]{0,2}_?[0-9]{0,4})/
+
+  # ========================================================================= #
+  # === REGEX_FOR_INPUT_CONTAINING_TWO_HYPHENS_AND_ONE_UNDERSCORE
+  #
+  # This is input for programs such as 'ntfs-3g_ntfsprogs-2017.3.23'.
+  #
+  # See: http://rubular.com/r/15pAuHKxt5
+  # ========================================================================= #
+  REGEX_FOR_INPUT_CONTAINING_TWO_HYPHENS_AND_ONE_UNDERSCORE =
+    /([a-z]{1}.+)(-)(\d{1,4}\.\d\.\d{1,2})/
+
+end

data/lib/program_information/initialize.rb

@@ -0,0 +1,34 @@
+#!/System/Index/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+module ProgramInformation
+
+class ProgramInformation # === ProgramInformation::ProgramInformation
+
+  # ========================================================================= #
+  # === initialize
+  #
+  # Specific Usage Example:
+  #   ProgramInformation::ProgramInformation.new('util-linux-ng-2.15')
+  # ========================================================================= #
+  def initialize(
+      i                   = ARGV,
+      run_already         = true,
+      optional_be_verbose = false
+    )
+    reset
+    set_input(i)
+    if optional_be_verbose
+      set_be_verbose(optional_be_verbose)
+    end
+    case run_already
+    when :do_run_already
+      run_already = true
+    when :dont_run_already, :do_not_run_already
+      run_already = false
+    end
+    run if run_already
+  end
+
+end; end

data/lib/program_information/menu.rb

@@ -0,0 +1,29 @@
+#!/System/Index/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'program_information/menu.rb'
+# =========================================================================== #
+module ProgramInformation
+
+class ProgramInformation
+
+  # ========================================================================= #
+  # === menu                                                       (menu tag)
+  # ========================================================================= #
+  def menu(i)
+    if i.is_a? Array
+      i.each {|entry| menu(entry) }
+    else
+      case i
+      # ===================================================================== #
+      # === help
+      # ===================================================================== #
+      when /-?-?help$/i
+        show_help
+        exit
+      end
+    end
+  end
+
+end; end

data/lib/program_information/program_information.rb

@@ -0,0 +1,568 @@
+#!/System/Index/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# === ProgramInformation::ProgramInformation
+#
+# The main class will reside here.
+#
+# This class can provide us with the proper name, and the proper version
+# for any given program.
+#
+# We simply take the given input and use three components for it:
+#
+#   (1) real_short_name
+#   (2) short_name
+#   (3) program_version
+#
+# Note that real_short_name depends on short_name. It simply is short_name
+# with all instances of the '_' character removed. It is thus a dependent
+# variable.
+#
+# The three numbers above also correspond to respective @instance_variables,
+# so in other words we have @real_short_name, @short_name and
+# @program_version.
+#
+# The input can be a bit "unclean". The class will try to get the "best"
+# result out of any given input, no matter how unclean it is.
+#
+# It is recommended to use this class when wanting to determine the
+# short_name and the program version of any given program.
+# =========================================================================== #
+# require 'program_information/program_information.rb'
+# =========================================================================== #
+require 'remove_file_suffix'
+require 'program_information/project/project_base_directory.rb'
+require 'program_information/toplevel_methods/e.rb'
+require 'program_information/toplevel_methods/return_proper_pipe_token_to_this_input.rb'
+require 'program_information/toplevel_methods/remove_archive_type.rb'
+require 'program_information/constants/constants.rb'
+require 'program_information/version/version.rb'
+require 'program_information/initialize.rb'
+require 'program_information/menu.rb'
+require 'program_information/reset.rb'
+require 'program_information/report.rb'
+require 'program_information/run.rb'
+
+module ProgramInformation
+
+class ProgramInformation # === ProgramInformation::ProgramInformation
+
+  # ========================================================================= #
+  # === return_proper_pipe_token_to_this_input
+  # ========================================================================= #
+  def return_proper_pipe_token_to_this_input(i)
+    ::ProgramInformation.return_proper_pipe_token_to_this_input(i)
+  end
+
+  # ========================================================================= #
+  # === remove_file_suffix
+  #
+  # Delegate towards class RemoveFileSuffix. This is easier to handle
+  # Archive.
+  # ========================================================================= #
+  def remove_file_suffix(i)
+    RemoveFileSuffix[i.to_s]
+  end
+
+  # ========================================================================= #
+  # === do_not_replace_plus
+  # ========================================================================= #
+  def do_not_replace_plus
+    @replace_plus_with_long_name = false
+  end; alias do_not_replace_anything do_not_replace_plus # === do_not_replace_anything
+
+  # ========================================================================= #
+  # === set_program_version
+  #
+  # Use this method whenever you wish to assign to the @program_version
+  # variable.
+  #
+  # The input to this method may include stuff such as ".tar.xz", which
+  # should be chopped off, as it is not part of the program version.
+  #
+  # Keep in mind that we may also return nil.
+  #
+  # Until March 2015 we also replaced all '_' with '.' characters,
+  # but input such as "ncbi_cxx--12_0_0.tar.gz" would break as a
+  # consequence, so this was disabled again.
+  # ========================================================================= #
+  def set_program_version(i)
+    i = remove_file_suffix(i) unless i.nil? # Disallow archive-types here.
+    # ======================================================================= #
+    # The following check is not good at all because we may have input
+    # such as "1-0.112.0". Polkitqt has this, for instance.
+    # Thus, the following line was disabled on Feb 2016.
+    # ======================================================================= #
+    # if i.include? '-' # In this case, we use only the last part.
+    #   i = i.split('-').last
+    # end
+    # ======================================================================= #
+    # And if result is actually an empty String, but the original input
+    # has included at the least one number, such as in "3.3.6-pl1",
+    # then we will simply use that instead.
+    # ======================================================================= #
+    if i.is_a?(String) and i.empty? and
+       @input =~ /\d+/ # <- If the input has at the least one Number.
+      i = @input.dup
+    end
+    @program_version = i
+  end; alias set_version set_program_version # === set_version
+
+  # ========================================================================= #
+  # === be_verbose?
+  # ========================================================================= #
+  def be_verbose?
+    @be_verbose
+  end
+
+  # ========================================================================= #
+  # === remove_plus_token?
+  # ========================================================================= #
+  def remove_plus_token?
+    @remove_plus_token
+  end
+
+  # ========================================================================= #
+  # === input?
+  # ========================================================================= #
+  def input?
+    @input
+  end
+
+  # ========================================================================= #
+  # === return_array
+  #
+  # This method will return a composite, 3-member Array that will hold the
+  # short_name, the real_short_name, and the program_version.
+  # ========================================================================= #
+  def return_array
+    [ short_name?, real_short_name?, program_version? ]
+  end; alias array? return_array # === array?
+
+  # ========================================================================= #
+  # === remove_plus_and_minus?
+  # ========================================================================= #
+  def remove_plus_and_minus?
+    @remove_plus_and_minus
+  end; alias remove_plus_and_minus remove_plus_and_minus? # === remove_plus_and_minus
+
+  # ========================================================================= #
+  # === apostroph?
+  # ========================================================================= #
+  def apostroph?
+    APOSTROPH
+  end
+
+  # ========================================================================= #
+  # === replace_plus_with_long_name?
+  # ========================================================================= #
+  def replace_plus_with_long_name?
+    @replace_plus_with_long_name
+  end
+
+  # ========================================================================= #
+  # === short_name_and_version?
+  #
+  # This method returns an aggregated @short_name+'-'+@program_version
+  # string.
+  # ========================================================================= #
+  def short_name_and_version?
+    "#{short_name?}-#{program_version?}"
+  end; alias short_name_and_version short_name_and_version? # === short_name_and_version
+
+  # ========================================================================= #
+  # === set_short_name_then_version
+  #
+  # This method will combine two other methods.
+  # ========================================================================= #       
+  def set_short_name_then_version(a, b)
+    set_short_name(a)
+    set_program_version(b)
+  end; alias set_name_then_version set_short_name_then_version # === set_name_then_version
+
+  # ========================================================================= #
+  # === return_real_short_name_and_version
+  #
+  # We delegate to the module-method here.
+  # ========================================================================= #
+  def return_real_short_name_and_version(i)
+    ::ProgramInformation.return_real_short_name_and_version(i)
+  end
+
+  # ========================================================================= #
+  # === return_name_and_version
+  #
+  # This method will return an array with two elements:
+  #
+  #   (1) The first element is the name of the program in question.
+  #   (2) The second element is the version of the program in question.
+  #
+  # The input can be rather tricky and complicated.
+  #
+  # Consider the following examples:
+  #
+  #     'libunwind-1.0-rc1'
+  #     'htop-1.0.0'
+  #     'WebKit-r93670'
+  #     'xfce4-dev-tools-4.8.0'
+  #     'e_dbus-1.7.10.tar.gz'
+  #     'boost_1_54_0.tar.bz2'
+  #     'short-mime-1.0.0-rc1'
+  #
+  # This can all be valid input.
+  #
+  # Which are the key-assumptions that we can do here?
+  #
+  # I think the best assumption we can do is to find the first NUMBER in
+  # the given string, and then group the rest of the data according to
+  # this NUMBER. This will not work in the case of something such as
+  # WebKit-r93, as there is a 'r' character before that number.
+  # So we will have to make a second assumption: if the character preceding
+  # the first found integer is NOT a '-' character, we will instead split
+  # on that character instead. This will however lead to a problem for 
+  # something like "xfce4-dev-tools-4.8.0". So, in case there is a '-'
+  # character immediately after the pos variable, we assume we have such
+  # a special case.
+  #
+  # On Sep 2011, I came up with a far simpler idea. We simply have to
+  # find the most important '-' and then split accordingly. As long as
+  # we can identify the most important '-' correctly, so long will
+  # everything else "just work". This also did not work out, so I
+  # switched to a regex instead. Since then it has worked very fine.
+  #
+  # Take input such as:
+  #
+  #   "font-bitstream-75dpi-1.0.0"
+  #
+  # Note though that this approach does not work with input like:
+  #   "CrownCutlass-Alpha1.4"
+  # unless we assume that alpha is a part of the version,
+  # which is possibly correct.
+  # ========================================================================= #
+  def return_name_and_version(i = nil)
+    if i
+      determine_the_three_main_variables(i)
+    end
+    # ======================================================================= #
+    # We must consider what we wish to do about the '_' characters. We could
+    # remove them, but certain programs such as e_dbus may require it as 
+    # part of their name. Also, Version entries such as '1_2_3' will become
+    # '123' rather than '1.2.3'. Thus, on Jan 2014 I have disabled the
+    # following line.
+    # ======================================================================= #
+    # i.delete!('_') if i.include? '_'
+    return [
+      @short_name, @program_version
+    ]
+  end; alias rnav return_name_and_version # === rnav
+
+  # ========================================================================= #
+  # === set_shall_we_downcase
+  # ========================================================================= #
+  def set_shall_we_downcase(
+      i = SHALL_WE_DOWNCASE
+    )
+    @shall_we_downcase = i
+  end
+
+  # ========================================================================= #
+  # === do_not_downcase
+  # ========================================================================= #
+  def do_not_downcase
+    @shall_we_downcase = false
+  end
+  
+  # ========================================================================= #
+  # === set_be_verbose
+  #
+  # Set to report in a verbose way here.
+  # ========================================================================= #
+  def set_be_verbose(i = BE_VERBOSE)
+    case i
+    when :be_verbose
+      i = true
+    end
+    @be_verbose = i
+  end
+
+  # ========================================================================= #
+  # === determine_the_three_main_variables
+  #
+  # This method will determine the three main instance variables:
+  #
+  #   - @short_name
+  #   - @real_short_name
+  #   - @program_version
+  #
+  # We must be careful, as the input may not include any '-' or '_' token,
+  # and then the regex would fail. Hence, the behaviour of this method
+  # will depend on whether the input includes a '-' or whether it
+  # does not.
+  #
+  # Note that presently, set_input() will modify the given input and
+  # ensure that there will be a '-' token, even in input that does
+  # not have any '-' or '_' such as in 'sendmail.8.15.2'.
+  # ========================================================================= #
+  def determine_the_three_main_variables(i = @input)
+    if i
+      if i.include? '|'
+        splitted        = i.split('|')
+        short_name      = splitted.first.to_s.dup
+        program_version = splitted.last.to_s.dup
+        set_short_name(short_name)
+        set_program_version(program_version)
+      else
+        opn; e "The input `#{i}` does not include a | character."
+      end
+    end
+  end; alias determine_name_and_program_version determine_the_three_main_variables # === determine_name_and_program_version
+
+  # ========================================================================= #
+  # === set_real_short_name
+  #
+  # The instance variable @real_short_name is not allowed to include any
+  # '-' characters. It may also not include any '_' characters.
+  #
+  # The latter could be found as part of program names such as "SDL_image".
+  # The @short_name variant may include these '_' tokens.
+  #
+  # Note that as of September 2017, we also disallow '.' tokens, such as
+  # may occur accidentally in input like "sendmail.5.8.2".
+  # ========================================================================= #
+  def set_real_short_name(i = @short_name)
+    i = i.to_s.dup.delete('-_.').rstrip
+    @real_short_name = i
+  end
+
+  # ========================================================================= #
+  # === set_short_name
+  #
+  # Use this method whenever you wish to assign to the @short_name variable.
+  #
+  # This variable is allowed to keep '-' and '_' entries, but some
+  # settings may also modify this.
+  # ========================================================================= #
+  def set_short_name(i)
+    i = i.dup
+    # ======================================================================= #
+    # First, consider getting rid of '+' and '-' tokens in the
+    # @short_name variant of the program name.
+    # For this to work, @remove_plus_and_minus has to be set to true.
+    # ======================================================================= #
+    if remove_plus_and_minus?
+      i.delete!('+') if i.include? '+'
+      i.delete!('-') if i.include? '-'
+    end
+    # ======================================================================= #
+    # === Get rid of '+' tokens, if they are included.
+    # ======================================================================= #
+    if remove_plus_token?
+      i.delete!('+') if i.include? '+'
+    # ======================================================================= #
+    # === Alternatively, replace '+' with the string 'plus' should it
+    # exist there.
+    # ======================================================================= #
+    elsif replace_plus_with_long_name?
+      i.gsub!(/\+/, 'plus') if i.include? '+'
+    end
+    @short_name = i
+    set_real_short_name(i) # We will also sync towards @real_short_name.
+  end; alias set_name         set_short_name # === set_name
+       alias set_program_name set_short_name # === set_program_name
+
+  # ========================================================================= #
+  # === remove_source_like_strings
+  # ========================================================================= #
+  def remove_source_like_strings(i)
+    # ======================================================================= #
+    # i.gsub!(/--/,'-') if i.include? '--' # Replace '--' with '-'.
+    # ^^^ May not be good, depending on the input.
+    # ======================================================================= #
+    i.sub!(/-src/,'')     if i.include?  '-src' # Get rid of -src entries.
+    i.sub!(/\.source/,'') if i.include?  '.source'
+    i.sub!(/-source$/,'') if i.end_with? '-source'
+    return i
+  end
+
+  # ========================================================================= #
+  # === remove_archive_type
+  # ========================================================================= #
+  def remove_archive_type(i)
+    ::ProgramInformation.remove_archive_type(i)
+    return i
+  end
+
+  # ========================================================================= #
+  # === e
+  # ========================================================================= #
+  def e(i = '')
+    ::ProgramInformation.e(i)
+  end
+
+  # ========================================================================= #
+  # === real_short_name?
+  #
+  # Keep in mind that @real_short_name does not have any '-' tokens.
+  # ========================================================================= #
+  def real_short_name?
+    @real_short_name
+  end; alias real_name?           real_short_name? # === real_name?
+       alias real_program_name?   real_short_name? # === real_program_name?
+       alias real_short_name      real_short_name? # === real_short_name
+       alias name_of_the_program? real_short_name? # === name_of_the_program?
+
+  # ========================================================================= #
+  # === short_name?
+  #
+  # Reader method for the @short_name instance variable.
+  #
+  # short_name is an alias to @short_name.
+  # ========================================================================= #
+  def short_name?
+    @short_name
+  end; alias program_name             short_name? # === program_name
+       alias program_name?            short_name? # === program_name?      
+       alias name                     short_name? # === name
+       alias name?                    short_name? # === name?
+       alias return_short_name        short_name? # === return_short_name
+       alias short_name               short_name? # === short_name
+       alias return_name              short_name? # === return_name
+       alias first                    short_name? # === first
+       alias return_program_real_name short_name? # === return_program_real_name
+
+  # ========================================================================= #
+  # === program_version?
+  #
+  # Getter method for the @program_version variable.
+  # ========================================================================= #
+  def program_version?
+    @program_version
+  end; alias program_version         program_version? # === program_version
+       alias version                 program_version? # === version
+       alias version?                program_version? # === version?
+       alias last?                   program_version? # === last?
+       alias last                    program_version? # === last?
+       alias version_of_the_program? program_version? # === version_of_the_program?
+
+  # ========================================================================= #
+  # === set_input
+  #
+  # This method will, after performing some sanitize-operations, assign
+  # to the @input variable.
+  # ========================================================================= #
+  def set_input(i)
+    if i.is_a? Array
+      menu(i)
+      i = i.join(' ').strip
+    end
+    i = i.to_s.dup if i.frozen?
+    i = File.basename(i)
+    # ======================================================================= #
+    # We .squeeze away '--' tokens.
+    # ======================================================================= #
+    i.squeeze!('-')
+    i.strip!
+    # ======================================================================= #
+    # Next, some simple replacements without any method.
+    # ======================================================================= #
+    i.sub!(/-paco/,'')        if i.include? '-paco'
+    i.sub!(/\/Programs\//,'') if i.include? '/Programs'
+    # ======================================================================= #
+    # The following must not conflict with i.e. "pkgconfig", hence why we
+    # also include a '/' character.
+    # ======================================================================= #
+    i.gsub!(/\/pkg/,'') if i.include? '/pkg'
+    # ======================================================================= #
+    # i.gsub!(/\//,'-') # Controversial. Disabled for now as of Jan 2014.
+    # ======================================================================= #
+    # We don't want either { or }.
+    # ======================================================================= #
+    i.delete!('{') if i.include? '{'
+    i.delete!('}') if i.include? '}'
+    # ======================================================================= #
+    # As of July 2016, we get rid of all tokens that follow a '#' character.
+    # We also will get rid of the '#' as well. Must come before we call
+    # remove_archive_type().
+    # ======================================================================= #
+    if i.include? '#'
+      i = i[0...i.index('#')]
+    end
+    i = remove_archive_type(i)
+    i = remove_source_like_strings(i)
+    # ======================================================================= #
+    # Next, we correct for input such as "nana%201.5.4". This one has no
+    # '-' token and no '_' token, but a '%' token. This '%' token will be
+    # replaced.
+    # ======================================================================= #
+    if i.include? '%'
+      unless i.include?('_') or i.include?('-')
+        i.tr!('%','-')
+      end
+    end
+    # ======================================================================= #
+    # Leading '-' will be removed.
+    # ======================================================================= #
+    i[0,1] = '' if i.start_with? '-'
+    # ======================================================================= #
+    # === Handle downcasing of the given input
+    #
+    # This will consider downcasing the input. The reason as to why this is
+    # necessary is so that input such as "Libgnome" can become "libgnome".
+    # ======================================================================= #
+    i.downcase! if @shall_we_downcase
+    # ======================================================================= #
+    # === Handle '+' tokens
+    # ======================================================================= #
+    if REMOVE_PLUS_TOKEN
+      i.delete!('+') if i.include? '+'
+    end
+    i = return_proper_pipe_token_to_this_input(i)
+    @input = i
+  end
+
+  # ========================================================================= #
+  # === show_help                                                  (help tag)
+  #
+  # To invoke this method, try:
+  #
+  #   pinfo --show-help
+  #
+  # ========================================================================= #
+  def show_help
+    e
+    e 'This class is able to split a given input (a string) into'
+    e 'the inferred program-name, and associated program version '\
+      'of said string.'
+    e
+    e 'For example, if you have this input string:'
+    e
+    e '  gobject-introspection-1.52.1'
+    e
+    e 'then this class can split this into these constituents:'
+    e
+    e '  @real_short_name: gobjectintrospection'
+    e '  @short_name:      gobject-introspection'
+    e '  @program_version: 1.52.1'
+    e
+    e 'This is especially useful for other projects that require this'
+    e 'functionality, such as the rbt gem.'
+    e
+  end
+
+end
+
+# =========================================================================== #
+# === ProgramInformation[]
+# =========================================================================== #
+def self.[](i)
+  ::ProgramInformation::ProgramInformation.new(i)
+end; self.instance_eval { alias new      [] } # === ProgramInformation.new
+     self.instance_eval { alias parse    [] } # === ProgramInformation.parse
+     self.instance_eval { alias combined [] } # === ProgramInformation.combined
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  ProgramInformation::ProgramInformation.new(ARGV)
+end # pinfo /Users/x/SRC/gobjectintrospection/gobject-introspection-1.52.1.tar.xz