studium 0.10.1

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

@@ -0,0 +1,53 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'studium/exams/show_upcoming_exams/menu.rb'
+# =========================================================================== #
+require 'studium/exams/show_upcoming_exams/help.rb'
+
+module Studium
+
+class ShowUpcomingExams < Studium::Base
+
+  # ========================================================================= #
+  # === 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 --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
+
+end; end

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

@@ -0,0 +1,195 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'studium/exams/show_upcoming_exams/report.rb'
+# =========================================================================== #
+module Studium
+
+class ShowUpcomingExams < Studium::Base # === Studium::ShowUpcomingExams
+
+  # ========================================================================= #
+  # === report                                                   (report tag)
+  # ========================================================================= #
+  def report
+    _ = @dataset
+    if _.empty?
+      opnn; e 'You have not registered for any upcoming exams.'
+    else
+      current_month = month?
+      # ===================================================================== #
+      # At this point, we assume (usually correctly so) that the main
+      # dataset was already sorted.
+      # ===================================================================== #
+      index = 0
+      case @show_n_upcoming_exams
+      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)
+      n_ects_in_this_month = 0
+      _.each {|name_of_the_lecture, inner_hash| index += 1
+        if inner_hash.has_key? 'registered'
+          the_exam_will_happen_when = inner_hash['registered'].first
+        else
+          the_exam_will_happen_when = inner_hash['not_yet_registered'].first
+        end
+        colourized_and_padded_index = (' ' * (2 - index.to_s.size ))
+        colourized_and_padded_index << orange('(')+
+                                       goldenrod(index.to_s)+
+                                       orange(') ')
+        priority_of_the_lecture = inner_hash[:priority]
+        n_ects_points = inner_hash[:ects] # How many ECTS this lecture has.
+        startzeit = return_startzeit_from(the_exam_will_happen_when)
+        colourized_startzeit = royalblue(' Startzeit: ')+
+                               slateblue(startzeit)
+        # =================================================================== #
+        # === Consider showing 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
+        # =================================================================== #
+        # === Add the date of the exam.
+        # =================================================================== #
+        date_of_the_exam = return_date_of_the_exam(the_exam_will_happen_when)
+        colourized_date_of_the_exam = return_red_vertical_bar+
+          yellowgreen(
+            date_of_the_exam+', '
+          )
+        german_weekday = german_weekday?(date_of_the_exam).ljust(11) # "Donnerstag" is the longest name.
+        colourized_german_weekday = mediumpurple(german_weekday)
+        # =================================================================== #
+        # Justify the name of the lecture a bit.
+        # =================================================================== #
+        if inner_hash.has_key? 'not_yet_registered'
+          name_of_the_lecture = name_of_the_lecture.dup if name_of_the_lecture.frozen?
+          name_of_the_lecture << ' ← we still have to register for this exam!'
+        end
+        padded_name_of_the_lecture = name_of_the_lecture.ljust(@n_ljust_to_the_left)
+        if padded_name_of_the_lecture.size > @n_ljust_to_the_left
+          padded_name_of_the_lecture = padded_name_of_the_lecture[
+            0 .. (@n_ljust_to_the_left - 6)
+          ]+'[...]'
+        end
+        if inner_hash.has_key? 'not_yet_registered'
+          # ================================================================= #
+          # If we aren't yet registered for an exam, then we will
+          # always colourize this in crimson().
+          # ================================================================= #
+          colourized_and_padded_name_of_the_lecture =
+              crimson(padded_name_of_the_lecture)
+        else
+          # ================================================================= #
+          # === Colourize the lecture based on the priority
+          #
+          # Next, colourize the name of the lecture according to the
+          # priority. Lectures that are part of the vector-curriculum
+          # will always be re-assigned priority one.
+          # ================================================================= #
+          if is_part_of_the_vector_curriculum?(name_of_the_lecture)
+            colourized_and_padded_name_of_the_lecture =
+              mediumturquoise(padded_name_of_the_lecture)
+          else
+            case priority_of_the_lecture
+            when 1
+              colourized_and_padded_name_of_the_lecture =
+                lightsteelblue(padded_name_of_the_lecture)
+            else
+              colourized_and_padded_name_of_the_lecture =
+                lightslategray(padded_name_of_the_lecture)
+            end
+          end
+        end
+        # =================================================================== #
+        # Add the "Ort" of the exam.
+        # =================================================================== #
+        the_location = return_location(the_exam_will_happen_when).lstrip
+        colourized_location = paleturquoise(
+          the_location
+        ).sub(/:/, swarn(' ->')+paleturquoise) # Return the "Ort" here.
+        # =================================================================== #
+        # Next, find out in how many days the exam will happen:
+        # =================================================================== #
+        the_exam_will_happen_in_n_days = in_n_days(date_of_the_exam+' '+startzeit.to_s)
+        if the_exam_will_happen_in_n_days < 0.5
+          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
+        # =================================================================== #
+        # Display a horizontal bar if we are at a new month.
+        # =================================================================== #
+        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.
+            # =============================================================== #
+            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
+        # =================================================================== #
+        # Next, output the colourized variants - the big display part:
+        # =================================================================== #
+        if @report_result
+          result = '  '+
+                   colourized_and_padded_index+                   # First, we will show the index.
+                   colourized_and_padded_name_of_the_lecture+' '+ # Now we will show the name of the lecture.
+                   colourized_date_of_the_exam+                   # THe date when the exam happens
+                   colourized_german_weekday+ # The weekday in german.
+                   colourized_in_n_days+
+                   colourized_startzeit
+          e result
+        end
+        # =================================================================== #
+        # Also show the location of the exam at hand.
+        # =================================================================== #
+        location_of_the_exam = (' ' * (@n_ljust_to_the_left+8))+
+                               return_red_vertical_bar.rstrip+
+                               (' ' * 12)+colourized_location # Add the Ort too.
+        if TRY_TO_SHOW_PRIORITIES_FOR_THE_LECTURES
+          # ================================================================= #
+          # And append the priority as well.
+          # ================================================================= #
+          colourized_priority = springgreen(
+            ' Priorität: '+priority_of_the_lecture.to_s
+          )
+          location_of_the_exam << colourized_priority
+        end
+        # =================================================================== #
+        # Next append how many ECTS points this exam has.
+        # =================================================================== #
+        location_of_the_exam << limegreen(
+          ' ('+n_ects_points.to_s+' ECTS)'
+        )
+        e location_of_the_exam if @report_result
+      }
+      if @report_result
+        display_total_ects
+        e
+      end
+    end
+  end
+
+end; end

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

