studium 0.13.1

data/lib/studium/exams/exam_question/exam_question.rb

@@ -0,0 +1,1135 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# === Studium::Exams::ExamQuestion
+#
+# This class, created in December 2021 / January 2022, 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/exam_question/exam_question.rb'
+# Studium::Exams::ExamQuestion.new(ARGV)
+# y = Studium.ask_question('amg2') { :do_not_run_yet }
+# =========================================================================== #
+require 'studium/base/base.rb'
+
+module Studium
+
+module Exams
+
+class ExamQuestion < ::Studium::Base # === Studium::Exams::ExamQuestion
+
+  require 'studium/constants/constants.rb'
+  require 'studium/exams/exam_question/answer.rb'
+  require 'studium/exams/exam_question/menu.rb'
+  require 'studium/exams/exam_question/misc.rb'
+  require 'studium/exams/exam_question/reset.rb'
+  require 'studium/statistics/report_how_many_exam_questions_were_answered.rb'
+
+  begin
+    require 'verbose_truth'
+  rescue LoadError; end
+
+  # ========================================================================= #
+  # === @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
+    )
+    set_commandline_arguments(
+      commandline_arguments
+    )
+    reset
+    # ======================================================================= #
+    # === 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
+
+  # ========================================================================= #
+  # === 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
+    opnn; e "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
+
+  # ========================================================================= #
+  # === delay?
+  # ========================================================================= #
+  def delay?
+    @internal_hash[:delay]
+  end; alias delay delay? # === delay
+
+  # ========================================================================= #
+  # === 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=
+
+  # ========================================================================= #
+  # === 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
+
+  # ========================================================================= #
+  # === topic?
+  # ========================================================================= #
+  def topic?
+    @internal_hash[:topic]
+  end; alias exam_topic?  topic? # === exam_topic?
+       alias exam_title?  topic? # === exam_title?
+       alias which_topic? topic? # === which_topic?
+       alias topic        topic? # === topic
+       alias title        topic? # === title
+       alias title?       topic? # === title?
+       alias category?    topic? # === category?
+
+  # ========================================================================= #
+  # === dataset?
+  # ========================================================================= #
+  def dataset?
+    @internal_hash[:dataset_from_the_file]
+  end
+
+  # ========================================================================= #
+  # === set_dataset
+  # ========================================================================= #
+  def set_dataset(i)
+    @internal_hash[:dataset_from_the_file] = i
+  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
+    # ======================================================================= #
+    @internal_hash[:n_exam_questions_in_total] = dataset.size
+    _ = dataset.reject {|line|
+      line.end_with? '[]'
+    }
+    set_exam_pool(_) if _ # Keep track of the unanswered exam questions here.
+    # ======================================================================= #
+    # === :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
+
+  # ========================================================================= #
+  # === set_exam_question
+  # ========================================================================= #
+  def set_exam_question(i)
+    i = i.dup if i.frozen?
+    i.strip! # Get rid of trailing newlines.
+    i[0,  2] = '' if i.start_with?('- ') # Chop off leading '-' components.
+    i[-2, 2] = '' if i.end_with?(' A')
+    i[-2, 2] = '' if i.end_with?('?A')
+    i[-3, 3] = '' if i.end_with?(' A?')
+    i[-2, 2] = '' if i.end_with?('! ?') # Preserve the ! here.
+    # ======================================================================= #
+    # i[-2,2] = '' if i.end_with? 'A?'
+    # ^^^ The above check is not good because the question may end like:
+    #   "T-DNA?". Perhaps we have to think of another way.
+    # ======================================================================= #
+    if i.end_with? '. ?' # This can not be correct - it must be a typo.
+      i[-2, 2] = '' # Thus get rid of the last two entries.
+    end
+    if i.end_with? '.?','!?' # These two values can not be correct - it must thus be a typo.
+      i.chop! # Thus get rid of the last two entries.
+    end
+    i.strip! # ← Always chop off trailing newlines, just in case.
+    # ======================================================================= #
+    # A question typically will have a trailing '?', thus we ensure this
+    # by actually appending a question mark '?' - unless the string
+    # already ends with '?', '.' or a '!'.
+    # ======================================================================= #
+    unless i.rstrip.end_with?('?','.','!')
+      i << '?' # Ensure a trailing '?' here.
+    end
+    # ======================================================================= #
+    # Next we will determine how many characters are in the given line.
+    # We need to exclude ANSII escape sequences, though, as they
+    # will not be shown on the commandline - they will be interpreted
+    # differently, such as displaying a red underline colour for the
+    # given text.
+    # ======================================================================= #
+    trimmed_sequence = remove_escape_sequences(
+      remove_tags_from_this_input(i)
+    )
+    n_characters_to_consider_in_the_line = trimmed_sequence.size
+    if n_characters_to_consider_in_the_line > @internal_hash[:word_wrap_at]
+      i = word_wrap(i, @internal_hash[:word_wrap_at])
+    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
+      if use_colours? and commandline? and (i.count('"') > 1)
+        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 }
+        i.gsub!(use_this_regex,
+          '"'+forestgreen('\1'.delete(N))+ # forestgreen is the hardcoded colour to be used for now.
+          use_this_colour+'"' 
+        )
+      end
+    end
+    @internal_hash[:exam_question] = i
+  end; alias set_question set_exam_question # === set_question
+
+  # ========================================================================= #
+  # === 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
+
+  # ========================================================================= #
+  # === 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
+
+  # ========================================================================= #
+  # === default_delay?
+  # ========================================================================= #
+  def default_delay?
+    DEFAULT_DELAY
+  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
+
+  # ========================================================================= #
+  # === show_line
+  # ========================================================================= #
+  def show_line
+    e exam_question_line?
+  end
+
+  # ========================================================================= #
+  # === exam_question?
+  # ========================================================================= #
+  def exam_question?
+    @internal_hash[:exam_question]
+  end; alias question? exam_question? # === question?
+       alias question  exam_question? # === question
+       alias first     exam_question? # === first
+
+  # ========================================================================= #
+  # === 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
+
+  # ========================================================================= #
+  # === report_how_many_topics_are_available
+  # ========================================================================= #
+  def report_how_many_topics_are_available
+    opnn; e 'There are exactly '+
+            simp(Studium.available_topics?.size.to_s)+
+            ' topics available.'
+  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(_)
+      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
+
+  # ========================================================================= #
+  # === internal_hash?
+  # ========================================================================= #
+  def internal_hash?
+    @internal_hash
+  end
+
+  # ========================================================================= #
+  # === 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 no"
+      e '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
+
+  # ========================================================================= #
+  # === exam_answer?
+  # ========================================================================= #
+  def exam_answer?
+    @internal_hash[:exam_answer]
+  end; alias answer? exam_answer? # === answer?
+       alias answer  exam_answer? # === answer
+       alias last    exam_answer? # === last
+
+  # ========================================================================= #
+  # === set_exam_answer
+  #
+  # This method can be used to keep track of the current exam-answer - that
+  # is the answer that fits to the exam-question at hand. Before it is
+  # set, though, this method will do various sanitizing actions, to make
+  # sure the answer is sufficiently "improved", before it is displayed
+  # to the user (or whoever invoked this class).
+  #
+  # Perhaps this should be factored out into a separate method, but for
+  # now it will remain as it is.
+  #
+  # Note that every question must have an associated answer. This is
+  # the very basic assumption for the "studium" gem every question
+  # must adhere to.
+  # ========================================================================= #
+  def set_exam_answer(
+      i
+    )
+    # ======================================================================= #
+    # === Handle Array as input
+    #
+    # This can happen due to assign_url() returning an Array.
+    # ======================================================================= #
+    i = i.first if i.is_a? Array
+    i = i.dup if i.frozen? # Work on non-frozen Strings past this point here.
+    i.strip! # This also implies .chomp.
+    i[-3, 3] = '' if i.end_with?(' []') # Get rid of trailing [], just in case.
+    # ======================================================================= #
+    # === Get rid of ' A:' if they are in that string.
+    #
+    # At this point, we do no longer want to have 'A:' in our answer-string,
+    # so we get rid of it.
+    #
+    # The old code up until 2022 was:
+    #
+    #   if i.include? ' A:'
+    #     i.sub!(/ A:/,'') unless i.include? ') A:' # The unless check exists to avoid rare cases..
+    #
+    # ======================================================================= #
+    i[0, 3] = '' if i.start_with?('A: ') # Three characters are in the argument.
+    i[0, 2] = '' if i.start_with?('- ')
+    i[0, 2] = '' if i.start_with?(': ','? ','?:')
+    i.sub!(/^\?/,'') if i.start_with? '?' # Only chop it away at the beginning.
+    if i.include? '(a)' # Also assume (b) (c) etc..
+      i.gsub!(/\(a\)/, N+'  (a)')
+      i.gsub!(/\(b\)/, N+'  (b)') if i.include? '(b)'
+      i.gsub!(/\(c\)/, N+'  (c)') if i.include? '(c)'
+      i.gsub!(/\(d\)/, N+'  (d)') if i.include? '(d)'
+      i.gsub!(/\(e\)/, N+'  (e)') if i.include? '(e)'
+      i.gsub!(/\(f\)/, N+'  (f)') if i.include? '(f)'
+    end
+    # ======================================================================= #
+    # Assume () modifications. But this conflicts with entries that have
+    # a pure () as part of their answer, which may happen on computer
+    # related questions such as foobar(). Hence, since as of December 2014,
+    # I have disabled the following line.
+    # ======================================================================= #
+    # i.gsub!(/\(\)/, N+'- ') if i.include? '()'
+    # ======================================================================= #
+    if debug?
+      e "We will now set the answer to: #{sfancy(i)}" if commandline?
+    end
+    # ======================================================================= #
+    # === Replace <br> tags, should they be part of the answer
+    # ======================================================================= #
+    i.gsub!(/<br>/, N) if i.include? '<br>'
+    # ======================================================================= #
+    # === 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 (i.count('"') > 1)
+        use_this_regex = /"(.+?\s*.*?)"/ # See: http://rubular.com/r/6WK5NjMJld
+        use_this_colour = ::Colours.send(colour_for_answers?) { :omit_end }
+        i.gsub!(
+          use_this_regex,
+          '"'+steelblue('\1'.delete(N))+
+          use_this_colour+'"'
+        )
+      end
+    end
+    @internal_hash[:exam_answer] = i
+  end; alias set_answer set_exam_answer # === set_answer
+
+  # ========================================================================= #
+  # === 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
+
+  # ========================================================================= #
+  # === 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
+
+  # ========================================================================= #
+  # === pick_a_random_line_from_the_obtained_dataset
+  # ========================================================================= #
+  def pick_a_random_line_from_the_obtained_dataset
+    _ = dataset?.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)
+  end
+
+  # ========================================================================= #
+  # === set_split_position
+  # ========================================================================= #
+  def set_split_position(i = nil)
+    @internal_hash[:split_position] = i
+  end; alias set_index_position set_split_position # === set_index_position
+
+  # ========================================================================= #
+  # === split_position?
+  # ========================================================================= #
+  def split_position?
+    @internal_hash[:split_position]
+  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
+      opnn; e swarn('Do note that there are too many exam questions '\
+              'registered in the file:')
+      e
+      e "  #{sfile(which_file?)}"
+      e
+    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
+
+  # ========================================================================= #
+  # === 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
+
+  # ========================================================================= #
+  # === 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
+
+  # ========================================================================= #
+  # === n_questions_already_answered?
+  # ========================================================================= #
+  def n_questions_already_answered?
+    @internal_hash[:n_exam_questions_answered]
+  end
+
+  # ========================================================================= #
+  # === report_whether_we_will_show_the_topic
+  # ========================================================================= #
+  def report_whether_we_will_show_the_topic
+    opnn; e 'Will we show the topic of the exams when '\
+            'asking a question: '+
+            simp(VerboseTruth[may_we_show_the_topic?])
+  end
+
+  # ========================================================================= #
+  # === exam_question_line?
+  # ========================================================================= #
+  def exam_question_line?
+    @internal_hash[:exam_question_line]
+  end; alias line?               exam_question_line? # === line?
+       alias line                exam_question_line? # === line
+       alias full_question_line? exam_question_line? # === full_question_line?
+
+  # ========================================================================= #
+  # === set_default_topic_for_the_gui
+  # ========================================================================= #
+  def set_default_topic_for_the_gui(
+      what,
+      into = "#{log_dir?}use_this_exam_topic.yml"
+    )
+    opnn; e "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
+
+  # ========================================================================= #
+  # === line_contains_italic_token?
+  # ========================================================================= #
+  def line_contains_italic_token?(i = line?)
+    (i.include?('<it>') and i.include?('</it>')) or
+    (i.include?('<i>')  and i.include?('</i>'))
+  end
+
+  # ========================================================================= #
+  # === line_contains_underline_token?
+  # ========================================================================= #
+  def line_contains_underline_token?(i = line?)
+    (i.include?('<ud>') and i.include?('</ud>')) or
+    (i.include?('<u>')  and i.include?('</u>'))
+  end
+
+  # ========================================================================= #
+  # === line_contains_bold_token?
+  # ========================================================================= #
+  def line_contains_bold_token?(i = line?)
+    (i.include?('<b>') and i.include?('</b>'))
+  end
+
+  # ========================================================================= #
+  # === invoke_all_the_necessary_steps_before_the_question_is_asked
+  # ========================================================================= #
+  def invoke_all_the_necessary_steps_before_the_question_is_asked
+    determine_the_topic
+    try_to_read_in_the_dataset_from_the_corresponding_exam_file
+    sanitize_the_obtained_dataset
+    pick_a_random_line_from_the_obtained_dataset
+    parse_the_random_line_from_the_obtained_dataset
+  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
+
+  # ========================================================================= #
+  # === set_exam_question_line_and_then_parse_that_line
+  # ========================================================================= #
+  def set_exam_question_line_and_then_parse_that_line(i)
+    set_exam_question_line(i)
+    parse_that_line
+  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?
+
+  # ========================================================================= #
+  # === run                                                         (run tag)
+  # ========================================================================= #
+  def run
+    menu_on_the_commandline_as_a_string
+    menu
+    invoke_all_the_necessary_steps_before_the_question_is_asked
+    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
+
+  # ========================================================================= #
+  # === Studium::Exams::ExamQuestion[]
+  # ========================================================================= #
+  def self.[](i = '')
+    new(i)
+  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::ExamQuestion.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?.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
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  Studium::Exams::ExamQuestion.new(ARGV)
+  pp Studium.return_question_answer_as_array(:biotech2)
+end # rb exam_question.rb amg1