studium 0.16.9

data/lib/studium/exams/ask_exam_question/ask_exam_question.rb

@@ -0,0 +1,2757 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# === Studium::Exams::AskExamQuestion
+#
+# This class, re-written in December 2021 / January 2022 and then again
+# in June 2023, can handle exam questions and study-related questions.
+#
+# The user can pass a given topic to this class, as a String, such as
+# "microbiology", and then this class will randomly select one of the
+# existing entries fitting to that particular topic at hand, and then
+# ask the question, before revealing the answer after a delay. The
+# specified delay is usually fairly small, at about 3 seconds, but
+# this can be set by the user to any different value.
+#
+# The delay, e. g. 3 seconds, is read in from a yaml file (if that
+# file exists, otherwise we will use a default value). Alternatively
+# the delay can be set from the commandline via, for instance:
+#
+#   qa 'delay = 5'
+#
+# The topic given thus determines which exam question is to be handled.
+#
+# By default, if no argument is provided to this class, then a random
+# topic (and thus a random question) will be picked, from all the
+# available topics.
+#
+# Every time a question is asked, the "last asked question" 
+# information is stored into a file.
+#
+# The "exam pool" constitutes the available, unanswered exams.
+#
+# The method Studium.runmode? will tell us whether we are on
+# the commandline or whether we are used on the www, such as
+# from a .cgi script.
+#
+# The class can operate on one question at a time, or in batch
+# mode, which will call "all questions". (By default, I usually
+# prefer to just have one question asked).
+#
+# Usage examples in ruby code:
+#
+#   x = Studium::Exams::ExamQuestion.new('- Wir können Melanome nach der "ABCDE" Regel beurteilen. Wofür stehen diese Abkürzungen? (1) A: Asymmetry (2) B: Border (3) C: Color (4) D: Diameter (5) E: Evolving')
+#   x = Studium::Exams::ExamQuestion.new('- Nenne die beiden wichtigsten Mechanismen zur Verhinderung der Selbstbefruchtung. A: (1) physische Trennung von männlichen und weiblichen Gametophyten (2) genetisch, über die Selbst-Inkompatibilität')
+#   x = Studium::Exams::ExamQuestion.new('- Nenne die Zucker des Calvin-Zyklus, beginnend von RUBISCO, im "Uhrzeigersinn"! A: (1) 3-Phosphoglycerat (2) 1,3-Bisphosphoglycerat (3) G3P (4) 5-G3P und Ribulose-1-5-Bisphosphat.')
+#   x = Studium::Exams::ExamQuestion.new('- abc? def? ya') { :do_not_run_yet }
+#
+# =========================================================================== #
+# require 'studium/exams/ask_exam_question/ask_exam_question.rb'
+# Studium::Exams::AskExamQuestion.new(ARGV)
+# y = Studium.ask_question('amg2') { :do_not_run_yet }
+# =========================================================================== #
+require 'studium/base/base.rb'
+
+module Studium
+
+module Exams
+
+class AskExamQuestion < Studium::Base # === Studium::Exams::AskExamQuestion
+
+  require 'studium/exams/exam_question/exam_question.rb'
+  require 'studium/statistics/report_how_many_exam_questions_were_answered.rb'
+
+  # ========================================================================= #
+  # === DEFAULT_COLOUR_TO_USE
+  # ========================================================================= #
+  DEFAULT_COLOUR_TO_USE = :olivedrab
+
+  # ========================================================================= #
+  # === USE_THESE_COLOURS
+  #
+  # This Hash is used to set up colours. It will be passed to methods
+  # that belong to the Colours module ("namespace"), which in turn
+  # can be found in the gem called "colours".
+  #
+  # Using a Hash like this allows the user to customize the colours as
+  # well.
+  #
+  # For the question, we prefer to use :olivedrab.
+  # ========================================================================= #
+  USE_THESE_COLOURS = {
+    one:            :steelblue,
+    two:            :mediumseagreen,
+    three:          :mediumpurple, # ← Used to be 'peru' up until 23.11.2019.
+    four:           :olivedrab,
+    five:           :lightgreen,
+    default_colour: DEFAULT_COLOUR_TO_USE # Make use of the colour defined above ^^^ here.
+  }
+
+  # ========================================================================= #
+  # === DEFAULT_COLOUR_AS_ESCAPE_SEQUENCE
+  # ========================================================================= #
+  DEFAULT_COLOUR_AS_ESCAPE_SEQUENCE = 
+    ::Colours.remove_trailing_end_from(
+      ::Colours.send(USE_THESE_COLOURS[:default_colour])
+    )
+
+  # ========================================================================= #
+  # === EMPHASIZE_WORDS_IN_QUOTES_IN_A_GIVEN_QUESTION
+  #
+  # This constant is like the constant called
+  # EMPHASIZE_WORDS_IN_QUOTES_IN_A_GIVEN_ANSWER, except that here
+  # we work on double-quotes, aka '"' characters, in a question.
+  #
+  # As of November 2019, this defaults to false, since we already
+  # use many other colours at this point.
+  # ========================================================================= #
+  EMPHASIZE_WORDS_IN_QUOTES_IN_A_GIVEN_QUESTION = false
+
+  # ========================================================================= #
+  # === EMPHASIZE_WORDS_IN_QUOTES_IN_A_GIVEN_ANSWER
+  # ========================================================================= #
+  EMPHASIZE_WORDS_IN_QUOTES_IN_A_GIVEN_ANSWER = false
+
+  # ========================================================================= #
+  # === MAY_WE_SHOW_THE_TOPIC
+  #
+  # If MAY_WE_SHOW_THE_TOPIC is true then we show the topic.
+  #
+  # We will grab the entry from the yaml file, but we have to make sure
+  # that the file exists, before loading it..
+  # ========================================================================= #
+  _ = "#{::Studium.yaml_directory?}show_topic.yml"
+  if File.exist? _
+    MAY_WE_SHOW_THE_TOPIC = YAML.load_file(_)
+  else
+    MAY_WE_SHOW_THE_TOPIC = false
+  end
+
+  # ========================================================================= #
+  # === SHALL_WE_DEBUG
+  #
+  # Shall we debug or shall we not debug. This is specific to this
+  # class here.
+  # ========================================================================= #
+  SHALL_WE_DEBUG = false
+
+  # ========================================================================= #
+  # === SHOW_STATISTICS
+  #
+  # If SHOW_STATISTICS is true then we will show the statistics.
+  # ========================================================================= #
+  SHOW_STATISTICS = true
+
+  # ========================================================================= #
+  # === STORE_TEXT
+  #
+  # Next comes the string that we will save if we set a new delay.
+  # ========================================================================= #
+  STORE_TEXT = '# ====================================================================== #
+# How long to wait before showing the answer in question, in seconds.
+# ====================================================================== #
+delay: '
+
+
+  # ========================================================================= #
+  # === @rename_konsole_tab
+  # ========================================================================= #
+  @rename_konsole_tab = false
+
+  # ========================================================================= #
+  # === Studium::Exams::ExamQuestion.rename_konsole_tab?
+  # ========================================================================= #
+  def self.rename_konsole_tab?
+    @rename_konsole_tab
+  end
+
+  # ========================================================================= #
+  # === Studium::Exams::ExamQuestion.set_rename_konsole_tab
+  # ========================================================================= #
+  def self.set_rename_konsole_tab(i)
+    @rename_konsole_tab = i
+  end
+
+  # ========================================================================= #
+  # === initialize
+  #
+  # The very first argument given to this class is usually the topic that
+  # is sought - such as "bem1" or "amg1" or "plants", and so forth.
+  # ========================================================================= #
+  def initialize(
+      commandline_arguments = ARGV,
+      run_already           = true,
+      &block
+    )
+    reset
+    set_commandline_arguments(
+      commandline_arguments
+    )
+    # ======================================================================= #
+    # === Handle blocks next
+    # ======================================================================= #
+    if block_given?
+      yielded = yield
+      case yielded # (case tag)
+      # ===================================================================== #
+      # === :disable_colours
+      # ===================================================================== #
+      when :disable_colours,
+           :no_colours
+        # =================================================================== #
+        # The user does not want to use colours in this case, so let's
+        # disable colours then.
+        # =================================================================== #
+        disable_colours
+        set_mode :www # ← Experimental as of 13.04.2019.
+      # ===================================================================== #
+      # === :then_determine_the_split_position_without_using_colours
+      # ===================================================================== #
+      when :then_determine_the_split_position_without_using_colours
+        @internal_hash[:do_determine_the_split_position] = true
+        disable_colours
+      # ===================================================================== #
+      # === :then_determine_the_split_position
+      # ===================================================================== #
+      when :then_determine_the_split_position
+        @internal_hash[:do_determine_the_split_position] = true
+      # ===================================================================== #
+      # === :then_determine_the_split_position_while_disabling_the_colours
+      # ===================================================================== #
+      when :then_determine_the_split_position_while_disabling_the_colours
+        @internal_hash[:do_determine_the_split_position] = true
+        disable_colours
+        set_mode :www # ← Experimental as of 13.04.2019.
+      # ===================================================================== #
+      # === :do_not_run_yet
+      # ===================================================================== #
+      when :do_not_run_yet
+        run_already = false
+      end
+    end
+    case run_already
+    # ======================================================================= #
+    # === :do_not_run
+    #
+    # Handle the situation when we do not want to run automatically.
+    #
+    # This is for arguments such as :dont_run_yet.
+    # ======================================================================= #
+    when :do_not_run,
+         :do_not,
+         :dont_run,
+         :dont_run_yet,
+         :do_not_run_yet
+      run_already = false
+    # ======================================================================= #
+    # === :commandline
+    # ======================================================================= #
+    when :commandline
+      run_already = false
+      set_commandline
+    end
+    run if run_already
+  end
+
+  # ========================================================================= #
+  # === reset                                                     (reset tag)
+  # ========================================================================= #
+  def reset
+    super()
+    infer_the_namespace
+    # ======================================================================= #
+    # === :dataset_from_the_file
+    #
+    # The next variable must be initially nil, in order to distinguish it
+    # from the the startup-situation, before any exam file has been
+    # read in.
+    # ======================================================================= #
+    @internal_hash[:dataset_from_the_file] = nil
+    # ======================================================================= #
+    # === :reject_lines_that_end_with_a_done_token
+    #
+    # If this variable is set to true (which is the default) then all
+    # entries that end with [] will be removed.
+    # ======================================================================= #
+    @internal_hash[:reject_lines_that_end_with_a_done_token] = true
+    # ======================================================================= #
+    # === :n_exam_questions_in_total
+    # ======================================================================= #
+    @internal_hash[:n_exam_questions_in_total] = 0
+    # ======================================================================= #
+    # === :n_exam_questions_answered
+    # ======================================================================= #
+    @internal_hash[:n_exam_questions_answered] = 0
+    # ======================================================================= #
+    # === :may_we_show_the_topic
+    # ======================================================================= #
+    @internal_hash[:may_we_show_the_topic] = MAY_WE_SHOW_THE_TOPIC
+    # ======================================================================= #
+    # === :delay
+    # ======================================================================= #
+    @internal_hash[:delay] = 2.8
+    # ======================================================================= #
+    # === :colour_for_answers
+    # ======================================================================= #
+    @internal_hash[:colour_for_answers] = nil
+    # ======================================================================= #
+    # === :colour_for_questions
+    # ======================================================================= #
+    @internal_hash[:colour_for_questions] = nil
+    # ======================================================================= #
+    # === :exam_file
+    #
+    # This instance variable will keep track where the full path to the
+    # exam file can be found.
+    # ======================================================================= #
+    @internal_hash[:exam_file] = nil
+    # ======================================================================= #
+    # === :debug
+    # ======================================================================= #
+    @internal_hash[:debug] = SHALL_WE_DEBUG
+    # ======================================================================= #
+    # === :topic_to_use
+    # ======================================================================= #
+    @internal_hash[:topic_to_use] = nil
+    # ======================================================================= #
+    # === :result_for_www
+    #
+    # This can be a String, which is then used for display on the www.
+    #
+    # Initially it is set to nil, though, to indicate that we will not
+    # need it when in commandline-mode.
+    # ======================================================================= #
+    @internal_hash[:result_for_www] = nil
+    # ======================================================================= #
+    # === :use_these_colours
+    # ======================================================================= #
+    @internal_hash[:use_these_colours] = USE_THESE_COLOURS
+    # ======================================================================= #
+    # === :numbers_in_parens
+    # ======================================================================= #
+    @internal_hash[:numbers_in_parens] = false
+    # ======================================================================= #
+    # === :separator_token_to_use_when_asking_questions_and_revealing_the_answer
+    # ======================================================================= #
+    if Studium.shall_we_make_use_of_unicode_symbols?
+      @internal_hash[:separator_token_to_use_when_asking_questions_and_revealing_the_answer] = Studium.unicode_horizontal_bar
+    else
+      @internal_hash[:separator_token_to_use_when_asking_questions_and_revealing_the_answer] = '*'
+    end
+    # ======================================================================= #
+    # === @exam_question
+    # ======================================================================= #
+    @exam_question = Studium::Exams::ExamQuestion.new { :do_not_run_yet }
+    set_be_verbose # Be verbose, output lots of stuff to the user.
+    try_to_load_custom_colours
+    set_delay
+    # ======================================================================= #
+    # The default colours will not be made available when we run in the www-mode.
+    # ======================================================================= #
+    if are_we_in_www_mode?
+      disable_colours
+    end
+  end
+
+  # ========================================================================= #
+  # === separator_token_to_use_when_asking_questions_and_revealing_the_answer?
+  # ========================================================================= #
+  def separator_token_to_use_when_asking_questions_and_revealing_the_answer?
+    @internal_hash[:separator_token_to_use_when_asking_questions_and_revealing_the_answer]
+  end; alias separator_token_to_be_used? separator_token_to_use_when_asking_questions_and_revealing_the_answer? # === separator_token_to_be_used?
+       alias separator_token?            separator_token_to_use_when_asking_questions_and_revealing_the_answer? # === separator_token?
+
+  # ========================================================================= #
+  # === result?
+  # ========================================================================= #
+  def result?
+    @internal_hash[:result_for_www]
+  end
+
+  # ========================================================================= #
+  # === try_to_load_custom_colours
+  #
+  # This method can be used to designate specific colours for use by
+  # this class.
+  # ========================================================================= #
+  def try_to_load_custom_colours
+    _ = "#{::Studium.project_yaml_directory?}colours/custom_colours.yml"
+    if File.exist? _
+      dataset = YAML.load_file(_)
+      
+      if dataset.has_key?('colour_for_one')
+        @internal_hash[:use_these_colours][:one] = dataset['colour_for_one']
+      end
+
+      if dataset.has_key?('colour_for_two')
+        @internal_hash[:use_these_colours][:two] = dataset['colour_for_two']
+      end
+
+      if dataset.has_key?('colour_for_three')
+        @internal_hash[:use_these_colours][:three] = dataset['colour_for_three']
+      end
+
+      if dataset.has_key?('colour_for_four')
+        @internal_hash[:use_these_colours][:four] = dataset['colour_for_four']
+      end
+
+      if dataset.has_key?('colour_for_five')
+        @internal_hash[:use_these_colours][:five] = dataset['colour_for_five']
+      end
+
+      set_colour_for_questions(
+        dataset['colour_for_questions']
+      )
+      set_colour_for_answers(
+        dataset['colour_for_answers']
+      )
+    else
+      if is_on_roebe?
+        e 'No file could be found at '+sfile(_)+'.'
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === default_colour?
+  # ========================================================================= #
+  def default_colour?
+    USE_THESE_COLOURS[:default_colour]
+  end
+
+  # ========================================================================= #
+  # === set_exam_question_line
+  # ========================================================================= #
+  def set_exam_question_line(i)
+    @exam_question.set_exam_question_line(i)
+  end
+
+  # ========================================================================= #
+  # === sleep_default_delay
+  #
+  # This method can be used to sleep for the specified duration.
+  #
+  # Since as of April 2012 the method will also handle SIGINT-events
+  # gracefully.
+  # ========================================================================= #
+  def sleep_default_delay(
+      i = delay?
+    )
+    begin
+      sleep(i)
+    rescue Interrupt # We are silent here.
+      exit_program
+    end
+  end; alias default_sleep       sleep_default_delay # === default_sleep
+       alias do_sleep            sleep_default_delay # === do_sleep
+       alias start_default_sleep sleep_default_delay # === start_default_sleep
+
+  # ========================================================================= #
+  # === default_delay?
+  # ========================================================================= #
+  def default_delay?
+    DEFAULT_DELAY
+  end
+
+  # ========================================================================= #
+  # === dataset_from_the_file?
+  # ========================================================================= #
+  def dataset_from_the_file?
+    @internal_hash[:dataset_from_the_file]
+  end; alias dataset? dataset_from_the_file? # === dataset?
+
+  # ========================================================================= #
+  # === set_dataset_from_the_file
+  # ========================================================================= #
+  def set_dataset_from_the_file(i)
+    @internal_hash[:dataset_from_the_file] = i
+  end; alias set_dataset set_dataset_from_the_file # === set_dataset
+
+  # ========================================================================= #
+  # === set_exam_file
+  #
+  # The file location will be something like:
+  #
+  #   /Programs/Ruby/2.3.1/lib/ruby/site_ruby/2.3.0/studium/exam_topics/physiologie
+  #
+  # ========================================================================= #
+  def set_exam_file(i)
+    @internal_hash[:exam_file] = i
+  end; alias set_file set_exam_file # === set_file
+
+  # ========================================================================= #
+  # === set_delay
+  #
+  # Set the default delay value via this method.
+  # ========================================================================= #
+  def set_delay(
+      i = :load_from_file
+    )
+    case i
+    # ======================================================================= #
+    # === :default
+    # ======================================================================= #
+    when :default,
+         :load_from_file,
+         nil
+      # ===================================================================== #
+      # === :delay
+      # ===================================================================== #
+      if File.exist? FILE_DELAY
+        i = YAML.load_file(FILE_DELAY)
+        i = i['delay'] if i.respond_to?('delay')
+      else
+        # =================================================================== #
+        # This is the default if the file can not be found/read. It
+        # can be found in the file studium/constants/delay.rb.
+        # =================================================================== #
+        i = DEFAULT_DELAY
+      end
+    end
+    if i.is_a? Hash
+      i = i['delay']
+    end
+    @internal_hash[:delay] = i.to_f
+  end; alias determine_the_default_delay set_delay # === determine_the_default_delay
+       alias delay=                      set_delay # === delay=
+
+  # ========================================================================= #
+  # === show_the_header
+  # ========================================================================= #
+  def show_the_header(
+      topic_to_use = topic_to_use?
+    )
+    e steelblue(topic_to_use)
+  end
+
+  # ========================================================================= #
+  # === show_available_topics                                    (topics tag)
+  #
+  # This method will show which topics are all available.
+  #
+  # By default, it will also exit after having done so.
+  #
+  # To invoke this method, try:
+  #
+  #   qa topics?
+  #   qa --show-available-topics
+  #
+  # ========================================================================= #
+  def show_available_topics(
+      shall_we_exit = true
+    )
+    e
+    use_these_topics = Studium.available_topics.sort # And sort it.
+    use_these_topics.each_with_index {|category, index|
+      # ===================================================================== #
+      # Number the results via the index.
+      # ===================================================================== #
+      index = '%4s' % ('('+(index+1).to_s)
+      result = ' '.dup
+      if use_colours?
+        result << ::Colours::CYAN if commandline?
+      end
+      result << "#{index}) - " # Add the index here.
+      if use_colours? # And "close" the escape-sequences next.
+        result << rev if commandline?
+      end
+      category = category.to_s.delete('_')
+      category = steelblue(category) if use_colours?
+      result << category
+      e result
+    }
+    e
+    exit if shall_we_exit
+  end
+
+  # ========================================================================= #
+  # === numbers_in_parens?
+  # ========================================================================= #
+  def numbers_in_parens?
+    @internal_hash[:numbers_in_parens]
+  end
+
+  # ========================================================================= #
+  # === do_reveal_the_answer  (answer tag, answers tag, reveal tag, show tag)
+  #
+  # This method will show the proper answer to the given exam question as
+  # hand.
+  #
+  # The second argument to this method, called `include_numbers_in_parens`,
+  # can be used to keep track as to whether we have numbers such as (2).
+  # ========================================================================= #
+  def do_reveal_the_answer(
+      use_this_answer           = @exam_question.answer?,
+      include_numbers_in_parens = numbers_in_parens?,
+      padding_to_use            = '    ',
+      use_colours               = use_colours?
+    )
+    # ======================================================================= #
+    # The variable result will eventually contain what we will display to
+    # the user.
+    # ======================================================================= #
+    result = padding_to_use.dup # Use four spaces as indent, since as of March 2023.
+    # ======================================================================= #
+    # Try to cut down at about 76 characters per line, or whatever the
+    # limit-per-line is. We have to ignore special tags, though, such
+    # as <u> or <orange>. We also have to call this BEFORE replacing
+    # these tags with the corresponding escape values.
+    # ======================================================================= #
+    unless include_numbers_in_parens
+      string_without_tags = remove_tags_from_this_input(use_this_answer.dup)
+      n_characters_to_consider_in_the_line = string_without_tags.size
+      if n_characters_to_consider_in_the_line > word_wrap_at?
+        use_this_answer = word_wrap(use_this_answer, word_wrap_at?) # word-wrap is a value such as 85.
+        use_this_answer.gsub!(/\n/, N+LEFT_PADDING) if use_this_answer.include? N # Also pad these newlines.
+      end
+    end
+    #use_this_colour = ::Colours.send(colour_for_answers?) { :omit_end } if use_colours?
+    # ======================================================================= #
+    # Next we must replace the number-words with the corresponding HTML
+    # colour. So, for instance, <one> will eventually become
+    # <steelblue>.
+    # ======================================================================= #
+    _ = ::Colours.replace_number_words_with_the_corresponding_html_colour(
+          use_this_answer,
+          USE_THESE_COLOURS.merge(default_colour: colour_for_answers?)
+        )
+    result << ::Colours.fancy_parse(_, colour_for_answers?)
+    # if exam_answer.include? 'IMAGE: '
+    #   image_path = exam_answer.scan(/IMAGE: (.+)$/).flatten
+    #   image_path = image_path.first if image_path.is_a? Array
+    #   system("tiv #{image_path}")
+    #   exam_answer.sub!(/IMAGE: (.+)$/, '')
+    # end
+    # ======================================================================= #
+    # === Handle URLs next
+    # ======================================================================= #
+    if use_this_answer.include? ' URL:' # This is the valid form; the check is necessary.
+      # ===================================================================== #
+      # Since as of May 2022, if we are on a roebe-system, we will also
+      # assign to the xorg-buffer next. We have to supply a regex to do
+      # this for us.
+      # ===================================================================== #
+      use_this_regex = /URL: (https?.*)/ # See: https://rubular.com/r/xJfOSCoi0Q7TWS
+      use_this_answer =~ use_this_regex
+      set_xorg_buffer($1.to_s.dup)
+      use_this_answer = assign_url(use_this_answer)
+    # ======================================================================= #
+    # === Handle entries that include the substring ' https://'
+    # ======================================================================= #
+    elsif use_this_answer.include? '  https://'
+      use_this_answer = colourize_https_substring(use_this_answer) if use_colours?
+    end
+    if use_this_answer.include?(' URL:') or use_this_answer.include?('  https://')
+      assign_url_or_colourize_https_substring(use_this_answer) if use_colours?
+    end
+    # ======================================================================= #
+    # === Get rid of (2) and similar numbers
+    #
+    # We assume this to also include (1) and (3) and so forth here.
+    # ======================================================================= #
+    if use_this_answer.include? '(2)'
+      # ===================================================================== #
+      # Do a word wrap if the size range from the part up to the first
+      # '(' is larger than the allowed characters per line.
+      #
+      # Since as of August 2019 we will honour HTML colour-tags though
+      # and add that to the subrange size.
+      # ===================================================================== #
+      subrange = use_this_answer[0 .. (use_this_answer.index('(') - 1)].dup
+      subrange_size = subrange.size
+      if does_this_line_include_a_html_colour?(subrange)
+        subrange_size += return_this_line_has_n_characters_as_html_colour_tags(subrange)
+      end
+      if subrange_size > word_wrap_at?
+        use_this_answer[0 .. (use_this_answer.index('(') - 1)] = ''.dup
+        subrange = word_wrap(subrange, word_wrap_at?).dup+N
+        use_this_answer[0,0] = subrange
+      end
+      12.times { |iteration_number_n|
+        if use_colours
+          # ================================================================= #
+          # Colourize the parens - and also add a leading newline.
+          # ================================================================= #
+          replace_with_this = N+
+                              '  '+
+                              rev+
+                              slategray('(')+
+                              skyblue(iteration_number_n.to_s.chomp)+
+                              slategray(')')
+          use_this_colour = ::Colours.send(colour_for_answers?) { :omit_end }
+          replace_with_this << use_this_colour
+          # ================================================================= #
+          # Then perform a .gsub next:
+          # ================================================================= #
+          result.gsub!(/\(#{iteration_number_n}\)/, replace_with_this)
+        else
+          result.gsub!(/\(#{iteration_number_n}\)/,
+            N+'('+iteration_number_n.to_s+')') # Will add a leading newline.
+        end
+      } # The above is equivalent to the below, by the way:
+        # exam_answer.gsub!(/\(6\)/, N+'(6)')
+    end
+    # ======================================================================= #
+    # Next, consider colourizing all questions that have at the least 2
+    # '"' characters. These will be colourized if a certain constant is
+    # set to true.
+    # ======================================================================= #
+    if EMPHASIZE_WORDS_IN_QUOTES_IN_A_GIVEN_QUESTION and !include_numbers_in_parens
+      if use_colours and commandline? and (use_this_answer.count('"') > 1)
+        use_this_answer = use_this_answer.dup
+        use_this_regex = /"(.+?\s*.*?)"/ # See: https://rubular.com/r/6WK5NjMJld
+        # =================================================================== #
+        # Next make use of the default colour to use.
+        # =================================================================== #
+        use_this_colour = ::Colours.send(colour_for_questions?) { :omit_end }
+        use_this_answer.gsub!(
+          use_this_regex,
+          '"'+forestgreen('\1'.delete(N))+ # forestgreen is the hardcoded colour to be used for now.
+          use_this_colour+'"' 
+        )
+      end
+    end
+    # ======================================================================= #
+    # === Handle entries that are between <ud>foo</ud> tags
+    # ======================================================================= #
+    if line_contains_underline_token?(result) and use_colours?
+      # ===================================================================== #
+      # Colourize <ud> for underline next:
+      # ===================================================================== #
+      result = replace_underline_token_with_default_colour(result).to_s+
+               colour_for_answers?.to_s
+    end
+    # ======================================================================= #
+    # === Handle italic text next
+    # ======================================================================= #
+    if line_contains_italic_token?(result) and use_colours?
+      # ===================================================================== #
+      # Colourize <i> for italic next:
+      # ===================================================================== #
+      append_this = ''.dup
+      if ::Colours.respond_to? use_this_colour.to_sym
+        append_this << ::Colours.send(use_this_colour,'')
+      else
+        append_this << use_this_colour
+      end
+      result = replace_italic_token_with_default_colour(result)+
+               append_this
+    end
+    # ======================================================================= #
+    # === Handle entries that are between <b>foo</b> tags
+    # ======================================================================= #
+    if line_contains_bold_token?(result) and use_colours?
+      # ===================================================================== #
+      # Colourize <b> for bold font-style next:
+      # ===================================================================== #
+      result = replace_bold_token_with_default_colour(result)+
+               use_this_colour
+    end
+    # ======================================================================= #
+    # === Colourize https-links, if we use colours.
+    #     This will also include links to wikipedia.
+    # ======================================================================= #
+    if use_colours? and result.include?('https://') 
+      use_this_regex =
+        /(https:\/\/.+)$/ # See: https://rubular.com/r/drYvZc4a91
+      result.sub!(use_this_regex, mediumaquamarine('\\1'))
+    end
+    if result.include?(' URL:')
+      result.gsub!(/ URL:/, royalblue(' →'))
+    end
+    if result.include? "\n"
+      result = result.split("\n").map {|entry|
+        entry = entry.dup if entry.frozen?
+        entry.lstrip!
+        entry.prepend(padding_to_use) unless entry.start_with?(padding_to_use)
+        entry
+      }.join("\n")
+    end
+    result << "\n\n"
+    # ======================================================================= #
+    # Add a <div> element if we run in www-mode.
+    # ======================================================================= #
+    if www_mode?
+      e '<div id="answer_div">'+N
+      e use_this_answer
+      e "</div>\n"
+    else
+      e "#{result.rstrip}\n\n"
+    end
+  end; alias reveal_the_exam_answer do_reveal_the_answer # === reveal_the_exam_answer
+       alias reveal_the_answer      do_reveal_the_answer # === reveal_the_answer
+       alias show_this_answer       do_reveal_the_answer # === show_this_answer
+       alias show_the_answer        do_reveal_the_answer # === show_the_answer
+       alias show_answer            do_reveal_the_answer # === show_answer
+
+  # ========================================================================= #
+  # === topic_to_use?
+  # ========================================================================= #
+  def topic_to_use?
+    @internal_hash[:topic_to_use]
+  end; alias last_topic?  topic_to_use? # === last_topic?
+       alias topic?       topic_to_use? # === topic?
+       alias topic        topic_to_use? # === topic
+       alias exam_topic?  topic_to_use? # === exam_topic?
+       alias exam_title?  topic_to_use? # === exam_title?
+       alias which_topic? topic_to_use? # === which_topic?
+       alias title        topic_to_use? # === title
+       alias title?       topic_to_use? # === title?
+       alias category?    topic_to_use? # === category?
+
+  # ========================================================================= #
+  # === word_wrap_at?
+  # ========================================================================= #
+  def word_wrap_at?
+    @exam_question.word_wrap_at?
+  end
+
+  # ========================================================================= #
+  # === exam_answer?
+  # ========================================================================= #
+  def exam_answer?
+    @exam_question.answer?
+  end; alias answer? exam_answer? # === answer
+
+  # ========================================================================= #
+  # === colour_for_answers?
+  # ========================================================================= #
+  def colour_for_answers?
+    @internal_hash[:colour_for_answers]
+  end
+
+  # ========================================================================= #
+  # === colour_for_questions?
+  # ========================================================================= #
+  def colour_for_questions?
+    @internal_hash[:colour_for_questions]
+  end
+
+  # ========================================================================= #
+  # === line_contains_underline_token?
+  # ========================================================================= #
+  def line_contains_underline_token?(i)
+    @exam_question.line_contains_underline_token?(i)
+  end
+
+  # ========================================================================= #
+  # === line_contains_italic_token?
+  # ========================================================================= #
+  def line_contains_italic_token?(i)
+    @exam_question.line_contains_italic_token?(i)
+  end
+
+  # ========================================================================= #
+  # === line_contains_bold_token?
+  # ========================================================================= #
+  def line_contains_bold_token?(i)
+    @exam_question.line_contains_bold_token?(i)
+  end
+
+  # ========================================================================= #
+  # === show_line
+  # ========================================================================= #
+  def show_line
+    e exam_question_line?
+  end
+
+  # ========================================================================= #
+  # === append_into_onto_daily_exam_questions_file
+  # ========================================================================= #
+  def append_into_onto_daily_exam_questions_file
+    log_dir = "#{log_dir?}daily_exam_questions/"
+    mkdir(log_dir) unless File.directory?(log_dir)
+    target_file = "#{log_dir}#{dd_mm_yyyy}_daily_exam_questions.md"
+    unless File.exist? target_file
+      append_what_into(
+        '# === Created on '+dd_mm_yyyy+' at '+hh_mm_ss+"\n",
+        target_file
+      )
+    end
+    append_what_into("#{line?}\n", target_file)
+  end
+
+  # ========================================================================= #
+  # === return_the_full_expanded_exam_title
+  # ========================================================================= #
+  def return_the_full_expanded_exam_title(exam_title = exam_title?)
+    return Studium.find_corresponding_exam_title(exam_title)
+  end
+
+  # ========================================================================= #
+  # === n_questions_already_answered?
+  # ========================================================================= #
+  def n_questions_already_answered?
+    @internal_hash[:n_exam_questions_answered]
+  end
+
+  # ========================================================================= #
+  # === set_exam_pool
+  #
+  # The "exam pool" constitutes the available, unanswered exams.
+  #
+  # What this means, essentially, is that every line ending with a '[]'
+  # will be disregarded.
+  # ========================================================================= #
+  def set_exam_pool(i = nil)
+    @internal_hash[:exam_pool] = i
+  end
+
+  # ========================================================================= #
+  # === show_how_many_exam_questions_were_already_solved_in_german
+  #
+  # Similar to the above, except that we will report in german.
+  #
+  # Invocation example:
+  #
+  #   qa --solved-in-german
+  #
+  # ========================================================================= #
+  def show_how_many_exam_questions_were_already_solved_in_german
+    Studium::Exams.report_how_many_exam_questions_were_already_solved(:german)
+  end
+
+  # ========================================================================= #
+  # === generate_statistical_webpage
+  #
+  # Invoke like so:
+  #
+  #   qa --www
+  #
+  # ========================================================================= #
+  def generate_statistical_webpage
+    require 'studium/statistics/report_how_many_exam_questions_were_answered.rb'
+    Studium::Statistics::ReportHowManyExamQuestionsWereAnswered.generate_webpage
+    target = return_pwd+'/Studium/html/statistics.html'
+    open_in_browser(target)
+  end
+
+  # ========================================================================= #
+  # === main_file_exists?
+  # ========================================================================= #
+  def main_file_exists?(
+      i = exam_file?
+    )
+    i and File.exist?(i)
+  end
+
+  # ========================================================================= #
+  # === edit_sanitize_topics_in_vim
+  #
+  # To trigger this, do:
+  #
+  #   qa --vim
+  #
+  # ========================================================================= #
+  def edit_sanitize_topics_in_vim
+    position_in_the_file = 445
+    file =
+      RUBY_STUDIUM_HOME_DIR+'toplevel_methods/find_exam_topic_and_exam_title.rb'
+    _ = 'vim '+file+' +'+position_in_the_file.to_s
+    esystem _
+  end
+
+  # ========================================================================= #
+  # === show_content_of_this_topic
+  #
+  # Invocation example:
+  #
+  #   qa ethik --show-everything
+  #
+  # ========================================================================= #
+  def show_content_of_this_topic(
+      i = topic?
+    )
+    dataset = filter_away_invalid_questions(
+      File.readlines(directory_to_the_exam_topics?+i)
+    )
+    dataset.each {|line|
+      e "  #{simp(line.chomp)}"
+    }
+  end
+
+  # ========================================================================= #
+  # === try_to_save_the_line                                       (save tag)
+  #
+  # This is called whenever the main line is obtained. The original line
+  # is copied, not any modified variant.
+  #
+  # We will store into a file, which is kept at @store_where.
+  #
+  # It usually defaults to the file /Depot/Studium/last_question_asked.md
+  # or wherever else the base-directory has been defined.
+  # ========================================================================= #
+  def try_to_save_the_line(
+      i = line?
+    )
+    _ = store_where? # Where to store.
+    if File.exist?(File.dirname(_))
+      if debug?
+        opne "Now saving: #{bold_blue(i)} into the file #{sfile(_)}"
+      end if commandline?
+      if File.writable?(File.dirname(_)) # Make sure the base-directory is writeable here.
+        write_what_into(i, _) # Save it.
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === set_default_topic_for_the_gui
+  # ========================================================================= #
+  def set_default_topic_for_the_gui(
+      what,
+      into = "#{log_dir?}use_this_exam_topic.yml"
+    )
+    opne "Now setting the default topic to `#{simp(what)}`."
+    write_what_into(what, into)
+  end
+
+  # ========================================================================= #
+  # === tell_whether_we_will_rename_the_kde_konsole_tab
+  # ========================================================================= #
+  def tell_whether_we_will_rename_the_kde_konsole_tab
+    e 'Will we rename the KDE konsole tab? '+
+      simp(
+        VerboseTruth[load_file_rename_konsole_tab.to_s]
+      )
+  end
+
+  # ========================================================================= #
+  # === store_where?
+  # ========================================================================= #
+  def store_where?
+    Studium.file_last_question_asked?
+  end
+
+  # ========================================================================= #
+  # === report_file_does_not_exist
+  # ========================================================================= #
+  def report_file_does_not_exist(
+      this_file = exam_file?
+    )
+    opne "#{rev}No file at `#{sfile(this_file)}` exists."
+  end
+
+  require 'studium/toplevel_methods/set_last_file_for_exam_questions.rb'
+  # ========================================================================= #
+  # === register_last_modified_file
+  # ========================================================================= #
+  def register_last_modified_file(
+      i = exam_file?
+    )
+    Studium.set_last_file_for_exam_questions(i) # , :be_verbose
+  end
+
+  require 'studium/toplevel_methods/n_questions_available.rb'
+  # ========================================================================= #
+  # === show_how_many_exam_questions_are_available
+  #
+  # This method can be called by passing in 'TOTAL' as argument.
+  #
+  # Example:
+  #
+  #   qa TOTAL?
+  #
+  # ========================================================================= #
+  def show_how_many_exam_questions_are_available
+    n_questions = ::Studium.n_questions_available?.to_s
+    result = 'Total amount of registered questions: '.dup
+    if commandline? and use_colours?
+      result << simp(n_questions.to_s)
+    else
+      result << n_questions.to_s
+    end
+    e result
+  end; alias total                        show_how_many_exam_questions_are_available # === total (total tag)
+       alias n_total_questions_available? show_how_many_exam_questions_are_available # === n_total_questions_available?
+
+  # ========================================================================= #
+  # === opnn
+  # ========================================================================= #
+  def opnn
+    super(
+      namespace:   namespace?,
+      use_colours: use_colours?
+    )
+  end
+
+  # ========================================================================= #
+  # === determine_whether_we_will_rename_the_konsole_tab
+  #
+  # This method should be called from within the method called reset().
+  # ========================================================================= #
+  def determine_whether_we_will_rename_the_konsole_tab
+    if is_on_roebe?
+      if File.exist? FILE_RENAME_KONSOLE_TAB
+        _ = load_file_rename_konsole_tab
+        if _ == true
+          do_rename_konsole_tab
+        else
+          do_not_rename_konsole_tab
+        end
+      else
+        do_not_rename_konsole_tab
+      end
+    else
+      do_not_rename_konsole_tab
+    end
+  end
+
+  # ========================================================================= #
+  # === show_last_question_asked
+  #
+  # This will show the last question asked.
+  # ========================================================================= #
+  def show_last_question_asked(
+      i = store_where?
+    )
+    if File.exist? i
+      e File.read(i)
+    end
+  end
+
+  # ========================================================================= #
+  # === consider_renaming_konsole_tab
+  #
+  # We will delegate to class SetTerminalTitle in order to rename the KDE
+  # konsole title.
+  # ========================================================================= #
+  def consider_renaming_konsole_tab
+    if Studium::Exams::AskExamQuestion.rename_konsole_tab?
+      rename_kde_konsole_tab(topic?)
+    end
+  end
+
+  # ========================================================================= #
+  # === do_rename_konsole_tab
+  # ========================================================================= #
+  def do_rename_konsole_tab
+    Studium::Exams::AskExamQuestion.set_rename_konsole_tab(true)
+  end
+  
+  # ========================================================================= #
+  # === do_not_rename_konsole_tab
+  # ========================================================================= #
+  def do_not_rename_konsole_tab
+    Studium::Exams::AskExamQuestion.set_rename_konsole_tab(false)
+  end
+
+  require 'studium/toplevel_methods/download.rb'
+  # ========================================================================= #
+  # === download_exam_topics
+  #
+  # You can use this method to download all exam topics.
+  #
+  # To call this, do:
+  #
+  #   qa --dexamtopics
+  #
+  # ========================================================================= #
+  def download_exam_topics
+    Studium.download_exam_topics
+  end
+
+  # ========================================================================= #
+  # === exam_pool?
+  # ========================================================================= #
+  def exam_pool?
+    @internal_hash[:exam_pool]
+  end
+
+  # ========================================================================= #
+  # === assign_url
+  #
+  # Only call this method after making a line.include? 'URL:' check.
+  # The reason for this is that we will only apply this method on
+  # a line that has this substring representing a remote URL.
+  # ========================================================================= #
+  def assign_url(i)
+    if use_unicode_symbols?
+      nice_token = '➡' # We will use a slightly prettier symbol for Unicode in this case.
+    else
+      nice_token = '=>'
+    end
+    i =~ /URL:\s*(.*)( |)/
+    url = sanitize_url($1.to_s.dup) # URL is something like: "http://de.wikipedia.org/wiki/Ester"
+    url = url.first if url.is_a? Array
+    i = i.dup if i.frozen?
+    begin
+      # ===================================================================== #
+      # The next regex shall also check for input such as:
+      #
+      #   URL: https://en.wikipedia.org/wiki/2,4-Dinitrophenol
+      #   URL: https://en.wikipedia.org/wiki/File:Histidin_-_Histidine.svg
+      #
+      # Since as of 11.11.2018, we also include any other entry that
+      # starts with 'https:'.
+      # ===================================================================== #
+      if $1 # See: https://rubular.com/r/rNeLS2MH6f
+        remote_URL = $1.to_s.dup
+        i.gsub!(/URL:\s*(.*)( |)/, nice_token+' \1') # ← Also add a '=>' token.
+        if is_on_roebe?
+          # ================================================================= #
+          # Store this on my home system in a file, in this case.
+          # ================================================================= #
+          what = "#{remote_URL}\n"
+          into = log_dir?+'last_exam_questions_URL.md'
+          append_what_into(what, into)
+        end
+      end
+      i = i.to_s.dup
+      return i
+    rescue Exception => error
+      e "Debugging for `#{sfancy(i.to_s)}`:"
+      pp error
+      p url.class
+      e sfancy(url)
+    end
+  end
+
+  # ========================================================================= #
+  # === open_the_last_file_via_your_editor
+  # ========================================================================= #
+  def open_the_last_file_via_your_editor(
+      this_file = last_file?
+    )
+    open_this_file_in_editor(this_file)
+  end
+
+  # ========================================================================= #
+  # === open_this_file_in_editor
+  #
+  # Open this file in the editor.
+  # ========================================================================= #
+  def open_this_file_in_editor(
+      this_file = __FILE__
+    )
+    use_this_editor = editor?
+    # ======================================================================= #
+    # Since as of December 2017, on my home system, I will use nano instead.
+    # ======================================================================= #
+    use_this_editor = 'nano -w' if is_on_roebe?
+    _ = "#{use_this_editor} #{this_file}" #&
+    esystem _
+  end
+
+  # ========================================================================= #
+  # === notify_the_user_that_all_questions_have_been_answered_already
+  # ========================================================================= #
+  def notify_the_user_that_all_questions_have_been_answered_already(
+      which_topic = which_topic?
+    )
+    opne 'All questions have already been answered '
+    opne "for the topic `#{orange(which_topic)}`. "\
+         "#{slateblue(cheering_person?)}"
+  end
+
+  # ========================================================================= #
+  # === custom_colours?
+  # ========================================================================= #
+  def custom_colours?
+    [
+      @internal_hash[:colour_for_questions],
+      @internal_hash[:colour_for_answers]
+    ]
+  end
+
+  # ========================================================================= #
+  # === show_filesize_of_all_exams
+  #
+  # To call this method, do:
+  #
+  #   qa --filesize?
+  #
+  # ========================================================================= #
+  def show_filesize_of_all_exams
+    this_exam_topic = directory_of_the_exam_topics?
+    all_filesizes = Dir["#{this_exam_topic}*"].map {|entry|
+      File.size?(entry)
+    }
+    sum = all_filesizes.sum
+    sum_in_kb = sum / 1000.0
+    sum_in_mb = sum_in_kb / 1000.0
+    e "#{rev}The total file size of all exams in "\
+      "#{sdir(this_exam_topic)} is:"
+    e
+    e '  '+simp(sum.to_s)+
+      ' Bytes ('+
+      sfancy(sum_in_mb.round(2).to_s)+' MB)'
+    e
+  end
+
+  # ========================================================================= #
+  # === colourize_https_substring
+  #
+  # Input that passes into the following method, can look like this:
+  #
+  #   'Das "CDT-Toxin". => https://www.ncbi.nlm.nih.gov/pubmed/24253566'
+  #
+  # ========================================================================= #  
+  def colourize_https_substring(i)
+    if i.include? 'https://'
+      use_this_regex = /(https:\/\/.+)/ # See: https://rubular.com/r/4quDI8hKxS
+      i =~ use_this_regex
+      i.gsub!(use_this_regex, slateblue('\1')) if $1
+    end
+    return i
+  end
+
+  # ========================================================================= #
+  # === assign_url_or_colourize_https_substring
+  # ========================================================================= #
+  def assign_url_or_colourize_https_substring(i)
+    if i.include?(' URL:')
+      assign_url(i)
+    elsif i.include?('  https://')
+      colourize_https_substring(i)
+    end
+  end
+
+  # ========================================================================= #
+  # === menu_on_the_commandline_as_a_string
+  # ========================================================================= #
+  def menu_on_the_commandline_as_a_string(
+      i = commandline_as_string
+    )
+    case i
+    # ======================================================================= #
+    # === qa --open
+    #
+    # This entry point can be used to open an exam topic file via the
+    # editor.
+    #
+    # A commandline example follows:
+    #
+    #   qa ab2 open
+    #
+    # ======================================================================= #
+    when /open (.+)/,
+         /(.+) open/
+      topic = $1.to_s.dup # Example: qa --open amg
+      topic = find_corresponding_exam_topic(topic)
+      topic = ::Studium.directory_to_my_exam_topics+File.basename(topic)
+      open_this_file_in_editor(topic)
+      exit
+    # ======================================================================= #
+    # === qa "delay = 3.0"
+    #
+    # Invoke this like so:
+    #
+    #   qa delay = 3.0
+    #
+    # ======================================================================= #
+    when /^DELAY =? ?(\d{0,1}.\d{1})/i,
+         /^DEL =? ?(\d{0,1}.\d{1})/i,
+         /^set_delay =? ?(\d{0,1}.\d{1})/i,
+         /^set_delay :? ?(\d{0,1}.\d{1})/i,
+         /^set_delay ?(\d{0,1}.\d{1})/i # === qa set_delay 3.1
+      _ = $1.to_s.dup
+      set_and_store_delay(_)
+    end
+  end
+
+  # ========================================================================= #
+  # === exam_file?
+  #
+  # This query-method shows as to where the specific file at hand is.
+  # ========================================================================= #
+  def exam_file?
+    @internal_hash[:exam_file]
+  end; alias file?       exam_file? # === file?
+       alias which_file? exam_file? # === which_file?
+
+  # ========================================================================= #
+  # === report_how_many_topics_are_available
+  # ========================================================================= #
+  def report_how_many_topics_are_available
+    opne 'There are exactly '+
+         simp(Studium.available_topics?.size.to_s)+
+         ' topics available.'
+  end
+
+  # ========================================================================= #
+  # === may_we_show_the_topic?
+  # ========================================================================= #
+  def may_we_show_the_topic?
+    @internal_hash[:may_we_show_the_topic]
+  end; alias may_we_show_the_topic may_we_show_the_topic? # === may_we_show_the_topic
+
+  # ========================================================================= #
+  # === set_may_we_show_the_topic
+  # ========================================================================= #
+  def set_may_we_show_the_topic(i = MAY_WE_SHOW_THE_TOPIC)
+    @internal_hash[:may_we_show_the_topic] = i
+  end; alias may_we_show_the_topic= set_may_we_show_the_topic # === may_we_show_the_topic=
+       alias set_show_topic         set_may_we_show_the_topic # === set_show_topic
+    
+  # ========================================================================= #
+  # === set_colour_for_questions
+  # ========================================================================= #
+  def set_colour_for_questions(i)
+    @internal_hash[:colour_for_questions] = i.to_sym
+  end
+
+  # ========================================================================= #
+  # === set_colour_for_answers
+  # ========================================================================= #
+  def set_colour_for_answers(i)
+    @internal_hash[:colour_for_answers] = i.to_sym
+  end
+
+  # ========================================================================= #
+  # === exam_question?
+  # ========================================================================= #
+  def exam_question?
+    @exam_question.question?
+  end; alias question? exam_question? # === question?
+
+  # ========================================================================= #
+  # === show_the_last_topic
+  #
+  # Invocation example:
+  #
+  #   qa --show-last-topic
+  #
+  # ========================================================================= #
+  def show_the_last_topic(
+      _ = Studium.file_last_topic?
+    )
+    if File.exist? _
+      e "#{rev}The last topic was `"+
+         simp(
+           expand_topic(File.read(_).chomp)
+         )+'`.'
+    else
+      opnn; no_file_exists_at(_.to_s)
+    end
+  end
+
+  # ========================================================================= #
+  # === store_delay                                               (store tag)
+  #
+  # This method will store/save the delay into a file.
+  # ========================================================================= #
+  def store_delay(i)
+    Studium.save_this_delay_between_questions_and_answers(i)
+  end
+
+  # ========================================================================= #
+  # === load_file_rename_konsole_tab
+  # ========================================================================= #
+  def load_file_rename_konsole_tab
+    YAML.load_file(FILE_RENAME_KONSOLE_TAB)
+  end
+
+  # ========================================================================= #
+  # === set_all_questions_from_the_topic_to_solved
+  #
+  # This will solve all questions from a given topic.
+  #
+  # Invocation example:
+  #
+  #   qa ALL_SOLVED
+  #
+  # ========================================================================= #
+  def set_all_questions_from_the_topic_to_solved
+    if commandline?
+      require 'studium/exams/solve_all_questions_from_this_topic.rb'
+      this_topic = which_topic?
+      e "#{rev}Setting all questions from the topic "\
+        "#{sfancy(this_topic)} to solved."
+      Studium::SolveAllQuestionsFromThisTopic.new(this_topic)
+    end
+  end
+
+  # ========================================================================= #
+  # === report_this_error
+  # ========================================================================= #
+  def report_this_error(error = nil)
+    opne 'We encountered an '+swarn('error')+
+          '. The @index_position was probably '\
+          'out of range.'
+    opne 'Feedbacking @line next:'
+    pp line?
+    opne "Feedbacking #{royalblue('the split position')} next:"
+    pp split_position?
+    if error
+      pp error
+      pp error.class
+    end
+  end
+
+  # ========================================================================= #
+  # === report_how_many_registered_questions_are_available
+  # ========================================================================= #
+  def report_how_many_registered_questions_are_available(
+      n_questions = ::Studium.n_questions_available?
+    )
+    opne "#{rev}There are #{simp(n_questions.to_s)} registered "\
+         "questions available."
+  end
+
+  # ========================================================================= #
+  # === show_how_many_exam_questions_were_already_solved
+  #
+  # Use this method to show how many exam questions were already solved.
+  #
+  # To invoke this method, do:
+  #
+  #   qa SOLVED?
+  #
+  # Or in code, do:
+  #
+  #   Studium::Exams.report_how_many_exam_questions_were_already_solved
+  #
+  # ========================================================================= #
+  def show_how_many_exam_questions_were_already_solved
+    Studium.report_how_many_exam_questions_were_already_solved
+  end
+
+  # ========================================================================= #
+  # === report_whether_we_will_show_the_topic
+  # ========================================================================= #
+  def report_whether_we_will_show_the_topic
+    opne 'Will we show the topic of the exams when '\
+         'asking a question: '+
+         simp(VerboseTruth[may_we_show_the_topic?])
+  end
+
+  # ========================================================================= #
+  # === consider_warning_the_user_if_there_are_too_many_exams_registered
+  #
+  # The threshold value of n exam questions at maximum is at 1000
+  # usually.
+  # ========================================================================= #
+  def consider_warning_the_user_if_there_are_too_many_exams_registered(
+      threshold_value = THRESHOLD_VALUE_N_EXAMS_AT_MAXIMUM
+    )
+    if WARN_THE_USER_IF_THERE_ARE_TOO_MANY_QUESTIONS_REGISTERED_IN_AN_EXAM_TOPIC and
+      # ===================================================================== #
+      # Check if we have more questions than we are allowed to have.
+      # ===================================================================== #
+      (n_exam_questions? > threshold_value)
+      e
+      opne swarn('Do note that there are too many exam questions '\
+           'registered in the file:')
+      e
+      e "  #{sfile(which_file?)}"
+      e
+    end
+  end
+
+  # ========================================================================= #
+  # === line?
+  #
+  # Delegate onto class ExamQuestion here.
+  # ========================================================================= #
+  def line?
+    @exam_question.line?
+  end
+
+  # ========================================================================= #
+  # === delay?
+  # ========================================================================= #
+  def delay?
+    @internal_hash[:delay]
+  end; alias delay delay? # === delay
+
+  # ========================================================================= #
+  # === report_the_default_topic_in_use
+  #
+  # This method will report the default topic in use. We must also check
+  # whether the file in questions exists, before proceeding.
+  #
+  # To invoke this, do:
+  #
+  #   qa --default-topic?
+  #
+  # ========================================================================= #
+  def report_the_default_topic_in_use(
+      this_file = "#{log_dir?}use_this_exam_topic.yml"
+    )
+    if File.exist? this_file
+      topic = File.read(this_file).chomp
+      e "The default topic in use is: #{simp(topic)}"
+    else
+      e "#{rev}No file exists at `#{sfile(this_file)}`. This "\
+        "means that"
+      e 'no default topic has been set.'
+      e
+      e 'If you wish to designate a default topic, use this invocation:'
+      e
+      e steelblue('  qa --set_default_topic=amg')
+      e steelblue('  qa --set_default_topic=phys')
+      e
+    end
+  end
+
+  # ========================================================================= #
+  # === menu                                                       (menu tag)
+  #
+  # This is the main menu-interface of this class, the part of the code
+  # where we take the commandline (if the user has done so) and evaluate
+  # what is to be done.
+  #
+  # By default, we will assume that the user has not given any special 
+  # instructions, hence why the default argument is nil.
+  #
+  # Next we show some usage examples:
+  #
+  #   qa "delay = 3.0"
+  #   qa delay?
+  #
+  # ========================================================================= #
+  def menu(
+      i = commandline_arguments?
+    )
+    if i.is_a? Array
+      i.each {|entry| menu(entry) }
+    else
+      case i # case tag
+      # ===================================================================== #
+      # === qa amg1 --also-ask-from-solved-questions
+      # === qa amg1 --full-pool
+      # === qa amg1 --all-questions
+      # === qa amg1 --everything
+      #
+      # This entry point allows us to pick a random question from ALL
+      # questions of the given example theme, not only from the pool
+      # that does not end with a trailing "[]".
+      #
+      # And yet another usage example:
+      #
+      #   qa agrarmarkt --full
+      #
+      # ===================================================================== #
+      when /^-?-?also(-|_| )?ask(-|_| )?from(-|_| )?solved(-|_| )?questions$/i,
+           /^-?-?full(-|_| )?pool$/i,
+           /^-?-?full$/i,
+           /^-?-?all(-|_| )?questions$/i,
+           /^-?-?everything$/i
+        @internal_hash[:reject_lines_that_end_with_a_done_token] = false
+      # ===================================================================== #
+      # === qa --last-question?
+      # ===================================================================== #
+      when 'LAST?', # qa LAST_QUESTION?
+           /^-?-?last$/,
+           /^-?-?last(_|-)?question\??$/i
+        show_last_question_asked
+        exit_program
+      # ===================================================================== #
+      # === qa --total?
+      # ===================================================================== #
+      when /^-?-?TOTAL\??$/i # qa TOTAL?
+        show_how_many_exam_questions_are_available
+        exit_program
+      # ===================================================================== #
+      # === SHOW_ALL
+      #
+      # Invocation example:
+      #
+      #   qa ethik --show-all
+      #
+      # ===================================================================== #
+      when /^-?-?show(_|-)?all$/i,
+           /^-?-?show(_|-)?everything$/i
+        show_content_of_this_topic(topic?)
+        exit
+      # ===================================================================== #
+      # === qa --n-topics
+      # ===================================================================== #
+      when /^-?-?n(_|-)?topics$/i # qa N_TOPICS
+        report_how_many_topics_are_available
+        exit_program
+      # ===================================================================== #
+      # === qa --show-statistics
+      # ===================================================================== #
+      when /^-?-?show(_|-| )?statistics/i
+        show_statistics
+        exit_program
+      # ===================================================================== #
+      # === qa --filesize?
+      # ===================================================================== #
+      when /^-?-?size\??/i,
+           /^-?-?filesize\??/i
+        show_filesize_of_all_exams
+        exit
+      # ===================================================================== #
+      # === qa --show-topic?
+      # ===================================================================== #
+      when /^-?-?show(_|-| )?topic\??/i
+        report_whether_we_will_show_the_topic
+        exit_program
+      # ===================================================================== #
+      # === qa --upload_exams
+      # ===================================================================== #
+      when 'examtopics?',
+           'upload_exam_topics',
+           /^upload_?exams/,
+           'uexams',
+           'uexam'
+        Studium.upload_exam_questions { :be_verbose }
+      # ===================================================================== #
+      # === qa ALL_SOLVED
+      #
+      # This entry point will mark all questions from a particular topic
+      # to "solved", that is, to have been answered already.
+      #
+      # Usage example:
+      #
+      #   qa agrarmarkt --all-solved
+      #
+      # ===================================================================== #
+      when /^-?-?all(-|_| )?solved$/i
+        set_all_questions_from_the_topic_to_solved
+        exit
+      # ===================================================================== #
+      # === qa --nquestions?
+      # ===================================================================== #
+      when /^-?-?n(_|-| )?questions\??$/i
+        report_how_many_registered_questions_are_available
+        exit
+      # ===================================================================== #
+      # === qa OPEN
+      #
+      # This entry point exists to edit this file here.
+      # ===================================================================== #
+      when 'OPEN',
+           'OPENALL',
+           'OALL',
+           /^-?-?open$/
+        open_this_file_in_editor
+        exit_program
+      # ===================================================================== #
+      # === qa --ask_last_topic
+      # ===================================================================== #
+      when /^-?-?ask(_|-)?last(_|-)?topic$/
+        target_file = "#{log_dir?}use_this_exam_topic.yml"
+        if File.exist? target_file
+          use_this_topic = YAML.load_file(
+            target_file
+          )
+          set_use_this_topic(use_this_topic)
+        else
+          no_file_exists_at(target_file)
+        end
+        exit_program
+      # ===================================================================== #
+      # === qa ftp
+      # ===================================================================== #
+      when 'ftp',
+           /^ftp(_|-)?upload$/
+        Studium.upload_exam_questions { :be_verbose }
+        exit_program
+      # ===================================================================== #
+      # === qa EDIT
+      # ===================================================================== #
+      when /^-?-?edit$/i,
+           /^-?-?vim$/i
+        edit_sanitize_topics_in_vim
+        exit_program
+      # ===================================================================== #
+      # === qa --set_default_topic=phys
+      # ===================================================================== #
+      when /^-?-?set_default_topic=(.+)/,
+           /^-?-?set-default-topic=(.+)/,
+           /^-?-?topic=(.+)/,
+           /^-?-?setdefaulttopic=(.+)/
+        set_default_topic_for_the_gui($1.to_s)
+        exit
+      # ===================================================================== #
+      # === qa --rename-tab?
+      # ===================================================================== #
+      when 'rename_tab?',
+           '--rename-tab?',
+           'renametab',
+           'renametab?' # qa rename_tab?
+        tell_whether_we_will_rename_the_kde_konsole_tab
+        exit_program
+      # ===================================================================== #
+      # === qa --download-exam-topics
+      # ===================================================================== #
+      when /download_?exam_?topics/,
+           /((_|-)+(_|-)+download(_|-)+exam(_|-)+topics)/,
+           /^-?-?dexamtopics/
+        download_exam_topics
+      # ===================================================================== #
+      # === qa --delay?
+      # ===================================================================== #
+      when 'del?',
+           'DELAY?',
+           'speed?', # qa delay?
+           'del',
+           /^-?-?delay\??$/i
+        report_the_delay
+        exit_program(:no_newline)
+      # ===================================================================== #
+      # === qa LASTTOPIC
+      # ===================================================================== #
+      when /^-?-?last(_|-)?topic$/i,
+           /^-?-?show(_|-)?last(_|-)?topic$/i,
+           'ltopic?'
+        show_the_last_topic
+        exit
+      # ===================================================================== #
+      # === qa --set-delay=2.8
+      # ===================================================================== #
+      when /^-?-?set(-|_| )?delay=(.+)/
+        set_and_store_delay($2.to_s.dup)
+        exit
+      # ===================================================================== #
+      # === qa --www
+      # ===================================================================== #
+      when /^-?-?www$/i
+        generate_statistical_webpage
+        exit
+      # ===================================================================== #
+      # === qa --finished?
+      # ===================================================================== #
+      when /^-?-?finished\??$/i
+        show_all_finished_exam_topics
+        exit
+      # ===================================================================== #
+      # === qa --help?
+      # ===================================================================== #
+      when 'HELP',
+           'help',
+           '--help',
+           '--hep',
+           '--help?',
+           'help?'
+        show_help_usage(:do_exit)
+      # ===================================================================== #
+      # === ptype --openlast
+      # ===================================================================== #
+      when /^OPEN(_|-)?LAST$/i,
+           /^OLAST$/i
+        open_the_last_file_via_your_editor
+        exit
+      # ===================================================================== #
+      # === qa --german?
+      # ===================================================================== #
+      when 'SOLVED_GERMAN?',
+           'german',
+           'german?',
+           'in_german?',
+           'n_solved_in_german?',
+           'nsolved2?',
+           'n_german?',
+           '--german?',
+           /^-?-?solved(_|-)?in(_|-)?german$/i
+        show_how_many_exam_questions_were_already_solved_in_german
+        exit_program
+      # ===================================================================== #
+      # === qa --nsolved?
+      # ===================================================================== #
+      when /SOLVED/,
+           'N_SOLVED?',
+           'n_solved?',
+           '--nsolved?',
+           '--nsolved',
+           'nsolved',
+           '--english?',
+           '--english',
+           'english',
+           'english?'
+        show_how_many_exam_questions_were_already_solved
+        exit_program
+      # ===================================================================== #
+      # === qa --log-dir?
+      #
+      # This entry point would tell us that the log directory output is at
+      # e. g. "/home/x/Temp/studium/".
+      # ===================================================================== #
+      when /^-?-?log\??$/i,
+           /^-?-?log(-|_| )?dir\??$/i,       # === qa log-dir?
+           /^-?-?store(-|_| )?where\??$/i,
+           /^-?-?dir\??$/i
+        e "#{rev}The log directory can be found at: #{sdir(log_dir?)}"
+        exit
+      # ===================================================================== #
+      # === qa --all-topics?
+      #
+      # Entry point for showing all available exam-topics:
+      #
+      #   qa --show_topics
+      #
+      # ===================================================================== #
+      when /^-?-?ALL/,
+           /^-?-?TOPICS/,
+           /^-?-?available(_|-)?topics\??$/i,
+           /^-?-?topics\??$/i,
+           /^-?-?show(_|-)?topics$/i,
+           /^-?-?all(_|-)?topics$/i,
+           /^-?-?ALL(-|_| )?TOPICS$/i,
+           /^-?-?all(-|_| )?topics\??$/i,
+           /^-?-?all(-|_| )?topics\??$/i,
+           /^-?-?show(-|_| )?available(-|_| )?topics$/i,
+           /^-?-?show(-|_| )?all(-|_| )?exam(-|_| )?topics$/i,
+           'detailed_topic'
+        show_available_topics # This also includes an exit-step.
+        exit
+      # ===================================================================== #
+      # === qa --default-topic?
+      # ===================================================================== #
+      when /^-?-?default(_|-)?topic\??$/i
+        report_the_default_topic_in_use
+        exit
+      else
+        if ::Studium.is_this_an_exam_topic?(i)
+          set_exam_topic(i)
+        end
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === show_all_finished_exam_topics
+  #
+  # To invoke this method, do:
+  #
+  #   qa --finished?
+  #
+  # ========================================================================= #
+  def show_all_finished_exam_topics
+    stats = Studium::Statistics::ReportHowManyExamQuestionsWereAnswered.new {
+      :do_not_show_the_result
+    }.internal_dataset
+    e "#{rev}The following topics are completely answered "\
+      "(#{colourize_percentage('100%')} answered ratio)."
+    array_finished_topics = []
+    stats.select {|key, value|
+      percentage = value[:percentage_of_questions_answered]
+      if percentage == 100.0
+        array_finished_topics << ::Studium.beautify_this_topic(key)
+      end
+    }
+    e
+    array_finished_topics.each {|topic|
+      e "  #{simp(topic)} is completely answered."
+    }
+    e
+  end
+
+  # ========================================================================= #
+  # === show_help_usage                                            (help tag)
+  #
+  # We show help usage of this class here via this method. It is typically
+  # used from the commandline.
+  #
+  # To show this help message, use this:
+  #
+  #   qa --help
+  #
+  # ========================================================================= #
+  def show_help_usage(
+      then_exit = false
+    )
+    case then_exit
+    # ======================================================================= #
+    # === :do_exit
+    # ======================================================================= #
+    when :do_exit,
+         :exit
+      then_exit = true
+    end
+    opne "Currently the following extra commands can be issued:#{N}#{N}"
+    lpad = ' ' * 4
+    e "#{lpad}--set_default_topic= #{yellow('   Set a default topic.')}"
+    e lpad+'TOPICS '+
+        yellow('                 List all available topics.')
+    e lpad+'TOTAL '+
+        yellow("                  Show how many questions are known in total.")
+    e lpad+'FINISHED '+
+        yellow('               Show which topics are '\
+        'completely finished (100% answered).')
+    e lpad+'EDIT '+
+        yellow('                   To edit the exam questions '\
+        'file, via vim.')
+    e lpad+'LAST_TOPIC '+
+        yellow('             Show the last topic used.')
+    e lpad+'BLOCK '+
+        yellow('                  List all questions that '\
+        'were already answered for a given section.')
+    e lpad+'OPEN '+
+        yellow('                   Open this file here in an editor.')
+    e lpad+'--download-exam-topics '+
+        yellow(' Download the exam topics.')
+    e lpad+'--all-questions        '+
+        yellow(' Ask all questions, including those marked '\
+        'with a trailing "[]".')
+    e lpad+'delay? '+
+        yellow('                 show the default delay.')
+    e lpad+"'delay = 5' "+
+        yellow('            to set a new delay to 5 seconds.')
+    e lpad+"'set-delay = 5' "+
+        yellow('        to set a new delay '\
+        'to 5 seconds. (as ^^^ above)')
+    if is_on_roebe? # Show more options only on my system.
+      e lpad+'rename_tab? '+
+        yellow('            whether to rename the KDE konsole tab or not.')
+      e lpad+'rename_tab: true'+
+        yellow('        enable renaming of the KDE konsole tab.')
+      e lpad+'rename_tab: false'+
+        yellow('       disable rename of the KDE konsole tab.')
+    end
+    e
+    exit if then_exit
+  end
+
+  # ========================================================================= #
+  # === report_the_delay
+  # ========================================================================= #
+  def report_the_delay
+    e "#{rev}The delay is set to: #{sfancy(delay?.to_s)}"
+  end
+
+  # ========================================================================= #
+  # === set_and_store_delay
+  #
+  # Combine two methods in one here.
+  # ========================================================================= #
+  def set_and_store_delay(i)
+    set_delay(i)
+    store_delay(i)
+  end
+
+  # ========================================================================= #
+  # === read_delay_from_file                                     (load delay)
+  #
+  # Use this method here, read_delay_from_file(), to read in the
+  # default delay from a stored file.
+  # ========================================================================= #
+  def read_delay_from_file
+    if File.exist? DELAY_CONSTANT_STORED_HERE
+      _ = YAML.load_file(DELAY_CONSTANT_STORED_HERE)
+      result = _['delay']
+    else # Else the file does not exist, so we use the default delay.
+      result = DEFAULT_DELAY
+    end
+    return result
+  end
+
+  # ========================================================================= #
+  # === sanitize_the_obtained_dataset                         (sanitized tag)
+  #
+  # This method exists primarily to remove all trailing "\n", and then
+  # remove all [] entries, as well as show how many exam questions are
+  # in that given file.
+  # ========================================================================= #
+  def sanitize_the_obtained_dataset
+    dataset = dataset?.map {|entry| entry.strip }
+    set_dataset(dataset)
+    # ======================================================================= #
+    # === :n_exam_questions_in_total
+    #
+    # Keep a record of the total number of exam questions here.
+    # ======================================================================= #
+    @internal_hash[:n_exam_questions_in_total] = dataset.size
+    _ = dataset.reject {|line|
+      line.rstrip.end_with? '[]'
+    }
+    if _ # Keep track of the unanswered exam questions here.
+      set_exam_pool(_)
+      # ===================================================================== #
+      # === :n_exam_questions_unanswered
+      # ===================================================================== #
+      @internal_hash[:n_exam_questions_unanswered] = _.size
+      # ===================================================================== #
+      # === :n_exam_questions_answered
+      # ===================================================================== #
+      @internal_hash[:n_exam_questions_answered]   = (
+        @internal_hash[:n_exam_questions_in_total] - _.size
+      )
+    end
+  end
+
+  # ========================================================================= #
+  # === fancy_cliner
+  #
+  # Since as of April 2022 this method can also optionally display some
+  # content. If this is the case then said content will be padded
+  # via '*'.
+  # ========================================================================= #
+  def fancy_cliner(
+      optional_content_to_be_displayed = nil,
+      use_this_as_the_separator_token  = separator_token_to_be_used?
+    )
+    print seagreen('') # Always reset the colour here first.
+    if optional_content_to_be_displayed
+      e mediumaquamarine(use_this_as_the_separator_token * 3)+' '+
+        forestgreen( # or lightskyblue
+          optional_content_to_be_displayed
+        )+
+        ' '+
+        mediumaquamarine(
+          use_this_as_the_separator_token * (75 - optional_content_to_be_displayed.size)
+        )
+    else
+      cliner(use_this_as_the_separator_token, :mediumaquamarine)
+    end
+  end
+
+  # ========================================================================= #
+  # === determine_the_exam_topic
+  #
+  # This variant also stores the exam-topic into a file, unless we are
+  # using the www-variant of this class.
+  # ========================================================================= #
+  def determine_the_exam_topic
+    _ = first_non_hyphen_argument?
+    set_exam_topic_to_use(
+      find_corresponding_exam_topic(_)
+    )
+    store_last_topic_into_file unless in_www_mode?
+  end; alias determine_the_topic determine_the_exam_topic # === determine_the_topic
+
+  # ========================================================================= #
+  # === set_topic_to_use
+  #
+  # This method has to store the expanded topic name, so that something
+  # like "bioanalytik" is actually turned into
+  # "bioanalytik_und_biosensoren". The method that handles this part is
+  # Studium.find_corresponding_exam_topic(). Usage example for this:
+  #
+  #   x = Studium.find_corresponding_exam_topic('bioanalytik') # => "bioanalytik_und_biosensoren"
+  #
+  # Whenever a topic is set through this method, this will also be stored
+  # into a file. This then allows us to query what the last topic was, e.
+  # g. via "qa --last_topic?".
+  # ========================================================================= #
+  def set_topic_to_use(
+      i = first_non_hyphen_argument?
+    )
+    i = i.first if i.is_a? Array
+    # ======================================================================= #
+    # === Handle Hashes
+    #
+    # If a Hash is given then we will try to find a specific key in that
+    # Hash.
+    # ======================================================================= #
+    if i.is_a?(Hash) and i.has_key?(:use_this_topic)
+      i = i[:use_this_topic]
+    end
+    case i
+    # ======================================================================= #
+    # === :random
+    #
+    # We fetch a random topic via this entry-point.
+    # ======================================================================= #
+    when :random,
+         :random_topic,
+         :default,
+         'fetch_a_random_topic',
+         'random_topic',
+         'random',
+         'rand',
+         '',
+         nil
+      i = Studium.random_exam_topic
+    # ======================================================================= #
+    # === molbio
+    #
+    # This entry point is special.
+    # ======================================================================= #
+    when 'molbio',
+         'molekularbiologie',
+         'molbio?'
+      i = 'amg|amg2|genex1|gentech1|gentech2|pcr'
+    # ======================================================================= #
+    # === OLAST
+    #
+    # Invocation example:
+    #
+    #   qa olast
+    #
+    # ======================================================================= #
+    when /^qlast$/i,
+         /^olast$/i # === olast tag
+      _ = Studium.file_last_topic?
+      if File.exist? _
+        i = File.read(_).strip
+      else
+        opnn; no_file_exists_at(_)
+        exit
+      end
+    end
+    i = i.to_s.dup # Work with a non-frozen String past this point.
+    # ======================================================================= #
+    # If the input has a '|', we assume that the user wants to randomly
+    # pick one entry.
+    # ======================================================================= #
+    if i.include? '|'
+      i = i.split('|').shuffle
+    end
+    i.tr!(' ','_') if i.include? ' '
+    i.downcase! # Convention is to store the file downcased.
+    # ======================================================================= #
+    # Before we do the real assignment, we will sanitize this through
+    # the Studium.find_corresponding_exam_topic "filter".
+    # ======================================================================= #
+    if Studium.is_this_a_registered_exam_topic?(i)
+      i = Studium.find_corresponding_exam_topic(i)
+    else
+      opne "Not a registered exam topic: #{i}" if be_verbose?
+    end
+    @internal_hash[:topic_to_use] = i
+    # ======================================================================= #
+    # Next we will store the topic into a file, unless we are in www-mode.
+    # We may have to lift this restriction eventually, though.
+    # ======================================================================= # 
+    unless in_www_mode?
+      store_last_topic_into_file(i)
+    end
+  end; alias set_exam_topic        set_topic_to_use # === set_exam_topic
+       alias set_exam_topic_to_use set_topic_to_use # === set_exam_topic_to_use
+       alias set_this_topic        set_topic_to_use # === set_this_topic
+
+  # ========================================================================= #
+  # === try_to_read_in_the_dataset_from_the_corresponding_exam_file
+  # ========================================================================= #
+  def try_to_read_in_the_dataset_from_the_corresponding_exam_file(
+      _ = exam_topics_directory?+
+          topic?.to_s
+    )
+    if File.exist? _
+      # ===================================================================== #
+      # Keep track of where the exam-file can be found.
+      # ===================================================================== #
+      set_exam_file(_)
+      dataset = read_in_exam_dataset_from_this_file(_)
+      set_dataset_from_the_file(dataset)
+    else
+      report_file_does_not_exist(_)
+    end
+  end
+
+  # ========================================================================= #
+  # === ask_the_question_then_sleep_then_reveal_the_answer_to_that_question
+  # ========================================================================= #
+  def ask_the_question_then_sleep_then_reveal_the_answer_to_that_question
+    # ======================================================================= #
+    # First warn the user if there are too many exams registered. This
+    # should be shown after the topic has been optionally displayed.
+    # Afterwards we will begin to ask the exam-question at hand.
+    # ======================================================================= #
+    consider_warning_the_user_if_there_are_too_many_exams_registered
+    # Store it into @internal_hash[:dataset_from_the_file].
+    store_relevant_information_pertaining_to_the_last_exam_question_asked
+    # ======================================================================= #
+    # First, handle the commandline situation:
+    # ======================================================================= #
+    if commandline?
+      consider_renaming_konsole_tab # Consider renaming the konsole tab first.
+      print return_either_grey_or_the_custom_colour_for_questions
+      # ===================================================================== #
+      # === Show the topic if the user requested us to do so. Since as of
+      #     April 2022 this is now embedded into the cliner-result.
+      # ===================================================================== #
+      if may_we_show_the_topic?
+        fancy_cliner(
+          Studium.find_corresponding_exam_title(exam_title?, be_verbose?)
+        )
+        e
+      else
+        fancy_cliner
+      end
+    end
+    do_ask_the_question # Ask the exam question here.
+    sleep_default_delay
+    determine_whether_there_are_numbers_in_parens_in_the_answer
+    do_reveal_the_answer
+  end; alias ask_question_then_show_the_answer_after_a_delay    ask_the_question_then_sleep_then_reveal_the_answer_to_that_question # === ask_question_then_show_the_answer_after_a_delay
+       alias do_ask_a_random_question_before_showing_the_answer ask_the_question_then_sleep_then_reveal_the_answer_to_that_question # === ask_question_then_show_the_answer_after_a_delay
+       alias show_question_then_sleep_then_show_answer          ask_the_question_then_sleep_then_reveal_the_answer_to_that_question # === show_question_then_sleep_then_show_answer
+       alias ask_sleep_show                                     ask_the_question_then_sleep_then_reveal_the_answer_to_that_question # === ask_sleep_show
+       alias ask_the_question_then_reveal_the_answer            ask_the_question_then_sleep_then_reveal_the_answer_to_that_question # === ask_the_question_then_reveal_the_answer
+
+  # ========================================================================= #
+  # === determine_whether_there_are_numbers_in_parens_in_the_answer
+  # ========================================================================= #
+  def determine_whether_there_are_numbers_in_parens_in_the_answer
+    _ = exam_answer?
+    if _.include?('(2)') and _.include?('(1)') # We also have to check for (1)
+      # ===================================================================== #
+      # at the same time, because some answers to exam questions contain
+      # just a "(2)" without a corresponding "(1)".
+      # ===================================================================== #
+      @internal_hash[:numbers_in_parens] = true
+    end
+  end
+
+  # ========================================================================= #
+  # === n_questions_available?
+  #
+  # Return how many questions are available in the given dataset at hand.
+  # ========================================================================= #
+  def n_questions_available?
+    @internal_hash[:n_exam_questions_in_total]
+  end; alias n_exam_questions? n_questions_available? # === n_exam_questions?
+       alias n_questions?      n_questions_available? # === n_questions?
+
+  # ========================================================================= #
+  # === ensure_that_the_directory_for_the_daily_questions_exists
+  # ========================================================================= #
+  def ensure_that_the_directory_for_the_daily_questions_exists
+    _ = File.dirname(FILE_DAILY_QUESTIONS_SOLVED)
+    unless File.directory? _
+      mkdir(_)
+    end
+  end
+
+  # ========================================================================= #
+  # === do_not_assume_numbers_in_parens
+  # ========================================================================= #
+  def do_not_assume_numbers_in_parens
+    @internal_hash[:numbers_in_parens] = false # Reset it here.
+  end
+
+  # ========================================================================= #
+  # === invoke_all_the_necessary_steps_before_the_question_is_asked
+  # ========================================================================= #
+  def invoke_all_the_necessary_steps_before_the_question_is_asked
+    ensure_that_the_directory_for_the_daily_questions_exists
+    do_not_assume_numbers_in_parens
+    determine_the_exam_topic
+    try_to_read_in_the_dataset_from_the_corresponding_exam_file
+    sanitize_the_obtained_dataset
+    random_line = pick_a_random_line_from_the_obtained_dataset
+    parse_the_random_line_from_the_obtained_dataset(random_line)
+    # sample_line = @internal_hash[:dataset_from_the_file].sample
+    # parse_the_random_line_from_the_obtained_dataset(sample_line)
+  end; alias initial_steps          invoke_all_the_necessary_steps_before_the_question_is_asked # === initial_steps
+       alias initialize_the_dataset invoke_all_the_necessary_steps_before_the_question_is_asked # === initialize_the_dataset
+
+  # ========================================================================= #
+  # === pick_a_random_line_from_the_obtained_dataset
+  # ========================================================================= #
+  def pick_a_random_line_from_the_obtained_dataset
+    _ = dataset_from_the_file?.reject {|line|
+      line.end_with?(' []')
+    } # Reject already solved exam questions.
+    use_this_sample = _.sample
+    set_exam_question_line(use_this_sample)
+    try_to_save_the_line(use_this_sample)
+    return use_this_sample
+  end
+
+  # ========================================================================= #
+  # === show_statistics
+  #
+  # To invoke this method from the commandline, try:
+  #
+  #   qa --show-statistics
+  #
+  # ========================================================================= #
+  def show_statistics(
+      dataset = dataset?
+    )
+    unless in_www_mode?
+      n_questions = n_questions_available?
+      n_answered  = n_questions_already_answered?
+      percentage = (n_answered.to_f * 100) / n_questions
+      result = olivedrab(n_questions.to_s)+
+               grey(' questions available, ')+
+               mediumaquamarine(n_answered.to_s)+
+               grey(' (')+
+               colourize_percentage(percentage.round(2).to_s+'%')+
+               grey(") already answered.#{N}")
+      # ===================================================================== #
+      # Also add how many questions in absolute numbers have to be answered
+      # still.
+      # ===================================================================== #
+      padded_amount_of_questions_answered = (n_questions - n_answered).to_s
+      padded_amount_of_questions_answered =
+        padded_amount_of_questions_answered.rjust(n_questions.to_s.size)
+      result << "#{crimson(padded_amount_of_questions_answered)} "\
+                "#{grey('questions could still be answered. Topic: ')}"\
+                "#{olive(return_the_full_expanded_exam_title)}"\
+                "#{grey('.')}#{rev}"
+      e result
+    end
+  end; alias report_statistics show_statistics # === report_statistics
+
+  # ========================================================================= #
+  # === have_all_the_exam_questions_for_this_topic_been_answered_already?
+  # ========================================================================= #
+  def have_all_the_exam_questions_for_this_topic_been_answered_already?(i = topic?)
+    _ = dataset?.reject {|line| line.end_with?('[]') }.size
+    _ == 0
+  end
+
+  require 'studium/logging/store_last_question_asked_into_file.rb'
+  # ========================================================================= #
+  # === do_log_related_and_backup_related_actions
+  #
+  # This method will backup files and similar activities.
+  #
+  # Note that the method exam_file?() will return a String such as:
+  #
+  #   "/home/x/programming/ruby/src/studium/lib/studium/exam_topics/protein_engineering"
+  #
+  # ========================================================================= #
+  def do_log_related_and_backup_related_actions
+    unless Studium.is_in_www_mode?
+      Studium.backup_this_exam_file(exam_file?) # { :be_verbose }
+      hash = {} # Build up our data structure here, as a Hash.
+      hash[:question_was_asked_when] = Time.now
+      hash[:question_full_line]      = line?
+      Studium::Log::StoreLastQuestionAskedIntoFile.new(hash) # { :be_verbose }
+      append_into_onto_daily_exam_questions_file
+    end
+  end
+
+  # ========================================================================= #
+  # === store_relevant_information_pertaining_to_the_last_exam_question_asked
+  # ========================================================================= #
+  def store_relevant_information_pertaining_to_the_last_exam_question_asked
+    _ = studium_log_dir?
+    mkdir(
+      File.dirname(Studium.file_last_topic?)
+    )
+    # ======================================================================= #
+    # Store the last exam topic first:
+    # ======================================================================= #
+    write_what_into(last_topic?, Studium.file_last_topic?)
+    target_directory = "#{_}information_pertaining_to_the_last_exam_question_asked/"
+    mkdir(target_directory) unless File.directory?(target_directory)
+    # ======================================================================= #
+    # Store the last exam-question-answer next:
+    # ======================================================================= #
+    last_exam_question_answer = Studium.file_last_question_asked?
+    what = line?
+    into = last_exam_question_answer
+    write_what_into(what, into)
+    # ======================================================================= #
+    # Store the last exam-question time next:
+    # ======================================================================= #
+    last_exam_question_answer_time = target_directory+'last_exam_question_answer_time.yml'
+    what = YAML.dump(Time.now)
+    into = last_exam_question_answer_time
+    write_what_into(what, into)
+    # ======================================================================= #
+    # Store the last exam-question next - this is just the question-part:
+    # ======================================================================= #
+    last_exam_question = "#{target_directory}last_exam_question.md"
+    what = exam_question?
+    into = last_exam_question
+    write_what_into(what, into)
+  end
+
+  # ========================================================================= #
+  # === parse_the_random_line_from_the_obtained_dataset
+  # ========================================================================= #
+  def parse_the_random_line_from_the_obtained_dataset(i)
+    @exam_question.parse(i)
+  end
+
+  # ========================================================================= #
+  # === pick_this_question_answer
+  # ========================================================================= #
+  def pick_this_question_answer(i)
+    set_exam_topic('Custom exam topic')
+    parse_the_random_line_from_the_obtained_dataset(i)
+    ask_the_question_then_sleep_then_reveal_the_answer_to_that_question
+  end
+
+  # ========================================================================= #
+  # === set_custom_colours
+  #
+  # This setter is, since as of January 2022, just calling two methods now.
+  # This was simpler to maintain than using another ad-hoc Hash.
+  #
+  # Valid keys for the colours should be, for instance, "colour_for_questions"
+  # or "colour_for_answers".
+  # ========================================================================= #
+  def set_custom_colours(i)
+    if i.is_a?(String) and i.include?('|')
+      # ===================================================================== #
+      # Allow custom input, as String, so users can override this.
+      # ===================================================================== #
+      splitted = i.split('|')
+      set_colour_for_questions(splitted.first)
+      set_colour_for_answers(splitted.last)
+    end
+  end
+
+  # ========================================================================= #
+  # === do_ask_the_question                           (question tag, ask tag)
+  #
+  # Simply display the question via this method.
+  # ========================================================================= #
+  def do_ask_the_question(
+      this_question   = exam_question?,
+      use_this_colour = colour_for_questions?
+    )
+    this_question = this_question.dup if this_question
+    # ======================================================================= #
+    # First, handle the commandline situation:
+    # ======================================================================= #
+    if commandline?
+      # ===================================================================== #
+      # === Handle underlined text next
+      # ===================================================================== #
+      if line_contains_underline_token?(this_question) and use_colours?
+        # =================================================================== #
+        # Colourize <ud> for underline next:
+        # =================================================================== #
+        this_question = replace_underline_token_with_default_colour(this_question, use_this_colour)
+      end
+      # ===================================================================== #
+      # === Handle italic text next
+      # ===================================================================== #
+      if line_contains_italic_token?(this_question) and use_colours?
+        # =================================================================== #
+        # Colourize <i> for italic next:
+        # =================================================================== #
+        this_question = replace_italic_token_with_default_colour(this_question, use_this_colour)
+      end
+      # ===================================================================== #
+      # === Colourize words in quotes
+      #
+      # Next, consider colourizing all answers that have at the least 2
+      # '"' characters. These will be colourized.
+      # ===================================================================== #
+      if EMPHASIZE_WORDS_IN_QUOTES_IN_A_GIVEN_ANSWER
+        if use_colours? and commandline? and (this_question.count('"') > 1)
+          use_this_regex = /"(.+?\s*.*?)"/ # See: http://rubular.com/r/6WK5NjMJld
+          use_this_colour = ::Colours.send(colour_for_answers?) { :omit_end }
+          this_question.gsub!(
+            use_this_regex,
+            '"'+steelblue('\1'.delete(N))+
+            use_this_colour+'"'
+          )
+        end
+      end
+      # ===================================================================== #
+      # Output the result finally, by making use of the toplevel method
+      # Colours.replace_number_words_with_the_corresponding_html_colour().
+      # ===================================================================== #
+      _ = ::Colours.replace_number_words_with_the_corresponding_html_colour(
+          DEFAULT_COLOUR_AS_ESCAPE_SEQUENCE+
+          this_question,
+          @internal_hash[:use_these_colours]
+      )
+      e ::Colours.fancy_parse(_, use_this_colour)
+      e if may_we_show_the_topic?
+      fancy_cliner
+    else # else tag
+      # ===================================================================== #
+      # === WWW mode
+      #
+      # Else we assume that this class is used on the web.
+      # ===================================================================== #
+      result  = ''.dup
+      result << "#{this_question}#{N}<br><br>"
+      @internal_hash[:result_for_www] = result
+      # ===================================================================== #
+      # Next, show the question, unless we operate in WWW mode.
+      # ===================================================================== #
+      e result unless www_mode?
+    end
+    e
+  end; alias ask_the_exam_question do_ask_the_question # === ask_the_exam_question
+       alias ask_the_question      do_ask_the_question # === ask_the_question
+       alias ask_this_question     do_ask_the_question # === ask_this_question
+       alias show_question         do_ask_the_question # === show_question
+
+  # ========================================================================= #
+  # === store_last_topic_into_file
+  #
+  # This method will store the last-exam-topic into a local file.
+  #
+  # By default we will not report this activity.
+  # ========================================================================= #
+  def store_last_topic_into_file(
+      what = topic?,
+      into = Studium.file_last_topic? # This would store into: "/root/Studium/last_topic.md"
+    )
+    base_dir = File.dirname(into)
+    unless File.directory?(base_dir)
+      mkdir(base_dir) # This is a directory such as "/home/x/Temp/studium/last_topic/".
+    end
+    write_what_into(what, into)
+  end
+
+  # ========================================================================= #
+  # === run                                                         (run tag)
+  # ========================================================================= #
+  def run
+    menu_on_the_commandline_as_a_string
+    menu
+    invoke_all_the_necessary_steps_before_the_question_is_asked
+    if have_all_the_exam_questions_for_this_topic_been_answered_already?(topic?)
+      notify_the_user_that_all_questions_have_been_answered_already
+    else
+      ask_the_question_then_sleep_then_reveal_the_answer_to_that_question
+      # ===================================================================== #
+      # After the answer has been shown, it is time to display some statistics.
+      # ===================================================================== #
+      show_statistics
+      do_log_related_and_backup_related_actions
+      # ===================================================================== #
+      # Register the last file that was modified.
+      # ===================================================================== #
+      register_last_modified_file
+    end
+  end
+
+end
+
+# =========================================================================== #
+# === Studium::Exams.question_answer
+# =========================================================================== #
+def self.question_answer(
+    topic       = 'random_topic',
+    run_already = true,
+    &block
+  )
+  Studium::Exams::ExamQuestion.new(topic, run_already, &block)
+end
+
+# =========================================================================== #
+# === Studium::Exams[]
+#
+# This will simply use AskQuestion as defined above.
+#
+# Usage examples, including aliases:
+#
+#   amg = Studium::Exams['amg']
+#   qa = Exams.question_answer('yo', :dont_run_yet)
+#
+# =========================================================================== #
+def self.[](i, run_already = true)
+  Studium::Exams::ExamQuestion.new(i, run_already)
+end; self.instance_eval { alias ask_question [] } # === ::Studium::Exams.ask_question
+
+end
+
+# =========================================================================== #
+# === Studium.ask_question
+#
+# This provides an easier API to ask a question.
+#
+# Usage example:
+#
+#   x = Studium.ask_question 'amg'
+#   y = Studium.ask_question('amg2') { :do_not_run_yet }
+#
+# =========================================================================== #
+def self.ask_question(
+    i           = ARGV,
+    run_already = true,
+    &block
+  )
+  Studium::Exams::ExamQuestion.new(i, run_already, &block)
+end; self.instance_eval { alias question_answer   ask_question } # === Studium.question_answer
+     self.instance_eval { alias new_exam          ask_question } # === Studium.new_exam
+     self.instance_eval { alias ask_question      ask_question } # === Studium.ask_question
+     self.instance_eval { alias ask_exam_question ask_question } # === Studium.ask_exam_question
+
+# =========================================================================== #
+# === Studium.random_question
+#
+# This method will ask a random exam question.
+# =========================================================================== #
+def self.random_question
+  ask_question(:random)
+end
+
+# =========================================================================== #
+# === Studium.delay_for_exam_questions?
+# =========================================================================== #
+def self.delay_for_exam_questions?
+  ::Studium::DEFAULT_DELAY
+end
+
+# =========================================================================== #
+# === Studium.random_exam_topic?
+#
+# This method will return a random exam topic when it is called.
+#
+# Usage examples:
+#
+#   Studium.random_exam_topic? # => "epigenetik"
+#   Studium.random_exam_topic? # => "abfall_als_ressource"
+#   Studium.random_exam_topic? # => "embryologie_und_entwicklung"
+#
+# =========================================================================== #
+def self.random_exam_topic?
+  ::Studium::Exams.all_topics_as_short_name.sort.sample
+end
+
+# =========================================================================== #
+# === Studium.return_question_answer_as_array
+#
+# This method will return the question-answer combination, as an Array.
+#
+# It will not make use of any colours; the reason for this is because
+# when this method was added as of the 13.04.2019, it was to be used
+# primarily on the www.
+#
+# If the input is a String and contains '- ' then we assume that we do
+# NOT want to find a specific topic. Instead we will use the given
+# input as exam-question + exam-answer as such.
+#
+# Invocation examples:
+#
+#   x = Studium.return_question_answer_as_array('amg1')
+#   x = Studium.return_question_answer_as_array('biotech1')
+#   x = Studium.return_question_answer_as_array(:biotech2)
+#   x = Studium.return_question_answer_as_array('- In Ruby: <one>Bundler</one> likes ... ? Gemfile.lock.')
+#
+# =========================================================================== #
+def self.return_question_answer_as_array(
+    topic = 'random_topic',
+    &block
+  )
+  _ = ::Studium::Exams::AskExamQuestion.new(topic, :do_not_run_yet, &block)
+  if topic.is_a?(String) and topic.include?('-')
+    _.set_exam_question_line_and_then_parse_that_line(topic)
+  else
+    _.invoke_all_the_necessary_steps_before_the_question_is_asked
+  end
+  _.disable_colours
+  # ========================================================================= #
+  # We will return the proper Array next:
+  # ========================================================================= #
+  [
+    _.question?,
+    _.answer?.to_s.delete("\n").squeeze(' ')
+  ]
+end; self.instance_eval { alias determine_question_answer_from_this         return_question_answer_as_array } # === Studium.determine_question_answer_from_this
+     self.instance_eval { alias determine_question_answer_from_this_line    return_question_answer_as_array } # === Studium.determine_question_answer_from_this_line
+     self.instance_eval { alias return_question_answer_from_this_exam_topic return_question_answer_as_array } # === Studium.return_question_answer_from_this_exam_topic
+
+# =========================================================================== #
+# === Studium.return_question_answer_and_the_whole_exam_line_as_array
+# =========================================================================== #
+def self.return_question_answer_and_the_whole_exam_line_as_array(
+    topic = 'random_topic',
+    &block
+  )
+  _ = ::Studium::Exams::AskExamQuestion.new(topic, :do_not_run_yet, &block)
+  if topic.is_a?(String) and topic.include?('-')
+    _.set_exam_question_line_and_then_parse_that_line(topic)
+  else
+    _.invoke_all_the_necessary_steps_before_the_question_is_asked
+  end
+  _.disable_colours
+  # ========================================================================= #
+  # We will return the proper Array next:
+  # ========================================================================= #
+  [
+    _.question?,
+    _.answer?.to_s.delete("\n").squeeze(' '),
+    _.line?
+  ]
+end
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  alias e puts
+  _ask_exam_question = Studium::Exams::AskExamQuestion.new(ARGV)
+  pp Studium.return_question_answer_as_array(:biotech2)
+end # qa amg1