studium 0.9.383

data/lib/studium/base/misc.rb

@@ -0,0 +1,819 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'studium/base/misc.rb'
+# =========================================================================== #
+require 'studium/base/commandline_arguments.rb'
+
+module Studium
+
+class Base # === Studium::Base
+
+  # ========================================================================= #
+  # === initialize
+  # ========================================================================= #
+  def initialize(
+      i           = nil,
+      run_already = true
+    )
+    reset
+    run if run_already
+  end
+
+  # ========================================================================= #
+  # === register_sigint
+  # ========================================================================= #
+  def register_sigint
+    Signal.trap('SIGINT') { exit }
+  end
+
+  # ========================================================================= #
+  # === enable_debug
+  # ========================================================================= #
+  def enable_debug
+    @debug = true
+  end; alias do_debug enable_debug # === do_debug
+
+  # ========================================================================= #
+  # === debug?
+  # ========================================================================= #
+  def debug?
+    @debug
+  end
+
+  # ========================================================================= #
+  # === append_what_into                                        (append tag)
+  #
+  # Use this method to save data into a specific file.
+  # ========================================================================= #
+  def append_what_into(what, into)
+    Studium.append_what_into(what, into)
+  end
+
+  # ========================================================================= #
+  # === write_what_into
+  #
+  # Use this method to save data into a specific file.
+  # ========================================================================= #
+  def write_what_into(what, into)
+    Studium.write_what_into(what, into)
+  end; alias store_what_into write_what_into # === store_what_into
+
+  # ========================================================================= #
+  # === spacer
+  # ========================================================================= #
+  def spacer
+    Studium.spacer
+  end
+
+  # ========================================================================= #
+  # === is_connected_to_the_www?
+  # ========================================================================= #
+  def is_connected_to_the_www?
+    !@no_connection_to_the_www
+  end
+
+  # ========================================================================= #
+  # === sanitize_url
+  #
+  # This is such a useful method that we will use it for all subclasses
+  # of Studium::Base.
+  # ========================================================================= #
+  def sanitize_url(i, optional_extra_modes = nil)
+    Studium.sanitize_url(i, optional_extra_modes)
+  end; alias sanitized_url sanitize_url # === sanitized_url
+
+  # ========================================================================= #
+  # === input?
+  # ========================================================================= #
+  def input?
+    @input # Only call this method if your class makes use of a variable called @input.
+  end
+
+  # ========================================================================= #
+  # === web_liner
+  # ========================================================================= #
+  def web_liner(this_token = '*')
+    (this_token * 80)+N
+  end
+
+  # ========================================================================= #
+  # === be_silent
+  # ========================================================================= #
+  def be_silent
+    @be_verbose = false
+  end; alias be_quiet be_silent # === be_quiet
+
+  # ========================================================================= #
+  # === html_log_dir?
+  # ========================================================================= #
+  def html_log_dir?
+    Studium.html_log_dir?
+  end
+
+  # ========================================================================= #
+  # === base_dir?
+  #
+  # This is the log dir - where we "operate on".
+  # ========================================================================= #
+  def base_dir?
+    Studium.log_dir?
+  end; alias log_dir? base_dir? # === log_dir?
+
+  # ========================================================================= #
+  # === is_on_roebe?
+  # ========================================================================= #
+  def is_on_roebe?
+    Studium.is_on_roebe?
+  end; alias is_roebe? is_on_roebe? # === is_roebe?
+       alias on_roebe? is_on_roebe? # === on_roebe?
+
+  # ========================================================================= #
+  # === already_solved_this_lva_number?
+  # ========================================================================= #
+  def already_solved_this_lva_number?(i)
+    Studium.already_solved_this_lva_number?(i)
+  end
+
+  # ========================================================================= #
+  # === www_connection_is_unavailable
+  # ========================================================================= #
+  def www_connection_is_unavailable
+    @no_connection_to_the_www = true
+  end; alias www_is_unavailable www_connection_is_unavailable # === www_is_unavailable
+
+  # ========================================================================= #
+  # === delete_file
+  # ========================================================================= #
+  def delete_file(i)
+    File.delete(i) if File.exist? i
+  end
+
+  # ========================================================================= #
+  # === is_a_weekday?
+  #
+  # This method will return true if the input is a String that represents
+  # a weekday, such as "Monday". Otherwise, false will be returned.
+  #
+  # Both german and english variants are allowed here.
+  # ========================================================================= #
+  def is_a_weekday?(i = 'Montag')
+    result = false
+    if ARRAY_GERMAN_WEEKDAYS.include? i
+      result = true
+    elsif ARRAY_ENGLISH_WEEKDAYS.include? i
+      result = true
+    end
+    return result
+  end
+
+  # ========================================================================= #
+  # === rinstall2
+  # ========================================================================= #
+  def rinstall2
+    cpruby
+    system 'ruby setup.rb --quiet config'
+    system 'ruby setup.rb --quiet setup'
+    system 'ruby setup.rb --quiet install'
+    delete_file 'setup.rb'
+    delete_file 'InstalledFiles'
+    delete_file '.config'
+  end
+
+  # ========================================================================= #
+  # === be_verbose?
+  # ========================================================================= #
+  def be_verbose?
+    @be_verbose
+  end
+
+  # ========================================================================= #
+  # === set_be_verbose
+  # ========================================================================= #
+  def set_be_verbose
+    @be_verbose = true
+  end; alias be_verbose set_be_verbose # === be_verbose
+
+  # ========================================================================= #
+  # === do_not_be_verbose
+  # ========================================================================= #
+  def do_not_be_verbose
+    @be_verbose = false
+  end
+
+  # ========================================================================= #
+  # === total_ects_points_passed
+  # ========================================================================= #
+  def total_ects_points_passed(i)
+    Studium.total_ects_points_passed(i)
+  end
+
+  # ========================================================================= #
+  # === set_this_cd_alias_to
+  # ========================================================================= #
+  def set_this_cd_alias_to(
+      cd_alias, new_content, be_verbose = :default
+    )
+    Studium.set_this_cd_alias_to(cd_alias, new_content, be_verbose)
+  end
+
+  # ========================================================================= #
+  # === return_all_exams_on_this_day
+  # ========================================================================= #
+  def return_all_exams_on_this_day(i)
+    Studium.return_all_exams_on_this_day(i)
+  end
+
+  # ========================================================================= #
+  # === return_local_path_of_this_pwdstud
+  # ========================================================================= #
+  def return_local_path_of_this_pwdstud(i = 1)
+    Studium.return_local_path_of_this_pwdstud(i)
+  end
+
+  # ========================================================================= #
+  # === return_directory_for
+  #
+  # This method will try to build up the most plausible, local path to
+  # an existing directory.
+  # ========================================================================= #
+  def return_directory_for(
+      name_of_the_lecture, university
+    )
+    Studium.return_directory_for(name_of_the_lecture, university)
+  end
+
+  # ========================================================================= #
+  # === return_steop_lectures                                     (steop tag)
+  #
+  # This method will return all registered STEOP lectures.
+  #
+  # The optional argument will determine whether solved STEOP lectures
+  # will also be returned. By default this is not the case, meaning
+  # that we will ignore STEOP lectures that have already been solved.
+  # ========================================================================= #
+  def return_steop_lectures(
+      optional_ignore_already_completed_steop_lectures = true
+    )
+    if ::Studium.main_dataset?
+      dataset = ::Studium.main_dataset?
+    else
+      dataset = return_dataset_from_the_file_lecture_information
+    end
+    selection = dataset.select {|a, b|
+      b.has_key?(:is_a_steop_lecture) and (b[:is_a_steop_lecture] == true)
+    }
+    if optional_ignore_already_completed_steop_lectures
+      selection = selection.reject {|a, b|
+        b.has_key?(:already_solved) and (b[:already_solved] == true)
+      }
+    end
+    return selection
+  end
+
+  # ========================================================================= #
+  # === no_ext_name
+  #
+  # This method will return the name of the file (or rather the
+  # input given to this method) without extension.
+  # ========================================================================= #
+  def no_ext_name(i)
+    i.sub(/#{File.extname(i)}$/,'')
+  end
+
+  # ========================================================================= #
+  # === remove_newlines
+  # 
+  # This method will remove newlines, aka "\n", from Strings and Arrays.
+  # ========================================================================= #
+  def remove_newlines(i)
+    if i.is_a? Array
+      i.map {|entry| remove_newlines(entry) }
+    else
+      i.delete(N)
+    end
+  end
+
+  # ========================================================================= #
+  # === remove_internal_comments
+  # ========================================================================= #
+  def remove_internal_comments(i)
+    if i.is_a? Array
+      i.map {|line|
+        if line.include? '#'
+          line = line[0 .. (line.index('#')-1)]
+        end
+        line.strip
+      }
+    end
+  end
+
+  # ========================================================================= #
+  # === remove_leading_comments
+  # ========================================================================= #
+  def remove_leading_comments(i)
+    if i.is_a? Array
+      i.reject {|line| line.start_with? '#' }
+    end
+  end
+
+  # ========================================================================= #
+  # === remove_empty_strings
+  #
+  # This method presently only works on Arrays. We will reject empty
+  # Strings from the Array at hand.
+  # ========================================================================= #
+  def remove_empty_strings(i)
+    if i.is_a? Array
+      i.reject {|line| line.empty? }
+    end
+  end
+
+  # ========================================================================= #
+  # === average_grade
+  # ========================================================================= #
+  def average_grade(
+      i        = :default,
+      round_to = 2 # <- Round to two numbers.
+    )
+    Studium.average_grade(i, round_to)
+  end
+
+  # ========================================================================= #
+  # === return_all_numbers_from
+  #
+  # This method will return all numbers from the given input.
+  # ========================================================================= #
+  def return_all_numbers_from(i)
+    return_this = nil
+    if i.is_a? Array
+      return_this = i.select {|line|
+        line =~ /\d+/ # Any entry with a number will be returned.
+      }
+    end
+    return_this
+  end
+
+  # ========================================================================= #
+  # === return_all_steop_lectures
+  # ========================================================================= #
+  def return_all_steop_lectures
+    return_sanitized_dataset_from_the_file_lecture_information.select {|a, b|
+      is_a_steop_lecture = obtain(:steop, b)
+      is_a_steop_lecture
+    }
+  end
+
+  # ========================================================================= #
+  # === load_yaml_dataset
+  #
+  # This method should ideally be used when a .yml file is to be loaded.
+  #
+  # The second argument can be used to rescue missing or erroneous
+  # yaml files.
+  #
+  # Invocation example for this is:
+  #   load_yaml_dataset(:rescue)
+  # ========================================================================= #
+  def load_yaml_dataset(
+      i, do_rescue = false
+    )
+    case do_rescue
+    when :rescue
+      do_rescue = true
+    end
+    if do_rescue
+      begin
+        YAML.load_file(i)
+      rescue LoadError, ArgumentError; end
+    else
+      YAML.load_file(i)
+    end
+  end
+
+  # ========================================================================= #
+  # === select_lectures_with_this_key
+  #
+  # This method allows us to select only entries with a particular
+  # key. The key has to be passed to the method and - for now - has
+  # to be exactly the same as the key (e. g. string for strings
+  # and symbols for symbols; no automatic conversions for now).
+  #
+  # The advantage of this method is that it will simplify a lot of
+  # code; all code that requires us to select only specific
+  # lectures.
+  #
+  # Usage examples:
+  #   .select_lectures_with_this_key(:exam_registration_at)
+  #   .select_lectures_with_this_key(:already_solved)
+  # ========================================================================= #
+  def select_lectures_with_this_key(
+      searching_for_this_key
+    )
+    dataset = return_sanitized_dataset_from_the_file_lecture_information
+    dataset.select! {|name_of_the_lecture, inner_hash|
+      inner_hash.has_key? searching_for_this_key
+    } if dataset # <- Must check here, since there may be a nil.
+    return dataset
+  end
+
+  # ========================================================================= #
+  # === konsole_support?
+  # ========================================================================= #
+  def konsole_support?
+    Studium.konsole_support?
+  end
+
+  # ========================================================================= #
+  # === rename_konsole_tab?
+  # ========================================================================= #
+  def rename_konsole_tab?(
+      i = FILE_RENAME_KONSOLE_TAB
+    )
+    if File.exist? i
+      YAML.load_file(i)
+    else
+      false
+    end
+  end
+
+  # ========================================================================= #
+  # === return_dataset_for_this_topic
+  # ========================================================================= #
+  def return_dataset_for_this_topic(i)
+    Studium.return_dataset_for_this_topic(i)
+  end
+
+  # ========================================================================= #
+  # === rename_kde_konsole_tab
+  # ========================================================================= #
+  def rename_kde_konsole_tab(
+      title = '.'
+    )
+    if Object.const_defined?(:Roebe) and
+       Roebe.respond_to?(:rename_konsole_title_to)
+      Roebe.rename_konsole_title_to(title, :be_quiet)
+    end
+  end
+
+  # ========================================================================= #
+  # === last_file?
+  # ========================================================================= #
+  def last_file?
+    _ = Studium.file_for_exam_questions
+    _ = load_yaml_dataset(_).chomp
+    # ======================================================================= #
+    # If we are on roebe then we will use another path.
+    # ======================================================================= #
+    if is_on_roebe?
+      _ = Studium::MY_EXAM_TOPICS+File.basename(_)
+    end
+    return _
+  end
+
+  # ========================================================================= #
+  # === cheering_person
+  # ========================================================================= #
+  def cheering_person
+    '\o/'
+  end; alias cheering_person? cheering_person # === cheering_person?
+       alias cheering_dude?   cheering_person # === cheering_dude?
+
+  # ========================================================================= #
+  # === file_lecture_information?
+  # ========================================================================= #
+  def file_lecture_information?
+    ::Studium.file_lecture_information?
+  end
+
+  # ========================================================================= #
+  # === return_solved_lectures
+  #
+  # This method will return only those entries that have the key
+  # :already_solved set to true.
+  # ========================================================================= #
+  def return_solved_lectures
+    already_solved = select_lectures_with_this_key(:already_solved).select {|a,b|
+      obtain(:already_solved, b) == true
+    }
+    already_solved
+  end
+
+  # ========================================================================= #
+  # === is_prüfungsimmanent?
+  #
+  # This method can determine whether a course is "prüfungsimmanent",
+  # aka whether this course requires continuous, mandatory presence
+  # (of the student).
+  #
+  # The argument to this method should be the type of the lecture at
+  # hand, such as "VO" or "VU" or "SE" or "PR", as a String.
+  #
+  # The method will always return a boolean value, aka true or
+  # false. If true is the return value then this means that "yes,
+  # this course requires mandatory presence".
+  # ========================================================================= #
+  def is_prüfungsimmanent?(
+      i, ignore_these_types = nil
+    )
+    Studium.is_prüfungsimmanent?(i, ignore_these_types)
+  end; alias is_a_prüfungsimmanent_course?    is_prüfungsimmanent? # === is_a_prüfungsimmanent_course?
+       alias is_this_a_prüfungsimment_course? is_prüfungsimmanent? # === is_this_a_prüfungsimment_course?
+
+  # ========================================================================= #
+  # === find_corresponding_exam_topic
+  #
+  # This method will find the corresponding exam topic, based on a short
+  # input. For example, "bem1" will be short for basic biochemistry.
+  # ========================================================================= #
+  def find_corresponding_exam_topic(i)
+    Studium.find_corresponding_exam_topic(i)
+  end; alias return_file_associated_with_this_exam_topic find_corresponding_exam_topic # === return_file_associated_with_this_exam_topic
+
+  # ========================================================================= #
+  # === available_topics_as_short_name
+  # ========================================================================= #
+  def available_topics_as_short_name
+    Studium::Exams.all_topics_as_short_name.sort
+  end; alias available_topics?      available_topics_as_short_name # === available_topics?
+       alias return_all_exam_topics available_topics_as_short_name # === return_all_exam_topics
+
+  # ========================================================================= #
+  # === return_n_exam_questions_in
+  #
+  # This method will return how many exam questions are in the given topic
+  # xyz.
+  # ========================================================================= #
+  def return_n_exam_questions_in(this_topic)
+    Studium::Exams.return_n_questions_in_this_topic(this_topic)
+  end
+
+  # ========================================================================= #
+  # === return_n_questions_were_answered_for_this_topic
+  # ========================================================================= #
+  def return_n_questions_were_answered_for_this_topic(i)
+    Studium::Exams.return_n_questions_were_answered_for_this_topic(i)
+  end
+
+  # ========================================================================= #
+  # === beautiful_url
+  #
+  # Until 10.12.2019 this exclusively used BeautifulUrl.
+  #
+  # Since as of 10.12.2019, this method will actually tap into
+  # Studium.return_url_from if it is registered.
+  # ========================================================================= #
+  def beautiful_url(i)
+    unless Studium.respond_to? :is_this_url_registered?
+      require 'studium/misc/return_remote_homepage_of_this_lecture.rb'
+    end
+    if Studium.is_this_url_registered?(i)
+      i = Studium.return_url_from(i)
+    else
+      i = BeautifulUrl[i]
+    end
+    if i.is_a? Array
+      i = i.first
+    end
+    i
+  end
+
+  # ========================================================================= #
+  # === expand_topic
+  #
+  # This will expand e. g. 'allgemeine_genetik' to 'Allgemeine Genetik'.
+  # ========================================================================= #
+  def expand_topic(i)
+    Studium.find_corresponding_exam_title(i)
+  end
+
+  # ========================================================================= #
+  # === return_ects_points_from_these_lectures
+  #
+  # Input to this method should be a Hash containing our lectures.
+  #
+  # An example for this is shown next:
+  #
+  #   {"051010"=>"Programmierung 1",
+  #    "051110"=>"Mathematische Grundlagen der Informatik 1"}
+  #
+  # ========================================================================= #
+  def return_ects_points_from_these_lectures(hash)
+    n_ects_points = 0 # Keep track of the amount of ECTS points here.
+    hash.each_pair {|lecture_id, name_of_the_lecture|
+      lecture_id = ensure_main_encoding(lecture_id)
+      name_of_the_lecture = ensure_main_encoding(name_of_the_lecture).squeeze(' ')
+      points = Studium.return_ects_from_this_lecture_stored_in_the_file_lecture_information(
+        name_of_the_lecture, lecture_id
+      )
+      n_ects_points += points
+    }
+    return n_ects_points
+  end
+
+  # ========================================================================= #
+  # === turn_this_array_into_the_full_dataset
+  #
+  # This method accepts an Array of lectures that will be replaced with
+  # a full dataset.
+  # ========================================================================= #
+  def turn_this_array_into_the_full_dataset(
+      i, use_this_dataset
+    )
+    hash = {}
+    i.flatten.each {|name_of_the_lecture|
+      pointer = use_this_dataset[name_of_the_lecture]
+      hash[name_of_the_lecture] = pointer
+    }
+    hash
+  end
+
+  # ========================================================================= #
+  # === ensure_that_the_log_directory_exists
+  #
+  # This method will try to make sure that the log directory exists.
+  # ========================================================================= #
+  def ensure_that_the_log_directory_exists
+    _ = log_dir?
+    unless File.directory? _
+      mkdir(_)
+    end
+  end
+
+  # ========================================================================= #
+  # === create_directory
+  # ========================================================================= #
+  def create_directory(i)
+    FileUtils.mkdir_p(i)
+  end; alias mkdir create_directory # === mkdir
+
+  # ========================================================================= #
+  # === change_directory
+  # ========================================================================= #
+  def change_directory(
+      i = Dir.pwd
+    )
+    FileUtils.chdir(i)
+  end; alias cd change_directory # === cd
+
+  # ========================================================================= #
+  # === return_passed_courses
+  #
+  # This method will quickly return all passed courses.
+  # ========================================================================= #
+  def return_passed_courses
+    return_dataset_from_file_lecture_information.select {|key, hash|
+      hash.has_key?(:already_solved) and
+      (hash[:already_solved] == true)
+    }
+  end
+
+  # ========================================================================= #
+  # === csv_file?
+  # ========================================================================= #
+  def csv_file?
+    PASSED_EXAMS_PER_MONTH
+  end
+
+  # ========================================================================= #
+  # === return_sanitized_dataset_from_the_file_lecture_information
+  #
+  # This method will return the dataset stored in the file
+  # 'lecture_information.yml'.
+  # ========================================================================= #
+  def return_sanitized_dataset_from_the_file_lecture_information
+    Studium.return_sanitized_dataset_from_the_file_lecture_information
+  end; alias return_dataset_from_the_file_lecture_information       return_sanitized_dataset_from_the_file_lecture_information # === return_dataset_from_the_file_lecture_information
+       alias return_dataset_from_file_lecture_information           return_sanitized_dataset_from_the_file_lecture_information # === return_dataset_from_file_lecture_information
+       alias lecture_information_dataset                            return_sanitized_dataset_from_the_file_lecture_information # === lecture_information_dataset
+       alias lecture_information                                    return_sanitized_dataset_from_the_file_lecture_information # === lecture_information_dataset
+       alias dataset_from_file_lecture_information                  return_sanitized_dataset_from_the_file_lecture_information # === dataset_from_file_lecture_information
+       alias dataset_from_lecture_information                       return_sanitized_dataset_from_the_file_lecture_information # === dataset_from_lecture_information
+       alias dataset_lecture_information                            return_sanitized_dataset_from_the_file_lecture_information # === dataset_lecture_information
+       alias return_lecture_information                             return_sanitized_dataset_from_the_file_lecture_information # === return_lecture_information
+       alias return_data_from_the_file_lecture_information          return_sanitized_dataset_from_the_file_lecture_information # === return_data_from_the_file_lecture_information
+       alias return_all_lectures                                    return_sanitized_dataset_from_the_file_lecture_information # === return_all_lectures
+       alias return_lectures_from_file_lecture_information          return_sanitized_dataset_from_the_file_lecture_information # === return_lectures_from_file_lecture_information
+       alias dataset_from_the_file_lecture_information              return_sanitized_dataset_from_the_file_lecture_information # === dataset_from_the_file_lecture_information
+       alias return_sanitized_dataset_from_file_lecture_information return_sanitized_dataset_from_the_file_lecture_information # === return_sanitized_dataset_from_file_lecture_information
+       alias return_dataset_from_the_lectures                       return_sanitized_dataset_from_the_file_lecture_information # === return_dataset_from_the_lectures
+       alias return_sanitized_dataset                               return_sanitized_dataset_from_the_file_lecture_information # === return_sanitized_dataset
+       alias return_all_lectures_from_the_file_lecture_information  return_sanitized_dataset_from_the_file_lecture_information # === return_all_lectures_from_the_file_lecture_information
+
+  # ========================================================================= #
+  # === return_lectures_with_at_the_least_one_upcoming_exam
+  #
+  # This method will return all lectures that have at the least
+  # one upcoming exam entry. In this context "upcoming" refers
+  # to an exam date that comes after today (or any day before
+  # today).
+  # ========================================================================= #
+  def return_lectures_with_at_the_least_one_upcoming_exam
+    today = Time.now
+    return_sanitized_dataset_from_the_file_lecture_information.select {|name_of_the_course, hash_dataset|
+      if hash_dataset.has_key? 'exams'
+        exams = hash_dataset['exams']
+        if exams.is_a? Array
+          exams = exams.first
+        end
+        exams = remove_german_weekdays(exams)
+        exams.delete!(',')
+        time_parsed = Time.parse(exams)
+        today < time_parsed # Check that the courses are not too old.
+      else
+        false
+      end
+    }
+  end
+
+  require 'studium/toplevel_methods/return_lva_number_of_this_lecture.rb'
+  # ========================================================================= #
+  # === return_lva_number_of_this_lecture
+  # ========================================================================= #
+  def return_lva_number_of_this_lecture(this_lecture)
+    ::Studium.return_lva_number_of_this_lecture(this_lecture)
+  end
+
+  # ========================================================================= #
+  # === copy
+  # ========================================================================= #
+  def copy(from, to)
+    if from.is_a? Array
+      from.each {|entry|
+        copy(entry, to)
+      }
+    else
+      FileUtils.copy(from, to)
+    end
+  end; alias copy_file copy # === copy_file
+
+  # ========================================================================= #
+  # === create_file
+  # ========================================================================= #
+  def create_file(i)
+    FileUtils.touch(i)
+  end; alias touch create_file # === touch
+
+  # ========================================================================= #
+  # === cpruby
+  # ========================================================================= #
+  def cpruby
+    base_dir = ENV['USERS']
+    base_dir = '/home' if base_dir.nil?
+    path_to_setup_rb_file =
+      "#{base_dir}/x/DATA/PROGRAMMING_LANGUAGES/RUBY/src/roebe/lib/roebe/setup/setup.rb"
+    copy(path_to_setup_rb_file,'.')
+  end
+
+  # ========================================================================= #
+  # === rev                                                         (rev tag)
+  # ========================================================================= #
+  def rev
+    ::Studium::Colours.rev
+  end; alias revert rev # === revert
+
+  # ========================================================================= #
+  # === file_read_with_proper_encoding
+  # ========================================================================= #
+  def file_read_with_proper_encoding(this_file)
+    Studium.file_read_with_proper_encoding(this_file)
+  end
+
+  # ========================================================================= #
+  # === read_this_file_with_default_encoding
+  #
+  # This method will read in a file, that should ideally exist, in the
+  # default project-wide encoding.
+  #
+  # A few aliases exist to this method, such as "read_this_file()".
+  # ========================================================================= #
+  def read_this_file_with_default_encoding(
+      this_file
+    )
+    File.read(this_file, encoding: USE_THIS_ENCODING)
+  end; alias read_as_string_with_default_encoding read_this_file_with_default_encoding # === read_as_string_with_default_encoding
+       alias read_file                            read_this_file_with_default_encoding # === read_file
+       alias read_this_file                       read_this_file_with_default_encoding # === read_this_file
+       alias read_file_with_default_encoding      read_this_file_with_default_encoding # === read_file_with_default_encoding
+       alias read_in_with_default_encoding        read_this_file_with_default_encoding # === read_in_with_default_encoding
+
+  # ========================================================================= #
+  # === replace_regular_numbers_with_unicode_numbers
+  #
+  # This method will replace numbers such as 1 with ¹.
+  # ========================================================================= #
+  def replace_regular_numbers_with_unicode_numbers(i)
+    i.tr('0','⁰').
+      tr('1','¹').
+      tr('2','²').
+      tr('3','³').
+      tr('4','⁴').
+      tr('5','⁵').
+      tr('6','⁶').
+      tr('7','⁷').
+      tr('8','⁸').
+      tr('9','⁹')
+  end
+
+end; end