open 0.1.30

data/lib/open/open.rb

@@ -0,0 +1,1057 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# === Open::Open
+#
+# This class will simply open a given file. It may also "open" the file
+# in the browser, that is, to use primarily firefox to display the file
+# content as such.
+#
+# Usage example:
+#
+#   Open::Open.new(ARGV)
+#
+# =========================================================================== #
+# require 'open/open.rb'
+# Open::Open.new(ARGV)
+# =========================================================================== #
+require 'open/base/base.rb'
+
+module Open
+
+class Open < ::Open::Base # === Open::Open
+
+  require 'open/in_editor/in_editor.rb'
+  require 'open/in_browser/in_browser.rb'
+  require 'open/toplevel_code/toplevel_code.rb'
+
+  begin
+    require 'roebe/classes/find_expanded_alias.rb'
+  rescue LoadError; end
+
+  # ========================================================================= #
+  # === LIBREOFFICE
+  #
+  # A hardcoded path. This is no longer as important as it used to be,
+  # though. In the future, it may include an ENV value.
+  # ========================================================================= #
+  # LIBREOFFICE = '/usr/bin/soffice'
+  # LIBREOFFICE = '/opt/libreoffice/program/soffice'
+  if ENV['PATH_TO_THE_LIBREOFFICE_EXECUTABLE']
+    LIBREOFFICE = ENV['PATH_TO_THE_LIBREOFFICE_EXECUTABLE'].to_s.dup
+  else
+    LIBREOFFICE = '/usr/bin/soffice'
+  end
+
+  # ========================================================================= #
+  # === USE_THIS_MPLAYER_COMMAND
+  # ========================================================================= #
+  USE_THIS_MPLAYER_COMMAND =
+    'mplayer -vo x11'
+
+  # ========================================================================= #
+  # === DELAY_IF_WE_HAVE_MORE_THAN_N_ENTRIES
+  # ========================================================================= #
+  DELAY_IF_WE_HAVE_MORE_THAN_N_ENTRIES = 4
+
+  # ========================================================================= #
+  # === USE_THIS_DELAY
+  #
+  # Sleep in n seconds before opening a file, if we have more
+  # entries than the above threshold value did define.  
+  # ========================================================================= #
+  USE_THIS_DELAY = 0.65
+
+  # ========================================================================= #
+  # === ARRAY_EXTENSIONS_THAT_CAN_BE_OPENED_IN_THE_EDITOR
+  #
+  # All extensions that can be opened in the editor should be registered
+  # in this constant.
+  #
+  # For example, "h" means ".h" aka a C or C++ header file.
+  # ========================================================================= #
+  ARRAY_EXTENSIONS_THAT_CAN_BE_OPENED_IN_THE_EDITOR = %w(
+    php rb txt yaml yml cgi 
+    md gemspec html csv py
+    conf c sh js log css cr
+    ascii la pl perl json
+    js fasta fa m3u cpp
+    go gff gff3 
+    gen h
+    erb sinatra
+    sql
+  ).sort << '' # The last part is for files like "TODO" which lack an extension.
+
+  # ========================================================================= #
+  # === ARRAY_LIBREOFFICE_EXTENSIONS
+  #
+  # All libreoffice extensions will be stored here.
+  # ========================================================================= #
+  ARRAY_LIBREOFFICE_EXTENSIONS = %w(
+    xls
+    odt
+    doc
+    docx
+    ppt
+    xlsx
+    sxw
+    swx 
+    rtf
+    ods
+    odp
+    pptx
+    pps
+  )
+
+  # ========================================================================= #
+  # === ARRAY_IMAGES
+  #
+  # All file-extensions for images can be registered in this Array.
+  # ========================================================================= #
+  ARRAY_IMAGES = %w(
+    png
+    jpg
+    gif
+    jpeg
+    tiff
+    tif
+    bmp
+  )
+
+  # ========================================================================= #
+  # === ARRAY_VIDEOS
+  # ========================================================================= #
+  ARRAY_VIDEOS = %w(
+    vob
+    avi
+    flv
+    mp3
+    mp4
+  )
+
+  # ========================================================================= #
+  # === initialize
+  # ========================================================================= #
+  def initialize(
+      i           = nil,
+      run_already = true,
+      &block
+    )
+    reset
+    set_input(i)
+    # ======================================================================= #
+    # === Handle blocks next
+    # ======================================================================= #
+    if block_given?
+      yielded = yield
+      # ===================================================================== #
+      # === Handle hashes next
+      # ===================================================================== #
+      if yielded.is_a? Hash
+        # =================================================================== #
+        # === :use_this_editor
+        # =================================================================== #
+        if yielded.has_key? :use_this_editor
+          set_use_this_editor(yielded.delete(:use_this_editor))
+        end
+        # =================================================================== #
+        # === :open_via_fullscreen
+        # =================================================================== #
+        if yielded.has_key? :open_via_fullscreen
+          @open_via_fullscreen = yielded.delete(:open_via_fullscreen)
+        end
+      end
+    end
+    run if run_already
+  end
+
+  # ========================================================================= #
+  # === reset                                                     (reset tag)
+  # ========================================================================= #
+  def reset
+    super()
+    infer_the_namespace
+    # ======================================================================= #
+    # === @image_editor
+    # ======================================================================= #
+    @image_editor = 'gimp'
+    # ======================================================================= #
+    # === @editor
+    # ======================================================================= #
+    @editor = use_which_editor?
+    # ======================================================================= #
+    # === @set_the_main_book
+    # ======================================================================= #
+    @set_the_main_book = false
+    # ======================================================================= #
+    # === @open_via_fullscreen
+    # ======================================================================= #
+    @open_via_fullscreen = false
+  end
+
+  # ========================================================================= #
+  # === set_the_main_book?
+  # ========================================================================= #
+  def set_the_main_book?
+    @set_the_main_book
+  end
+
+  # ========================================================================= #
+  # === set_use_this_editor
+  # ========================================================================= #
+  def set_use_this_editor(
+      i = use_which_editor?
+    )
+    @editor = i.to_s
+  end
+
+  # ========================================================================= #
+  # === replace_localhost_with_data
+  # ========================================================================= #
+  def replace_localhost_with_data(i)
+    if i.include? 'programming'
+      return i.sub('localhost','/home/x/')
+    else
+      return i.sub('localhost','/home/x/data/')
+    end
+  end
+
+  # ========================================================================= #
+  # === set_input
+  # ========================================================================= #
+  def set_input(i = ARGV)
+    i = [i] unless i.is_a? Array
+    i.map! {|entry|
+      entry = entry.to_s.dup
+      # ===================================================================== #
+      # Split away at '::' if this is part of that substring.
+      # ===================================================================== #
+      if entry.include? '::'
+        splitted = entry.split('::')
+        entry = splitted.last
+      end
+      if entry.include? '^'
+        entry.delete!('^')
+      end
+      case entry
+      # ===================================================================== #
+      # === open --everything
+      #
+      # This actually refers only to files, so we select for files next.
+      # ===================================================================== #
+      when /^-?-?everything?$/i
+        entry = Dir['**/**'].select {|inner_entry| File.file?(inner_entry) }
+      # ===================================================================== #
+      # === open --important-exam
+      # ===================================================================== #
+      when /^-?-?important(-|_)?exams?$/i
+        base_dir = ENV['USERS']
+        base_dir = '/home' if base_dir.nil?
+        entry = "#{base_dir}/x/programming/ruby/src/studium/lib/studium/yaml/important_exams.yml"
+      end
+      # ===================================================================== #
+      # Get rid of localhost next. This must be handled with more care,
+      # because some files may include the string 'localhost' as part of
+      # their name, such as 'remove_localhost.rb'. In this case, we will
+      # additionally check whether the file exists.
+      # ===================================================================== #
+      if entry.is_a?(String) and entry.include?('localhost')
+        unless File.exist? entry # See the above header for an explanation.
+          entry = replace_localhost_with_data(entry)
+        end
+      end
+      if entry.is_a? String
+        entry.chop! if entry.end_with? '#'  # Don't need trailing '#' tokens.
+        entry.chop! if entry.end_with? ':-' # ← This check must come before the check against ':'. 
+        entry.chop! if entry.end_with? ':'  # Chop off trailing ':' tokens.
+        # ===================================================================== #
+        # Next, we handle input such as:
+        #   'lib/lpc/requires/basic_requires.rb:begin'
+        # This evidently does not end with a ':' character, but it clearly
+        # has a fairly useless ':' component in it. If that is the case,
+        # we will treat this as input that is only valid up towards the
+        # very right ':', anchored on the '.rb:' part.
+        # ===================================================================== #
+        if entry.include? '.rb:'
+          # =================================================================== #
+          # The following code means to find the index at '.rb:' and then add
+          # 2 to it - this should be the correct name of the entry at hand.
+          # =================================================================== #
+          entry = entry[0 .. (entry.index('.rb:')+2)]
+        end
+        if entry.end_with?(',') and !File.exist?(',')
+          entry.chop!
+        elsif entry.end_with?('.') and File.exist?(entry[0..-2])
+          # =================================================================== #
+          # This clause will be entered if we have input something like
+          # "colours.rb." where the user may have wanted to type in
+          # "colours.rb" - and IF the file exists.
+          # =================================================================== #
+          opnn; e "Assuming a superfluous trailing '.', so removing "\
+                  "the last '.' there."
+          entry.chop!
+        end
+      end
+      case entry # Work only on the first entry. (case tag)
+      # ===================================================================== #
+      # === open ME
+      # ===================================================================== #
+      when 'ME',
+           'SELF',
+           'ALL',/
+           ^-?-?this(_|-)?file/
+        open_this_file_here
+        exit
+      # ===================================================================== #
+      # === open --help
+      # ===================================================================== #
+      when /^-?-?help$/i,
+           'show_help'
+        show_help
+        exit
+      end unless File.exist?(entry.to_s)
+      entry
+    }
+    @input = i # This must be an Array.
+  end; alias set_input_files set_input # === set_input_files
+
+  # ========================================================================= #
+  # === input?
+  # ========================================================================= #
+  def input?
+    @input
+  end; alias input_file?  input? # === input_file?
+       alias input_files? input? # === input_files?
+
+  # ========================================================================= #
+  # === check_whether_the_user_has_provided_any_input
+  # ========================================================================= #
+  def check_whether_the_user_has_provided_any_input
+    _ = input_files?
+    local_files = Dir['*'].select {|entry| File.file? entry }
+    if _.empty? and !local_files.empty? and (local_files.size == 1)
+      # ===================================================================== #
+      # Handle the case where no specific input was given, but only
+      # one file exists in the local directory.
+      # ===================================================================== #
+      set_input_files(local_files.first)
+      _ = input_files?
+    end
+    if _.empty?
+      if is_on_roebe? and !is_bluefish_running?
+        start_bluefish
+      else
+        opnn; e 'Please provide at least one argument - the file '\
+                'you wish to open.'
+        exit
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === start_bluefish
+  # ========================================================================= #
+  def start_bluefish
+    esystem 'bluefish &'
+  end
+
+  # ========================================================================= #
+  # === is_bluefish_running?
+  # ========================================================================= #
+  def is_bluefish_running?
+    `ps ax | grep bluefish`.split("\n").reject {|entry|
+      entry.include? 'grep'
+    }.size > 0
+  end
+
+  # ========================================================================= #
+  # === consider_padding
+  #
+  # Simply add a surrounding '"' to the given input, so that any resulting
+  # system() call will still work if we have awkward filenames.
+  # ========================================================================= #
+  def consider_padding(i)
+    if i.include?(' ') or i.include?('(')
+      i = '"'+i+'"'
+    end
+    return i
+  end
+
+  # ========================================================================= #
+  # === play_multimedia_file
+  # ========================================================================= #
+  def play_multimedia_file(i)
+    esystem "#{USE_THIS_MPLAYER_COMMAND} #{i}" # open 
+  end
+
+  # ========================================================================= #
+  # === open_this_file_here
+  # ========================================================================= #
+  def open_this_file_here
+    do_open_in_editor(this_file?+IN_BACKGROUND)
+  end
+
+  # ========================================================================= #
+  # === return_this_file_here
+  # ========================================================================= #
+  def return_this_file_here
+    __FILE__
+  end; alias this_file? return_this_file_here # === this_file?
+
+  # ========================================================================= #
+  # === delay?
+  # ========================================================================= #
+  def delay?
+    USE_THIS_DELAY
+  end
+
+  # ========================================================================= #
+  # === find_and_return_last_file
+  # ========================================================================= #
+  def find_and_return_last_file
+    array = Dir['*'].reject {|entry| ! File.file? entry }
+    array.map! {|entry|
+      [entry, File.ctime(entry)]
+    }
+    result = array.sort_by {|entry| entry[1] }.reverse
+    result = result.first[0]
+    return result
+  end
+
+  # ========================================================================= #
+  # === can_be_opened_in_the_editor?
+  # ========================================================================= #
+  def can_be_opened_in_the_editor?(i)
+    _ = File.extname(i).delete('.')
+    ARRAY_EXTENSIONS_THAT_CAN_BE_OPENED_IN_THE_EDITOR.include? i
+  end
+
+  # ========================================================================= #
+  # === try_to_open_this_file_in_the_editor
+  # ========================================================================= #
+  def try_to_open_this_file_in_the_editor(
+      i = input_files?
+    )
+    # ======================================================================= #
+    # === First check whether we have passed an Array
+    # ======================================================================= #
+    if i.is_a? Array # Array tag
+      if i.size > DELAY_IF_WE_HAVE_MORE_THAN_N_ENTRIES
+        opnn; e 'More than '+simp(DELAY_IF_WE_HAVE_MORE_THAN_N_ENTRIES.to_s)+
+                ' entries given ('+i.size.to_s+'), hence we will use a '\
+                'small delay (of '+sfancy(delay?.to_s)+' seconds).'
+      end
+      i.each {|entry|
+        sleep delay? if i.size > DELAY_IF_WE_HAVE_MORE_THAN_N_ENTRIES # Small delay.
+        try_to_open_this_file_in_the_editor(entry)
+      }
+    else
+      # ===================================================================== #
+      # Get rid of localhost-string parts next.
+      # ===================================================================== #
+      if i.include? 'localhost'
+        i = replace_localhost_with_data(i)
+      end unless File.exist? i
+      # ===================================================================== #
+      # Next, we chop off '?' characters. This is, however had, not good if
+      # this is part of the filename. So we must check if the file exists,
+      # prior to doing this check.
+      # ===================================================================== #
+      unless File.exist? i
+        i = i[0..i.index('?')] if i.include? '?'
+      end
+      # ===================================================================== #
+      # Get rid of '#' in the input, if it exists.
+      # ===================================================================== #
+      i = i[0..i.index('#')] if i.include? '#'
+      case i
+      when 'LAST' # Assign the last file.
+        i = find_and_return_last_file
+      end
+      # ===================================================================== #
+      # Next, act on the extension name.
+      # ===================================================================== #
+      _ = File.extname(i).delete('.').downcase
+      case _ # case tag
+      # ===================================================================== #
+      # === open .pdf files
+      # ===================================================================== #
+      when 'pdf'
+        open_in_pdf_viewer(i)
+      # ===================================================================== #
+      # === epub
+      # ===================================================================== #
+      when 'epub'
+        esystem "okular #{i} &"
+      # ===================================================================== #
+      # === torrent
+      # ===================================================================== #
+      when 'torrent'
+        open_this_torrent_file(i)
+      # ===================================================================== #
+      # === Extensions that can be opened in the editor
+      # ===================================================================== #
+      when *ARRAY_EXTENSIONS_THAT_CAN_BE_OPENED_IN_THE_EDITOR
+        open_in_browser_or_in_editor(i)
+      # ===================================================================== #
+      # === All registered images
+      # ===================================================================== #
+      when *ARRAY_IMAGES
+        open_in_gimp(i)
+      # ===================================================================== #
+      # === All libreoffice extensions
+      # ===================================================================== #
+      when *ARRAY_LIBREOFFICE_EXTENSIONS
+        open_in_office(i)
+      # ===================================================================== #
+      # === All videos
+      # ===================================================================== #
+      when *ARRAY_VIDEOS
+        play_multimedia_file(i)
+      else
+        if File.exist? i
+          opnn; e "Not registered extension `#{sfancy(_)}`."
+          opnn; e 'We will attempt to open it anyway though.'
+          open_in_browser_or_in_editor(i)
+        else # else we conclude that the file does not exist.
+          no_file_was_found_at(i)
+        end
+      end
+    end
+  end; alias consider_opening_the_given_input try_to_open_this_file_in_the_editor # === consider_opening_the_given_input
+       alias open_in_editor                   try_to_open_this_file_in_the_editor # === open_in_editor
+       alias open_these_files                 try_to_open_this_file_in_the_editor # === open_these_files
+
+  # ========================================================================= #
+  # === open_this_torrent_file
+  # ========================================================================= #
+  def open_this_torrent_file(i)
+    if i.include?("'") and !i.include?('"')
+      i = '"'+i+'"'
+    end
+    _ = "transmission #{i} &"
+    esystem(_)  
+  end
+
+  # ========================================================================= #
+  # === try_to_find_files_based_on_hyphens_as_part_of_the_input
+  #
+  # This method will try to find files based on '::' input.'
+  # ========================================================================= #
+  def try_to_find_files_based_on_hyphens_as_part_of_the_input(i)
+    if i.include? '::'
+      # ===================================================================== #
+      # In this case, replace '::', after passing it through the
+      # snakecase() method.
+      # ===================================================================== #
+      i = snakecase_and_prepend_first_name_and_lib(i).tr('::','/')+'/'
+    end
+    unless i.start_with?('/home')
+      # ===================================================================== #
+      # We assume that only ruby files follow the '::' layout, for now. (Jun 2017)
+      # ===================================================================== #
+      i.prepend('$RUBY_SRC/')
+    end
+    if i.include? '$'
+      i = convert_global_env(i)
+    end
+    i.squeeze!('/')
+    unless i.end_with?('*')
+      i << '*'
+    end
+    these_files = Dir[i]
+    open_these_files(these_files)
+  end
+
+  # ========================================================================= #
+  # === snakecase_and_prepend_first_name_and_lib
+  #
+  # This combines snakecase() by also prepending the first-name
+  # and "lib/" prefix.
+  # ========================================================================= #
+  def snakecase_and_prepend_first_name_and_lib(i)
+    if i.include? '::'
+      splitted = i.split('::')
+      first_name = splitted.first.downcase
+    end
+    i = snakecase(i)
+    return first_name+'/lib/'+i
+  end
+
+  # ========================================================================= #
+  # === register_this_pdf_file
+  # ========================================================================= #
+  def register_this_pdf_file(what)
+    begin
+      require 'save_file'
+      require 'roebe/constants/file_constants.rb'
+      require 'roebe/constants/directory_constants.rb'
+    rescue LoadError; end
+    into = Roebe.file_these_pdf_files_were_opened
+    old_dataset = nil
+    if File.exist? into
+      # ===================================================================== #
+      # Sanitize this .yml file, in that case.
+      # ===================================================================== #
+      old_dataset = YAML.load_file(into).uniq
+      this_content = old_dataset.map {|entry| entry.prepend(' - ') }.join("\n")
+      SaveFile.write_what_into(this_content, into)
+    end
+    _ = Roebe.log_directory?
+    mkdir(_) unless File.directory? _
+    if old_dataset and old_dataset.map {|entry|
+        # =================================================================== #
+        # ensure_main_encoding is necessary to avoid illegal byte sequences.
+        # =================================================================== #
+        # ensure_main_encoding(entry).strip.delete('-').strip
+        # ^^^ Disabled as of September 2021. Let's see if we really need it still.
+        entry.strip.delete('-').strip
+      }.include? what
+      # ===================================================================== #
+      # In this case, we will remove the old entries, and then append.
+      # ===================================================================== #
+      old_dataset = YAML.load_file(into).uniq.reject {|entry|
+        # entry = ensure_main_encoding(entry) # Need to use a consistent encoding here.
+        # ^^^ Disabled as of September 2021.
+        entry.include? what
+      }
+      this_content = old_dataset.map {|entry|
+        entry.prepend(' - ')
+      }.join("\n")
+      SaveFile.write_what_into(this_content, into)
+    end
+    what = "\n - #{what}"
+    touch(into) unless File.exist? into
+    SaveFile.append_what_into(what, into) # Silently store that.
+  end
+
+  # ========================================================================= #
+  # === open_in_browser_or_in_editor
+  #
+  # This method was required because sometimes we wish to open in the
+  # browser, and sometimes we wish to open in the editor.
+  # ========================================================================= #
+  def open_in_browser_or_in_editor(i)
+    if i.include? '//'
+      i = i.dup if i.frozen?
+      i.squeeze!('/')
+    end
+    # ======================================================================= #
+    # Next, we get the extension name.
+    # ======================================================================= #
+    _ = File.extname(File.basename(i)).delete '.'
+    case _
+    when 'html','php' # Open in both, in this case.
+      do_open_in_editor(i)
+      unless File.zero? i
+        ::Open.in_browser(i) unless _.include? 'php'
+      end
+    else
+      do_open_in_editor(i)
+    end
+  end
+
+  # ========================================================================= #
+  # === open_in_gimp
+  # ========================================================================= #
+  def open_in_gimp(i)
+    esystem "#{@image_editor} #{i}#{IN_BACKGROUND}"
+  end
+
+  # ========================================================================= #
+  # === open_in_office
+  #
+  # This method should be used to open files that do have a file extension
+  # such as .xls or .odt or .ppt. In other words, libreoffice-specifi files.
+  # ========================================================================= #      
+  def open_in_office(i)
+    i = consider_padding(i)
+    if File.exist? LIBREOFFICE
+      result = "#{LIBREOFFICE} #{i}#{IN_BACKGROUND}"
+    else # Try any other general location based on $PATH anyway.
+      result = File.basename(LIBREOFFICE)+' '+i+IN_BACKGROUND
+    end
+    esystem result
+  end
+
+  # ========================================================================= #
+  # === try_to_require_the_studium_project
+  # ========================================================================= #
+  def try_to_require_the_studium_project
+    unless Object.const_defined?(:Studium) and
+           Studium.respond_to?(:include_this_exam_topic?)
+      begin # We pull in only the relevant files from the Studium project.
+        require 'studium/constants/constants.rb'
+        require 'studium/toplevel_methods/find_exam_topic_and_exam_title.rb'
+        require 'studium/toplevel_methods/is_this_exam_topic_included.rb'
+      rescue LoadError
+        if is_on_roebe?
+          e 'The three files ('\
+            'studium/constants/constants.rb,'\
+            'studium/toplevel_methods/find_exam_topic_and_exam_title.rb and '\
+            'studium/toplevel_methods/is_this_exam_topic_included.rb '\
+            'forth) from the studium-project could not be loaded.'
+        end
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === do_open_in_editor
+  #
+  # This method will try to open the file via the specified (main)
+  # editor. Since as of August 2019, this will also be logged into
+  # a local file, if we are on a roebe-system.
+  # ========================================================================= #
+  def do_open_in_editor(
+      i, use_this_editor = @editor
+    )
+    if i.include? '//'
+      i.squeeze!('/')
+    end
+    if Object.const_defined? :Roebe
+      expanded_alias = Roebe::FindExpandedAlias.new(i) { :be_quiet }
+      if expanded_alias.is_included?
+        unless File.exist? i
+          points_at = expanded_alias.points_at?
+          if points_at.include?(';')
+            splitted = points_at.split(';')
+            if File.exist? splitted.first
+              points_at = splitted.first
+            end
+          end
+          opnn; e 'Making use of the aliased-pointer at'
+          opnn; e '  `'+steelblue(points_at)+'`.'
+          i = points_at
+        end
+      end
+    end
+    i = rds(i) # Get rid of // again, just in case.
+    # ======================================================================= #
+    # Make an exception for .cpp files:
+    # ======================================================================= #
+    if (File.extname(i).delete('.') == 'cpp')
+      if is_on_roebe? and ENV.has_key?('CPP_EDITOR')
+        use_this_editor = ENV['CPP_EDITOR'].to_s.dup
+      else
+        use_this_editor = 'geany' # We use geany for cpp files.
+      end
+    end
+    if i.include?("'") and !i.include?('"')
+      i = '"'+i+'"'
+    end
+    if i.include? '('
+      i = '"'+i+'"'
+    end
+    _ = "#{use_this_editor} #{i}"
+    esystem(_)
+    if File.file?(i) and Object.const_defined?(:Roebe) and
+       File.directory?(Roebe.log_dir?) and
+       is_on_roebe?
+      into = Roebe.log_dir?+'opened_files.yml'
+      if File.exist? into
+        array = YAML.load_file(into)
+      else
+        array = [into].flatten.compact
+      end
+      what = YAML.dump(array)
+      SaveFile.write_what_into(what, into)
+    end
+  end
+
+  # ========================================================================= #
+  # === run_rcfiles_then_run_ata_via_qdbus
+  # ========================================================================= #
+  def run_rcfiles_then_run_ata_via_qdbus
+    require 'rcfiles'
+    Rcfiles.run
+    esystem 'qdbus org.kde.konsole-`pidof -s konsole` /Sessions/2 runCommand "ata"'
+    esystem 'qdbus org.kde.konsole-`pidof -s konsole` /Sessions/3 runCommand "ata"'
+    esystem 'qdbus org.kde.konsole-`pidof -s konsole` /Sessions/4 runCommand "ata"'
+  end
+
+  # ========================================================================= #
+  # === open_in_pdf_viewer                                          (pdf tag)
+  #
+  # This method can be used to open a .pdf file. We will let the project
+  # PdfParadise handle this situation.
+  #
+  # Since as of 19.09.2018 we will keep a log of the opened .pdf files
+  # if we are on roebe. This can then be used to determine which were
+  # the last .pdf files that were read.
+  # ========================================================================= #
+  def open_in_pdf_viewer(i)
+    require 'pdf_paradise' unless Object.const_defined? :PdfParadise
+    # ======================================================================= #
+    # Since as of April 2022 we will use the absolute path to the .pdf
+    # file at hand. The reason for this is because this makes it easier
+    # to know which files are open, and we can store these file paths
+    # into a local file (such as a .yml file), and then use this at a
+    # later time to restore all .pdf files that were open. This thus
+    # constitutes some type of "session management".
+    # ======================================================================= #
+    i = File.absolute_path(i)
+    if File.exist? i
+      require 'pdf_paradise/main_pdf/main_pdf.rb'
+      require 'pdf_paradise/set_main_book.rb'
+      # ===================================================================== #
+      # Only enable the following on my home-system, and only in the
+      # books-subdirectory, and university-subdirectory.
+      # ===================================================================== #
+      if is_on_roebe? and set_the_main_book?
+        case return_pwd
+        # =================================================================== #
+        # The following checks were explained above. We will also run
+        # rcfiles, and send pidof. 
+        # =================================================================== #
+        when /^#{Regexp.quote('/home/x/books/')}/,
+             /^#{Regexp.quote('/home/x/studium/')}/
+          PdfParadise::SetMainBook.new(i)
+          run_rcfiles_then_run_ata_via_qdbus
+        end
+      end
+      PdfParadise.main_pdf(i) {{
+        open_via_fullscreen: @open_via_fullscreen
+      }}
+      register_this_pdf_file(i)
+    else
+      this_file_was_not_found(i)
+    end
+  end
+
+  # ========================================================================= #
+  # === return_assumed_path_to_ruby_src_lib_of
+  #
+  # Input to this method should be a String like:
+  #
+  #   roebe/classes/kde/kde_konsole/kde_konsole.rb
+  #
+  # ========================================================================= #
+  def return_assumed_path_to_ruby_src_lib_of(this_file)
+    first_part = File.dirname(this_file)
+    if first_part.include? '/'
+      first_part = first_part.split('/').first
+    end
+    return "#{RUBY_SRC}#{first_part}/lib/#{this_file}"
+  end
+
+  # ========================================================================= #
+  # === show_help                                                  (help tag)
+  # ========================================================================= #
+  def show_help
+    opnn; e 'The following options are available:'
+    e
+    ecomment '  SELF                       # Open this .rb file here.'
+    ecomment '  --use-this-browser=firefox # Assign a new browser, in this case firefox.'
+    ecomment '  --browser?                 # '\
+             'Show which browser is the currently assigned one.'
+    e
+  end
+
+  # ========================================================================= #
+  # === menu                                                       (menu tag)
+  # ========================================================================= #
+  def menu(
+      i = input?
+    )
+    if i.is_a? Array
+      i.each {|entry| menu(entry) }
+    else
+      case i # (case tag)
+      # ===================================================================== #
+      # === open --browser?
+      # ===================================================================== #
+      when /^-?-?browser\??$/
+        _ = YAML.load_file(::Open.file_browser?)
+        e 'The browser currently in use is `'+sfancy(_)+'`.'
+        exit
+      # ===================================================================== #
+      # === open --use-this-browser=firefox
+      # ===================================================================== #
+      when /^-?-?use(-|_)?this(-|_)?browser=(.+)/
+        ::Open.permanently_use_this_browser = $3.to_s.dup
+        exit
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === try_to_require_the_beautiful_url_project
+  # ========================================================================= #
+  def try_to_require_the_beautiful_url_project
+    unless Object.const_defined? :BeautifulUrl
+      begin
+        require 'roebe/requires/failsafe_require_of_beautiful_url.rb'
+      rescue LoadError; end
+    end
+  end
+
+  # ========================================================================= #
+  # === run_everything
+  # ========================================================================= #
+  def run_everything
+    input_files = input_files?.flatten
+    # ======================================================================= #
+    # Iterate over all input files that were passed to us.
+    # ======================================================================= #
+    input_files.each {|this_file|
+      # ===================================================================== #
+      # Check whether the input includes the ':' character:
+      # ===================================================================== #
+      if this_file.include?(':') and !File.exist?(this_file) and
+        File.exist?(this_file.split(':').first.to_s)
+        this_file = this_file.split(':').first.to_s
+      end
+      if this_file.start_with?('http:') and !File.exist?(this_file)
+        this_file.delete_prefix!('http:')
+      end
+      # ===================================================================== #
+      # === Query whether the file exists or whether it does not
+      # ===================================================================== #
+      if File.exist?(this_file) # This is the simplest way - the file exists here.
+        # =================================================================== #
+        # However had, in December 2022 it was noticed that a file such
+        # as "curricula.yml" may exist, as well as a directory called
+        # "curricula/". Thus, we may input "curricula" and refer to
+        # curricula.yml rather than curricula/. So, what to do in this
+        # case? Well - we will do a minimal glob, that is, if a file
+        # exists as described above, then we will prioritize this over
+        # the directory name.
+        # =================================================================== #
+        if File.directory?(this_file) and !File.file?(this_file) and
+           (Dir[this_file+'*'].size > 0)
+          this_file = Dir[this_file+'.*'].first.to_s # Pick a real file in this case.
+        end
+        try_to_open_this_file_in_the_editor(this_file)
+      else # Ok, the file was not instantly found. Run more checks here.
+        possible_matches = Dir[('*'+this_file+'*').squeeze('*')] # ← This may be an empty Array as well.
+        # =================================================================== #
+        # Since as of Jan 2018, if the variable possible_matches is NOT
+        # empty, we will sort it in a way so that the shorter file names
+        # are on top of the array.
+        # =================================================================== #
+        unless possible_matches.empty?
+          possible_matches = possible_matches.sort_by {|entry| entry.size }
+        end
+        # =================================================================== #
+        # === Check whether the input is an exam-question next
+        #
+        # This check should come before we delegate towards FindExpandedAlias.
+        # =================================================================== #
+        if Object.const_defined?(:Studium) and
+           ::Studium.respond_to?(:include_this_exam_topic?) and
+           ::Studium.respond_to?(:find_corresponding_exam_topic) and
+           ::Studium.include_this_exam_topic?(this_file) # open ab2
+          _ = ::Studium.find_corresponding_exam_topic(
+            ::Studium.find_corresponding_exam_topic(this_file),
+            :be_quiet
+          ) # This can be false.
+          if _
+            if is_on_roebe?
+              _ = Studium.my_exam_topics_directory?+File.basename(_)
+            else
+              _ = Studium.exam_topics_directory?+File.basename(_)
+            end
+            open_in_editor(_)
+          end
+        # =================================================================== #
+        # === Query whether BeautifulUrl includes this file.
+        # =================================================================== #
+        elsif BeautifulUrl.does_include?(this_file) # open linux
+          _ = beautiful_url(this_file)
+          consider_opening_the_given_input(_) # Then try again.
+        # =================================================================== #
+        # Ok, the following else-clauses handle the situation
+        # that the given input could not be found.
+        # =================================================================== #
+        elsif this_file.include? 'project_'
+          do_open_in_editor(this_file)
+        # =================================================================== #
+        # At the least one entry has been found.
+        # =================================================================== #
+        elsif ((_ = possible_matches).size > 0) # If we can find at least one entry.
+          consider_opening_the_given_input(_.first) # Recursive call.
+        # =================================================================== #
+        # Same as above, but both prepend and append a '*' character.
+        # =================================================================== #
+        elsif ((_ = possible_matches).size > 0) # If we can find at least one entry.
+          consider_opening_the_given_input(_.first)
+        # =================================================================== #
+        # Next, try to pass it through class Roebe::FindExpandedAlias.
+        # =================================================================== #
+        elsif File.exist?(_ = Roebe.find_expanded_alias(this_file).to_s)
+          open_in_editor(_)
+        # =================================================================== #
+        # Next, try to handle input containing two ':' tokens.
+        # =================================================================== #
+        elsif this_file.include?('::')
+          try_to_find_files_based_on_hyphens_as_part_of_the_input(this_file)
+        # =================================================================== #
+        # Use RUBY_SRC as shortcut on my home system.
+        # =================================================================== #
+        elsif is_on_roebe? and
+              File.exist?(return_assumed_path_to_ruby_src_lib_of(this_file))
+          use_this_file_instead = return_assumed_path_to_ruby_src_lib_of(this_file)
+          e rev+'Since we are on roebe, we will use another path, aka'
+          e
+          e "  #{steelblue(use_this_file_instead)}"
+          e
+          open_in_editor(use_this_file_instead)
+        # =================================================================== #
+        # === Check for aliases next
+        #
+        # Next, try to find an expanded alias here.
+        # =================================================================== #
+        elsif Roebe.const_defined?(:FindExpandedAlias) and
+              (::Roebe::FindExpandedAlias[this_file] != this_file)
+          do_open_in_editor(this_file)
+        else
+          opnn; e 'No match could be found for `'+sfancy(this_file)+'`.'
+        end
+      end
+    }
+  end
+
+  # ========================================================================= #
+  # === run                                                         (run tag)
+  # ========================================================================= #
+  def run
+    check_whether_the_user_has_provided_any_input
+    try_to_require_the_studium_project
+    try_to_require_the_beautiful_url_project
+    menu
+    run_everything
+  end
+
+  # ========================================================================= #
+  # === Open::Open[]
+  # ========================================================================= #
+  def self.[](i = ARGV, &block)
+    new(i, &block) # Always delegate here.
+  end
+
+end
+
+# =========================================================================== #
+# === Open.open
+# =========================================================================== #
+def self.open(i = ARGV, &block)
+  ::Open::Open.new(i, &block)
+end; self.instance_eval { alias [] open } # === Open[]
+
+# =========================================================================== #
+# === Open.pdf_viewer?
+# =========================================================================== #
+def self.pdf_viewer?
+  unless (Object.const_defined?(:PdfParadise) and PdfParadise.const_defined?(:MainPdf))
+    require 'pdf_paradise/main_pdf/main_pdf.rb' 
+  end
+  return ::PdfParadise.use_which_pdf_viewer?
+end
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  Open::Open.new(ARGV)
+end # open