studium 0.13.1

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

@@ -0,0 +1,895 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'studium/exams/exam_question/misc.rb'
+# =========================================================================== #
+require 'studium/base/base.rb'
+
+module Studium
+
+module Exams
+
+class ExamQuestion < ::Studium::Base # === Studium::Exams::ExamQuestion
+
+  require 'studium/toplevel_methods/handle_archive_of_the_exam_questions.rb'
+  require 'studium/toplevel_methods/write_into_file_related_functionality.rb'
+  require 'studium/exams/exam_question/constants.rb'
+  require 'studium/exams/exam_question/question.rb'
+
+  # ========================================================================= #
+  # === 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
+    # ======================================================================= #
+    # Next 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
+    ask_the_exam_question
+    sleep_default_delay
+    reveal_the_exam_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
+
+  # ========================================================================= #
+  # === 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
+    )
+    print seagreen('') # Always reset the colour here first.
+    if optional_content_to_be_displayed
+      e mediumaquamarine('*' * 3)+' '+
+        forestgreen( # or lightskyblue
+          optional_content_to_be_displayed
+        )+
+        ' '+
+        mediumaquamarine(
+          '*' * (75 - optional_content_to_be_displayed.size)
+        )
+    else
+      cliner('*', :mediumaquamarine)
+    end
+  end
+
+  require 'studium/toplevel_methods/report.rb'
+  # ========================================================================= #
+  # === 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
+
+  # ========================================================================= #
+  # === 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?
+    )
+    opnn; e 'All questions have already been answered '
+    opnn; e "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
+
+  # ========================================================================= #
+  # === 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
+
+  # ========================================================================= #
+  # === 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
+
+  # ========================================================================= #
+  # === 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?
+
+  # ========================================================================= #
+  # === main_file_exists?
+  # ========================================================================= #
+  def main_file_exists?(
+      i = exam_file?
+    )
+    i and File.exist?(i)
+  end
+
+  # ========================================================================= #
+  # === show_the_last_topic
+  #
+  # Invocation example:
+  #
+  #   qa --show-last-topic
+  #
+  # ========================================================================= #
+  def show_the_last_topic(
+      _ = 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
+
+  # ========================================================================= #
+  # === 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)
+    opnn; e 'We encountered an '+swarn('error')+
+            '. The @index_position was probably '\
+            'out of range.'
+    opnn; e 'Feedbacking @line next:'
+    pp line?
+    opnn; e "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?
+    )
+    opnn; e "#{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
+
+  # ========================================================================= #
+  # === 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?
+        opnn; e "Now saving: #{bold_blue(i)} into the file #{sfile(_)}"
+      end if commandline?
+      if File.writable?(File.dirname(_))
+        write_what_into(i, _) # Save it.
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === store_where?
+  # ========================================================================= #
+  def store_where?
+    Studium.file_last_question_asked?
+  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.
+  # ========================================================================= #
+  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 }
+    end
+  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
+    require 'open'
+    Open.in_browser(
+      Dir.home+'/Studium/html/statistics.html'
+    )
+  end
+
+  # ========================================================================= #
+  # === report_file_does_not_exist
+  # ========================================================================= #
+  def report_file_does_not_exist(
+      this_file = exam_file?
+    )
+    opnn; e "#{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::ExamQuestion.rename_konsole_tab?
+      rename_kde_konsole_tab(topic?)
+    end
+  end
+
+  # ========================================================================= #
+  # === do_rename_konsole_tab
+  # ========================================================================= #
+  def do_rename_konsole_tab
+    Studium::Exams::ExamQuestion.set_rename_konsole_tab(true)
+  end
+  
+  # ========================================================================= #
+  # === do_not_rename_konsole_tab
+  # ========================================================================= #
+  def do_not_rename_konsole_tab
+    Studium::Exams::ExamQuestion.set_rename_konsole_tab(false)
+  end
+
+  # ========================================================================= #
+  # === 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(_)
+      @internal_hash[:dataset_from_the_file] =
+        read_in_exam_dataset_from_this_file(_)
+    else
+      report_file_does_not_exist(_)
+    end
+  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
+
+  # ========================================================================= #
+  # === result?
+  # ========================================================================= #
+  def result?
+    @internal_hash[:result_for_www]
+  end
+
+  # ========================================================================= #
+  # === exam_pool?
+  # ========================================================================= #
+  def exam_pool?
+    @internal_hash[:exam_pool]
+  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
+
+  # ========================================================================= #
+  # === word_wrap_at?
+  # ========================================================================= #
+  def word_wrap_at?
+    @internal_hash[:word_wrap_at]
+  end
+
+  # ========================================================================= #
+  # === set_exam_topic
+  #
+  # We need to store the expanded topic name, so that something like
+  # "bioanalytik" is turned into "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_exam_topic(
+      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
+    when nil, ''
+      i = 'random_topic' # or :random
+    end
+    i = i.to_s.dup # Work with a String past this point.
+    i.downcase! # Convention is to store the file downcased.
+    case i
+    # ======================================================================= #
+    # === random
+    #
+    # We fetch a random topic via this entry-point.
+    # ======================================================================= #
+    when 'fetch_a_random_topic',
+         'random_topic',
+         'random',
+         'rand'
+      i = ::Studium::Exams.random_short_name_topic # This is allowed, for random topics.
+      # i = ::Studium.return_random_exam_topic # ← This may be an alternative.
+    # ======================================================================= #
+    # === molbio
+    #
+    # This entry point is special.
+    # ======================================================================= #
+    when 'molbio',
+         'molekularbiologie',
+         'molbio?'
+      i = 'amg|amg2|genex1|gentech1|gentech2|pcr'
+    # ======================================================================= #
+    # === OLAST
+    # ======================================================================= #
+    when /^qlast$/i,
+         /^olast$/i # === olast tag
+      _ = FILE_LAST_TOPIC
+      if File.exist? _
+        i = File.read(FILE_LAST_TOPIC).strip
+      else
+        opnn; no_file_exists_at(_)
+      end
+    end
+    # ======================================================================= #
+    # If the input has a '|', we assume that the user wants to randomly
+    # pick one entry.
+    # ======================================================================= #
+    if i.include? '|'
+      i = i.split('|').shuffle
+    end
+    # ======================================================================= #
+    # 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
+      opnn; e "Not a registered exam topic: #{i}"
+    end
+    @internal_hash[:topic] = i
+    # ======================================================================= #
+    # Next we will store the topic into a file.
+    # ======================================================================= # 
+    unless in_www_mode?
+      store_last_topic_into_file(i)
+    end
+  end; alias set_this_topic           set_exam_topic # === set_this_topic
+       alias determine_the_topic      set_exam_topic # === determine_the_topic
+       alias determine_the_exam_topic set_exam_topic # === determine_the_exam_topic
+
+  # ========================================================================= #
+  # === 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
+
+  # ========================================================================= #
+  # === 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)+' questions available, '+
+               mediumaquamarine(n_answered.to_s)+
+               ' ('+
+               colourize_percentage(percentage.round(2).to_s+'%')+
+               ') 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)} questions "\
+                "could still be answered. Topic: "\
+                "#{olive(return_the_full_expanded_exam_title)}.#{rev}"
+      e result
+    end
+  end; alias report_statistics show_statistics # === report_statistics
+
+  # ========================================================================= #
+  # === parse_the_random_line_from_the_obtained_dataset
+  #
+  # This method must also determine the split-position in the given
+  # exam-question-line, which is also called the "index" position.
+  #
+  # Example string:
+  #
+  #  - Name abc def. A: <one>DNA-Methylation</one>.
+  #
+  # ========================================================================= #
+  def parse_the_random_line_from_the_obtained_dataset(
+      # ===================================================================== #
+      # Obtain a handle to the exam-question-line first.
+      # ===================================================================== #
+      _ = @internal_hash[:exam_question_line]
+    )
+    # if _
+    #   # =================================================================== #
+    #   # We will chop off leading '- ' tokens next. The reason for this
+    #   # is that these leading '- ' are NEVER a part of a question-answer
+    #   # combination. They exist purely because of this being visually
+    #   # more pleasing to my eyes, so a cosmetic thing.
+    #   # This was, however had, disabled in January of 2022, because it
+    #   # led to problems in regards to storing the full line, which had
+    #   # to be stored in an unmodified manner.
+    #   # =================================================================== #
+    #   _ = _.dup if _.frozen?
+    #   if _.start_with? '- '
+    #     _[0, 2] = '' # Chop off leading '- ' tokens.
+    #   end
+    # end
+    if _.nil?
+      notify_the_user_that_all_questions_have_been_answered_already
+      exit_program
+      return
+    end
+    # ======================================================================= #
+    # We must determine the question and answer next. We do this by
+    # determining the index to split at. First, initialize it to 0.
+    # ======================================================================= #
+    index_to_split_at = 0
+    # ======================================================================= #
+    # The first strategy that is employed by this method is that the most
+    # important '?' token is to be found. If it is found then we can split
+    # split on it. This is, by definition, the very last '?' that
+    # we can find in the given String, hence why we use .rindex()
+    # rather than .index().
+    # ======================================================================= #
+    if _.include?('?')
+      index_to_split_at = _.rindex('?')
+      # ===================================================================== #
+      # Some entries may have a '?' but also a 'A:' token. In this case,
+      # we have to change the index position. However had, we must be
+      # careful here, as a few answers will contain something like this
+      # here:
+      #
+      #   '(1) A: Asymmetry (2) B: Border (3) C: Color (4) D: Diameter (5) E: Evolving'
+      #
+      # ===================================================================== #
+      if _.include?('?') and
+         _.include?(' A: ') and
+         !(_ =~ /\d{1}\) A: /) # The last one here is explained above.
+        index_to_split_at = _.index(' A: ')
+      end
+      set_split_position(index_to_split_at)
+    elsif _.include?(' A: ') # This should be the only valid format in this case.
+      index_to_split_at = _.index(' A: ')
+      set_split_position(index_to_split_at)
+    else # And here we report that something isn't quite right in the given file.
+      opnn; e 'No ? and no A: was found. Please check the following line:'
+      e
+      e "  #{tomato(_)}"
+      e
+      opnn; e
+      opnn; report_this_error
+      opnn; e
+    end
+    set_exam_question(_[0 .. index_to_split_at])
+    set_exam_answer(_[index_to_split_at .. -1])
+  end; alias determine_the_split_position          parse_the_random_line_from_the_obtained_dataset # === determine_the_split_position
+       alias determine_index_position              parse_the_random_line_from_the_obtained_dataset # === determine_index_position
+       alias parse_that_line                       parse_the_random_line_from_the_obtained_dataset # === parse_that_line
+       alias determine_the_question_and_the_answer parse_the_random_line_from_the_obtained_dataset # === determine_the_question_and_the_answer
+       alias determine_question_answer             parse_the_random_line_from_the_obtained_dataset # === determine_question_answer
+
+  # ========================================================================= #
+  # === set_exam_question_line
+  #
+  # A full exam-question line, also shorter called "line", is a line that
+  # contains a question, and the associated answer to this question.
+  #
+  # This setter may not modify anything - we just want to assign to the
+  # correct entry in our main Hash. Additionally the line itself may
+  # not be tampered with at all, so that we can act on that information,
+  # such as by storing that line into a local file.
+  # ========================================================================= #
+  def set_exam_question_line(i)
+    if i.is_a? Array
+      i = i.first.to_s.dup # We only need the first entry in this case, if it is an Array.
+    end
+    # ======================================================================= #
+    # === Handle blocks next
+    # ======================================================================= #
+    if block_given?
+      case yield
+      # ===================================================================== #
+      # === :then_determine_the_split_position
+      # ===================================================================== #
+      when :then_determine_the_split_position
+        determine_the_split_position
+      end
+    end
+    @internal_hash[:exam_question_line] = i
+  end; alias set_line      set_exam_question_line # === set_line
+       alias set_this_line set_exam_question_line # === set_this_line
+
+  # ========================================================================= #
+  # === store_last_topic_into_file
+  #
+  # By default we will not report this activity.
+  # ========================================================================= #
+  def store_last_topic_into_file(
+      what = topic?,
+      into = FILE_LAST_TOPIC # This would store into: "/root/Studium/last_topic.md"
+    )
+    write_what_into(what, into)
+  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
+
+end; end; end