@@ -0,0 +1,38 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+module Studium
+
+class ShowUpcomingExams < Studium::Base # === Studium::ShowUpcomingExams.new
+
+  # ========================================================================= #
+  # === reset                                                     (reset tag)
+  # ========================================================================= #
+  def reset
+    super()
+    # ======================================================================= #
+    # === @namespace
+    # ======================================================================= #
+    @namespace = NAMESPACE
+    # ======================================================================= #
+    # === @report_result
+    # ======================================================================= #
+    @report_result = true
+    # ======================================================================= #
+    # === @show_n_upcoming_exams
+    # ======================================================================= #
+    @show_n_upcoming_exams = :all_of_them
+    # ======================================================================= #
+    # === @dataset_from_file_lecture_information
+    # ======================================================================= #
+    @dataset_from_file_lecture_information = 
+      return_dataset_from_file_lecture_information
+    # ======================================================================= #
+    # === @n_ljust_to_the_left
+    # ======================================================================= #
+    @n_ljust_to_the_left = 68
+    sanitize_dataset
+  end
+
+end; end

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

@@ -0,0 +1,20 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+module Studium
+
+class ShowUpcomingExams < Studium::Base
+
+  # ========================================================================= #
+  # === 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
+
+end; end

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

@@ -0,0 +1,494 @@
+#!/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'
+# =========================================================================== #
+require 'studium/base/base.rb'
+# =========================================================================== #
+# And internal .rb files of class Studium::ShowUpcomingExams.
+# =========================================================================== #
+require 'studium/exams/show_upcoming_exams/consider_autogenerating_exam_aliases.rb'
+require 'studium/exams/show_upcoming_exams/constants.rb'
+require 'studium/exams/show_upcoming_exams/initialize.rb'
+require 'studium/exams/show_upcoming_exams/menu.rb'
+require 'studium/exams/show_upcoming_exams/report.rb'
+require 'studium/exams/show_upcoming_exams/reset.rb'
+require 'studium/exams/show_upcoming_exams/run.rb'
+
+module Studium
+
+class ShowUpcomingExams < Studium::Base # === Studium::ShowUpcomingExams
+
+  # ========================================================================= #
+  # Toplevel-methods of the studium gem come next.
+  # ========================================================================= #
+  require 'studium/toplevel_methods/is_this_lecture_part_of_the_vector_curriculum.rb'
+  require 'studium/toplevel_methods/save_all_registered_upcoming_exams.rb'
+  require 'studium/toplevel_methods/total_ects_points_passed.rb'
+
+  # ========================================================================= #
+  # === set_input
+  # ========================================================================= #
+  def set_input(i = '')
+    i = i.first if i.is_a? Array
+    i = i.to_s.dup
+    @input = 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
+
+  # ========================================================================= #
+  # === 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|
+      inner_hash.has_key?('registered') or
+      inner_hash.has_key?('not_yet_registered')
+    }
+    sort_dataset_by_time
+  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
+          opnn; e crimson(name_of_the_lecture)+
+                  ' has no key called `'+
+                  sfancy('registered')+'`.'
+          opnn; e 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
+          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
+      parse_time_entry_from_this_string(the_exam_will_happen_when)
+    }
+  end
+
+  # ========================================================================= #
+  # === return_startzeit_from
+  # ========================================================================= #
+  def return_startzeit_from(i)
+    return i.scan(/\d{1,2}:\d{1,2}-\d{1,2}:\d{1,2}/).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
+      e (' ' * 60)+
+        limegreen('Total ECTS passed so far: ').to_s+
+        colourize_ects_points(::Studium.n_ects_passed_so_far).to_s
+      e (' ' * 60).to_s+
+        limegreen('ECTS of the above exams:  ')+
+        colourize_ects_points(plus)
+    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
+
+  # ========================================================================= #
+  # === dataset?
+  # ========================================================================= #
+  def dataset?
+    @dataset
+  end; alias result? dataset? # === result?
+
+  # ========================================================================= #
+  # === return_red_vertical_bar
+  # ========================================================================= #
+  def return_red_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
+
+  # ========================================================================= #
+  # === report_today
+  # ========================================================================= #
+  def report_today(
+      show_n_exams = show_n_exams?
+    )
+    if @report_result
+      opnn
+      e 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_ects_points
+  # ========================================================================= #
+  def colourize_ects_points(i)
+    lightgreen(i)
+  end
+
+  # ========================================================================= #
+  # === return_location                                             (ort tag)
+  # ========================================================================= #
+  def return_location(i)
+    if i.include? 'Ort'
+      ' '+i.scan(/(Ort: .+)$/).flatten.first
+    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
+    )
+    the_exam_will_happen_when = remove_german_weekdays(the_exam_will_happen_when).strip
+    the_exam_will_happen_when =~ REGEX_TO_EXTRACT_DATE_AND_TIME_FROM_AN_UPCOMING_EXAM
+    this_time = $1.to_s.dup
+    begin
+      Time.parse(this_time) # This method will return a time-parsed entry.
+    rescue Exception => error
+      e 'Input to this method was:'
+      e
+      e '  '+sfancy(the_exam_will_happen_when)
+      e
+      pp error
+      exit
+    end
+  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
+    )
+    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
+    result = '  '.dup
+    result << swarn('-' * (@n_ljust_to_the_left+6)).dup
+    if optional_this_month
+      n_tokens_to_the_right = 30
+      result << saddlebrown('[Beginn ')
+      german_name_for_this_month = return_german_name_for_this_english_month(optional_this_month).dup
+      result << darkgoldenrod(german_name_for_this_month)
+      if use_unicode_symbols?
+        # =================================================================== #
+        # Display a little smiley-face next, if we make use of unicode
+        # symbols.
+        # =================================================================== #
+        result << " #{darkgoldenrod(Roebe.black_smiling_face)}"
+      end
+      result << saddlebrown(']')
+      # ===================================================================== #
+      # 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
+          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] "
+              colourized_n_ects_points_string = colourize_ects_points(
+                n_ects_points_string
+              )
+              result << colourized_n_ects_points_string
+              n_tokens_to_the_right -= n_ects_points_string.size
+            end
+          end
+        end
+      end
+      result << swarn('-' * n_tokens_to_the_right)
+    end
+    e result
+  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
+
+  # ========================================================================= #
+  # === Studium::ShowUpcomingExams.next_exam?
+  #
+  # This class-method will always tell us which exam will come next.
+  #
+  # This method will return a String.
+  # ========================================================================= #
+  def self.next_exam?
+    self.new(:be_silent).result?.first
+  end
+
+  # ========================================================================= #
+  # === Studium::ShowUpcomingExams.return_all_registered_upcoming_exams
+  #
+  # Return all upcoming exams, without limitation, as an Array.
+  #
+  # Usage example:
+  #
+  #   dataset = Studium::ShowUpcomingExams.return_all_registered_upcoming_exams
+  #
+  # ========================================================================= #
+  def self.return_all_registered_upcoming_exams
+    Studium::ShowUpcomingExams.new(:do_not_report_anything).result?
+  end
+
+  # ========================================================================= #
+  # === Studium::ShowUpcomingExams[]
+  # ========================================================================= #
+  def self.[](i = '', &block)
+    new(i, &block)
+  end
+
+end
+
+# =========================================================================== #
+# === Studium.return_all_registered_upcoming_exams
+# =========================================================================== #
+def self.return_all_registered_upcoming_exams
+  Studium::ShowUpcomingExams.return_all_registered_upcoming_exams
+end
+
+# =========================================================================== #
+# === Studium.show_upcoming_exams
+# =========================================================================== #
+def self.show_upcoming_exams(
+    show_n_exams = :all_of_them
+  )
+  _ = Studium::ShowUpcomingExams.new(show_n_exams, :do_not_run_yet) {{
+    show_n_upcoming_exams: show_n_exams
+  }}
+  if block_given?
+     yielded = yield
+     case yielded
+     when :do_not_use_opn
+       _.do_not_use_opn
+     end
+  end
+  _.run
+end
+
+# =========================================================================== #
+# === Studium.d100
+# =========================================================================== #
+def self.d100
+  Studium.show_upcoming_exams(100)
+end
+
+# =========================================================================== #
+# === Studium.d20
+# =========================================================================== #
+def self.d20
+  Studium.show_upcoming_exams(20)
+end
+
+# =========================================================================== #
+# === Studium.d15
+# =========================================================================== #
+def self.d15
+  Studium.show_upcoming_exams(15)
+end
+
+# =========================================================================== #
+# === Studium.d10
+# =========================================================================== #
+def self.d10
+  Studium.show_upcoming_exams(10)
+end
+
+# =========================================================================== #
+# === Studium.d5
+# =========================================================================== #
+def self.d5
+  Studium.show_upcoming_exams(5)
+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
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  Studium::ShowUpcomingExams.new(ARGV)
+end # show_upcoming_exams