studium 0.18.7

data/lib/studium/exams/show_upcoming_exams/show_upcoming_exams.rb

@@ -0,0 +1,1537 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# === Studium::ShowUpcomingExams
+#
+# This class will show upcoming exams. How does it determine which exams
+# are upcoming?
+#
+# This is solely determined by the file called 'lecture_information.yml'.
+#
+# Usage example:
+#
+#   Studium::ShowUpcomingExams.new(ARGV)
+#
+# =========================================================================== #
+# require 'studium/exams/show_upcoming_exams/show_upcoming_exams.rb'
+# x = Studium.return_upcoming_exams_as_HTML
+# Studium.return_all_registered_upcoming_exams
+# Studium::ShowUpcomingExams.new
+# Studium.show_upcoming_exams(ARGV)
+# =========================================================================== #
+require 'studium/base/base.rb'
+
+module Studium
+
+class ShowUpcomingExams < Studium::Base # === Studium::ShowUpcomingExams
+
+  begin
+    require 'emoji_paradise' # Make the constant EmojiParadise known here, if possible.
+  rescue LoadError; end
+
+  # ========================================================================= #
+  # Toplevel-methods of the studium gem come next.
+  # ========================================================================= #
+  require 'studium/toplevel_methods/toplevel_methods.rb'
+
+  # ========================================================================= #
+  # === REGEX_TO_EXTRACT_DATE_AND_TIME_FROM_AN_UPCOMING_EXAM
+  # ========================================================================= #
+  REGEX_TO_EXTRACT_DATE_AND_TIME_FROM_AN_UPCOMING_EXAM = # See: http://rubular.com/r/6VxRmS5FKc
+      /(\d{1,2}\.\d{1,2}\.\d{4},?\s*\d{1,2}:\d{1,2}-\d{1,2}:\d{1,2})/
+
+  # ========================================================================= #
+  # === SHOW_LEADING_LVA_ID_NUMBER
+  #
+  # If the following constant is set to true, then we will also display
+  # the leading LVA-ID number.
+  #
+  # If it is false, that LVA-ID number will NOT be shown.
+  #
+  # The numbers make the display a bit uglier, but it may be more useful
+  # for the user if that user wants to use the LVA at hand via the
+  # browser. For instance I need to know the LVA-ID number, because that
+  # way I can quickly copy/paste the full name, and have the remote
+  # lecture course opened in my browser of choice. This is very convenient.
+  # ========================================================================= #
+  SHOW_LEADING_LVA_ID_NUMBER = true
+
+  # ========================================================================= #
+  # === TRY_TO_SHOW_PRIORITIES_FOR_THE_LECTURES
+  #
+  # The following constant will also attempt to show the priorities of
+  # a given lecture at hand.
+  #
+  # This depends on the priority value having been set in the file
+  # called "lecture_information.yml".
+  #
+  # If, however had, such a file exists, and the following constant is
+  # set to true, then this class will show the priority of the lecture.
+  # Lower number means higher priority, and the colours picked will reflect
+  # this priority loosely - the lower the priority, the brighter the
+  # colour.
+  #
+  # The reasoning behind this is that brighter colours should be easier to
+  # notice by the human eyes, and hence may signal a higher "importance".
+  #
+  # The whole idea behind this constant is to visualize more easily on
+  # the commandline which upcoming exams are more important than others.
+  # ========================================================================= #
+  TRY_TO_SHOW_PRIORITIES_FOR_THE_LECTURES = true
+
+  # ========================================================================= #
+  # === USE_OPN
+  # ========================================================================= #
+  USE_OPN = true
+
+  # ========================================================================= #
+  # === DISPLAY_HORIZONTAL_BAR_TO_INDICATE_A_NEW_MONTH
+  #
+  # If this constant is set to true, then a horizontal bar will be shown
+  # when a new month begins.
+  # ========================================================================= #
+  DISPLAY_HORIZONTAL_BAR_TO_INDICATE_A_NEW_MONTH = true
+
+  # ========================================================================= #
+  # === SEPARATOR_TOKEN_TO_USE
+  #
+  # This is the vertical separator token that is used to "separate"
+  # the display. Since as of January 2021, a unicode token is used;
+  # the original ASCII token can be seen in the following comment
+  # still.
+  # ========================================================================= #
+  SEPARATOR_TOKEN_TO_USE = '▏' # '┃' # '｜' #｜' #'❚' # '|'
+ 
+  # ========================================================================= #
+  # === SHOW_TOTAL_ECTS_POINTS_PASSED
+  # ========================================================================= #
+  SHOW_TOTAL_ECTS_POINTS_PASSED = true
+
+  # ========================================================================= #
+  # === initialize
+  #
+  # The first argument will keep track of the commandline-input.
+  #
+  # The input to this method should also handle blocks given, such as:
+  #
+  #   Studium::ShowUpcomingExams.new { :disable_colours }
+  #
+  # ========================================================================= #
+  def initialize(
+      i           = nil,
+      run_already = true,
+      &block
+    )
+    reset
+    case i
+    # ======================================================================= #
+    # === :be_silent
+    # ======================================================================= #
+    when :be_silent,
+         :do_not_report_anything
+      be_silent
+      i = nil
+      @report_result = false
+    # ======================================================================= #
+    # === :do_not_report_anything_and_do_not_update_the_cd_aliases
+    # ======================================================================= #
+    when :do_not_report_anything_and_do_not_update_the_cd_aliases
+      be_silent
+      i = nil
+      @report_result = false
+      @internal_hash[:shall_we_update_the_cd_aliases_with_new_exam_entries] = false
+    end
+    set_input(i)
+    # ======================================================================= #
+    # === Handle blocks next
+    #
+    # Next handle blocks given to the initializer:
+    # ======================================================================= #
+    if block_given?
+      yielded = yield
+      if yielded.is_a? Hash
+        # =================================================================== #
+        # === :show_n_upcoming_exams
+        # =================================================================== #
+        if yielded.has_key? :show_n_upcoming_exams
+          set_show_n_upcoming_exams(
+            yielded.delete(:show_n_upcoming_exams)
+          )
+        # =================================================================== #
+        # === :show_n_exams
+        # =================================================================== #
+        elsif yielded.has_key? :show_n_exams
+          set_show_n_upcoming_exams(
+            yielded.fetch(:show_n_exams)
+          )
+        end
+        # =================================================================== #
+        # === :array_of_symbols
+        # =================================================================== #
+        if yielded.has_key? :array_of_symbols
+          array_of_symbols.each {|this_symbol|
+            case this_symbol
+            # =============================================================== #
+            # === :do_not_exit
+            # =============================================================== #
+            when :do_not_exit
+              set_do_not_exit(false)
+            else
+              e 'Unhandled symbol: :'+this_symbol.to_s
+            end
+          }
+        end
+      else
+        case yielded # case tag
+        # === :do_not_exit
+        when :do_not_exit
+          set_do_not_exit(false)
+        when :disable_colours,
+             :no_colours
+          no_colours
+        end
+      end
+    end
+    if i.is_a? Symbol
+      case i
+      when :do_not_report_anything
+        do_not_report_anything
+      end
+    end
+    case run_already
+    when :dont_run_yet,
+         :do_not_run_yet
+      run_already = false
+    end
+    run if run_already
+  end
+
+  # ========================================================================= #
+  # === consider_autogenerating_exam_aliases
+  #
+  # This method will autogenerate the proper cd_aliases entries.
+  #
+  # It will only do so if these three conditions are met:
+  #
+  #   (1) the target system is a "roebe-system"
+  #   (2) a new entry has been added or removed in the file
+  #       'lecture_information.yml'
+  #   (3) a file exists as specified by the constant
+  #       FILE_ALL_REGISTERED_UPCOMING_EXAMS
+  #
+  # ========================================================================= #
+  def consider_autogenerating_exam_aliases(
+      use_this_file =
+        Studium.file_all_registered_upcoming_exams # Defaults to "/root/Studium/all_registered_upcoming_exams.yml".
+    )
+    if is_on_roebe? and commandline_mode? # Only do so on roebe-systems.
+      # ===================================================================== #
+      # Next we have to determine whether the file 'lecture_information.yml'
+      # has any different entry. If so, the cd_aliases entries will be
+      # autogenerated.
+      # ===================================================================== #
+      if File.exist? use_this_file
+        existing_dataset = YAML.load_file(use_this_file)
+        # =================================================================== #
+        # This may be in the wrong encoding, so we have to sanitize the
+        # Encoding still. Since as of April 2022 this is no longer in use.
+        # =================================================================== #
+        # existing_dataset = ensure_main_encoding(existing_dataset)
+        # =================================================================== #
+        # Next compare this to the dataset from the file
+        # 'lecture_information.yml'. We have to load up the
+        # original dataset again because the one available
+        # from the method reset(), may have been altered
+        # lateron.
+        # =================================================================== #
+        _ = ::Studium.return_sanitized_dataset_from_the_file_lecture_information.select {|a, b|
+          b.has_key?('registered') or
+          b.has_key?('not_yet_registered')
+        }
+        array = _.map {|name_of_the_lecture, inner_hash|
+          if inner_hash.has_key? 'registered'
+            entry = inner_hash['registered']
+          elsif inner_hash.has_key? 'not_yet_registered'
+            entry = inner_hash['not_yet_registered']
+          end
+          entry = entry.first
+          entry
+        }
+        # =================================================================== #
+        # Finally, compare the two Arrays, but sort them via Time:
+        # =================================================================== #
+        array = array.sort_by {|line|
+          line = line.split(',').first if line.include? ','
+          line = remove_weekdays(line)
+          Time.parse(line)
+        }
+        existing_dataset = existing_dataset.sort_by {|line|
+          line = line.split(',').first if line.include? ','
+          line = remove_weekdays(line)
+          Time.parse(line)
+        }
+        if (array == existing_dataset)
+          # ================================================================= #
+          # In this case, we pass through, as it is the very same dataset.
+          # ================================================================= #
+        else
+          # ================================================================= #
+          # Else we must update the cd-aliases.
+          # ================================================================= #
+          if @internal_hash[:shall_we_update_the_cd_aliases_with_new_exam_entries]
+            update_the_cd_aliases_with_new_exam_entries
+          end
+        end 
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === update_the_cd_aliases_with_new_exam_entries
+  #
+  # This will do a semi-silent update.
+  # ========================================================================= #
+  def update_the_cd_aliases_with_new_exam_entries
+    opne "Updating the #{gold('cd-aliases')} next - this "\
+         "may take a few seconds."
+    create_the_auto_stud_aliases(:do_not_exit, :be_quiet)
+    system 'history -c'
+  end
+
+  # ========================================================================= #
+  # === shall_we_exit?
+  # ========================================================================= #
+  def shall_we_exit?
+    @internal_hash[:shall_we_exit]
+  end
+
+  # ========================================================================= #
+  # === create_the_auto_stud_aliases
+  #
+  # To invoke this class, do:
+  #
+  #   show_upcoming_exams --autostud
+  #
+  # ========================================================================= #
+  def create_the_auto_stud_aliases(
+      shall_we_exit = shall_we_exit?,
+      be_verbose    = true
+    )
+    case be_verbose
+    when :be_quiet
+      be_verbose = false
+    end
+    case shall_we_exit
+    when :do_not_exit
+      shall_we_exit = false
+    end
+    base_dir = ROEBE_STUDIUM_DIR.dup
+    index = 0
+    @dataset.each {|name_of_the_lecture, inner_hash| index += 1
+      name_of_the_lecture = name_of_the_lecture.tr(' ','_')
+      # ===================================================================== #
+      # Sanitize the name of the lecture:
+      # ===================================================================== #
+      name_of_the_lecture.delete!(':/(),') # Get rid of ':','/','(',')', ','.
+      if name_of_the_lecture.end_with? '.'
+        name_of_the_lecture.chop!
+      end
+      if name_of_the_lecture.include? '_-_'
+        name_of_the_lecture.gsub!(/_-_/,'_')
+      end
+      if name_of_the_lecture.include? '_+_' # Replace '_+_' with '_'
+        name_of_the_lecture.gsub!(/_\+_/,'_')
+      end
+      if name_of_the_lecture.include? '__'
+        name_of_the_lecture.squeeze!('_')
+      end
+      university = inner_hash[:university].dup
+      # ===================================================================== #
+      # Note that the entries matched in the following variable will be
+      # upcased lateron anyway.
+      # ===================================================================== #
+      case university
+      when /^vetmed$/i
+        university = 'VETMED_UNI'
+      when 'tu_vienna','TU_VIENNA','TU Vienna'
+        university = 'TU_WIEN'
+      when 'meduni','MEDUNI','Meduni',
+           'boku','BOKU'
+        university << '_WIEN'
+      end
+      target_dir = base_dir+university.upcase.tr(' ','_')+'/'.dup
+      target_dir << name_of_the_lecture
+      pwdstud_name = "pwdstud#{index}:"
+      if be_verbose
+        opne rev+'Settting alias '+
+             simp(pwdstud_name.to_s.rjust(10))+
+             rev+' pointing to the directory '+
+             sdir(target_dir)
+      end
+      # ===================================================================== #
+      # Delegate towards Studium.set_this_cd_alias_to() next,
+      # in the file "studium/toplevel_methods/set_this_cd_alias_to.rb".
+      # ===================================================================== #
+      set_this_cd_alias_to(
+        pwdstud_name,
+        target_dir,
+        :be_quiet # But be quiet there.
+      )
+      begin
+        if is_on_roebe?
+          opne 'Autogenerating the cd-aliases next.'
+        end
+        require 'rcfiles'
+        Rcfiles.generate_files(:cd_aliases) {{ be_verbose: be_verbose? }}
+      rescue LoadError; end
+    }
+    exit if shall_we_exit
+  end
+
+  # ========================================================================= #
+  # === show_help                                                  (help tag)
+  #
+  # Invoke this method via:
+  #
+  #   show_upcoming_exams --help
+  #
+  # ========================================================================= #
+  def show_help
+    help_string = <<-EOF
+
+Input a number n, which means to show n upcoming exams.
+
+Other documented help options are:
+
+  --autostud # automatically set the proper
+             # cd-alias for all upcoming exams
+
+EOF
+    e help_string
+  end
+
+  # ========================================================================= #
+  # === menu                                                       (menu tag)
+  # ========================================================================= #
+  def menu(
+      i = @input
+    )
+    if i.is_a? Array
+      i.each {|entry| menu(entry) }
+    else
+      case i # case tag
+      # ===================================================================== #
+      # === show_upcoming_exams --only-registered
+      #
+      # Show only exams for which we are factually registered.
+      # ===================================================================== #
+      when /^-?-?only(-|_)?registered$/
+        do_show_only_exams_for_which_we_are_registered
+      # ===================================================================== #
+      # === show_upcoming_exams --auto-stud
+      # ===================================================================== #
+      when /^-?-?auto(-|_)?stud$/
+        create_the_auto_stud_aliases
+      # ===================================================================== #
+      # === show_upcoming_exams --be_silent
+      # ===================================================================== #
+      when /^-?-?be(_|-)?silent$/i
+        do_not_report_anything
+      # ===================================================================== #
+      # === show_upcoming_exams --disable-colours
+      # ===================================================================== #
+      when /^-?-?disable(_|-)?colours$/,
+           /^-?-?no(_|-)?colours$/
+        @use_colours = false
+      # ===================================================================== #
+      # === show_upcoming_exams --help
+      # ===================================================================== #
+      when /^-?-?help$/
+        show_help
+        exit
+      else
+        if i.to_s =~ /^(\d+)$/ # Is it a number? 
+          set_show_n_upcoming_exams($1.to_s.dup) # If so, feed into this method here.
+        end
+      end
+    end
+  end; alias check_against_menu menu # === check_against_menu
+
+  # ========================================================================= #
+  # === reset                                                     (reset tag)
+  # ========================================================================= #
+  def reset
+    super()
+    infer_the_namespace
+    # ======================================================================= #
+    # === :shall_we_exit
+    # ======================================================================= #
+    @internal_hash[:shall_we_exit] = true
+    # ======================================================================= #
+    # === @report_result
+    # ======================================================================= #
+    @report_result = true
+    # ======================================================================= #
+    # === @show_n_upcoming_exams
+    #
+    # By default all upcoming exams will be shown.
+    # ======================================================================= #
+    @show_n_upcoming_exams = :all_of_them
+    # ======================================================================= #
+    # === @dataset_from_file_lecture_information
+    # ======================================================================= #
+    @dataset_from_file_lecture_information = 
+      return_dataset_from_file_lecture_information
+    # ======================================================================= #
+    # === :show_only_exams_for_which_we_are_registered
+    # ======================================================================= #
+    @internal_hash[:show_only_exams_for_which_we_are_registered] = false
+    # ======================================================================= #
+    # === :n_ljust_to_the_left
+    # ======================================================================= #
+    @internal_hash[:n_ljust_to_the_left] = 66
+    # ======================================================================= #
+    # === :shall_we_update_the_cd_aliases_with_new_exam_entries
+    # ======================================================================= #
+    @internal_hash[:shall_we_update_the_cd_aliases_with_new_exam_entries] = true
+    sanitize_dataset
+    if Object.const_defined?(:EmojiParadise)
+      @emoji_checkbox = EmojiParadise.return_checkbox
+      @warning_sign   = EmojiParadise.warning_sign
+    else
+      @emoji_checkbox = ''
+      @warning_sign   = ''
+    end
+  end
+
+  # ========================================================================= #
+  # === do_show_only_exams_for_which_we_are_registered
+  # ========================================================================= #
+  def do_show_only_exams_for_which_we_are_registered
+    @internal_hash[:show_only_exams_for_which_we_are_registered] = true
+  end
+
+  # ========================================================================= #
+  # === show_only_exams_for_which_we_are_registered?
+  # ========================================================================= #
+  def show_only_exams_for_which_we_are_registered?
+    @internal_hash[:show_only_exams_for_which_we_are_registered]
+  end
+
+  # ========================================================================= #
+  # === set_input
+  # ========================================================================= #
+  def set_input(i = '')
+    i = i.first if i.is_a? Array
+    i = i.to_s.dup
+    @input = i
+  end
+
+  # ========================================================================= #
+  # === set_do_not_exit
+  # ========================================================================= #
+  def set_do_not_exit(i = true)
+    @internal_hash[:shall_we_exit] = i
+  end
+
+  # ========================================================================= #
+  # === input?
+  # ========================================================================= #
+  def input?
+    @input
+  end
+
+  # ========================================================================= #
+  # === set_show_n_upcoming_exams
+  # ========================================================================= #
+  def set_show_n_upcoming_exams(
+      i = :all_of_them
+    )
+    i = i.to_i if i.is_a? String
+    @show_n_upcoming_exams = i
+  end
+
+  # ========================================================================= #
+  # === do_not_report_anything
+  # ========================================================================= #
+  def do_not_report_anything
+    @report_result = false
+  end
+
+  # ========================================================================= #
+  # === sort_dataset_by_time
+  # ========================================================================= #
+  def sort_dataset_by_time
+    @dataset = @dataset.sort_by {|name_of_the_lecture, inner_hash|
+      # ===================================================================== #
+      # We will next select lectures that have the entry called
+      # registered.
+      # However had, not all lectures may have this entry - for example,
+      # some lectures have exam entries for which we have not yet
+      # registered. So the following code has to keep this in "mind".
+      # ===================================================================== #
+      if inner_hash.has_key? 'registered'
+        if inner_hash['registered'].respond_to? :first
+          the_exam_will_happen_when = inner_hash['registered'].first
+        else
+          opne crimson(name_of_the_lecture)+' has no key called `'+
+               sfancy('registered')+'`.'
+          opne swarn('Please fix this error before we can continue.')
+          exit
+        end
+      else
+        the_exam_will_happen_when = inner_hash['not_yet_registered']
+        if the_exam_will_happen_when and
+           the_exam_will_happen_when.respond_to?(:first)
+          the_exam_will_happen_when = the_exam_will_happen_when.first
+        else
+          opnn; ewarn 'No dataset found for the key '+
+                      slateblue('not_yet_registered')
+          opnn; ewarn 'This may be because you forgot to add '\
+                      'a " -" entry for this key.'
+          opnn; ewarn 'Please correct this error. '\
+                      'Exiting now until this error has been resolved.'
+          exit
+        end
+      end
+      result = parse_time_entry_from_this_string(the_exam_will_happen_when)
+      if result.nil?
+        e 'A problem was encountered for this lecture: '+name_of_the_lecture.to_s
+        e 'This should be corrected.'
+        exit
+      end
+      result
+    }
+  end
+
+  # ========================================================================= #
+  # === return_startzeit_from
+  # ========================================================================= #
+  def return_startzeit_from(i)
+    return i.scan(
+      /\d{1,2}:\d{1,2}-\d{1,2}:\d{1,2}/ # This is the regex we are currently using.
+    ).flatten.first
+  end
+
+  # ========================================================================= #
+  # === display_total_ects
+  # ========================================================================= #
+  def display_total_ects
+    if SHOW_TOTAL_ECTS_POINTS_PASSED
+      total_n_ects = @dataset.select {|a, b|
+        b[:ects]
+      }.map {|a,b|
+        b[:ects]
+      }.sum.to_s
+      plus = "+#{total_n_ects}"
+      e
+      result = ((' ' * 60)+
+                limegreen('Total ECTS passed so far: ').to_s+
+                colourize_ects_points(::Studium.n_ects_passed_so_far).to_s).dup 
+      if @emoji_checkbox and !@emoji_checkbox.empty?
+        result << goldenrod('      '+@emoji_checkbox+' ... ← registered for that course')
+      end
+      e result
+      result = ((' ' * 59).to_s+
+                limegreen('ECTS of the above exams:  ')+
+                colourize_ects_points(plus)).dup 
+      if @warning_sign and !@warning_sign.empty? # Offer an explanation to the user about the warning-sign.
+        result << crimson("      #{@warning_sign} ... ← outdated course exam-registration")
+      end
+      e result
+    end
+  end
+
+  # ========================================================================= #
+  # === n_exams?
+  # ========================================================================= #
+  def n_exams?
+    @dataset.size
+  end
+
+  # ========================================================================= #
+  # === return_date_of_the_exam
+  #
+  # This method will extract dd.mm.yyyy.
+  # ========================================================================= #
+  def return_date_of_the_exam(i)
+    i.scan(
+      /(\d{1,2}\.\d{1,2}\.\d{4})/
+    ).flatten.first
+  end
+
+  # ========================================================================= #
+  # === in_n_days
+  # ========================================================================= #
+  def in_n_days(i)
+    if i.include? '-'
+      i = i.split('-').first
+    end
+    future_time = Time.parse(i).to_i - Time.now.to_i
+    result = future_time.to_f / ONE_DAY.to_f
+    result.ceil(1)
+  end
+
+  # ========================================================================= #
+  # === return_red_vertical_bar
+  #
+  # Note that this will have the proper colour already.
+  # ========================================================================= #
+  def return_red_vertical_bar
+    "#{short_vertical_bar} "
+  end; alias return_vertical_bar return_red_vertical_bar # === return_red_vertical_bar
+
+  # ========================================================================= #
+  # === vertical_bar?
+  # ========================================================================= #
+  def vertical_bar?
+    SEPARATOR_TOKEN_TO_USE
+  end
+
+  # ========================================================================= #
+  # === short_vertical_bar
+  # ========================================================================= #
+  def short_vertical_bar
+    swarn(SEPARATOR_TOKEN_TO_USE)
+  end
+
+  # ========================================================================= #
+  # === show_n_upcoming_exams?
+  # ========================================================================= #
+  def show_n_upcoming_exams?
+    @show_n_upcoming_exams
+  end; alias show_n_exams? show_n_upcoming_exams? # === show_n_exams?
+
+  # ========================================================================= #
+  # === report_result?
+  # ========================================================================= #
+  def report_result?
+    @report_result
+  end
+
+  # ========================================================================= #
+  # === colourize_ects_points
+  # ========================================================================= #
+  def colourize_ects_points(i)
+    lightgreen(i)
+  end
+
+  # ========================================================================= #
+  # === return_location                                             (ort tag)
+  #
+  # This method will return a String, depending on whether the substring
+  # 'Ort' is part of the given input or whether it is not.
+  # ========================================================================= #
+  def return_location(i)
+    if i.include? 'Ort'
+      scan_result = i.scan(/(Ort: .+)$/).flatten
+      scan_result = scan_result.first if scan_result.respond_to?(:first)
+      " #{scan_result}"
+    else
+      '(No specific Ort has been found - or is known)'
+    end
+  end
+
+  # ========================================================================= #
+  # === is_part_of_the_vector_curriculum?
+  #
+  # This checks whether the lecture at hand is part of the individual
+  # Vector-Curriculum.
+  # ========================================================================= #
+  def is_part_of_the_vector_curriculum?(i = '')
+    ::Studium.is_this_lecture_part_of_the_vector_curriculum( # <- In the file studium/toplevel_methods/is_this_lecture_part_of_the_vector_curriculum.rb
+      i, :be_lenient
+    )
+  end
+
+  # ========================================================================= #
+  # === consider_renaming_the_konsole_tab
+  #
+  # We should actually check whether we are using Kde Konsole or not.
+  #
+  # We will then run system 'clear', but only if we have enabled
+  # reporting.
+  # ========================================================================= #
+  def consider_renaming_the_konsole_tab(
+      use_this_namespace = :Roebe
+    )
+    if report_result? and
+       konsole_support?
+      begin
+        require 'roebe/classes/kde/kde_konsole/kde_konsole.rb'
+      rescue LoadError; end
+      if Object.const_defined? use_this_namespace
+        # =================================================================== #
+        # We will also use a small icon for the KDE-renaming action.
+        # =================================================================== #
+        e Roebe.return_important_notification("Next #{n_exams?} exams")
+        system 'clear' # Required to get rid of the annoying KDebug output from KDE Konsole.
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === parse_time_entry_from_this_string
+  # ========================================================================= #
+  def parse_time_entry_from_this_string(
+      the_exam_will_happen_when
+    )
+    return if the_exam_will_happen_when.empty?
+    sanitized_the_exam_will_happen_when = remove_german_weekdays(the_exam_will_happen_when).strip
+    sanitized_the_exam_will_happen_when =~ REGEX_TO_EXTRACT_DATE_AND_TIME_FROM_AN_UPCOMING_EXAM
+    this_time = $1.to_s.dup
+    begin
+      this_time = Time.parse(this_time) # This method will return a time-parsed entry.
+    rescue Exception => error
+      e 'The original input to the method parse_time_entry_from_this_string() was:'
+      e
+      e "  #{sfancy(the_exam_will_happen_when)}"
+      e
+      pp error
+      e
+      e 'The caller() stack was:'
+      e
+      pp caller()
+      e
+      exit
+    end
+    return this_time
+  end
+
+  # ========================================================================= #
+  # === dataset?
+  # ========================================================================= #
+  def dataset?
+    @dataset
+  end; alias result? dataset? # === result?
+
+  # ========================================================================= #
+  # === n_ljust_to_the_left?
+  # ========================================================================= #
+  def n_ljust_to_the_left?
+    @internal_hash[:n_ljust_to_the_left]
+  end; alias left_pad? n_ljust_to_the_left? # === left_pad?
+
+  # ========================================================================= #
+  # === report_today
+  # ========================================================================= #
+  def report_today(
+      show_n_exams = show_n_exams?
+    )
+    if @report_result
+      opne yellowgreen('Heute ist der ')+
+           sfancy(dd_mm_yyyy)+' '+
+           yellowgreen('(')+
+           lightgreen(
+             # translate_dd_mm_yyy_to_weekday(dd_mm_yyyy)
+             german_weekday?(dd_mm_yyyy)
+           )+
+           yellowgreen('). Die nächsten ')+
+           lightslategray(show_n_exams.to_s)+
+           yellowgreen(' Prüfungen sind: ')
+      e
+    end
+  end
+
+  # ========================================================================= #
+  # === colourize_and_return_the_beginning_of_the_month
+  #
+  # This method must colourize a String such as:
+  #
+  #   "[Beginn Oktober 2023] ☻ ----------------------------------------------------"
+  #
+  # ========================================================================= #
+  def colourize_and_return_the_beginning_of_the_month(i)
+    i = i.dup
+    i.gsub!(/-/, tomato('-'))
+    if i.include?('☻')
+      i.sub!(/☻/, gold('☻'))
+    end
+    i.gsub!(/(\d{4})/, darkgoldenrod('\1'))
+    i.sub!(/(\[Beginn (.+))/, saddlebrown('\1'))
+    i.sub!(/\]/, saddlebrown(']'))
+    if i.include? 'ECTS' # Colourize e. g. [^^^ 22.0 ECTS].
+      i.sub!(
+        /(\[\^\^\^ \d{1,3}\.\d{1} ECTS\])/,
+        colourize_ects_points('\1')
+      )
+    end
+    return i
+  end
+
+  # ========================================================================= #
+  # === show_horizontal_bar
+  #
+  # This will show a red, horizontal bar - or, alternatively, also the
+  # name of the month at hand.
+  # ========================================================================= #
+  def show_horizontal_bar(
+      optional_this_month = nil,
+      current_year        = current_year?
+    )
+    if optional_this_month
+      if optional_this_month.is_a? Array
+        optional_this_month = optional_this_month.first
+      end
+      optional_this_month = number_to_month(optional_this_month)
+    end
+    # The next string is the one that will be shown to the left side.
+    if optional_this_month
+      the_left_string = ''.dup
+      the_left_string << '[Beginn '+
+                       "#{to_german_month(optional_this_month)} #{current_year}"+
+                       ']'
+      if use_unicode_symbols?
+        # ===================================================================== #
+        # Display a little smiley-face next, if we make use of unicode
+        # symbols.
+        # ===================================================================== #
+        the_left_string << " #{return_smiley_face}"
+      end
+      # ======================================================================= #
+      # The user may pass a special Hash to this method, in which case we
+      # may display some more - in particular n ECTS points registered so
+      # far for the given month.
+      # ======================================================================= #
+      if block_given?
+        yielded = yield
+        if yielded.is_a? Hash
+          # ================================================================= #
+          # === :n_ects_points_in_this_month
+          # ================================================================= #
+          if yielded.has_key? :n_ects_points_in_this_month
+            n_ects_points = yielded[:n_ects_points_in_this_month]
+            if n_ects_points > 0
+              n_ects_points_string = " [^^^ #{n_ects_points} ECTS] "
+              the_left_string << n_ects_points_string
+            end
+          end
+        end
+      end
+      # ======================================================================= #
+      # Next we will add '-' characters.
+      # ======================================================================= #
+      the_left_string = the_left_string.ljust(
+        @internal_hash[:n_ljust_to_the_left]+9, '-' # A bit hackish but it'll do for now.
+      )
+      the_left_string = colourize_and_return_the_beginning_of_the_month(the_left_string)
+      # ======================================================================= #
+      # Past this point we have the right side - this one can
+      # simply be appended, as-is.
+      # ======================================================================= #
+      the_left_string << short_vertical_bar+
+                         palegreen(' [Datum] ')+
+                         swarn('-'*1)+
+                         tomato(' ⌛')+
+                         swarn('-'*48)+
+                         "\n"
+      e tomato('-')+the_left_string
+    end
+  end
+
+  # ========================================================================= #
+  # === return_smiley_face
+  # ========================================================================= #
+  def return_smiley_face
+    Roebe.black_smiling_face
+  end
+
+  # ========================================================================= #
+  # === sanitize_dataset
+  # ========================================================================= #
+  def sanitize_dataset
+    # ======================================================================= #
+    # Select all lectures for which we are either registered, or
+    # not_yet_registered_for_an_upcoming_exam_at - the latter applies
+    # to lectures where we will still have to register for.
+    # ======================================================================= #
+    @dataset = @dataset_from_file_lecture_information.select {|name, inner_hash|
+      if inner_hash.nil?
+        e "#{rev}Some erroneous entry for `#{tomato(name)}#{rev}`."
+      end
+      # ===================================================================== #
+      # Next we must select all entries that are relevant. This will be
+      # done by querying the Hash stored in the inner_hash variable.
+      # ===================================================================== #
+      inner_hash.has_key?('registered') or
+      inner_hash.has_key?('not_yet_registered')
+    }
+    sort_dataset_by_time
+  end
+
+  # ========================================================================= #
+  # === Studium::ShowUpcomingExams.next_exam?
+  #
+  # This class-method will always tell us which exam will come next.
+  #
+  # This method will return an Array, such as:
+  #
+  #   ["500157 Populationsgenetik", {:ects=>1.5, :sws=>1.5,
+  #
+  # The first entry is the LVA-id and the name of the course; then comes
+  # the Hash with the data, exactly as it is stored in the file called
+  # 'lecture_information.yml'.
+  # ========================================================================= #
+  def self.next_exam?
+    new(:be_silent).result?.first
+  end
+
+  # ========================================================================= #
+  # === store_old_upcoming_exams
+  #
+  # This method will store the old upcoming exams. It will always trigger
+  # the storing-routine, so if you need to make additional checks, do so
+  # before calling that method.
+  # ========================================================================= #
+  def store_old_upcoming_exams
+    Studium.save_all_registered_upcoming_exams # ← Save the upcoming exams here. 
+  end
+
+  # ========================================================================= #
+  # === run                                                         (run tag)
+  # ========================================================================= #
+  def run
+    menu
+    consider_renaming_the_konsole_tab
+    consider_autogenerating_exam_aliases
+    report
+    store_old_upcoming_exams # ← Store the upcoming-exams into a file as well.
+  end
+
+  # ========================================================================= #
+  # === report                                                   (report tag)
+  # ========================================================================= #
+  def report
+    _ = dataset?
+    if _.empty?
+      opne 'You have not registered for any upcoming exams.'
+    else
+      left_pad      = left_pad?
+      current_month = month?
+      if show_only_exams_for_which_we_are_registered?
+        _.select! {|name_of_the_course, inner_hash|
+          inner_hash.has_key?('registered')
+        }
+      end
+      # ===================================================================== #
+      # At this point, we assume (usually correctly so) that the main
+      # dataset was already sorted.
+      # ===================================================================== #
+      index = 0
+      case show_n_upcoming_exams?
+      # ===================================================================== #
+      # === :all_of_them
+      # ===================================================================== #
+      when :all_of_them
+        # In this case, we show all of them.
+      else
+        if show_n_upcoming_exams?.to_s =~ /^(\d+)$/
+          n_exams_to_show = $1.to_s.dup.to_i
+          _ = _[0 .. (n_exams_to_show - 1)]
+        end
+      end
+      e
+      report_today(_.size) # Show the "Heute ist der ..." part here.
+      n_ects_in_this_month = 0 # Keep track of how many ECTS are "available" in this month.
+      # ===================================================================== #
+      # Keep in mind that the variable name_of_the_lecture also contains
+      # the LVA-ID, such as "330064 Mikrobiologie und Hygiene", so it is
+      # a slightly misnomer-named variable name.
+      # ===================================================================== #
+      today_is = ::Time.now
+      _.each {|name_of_the_lecture, inner_hash| index += 1
+        # =================================================================== #
+        # === Consider working without the lva-id number next:
+        # =================================================================== #
+        unless SHOW_LEADING_LVA_ID_NUMBER
+          splitted = name_of_the_lecture.split(' ')
+          name_of_the_lecture = splitted[1 .. -1].join(' ').strip 
+        end
+        use_this_as_ljust_value = left_pad
+        new_line_index = 10 # This is for the second row, containing "Ort:".
+        all_exams = inner_hash['exams']
+        next_exam_date = ::Studium.return_next_exam_date(all_exams)
+        next_exam_date_as_time_object = ::Time.parse(next_exam_date)
+        this_line = ''.dup # This is the line that will be shown.
+        n_ects_points             = inner_hash[:ects] # How many ECTS this lecture has.
+        priority_of_the_lecture   = inner_hash[:priority]
+        if inner_hash.has_key? 'registered'
+          the_exam_will_happen_when = inner_hash['registered'].first
+        else # else use the key 'not_yet_registered'.
+          the_exam_will_happen_when = inner_hash['not_yet_registered'].first
+        end # Must come before "startzeit = ".
+        # =================================================================== #
+        # Add the "Ort" of the exam.
+        # =================================================================== #
+        the_location = return_location( # This variable will contain only the location, aka 'Ort'.
+          the_exam_will_happen_when.delete("\t")
+        ).lstrip
+        # =================================================================== #
+        # === Add the date of the exam, stored in the variable
+        #     called `date_of_the_exam`.
+        # =================================================================== #
+        date_of_the_exam          = return_date_of_the_exam(the_exam_will_happen_when)
+        german_weekday            = german_weekday?(date_of_the_exam).ljust(11) # "Donnerstag" is the longest name.
+        # =================================================================== #
+        # === Handle new months next
+        #
+        # Display a horizontal bar if we are at a new month. This must
+        # come after we have defined the variable date_of_the_exam.
+        # =================================================================== #
+        if DISPLAY_HORIZONTAL_BAR_TO_INDICATE_A_NEW_MONTH and @report_result
+          # ================================================================= #
+          # Must first check whether it is a new month.
+          # ================================================================= #
+          actual_month = date_of_the_exam.scan(/\d{1,2}\.(\d{1,2})\.\d{4}/).flatten
+          if actual_month == current_month
+          else
+            # =============================================================== #
+            # Ok, this means we have a new month then. We can thus
+            # delegate towards show_horizontal_bar() to indicate this.
+            # =============================================================== #
+            current_month = actual_month.dup
+            show_horizontal_bar(current_month) {{ n_ects_points_in_this_month: n_ects_in_this_month }}
+            if n_ects_in_this_month > 0
+              n_ects_in_this_month = 0
+            end
+          end
+        end
+        n_ects_in_this_month += n_ects_points
+        # =================================================================== #
+        # Have a colourized german weekday show up in colours:
+        # =================================================================== #
+        colourized_german_weekday = mediumpurple(german_weekday)
+        startzeit                 = return_startzeit_from(the_exam_will_happen_when).strip.dup
+        colourized_startzeit      = royalblue('Startzeit: ')+
+                                    steelblue(startzeit)+rev
+        # =================================================================== #
+        # Next, find out in how many days the exam will happen - this has
+        # to come after we defined the two variables "date_of_the_exam" and
+        # "startzeit":
+        # =================================================================== #
+        the_exam_will_happen_in_n_days = in_n_days(date_of_the_exam+' '+startzeit.to_s)
+        # =================================================================== #
+        # Note that index.to_s.size will yield 3, if we have more than 100
+        # entries, so we have to pad it a little bit.
+        # =================================================================== #
+        colourized_and_padded_index = (' ' * (3 - index.to_s.size ))
+        use_this_as_leading_padding = '   ' # This is the default padding.
+        if next_exam_date_as_time_object < today_is
+          # In this case, it is an outdated lecture, so indicate this
+          # visually to the user too: 
+          use_this_as_leading_padding = ''.dup
+          if index > 9
+            use_this_as_leading_padding << ' '
+            use_this_as_ljust_value -= 1
+          else
+            new_line_index -= 1
+          end
+          use_this_as_leading_padding << crimson(@warning_sign) # And we'll use some red-colour variant in this event.
+          use_this_as_leading_padding << ' '
+          use_this_as_ljust_value += 1
+        elsif inner_hash.has_key? 'registered' # In this case prepend the emoji-checkbox.
+          use_this_as_leading_padding = ' '+goldenrod(@emoji_checkbox)+' '
+        end
+        # =================================================================== #
+        # Next, put together the leading-padding with the colours we will use
+        # for the index:
+        # =================================================================== #
+        colourized_and_padded_index << use_this_as_leading_padding+
+                                       orange('(')+
+                                       goldenrod(index.to_s)+
+                                       orange(') ')
+        this_line << colourized_and_padded_index
+        copy_of_the_lecture_name = name_of_the_lecture.dup
+        # =================================================================== #
+        # Truncate the name a bit - otherwise it looks rather terrible.
+        # =================================================================== #
+        if copy_of_the_lecture_name.size > 62
+          copy_of_the_lecture_name = copy_of_the_lecture_name[0 .. 58]+
+                                     ' [...] '
+        end
+        # =================================================================== #
+        # Justify the name of the lecture a bit and indicate to the
+        # user that he may register for this exam.
+        # =================================================================== #
+        if inner_hash.has_key? 'not_yet_registered'
+          unless copy_of_the_lecture_name.size + 34 >= use_this_as_ljust_value # See the next line for an explanation of the number here; +1
+            copy_of_the_lecture_name << ' ← [TODO: register for this exam]' # 33 chars
+          end
+        end
+        # =================================================================== #
+        # .ljust the result next:
+        # =================================================================== #
+        copy_of_the_lecture_name = copy_of_the_lecture_name.ljust(use_this_as_ljust_value, ' ')
+        if inner_hash.has_key? 'registered'
+          # ================================================================= #
+          # Registered exams will be coloured via lightgreen:
+          # ================================================================= #
+          copy_of_the_lecture_name = lightgreen(copy_of_the_lecture_name)
+        else # Else we are not registered for that exam.
+          # ================================================================= #
+          # In this case we need to distinguish:
+          #
+          #   - For courses that are of priority 1, we will use
+          #   - Otherwise the olivedrab colour will be used, as the default colour
+          #
+          # The old code before the rewrite in January 2024 used as the
+          # default colour "lightslategray".
+          # ================================================================= #
+          if priority_of_the_lecture == 1
+            copy_of_the_lecture_name = olivedrab(copy_of_the_lecture_name)
+          else
+            copy_of_the_lecture_name = darkolivegreen(copy_of_the_lecture_name)
+          end
+        end
+        if copy_of_the_lecture_name.include?(' ← [TODO: register for this exam]')
+          copy_of_the_lecture_name.sub!(
+            / ← \[TODO: register for this exam\]/,
+            rev+indianred(' ← [TODO: register for this exam]')
+          )
+        end
+        this_line << copy_of_the_lecture_name
+        this_line << " #{return_red_vertical_bar} "
+        this_line << colourized_german_weekday # Append the colourized germany weekday next.
+        this_line << " #{mediumorchid(next_exam_date)}"
+        this_line << " #{return_red_vertical_bar}"
+        if the_exam_will_happen_in_n_days < 0.5 # Assume "heute" aka today.
+          colourized_in_n_days = crimson('[    HEUTE   ] ')
+        else
+          colourized_in_n_days = skyblue('[+  ')+
+                                 orangered(
+                                   the_exam_will_happen_in_n_days.to_s.rjust(4)
+                                 )+
+                                 skyblue(' days] ')
+        end
+        this_line << "#{colourized_in_n_days}"
+        this_line << colourized_startzeit       
+        # =================================================================== #
+        # Next comes the big display part - we will show the built-up line:
+        # =================================================================== #
+        if @report_result
+          e this_line # And display it here.
+        end
+        if @report_result
+          # ================================================================= #
+          # We will work on a sanitized variant of `the_location`.
+          # ================================================================= #
+          sanitized_the_location = the_location.dup
+          if sanitized_the_location.size > 49
+            sanitized_the_location = word_wrap(sanitized_the_location, 49)
+          end
+          if sanitized_the_location.include? "\n"
+            sanitized_the_location = sanitized_the_location.split("\n")
+          else
+            sanitized_the_location = [sanitized_the_location]
+          end
+          # ================================================================= #
+          # Also show the location of the exam at hand. This will be done
+          # on a new line, for which we will modify the array next.
+          # ================================================================= #
+          sanitized_the_location.map! {|entry|
+            entry.strip!
+            entry = entry.prepend(
+              (
+                (' ' * (use_this_as_ljust_value+new_line_index))
+              )+'|'+(' ' * 14)
+            )
+            entry # Return it here.
+          }
+          joined_location = sanitized_the_location.join("\n").dup
+          if TRY_TO_SHOW_PRIORITIES_FOR_THE_LECTURES
+            # ================================================================= #
+            # And append the priority as well, onto the location_of_the_exam
+            # variable.
+            # ================================================================= #
+            joined_location << ' Priorität: '+priority_of_the_lecture.to_s # Used to be :springgreen
+          end
+          # ================================================================= #
+          # Next append how many ECTS points this exam has.
+          # ================================================================= #
+          joined_location << ' ('+n_ects_points.to_s+' ECTS)' # limegreen
+          if joined_location.include?(':')
+            joined_location.sub!(
+              /:/, " #{RIGHT_ARROW}"
+            )
+          end
+          if joined_location.include?('|')
+            joined_location.gsub!(/\|/, vertical_bar?)
+          end
+          if joined_location.include?('Priorität')
+            array = [] # This is our new Array.
+            splitted = joined_location.split('Priorität')
+            array << 'Priorität'+splitted.last
+            splitted = splitted.first
+            splitted = splitted.split('→')
+            array.prepend splitted.last
+            array.prepend splitted.first
+            array[2] = limegreen(array[2])
+            if array[1].include? vertical_bar?
+              splitted = array[1].split(vertical_bar?)
+              splitted[0] = slategray(" #{splitted[0].lstrip}")
+              splitted[1] = slategray(splitted[1])
+              splitted    = splitted.join(swarn(vertical_bar?))
+              array[1]    = splitted
+            else
+              array[1] = slategray(array[1])
+            end
+            if array[0].include?(vertical_bar?)
+              splitted = array[0].split(vertical_bar?)
+              splitted[1] = paleturquoise(splitted[1]) # This will include "Ort".
+              array[0] = splitted[0] + swarn(vertical_bar?) + splitted[1]
+            else
+              array[0] = paleturquoise(array[0])
+            end
+            joined_location = array[0] + swarn('→')+
+                              array[1] + array[2]
+          end
+          e joined_location
+        end
+      }
+      if @report_result
+        display_total_ects
+        e
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === Studium::ShowUpcomingExams.return_all_registered_upcoming_exams
+  #
+  # Return all upcoming exams, without limitation, as an Array. This Array
+  # can then be used, for example, in a GUI where it is displayed to the
+  # user.
+  #
+  # Usage example:
+  #
+  #   dataset = Studium::ShowUpcomingExams.return_all_registered_upcoming_exams
+  #
+  # ========================================================================= #
+  def self.return_all_registered_upcoming_exams(&block)
+    result = Studium::ShowUpcomingExams.new(
+      :do_not_report_anything_and_do_not_update_the_cd_aliases
+    ).result?
+    # ======================================================================= #
+    # === Handle blocks next
+    # ======================================================================= #
+    if block_given?
+      yielded = yield
+      case yielded
+      # ===================================================================== #
+      # === :only_for_registered_exams
+      # ===================================================================== #
+      when :only_for_registered_exams
+        result = result.select {|a, b|
+          b.has_key?('registered')
+        }
+      end
+    end
+    return result
+  end; self.instance_eval { alias upcoming_exams? return_all_registered_upcoming_exams } # === Studium::ShowUpcomingExams.upcoming_exams?
+
+  # ========================================================================= #
+  # === Studium::ShowUpcomingExams[]
+  # ========================================================================= #
+  def self.[](i = ARGV, &block)
+    new(i, &block)
+  end
+
+end
+
+# =========================================================================== #
+# === Studium.return_all_registered_upcoming_exams
+#
+# This method is recommended to be used if you need to return all
+# upcoming exams.
+# =========================================================================== #
+def self.return_all_registered_upcoming_exams(&block)
+  Studium::ShowUpcomingExams.return_all_registered_upcoming_exams(&block)
+end; self.instance_eval { alias upcoming_exams? return_all_registered_upcoming_exams } # === Studium.upcoming_exams?
+
+# =========================================================================== #
+# === Studium.d150
+# =========================================================================== #
+def self.d150
+  Studium::ShowUpcomingExams.new('--autostud') { :do_not_exit } if Studium.is_on_roebe?
+  Studium.show_upcoming_exams(150)
+end
+
+# =========================================================================== #
+# === Studium.d100
+# =========================================================================== #
+def self.d100
+  Studium::ShowUpcomingExams.new('--autostud') { :do_not_exit } if Studium.is_on_roebe?
+  Studium.show_upcoming_exams(100)
+end
+
+# =========================================================================== #
+# === Studium.d25
+# =========================================================================== #
+def self.d25
+  Studium::ShowUpcomingExams.new('--autostud') { :do_not_exit } if Studium.is_on_roebe?
+  Studium.show_upcoming_exams(25)
+end
+
+# =========================================================================== #
+# === Studium.d20
+# =========================================================================== #
+def self.d20
+  Studium::ShowUpcomingExams.new('--autostud') { :do_not_exit } if Studium.is_on_roebe?
+  Studium.show_upcoming_exams(20)
+end
+
+# =========================================================================== #
+# === Studium.d15
+# =========================================================================== #
+def self.d15
+  Studium::ShowUpcomingExams.new('--autostud') { :do_not_exit } if Studium.is_on_roebe?
+  Studium.show_upcoming_exams(15)
+end
+
+# =========================================================================== #
+# === Studium.d10
+# =========================================================================== #
+def self.d10
+  Studium::ShowUpcomingExams.new('--autostud') { :do_not_exit } if Studium.is_on_roebe?
+  Studium.show_upcoming_exams(10)
+end
+
+# =========================================================================== #
+# === Studium.d5
+# =========================================================================== #
+def self.d5
+  Studium::ShowUpcomingExams.new('--autostud') { :do_not_exit } if Studium.is_on_roebe?
+  Studium.show_upcoming_exams(5)
+end
+
+# =========================================================================== #
+# === Studium.d3
+# =========================================================================== #
+def self.d3
+  Studium::ShowUpcomingExams.new('--autostud') { :do_not_exit } if Studium.is_on_roebe?
+  Studium.show_upcoming_exams(3)
+end
+
+# =========================================================================== #
+# === Studium.next_exam?
+#
+# This method will return an Array.
+#
+# Result may be like this:
+#
+#   ["300178 Mikrob. Lebensgemeinschaften", {:ects=>3.0, etc..]
+#
+# =========================================================================== #
+def self.next_exam?
+  ::Studium::ShowUpcomingExams.next_exam?
+end
+
+# =========================================================================== #
+# === Studium.return_upcoming_exams_as_HTML
+# =========================================================================== #
+def self.return_upcoming_exams_as_HTML(
+    hash = {}
+  )
+  _ = '<div'.dup
+  if hash and hash.is_a?(Hash)
+    # ======================================================================= #
+    # === :css_style
+    # ======================================================================= #
+    if hash.has_key? :css_style
+      _ << ' style="'+
+           hash.delete(:css_style).to_s+
+           '"'
+    end
+  end
+  _ << ">\n"
+  Studium.enable_www_mode
+  time_now = ::Time.now
+  dataset = Studium.upcoming_exams? { :only_for_registered_exams }
+  dataset.each {|a, inner_hash|
+    homepage = inner_hash[:homepage]
+    homepage = homepage.first if homepage.is_a? Array
+    homepage = homepage.to_s
+    n_ECTS   = inner_hash[:ects]
+    registered_for_the_exam_on_this_day = inner_hash['registered']
+    if registered_for_the_exam_on_this_day.is_a? Array
+      registered_for_the_exam_on_this_day = registered_for_the_exam_on_this_day.first
+    end
+    only_the_exam_day = registered_for_the_exam_on_this_day.scan(
+      /\d{2}\.\d{2}\.\d{4}/
+    ).flatten.first
+    future_time = ::Time.parse(only_the_exam_day)
+    time_difference = future_time - time_now
+    _ << '<p class="default">'+"\n"
+    # ======================================================================= #
+    # The header. Note that the CSS class specific_exam_date can be
+    # used to style the specific exam date.
+    # ======================================================================= #
+    _ << Cyberweb.boldbr(
+           HtmlTags.a(homepage, content: a)+
+           ' <b class="indigo">['+n_ECTS.to_s+' ECTS]</b>'
+         )+'<br>'+
+         '<span class="marl1em">Exam on:</span> '+
+         '<span class="BOLD specific_exam_date">'+
+         registered_for_the_exam_on_this_day.to_s+
+         '</span> '+ # This has the special CSS class.
+         '(in <b class="darkgreen">'+(
+           (time_difference / 60 / 60) / 24
+         ).round(1).to_s+' days</b>)'
+    _ << "</p>\n"
+    _ << Cyberweb.fancy_spacer
+  }
+  _ << "</div>\n"
+  return _
+end
+
+# =========================================================================== #
+# === Studium.show_upcoming_exams
+# =========================================================================== #
+def self.show_upcoming_exams(
+    show_n_exams                  = :all_of_them, # This is also :default.
+    pass_this_array_onto_the_menu = nil,
+    &block
+  )
+  if show_n_exams.is_a?(Array) and show_n_exams.empty?
+    show_n_exams = :all_of_them
+  end
+  # ========================================================================= #
+  # === Handle blocks given to this method next
+  # ========================================================================= #
+  if block_given?
+    yielded = yield
+    if yielded.is_a? Hash
+      yielded.merge!(
+        show_n_upcoming_exams: show_n_exams
+      )
+    elsif yielded.is_a? Symbol
+      hash = { show_n_upcoming_exams: show_n_exams }
+      hash.merge!(
+        array_of_symbols: [yielded]
+      )
+    end
+  end
+  _ = Studium::ShowUpcomingExams.new(show_n_exams, :do_not_run_yet) { yielded }
+  if pass_this_array_onto_the_menu and
+    !pass_this_array_onto_the_menu.empty?
+    _.menu(pass_this_array_onto_the_menu)
+  end
+  # ========================================================================= #
+  # === Handle blocks next
+  # ========================================================================= #
+  if block_given?
+     yielded = yield
+     case yielded
+     when :do_not_use_opn
+       _.do_not_use_opn
+     end
+  end
+  _.run
+end
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  Studium.show_upcoming_exams(ARGV)
+end # showupcomingexams