studium 0.10.1

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

@@ -0,0 +1,382 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'studium/exams/ask_exam_question/menu.rb'
+# =========================================================================== #
+require 'studium/base/base.rb'
+
+module Studium
+
+module Exams
+
+class AskExamQuestion < Base # === Studium::Exams::AskExamQuestion
+
+  require 'studium/exams/ask_exam_question/help.rb'
+  require 'studium/toplevel_methods/handle_archive_of_the_exam_questions.rb'
+
+  # ========================================================================= #
+  # === 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
+
+  # ========================================================================= #
+  # === 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 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 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
+        @reject_lines_that_end_with_a_done_token = false
+      # ===================================================================== #
+      # === qa --show-topic?
+      # ===================================================================== #
+      when /^-?-?show(_|-| )?topic\??/i
+        report_whether_we_will_show_the_topic
+        exit_program
+      # ===================================================================== #
+      # === 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 --upload_exams
+      # ===================================================================== #
+      when 'examtopics?',
+           'upload_exam_topics',
+           /^upload_?exams/,
+           'uexams',
+           'uexam'
+        Studium.upload_exam_questions { :be_verbose }
+      # ===================================================================== #
+      # === qa ftp
+      # ===================================================================== #
+      when 'ftp',
+           /^ftp(_|-)?upload$/
+        Studium.upload_exam_questions { :be_verbose }
+        exit_program
+      # ===================================================================== #
+      # === qa EDIT
+      # ===================================================================== #
+      when 'EDIT',
+           /^-?-?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
+      # ===================================================================== #
+      # === SHOW_ALL
+      #
+      # Invocation example:
+      #
+      #   qa ethik SHOW_ALL
+      #
+      # ===================================================================== #
+      when /SHOW_?ALL/
+        show_content_of_this_topic(topic?)
+        exit
+      # ===================================================================== #
+      # === qa --last-question?
+      # ===================================================================== #
+      when 'LAST_QUESTION?',
+           'LAST_QUESTION', # qa LAST_QUESTION?
+           'LAST?',
+           '--last-question?',
+           'lastquestion?',
+           'lastquestion',
+           /^-?-?last$/
+        show_last_question_asked
+        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 TOTAL?
+      # ===================================================================== #
+      when /TOTAL/,'total' # qa TOTAL?
+        show_how_many_exam_questions_are_available
+        exit_program
+      # ===================================================================== #
+      # === qa --finished?
+      # ===================================================================== #
+      when /^-?-?finished\??$/i
+        show_all_finished_exam_topics
+        exit
+      # ===================================================================== #
+      # === qa --log-dir?
+      # ===================================================================== #
+      when 'log?',
+           'log_dir?',
+           'store_where?',
+           'store_where',
+           '--dir?',
+           'dir?',
+           /^-?-?log(-|_)?dir\??$/i
+        e "#{rev}The log directory can be found at: "\
+          "#{sdir(log_dir?)}"
+        exit
+      # ===================================================================== #
+      # === qa --help?
+      # ===================================================================== #
+      when 'HELP',
+           'help',
+           '--help',
+           '--hep',
+           '--help?',
+           'help?'
+        show_help_usage(:do_exit)
+      # ===================================================================== #
+      # === qa --default-topic?
+      # ==================================================================== #
+      when '--default-topic?',
+           '--default-topic',
+           'defaulttopic?',
+           'defaulttopic'
+        report_the_default_topic_in_use
+        exit
+      # ===================================================================== #
+      # === qa --filesize?
+      # ===================================================================== #
+      when 'size?',
+           /^-?-?filesize\??/i
+        show_filesize_of_all_exams
+        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 N_TOPICS
+      # ===================================================================== #
+      when /^-?-?n(_|-)?topics$/i # qa N_TOPICS
+        report_how_many_topics_are_available
+        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 --all-topics?
+      #
+      # Entry point for showing all available exam-topics:
+      #
+      #   qa show_topics
+      #
+      # ===================================================================== #
+      when 'ALL',
+           'all_topics',
+           'available_topics?',
+           'topics?',
+           /^-?-?show(_|-)?topics$/i,
+           'detailed_topic',
+           '--all-topics',
+           '--topics',
+           /^TOPICS/,
+           /ALL_TOPICS/,
+           'alltopics?',
+           'alltopics',
+           '--all-topics?',
+           /^-?-?show(-|_)?available(-|_)?topics$/i,
+           /^-?-?show(-|_)?all(-|_)?exam(-|_)?topics$/i
+        show_available_topics # This also includes exit.
+      else
+        if ::Studium.is_this_an_exam_topic?(i)
+          set_exam_topic(i)
+        end
+      end
+    end
+  end
+
+end; end; end

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

@@ -0,0 +1,938 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'studium/exams/ask_exam_question/misc.rb'
+# =========================================================================== #
+require 'studium/exams/ask_exam_question/answer.rb'
+require 'studium/exams/ask_exam_question/delay.rb'
+require 'studium/exams/ask_exam_question/initialize.rb'
+require 'studium/exams/ask_exam_question/menu.rb'
+require 'studium/exams/ask_exam_question/reset.rb'
+
+module Studium
+
+module Exams
+
+class AskExamQuestion < Base # === Studium::Exams::AskExamQuestion
+
+  begin
+    require 'verbose_truth'
+  rescue LoadError; end
+
+  # ========================================================================= #
+  # === add                                                         (add tag)
+  # ========================================================================= #
+  def add(i)
+    @result << i
+  end
+  
+  # ========================================================================= #
+  # === result?
+  # ========================================================================= #
+  def result?
+    @result
+  end; alias string? result? # === string?
+
+  # ========================================================================= #
+  # === reject_invalid_entries
+  #
+  # This method will remove entries that begin with '#' and empty entries.
+  # ========================================================================= #
+  def reject_invalid_entries
+    @dataset.reject! {|line|
+      line.strip.empty? or
+      line.start_with?('#')
+    }
+  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?
+        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
+
+  # ========================================================================= #
+  # === answer?
+  # ========================================================================= #
+  def answer?
+    @answer
+  end; alias last answer? # === last
+
+  # ========================================================================= #
+  # === show_statistics
+  # ========================================================================= #
+  def show_statistics(
+      dataset = @dataset
+    )
+    n_questions = dataset.size
+    n_answered = n_questions - 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 "\
+              "still have to be answered. Topic: "\
+              "#{olive(return_the_full_expanded_exam_title)}.#{rev}"
+    e result
+  end; alias report_statistics show_statistics # === report_statistics
+
+  # ========================================================================= #
+  # === return_the_full_expanded_exam_title
+  # ========================================================================= #
+  def return_the_full_expanded_exam_title
+    return Studium.find_corresponding_exam_title(exam_title?)
+  end
+
+  # ========================================================================= #
+  # === do_sleep
+  #
+  # Use this to sleep for the specified duration, stored in the ivar @delay.
+  #
+  # Since April 2012 the method will also handle SIGINT-events gracefully.
+  # ========================================================================= #
+  def do_sleep
+    begin
+      sleep(@delay)
+    rescue Interrupt # We are silent here.
+      exit_program
+    end
+  end; alias default_sleep       do_sleep # === default_sleep
+       alias start_default_sleep do_sleep # === 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
+
+  # ========================================================================= #
+  # === 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
+
+  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
+
+  # ========================================================================= #
+  # === consider_renaming_konsole_tab
+  #
+  # We will delegate to class SetTerminalTitle in order to rename the KDE
+  # konsole title.
+  # ========================================================================= #
+  def consider_renaming_konsole_tab
+    if AskExamQuestion.rename_konsole_tab?
+      rename_kde_konsole_tab(topic?)
+    end
+  end
+
+  # ========================================================================= #
+  # === may_we_show_the_topic?
+  # ========================================================================= #
+  def may_we_show_the_topic?
+    @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 = true)
+    @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
+
+  # ========================================================================= #
+  # === exam_file?
+  #
+  # This query-method shows as to where the specific file at hand is.
+  # ========================================================================= #
+  def exam_file?
+    @exam_file
+  end; alias file? exam_file? # === file?
+
+  # ========================================================================= #
+  # === 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)
+    @exam_file = i
+  end; alias set_file set_exam_file # === set_file
+
+  # ========================================================================= #
+  # === show_line
+  # ========================================================================= #
+  def show_line
+    e line?
+  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)
+    end
+  end
+
+  # ========================================================================= #
+  # === set_store_where
+  # ========================================================================= #
+  def set_store_where(i)
+    @store_where = i.to_s
+  end
+
+  # ========================================================================= #
+  # === store_where?
+  # ========================================================================= #
+  def store_where?
+    @store_where
+  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
+
+  # ========================================================================= #
+  # === 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
+    file  = "#{log_dir?}use_this_exam_topic.yml"
+    if File.exist? file
+      topic = File.read(file).chomp
+      e 'The default topic in use is: '+simp(topic)
+    else
+      e "#{rev}No file exists at `#{sfile(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
+
+  require 'studium/statistics/report_how_many_exam_questions_were_answered.rb'
+  # ========================================================================= #
+  # === 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
+
+  # ========================================================================= #
+  # === 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
+  end
+
+  # ========================================================================= #
+  # === opnn
+  # ========================================================================= #
+  def opnn
+    super(
+      namespace:   @namespace,
+      use_colours: use_colours?
+    )
+  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?
+
+  # ========================================================================= #
+  # === 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
+
+  # ========================================================================= #
+  # === determine_whether_we_will_rename_the_konsole_tab
+  # ========================================================================= #
+  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
+
+  # ========================================================================= #
+  # === load_file_rename_konsole_tab
+  # ========================================================================= #
+  def load_file_rename_konsole_tab
+    YAML.load_file(FILE_RENAME_KONSOLE_TAB)
+  end
+
+  # ========================================================================= #
+  # === do_rename_konsole_tab
+  # ========================================================================= #
+  def do_rename_konsole_tab
+    AskExamQuestion.set_rename_konsole_tab(true)
+  end
+  
+  # ========================================================================= #
+  # === do_not_rename_konsole_tab
+  # ========================================================================= #
+  def do_not_rename_konsole_tab
+    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
+
+  # ========================================================================= #
+  # === 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
+
+  # ========================================================================= #
+  # === show_content_of_this_topic
+  # ========================================================================= #
+  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
+
+  # ========================================================================= #
+  # === 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
+
+  # ========================================================================= #
+  # === 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
+
+  # ========================================================================= #
+  # === report_file_does_not_exist
+  # ========================================================================= #
+  def report_file_does_not_exist
+    opnn; e "#{rev}No file at `#{sfile(exam_file?)}` exists."
+  end
+
+  # ========================================================================= #
+  # === consider_warning_the_user_if_there_are_too_many_exams_registered
+  # ========================================================================= #
+  def consider_warning_the_user_if_there_are_too_many_exams_registered
+    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_questions? > THRESHOLD_VALUE_N_EXAMS_AT_MAXIMUM)
+      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
+
+  # ========================================================================= #
+  # === load_the_dataset_based_on_the_exam_topic_before_rejecting_invalid_entries
+  # ========================================================================= #
+  def load_the_dataset_based_on_the_exam_topic_before_rejecting_invalid_entries
+    load_the_dataset_based_on_the_exam_topic
+    reject_invalid_entries
+  end
+
+  # ========================================================================= #
+  # === main_file_exists?
+  # ========================================================================= #
+  def main_file_exists?(i = exam_file?)
+    File.exist? i
+  end
+
+  # ========================================================================= #
+  # === set_dataset
+  # ========================================================================= #
+  def set_dataset(i = nil)
+    @dataset = i
+  end; alias set_data set_dataset # === set_data
+
+  # ========================================================================= #
+  # === dataset?
+  # ========================================================================= #
+  def dataset?
+    @dataset
+  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
+
+  # ========================================================================= #
+  # === determine_the_exam_topic_then_determine_the_exam_file
+  # ========================================================================= #
+  def determine_the_exam_topic_then_determine_the_exam_file
+    determine_the_exam_topic
+    determine_the_exam_file
+  end
+
+  # ========================================================================= #
+  # === determine_the_exam_file
+  # ========================================================================= #
+  def determine_the_exam_file(exam_topic = exam_topic?)
+    unless ::Studium.is_this_a_registered_exam_topic?(exam_topic)
+      exam_topic = ::Studium.return_random_exam_topic
+    end
+    target_file = directory_to_the_exam_topics?+
+                  find_corresponding_exam_topic(exam_topic)
+    set_exam_file(target_file)
+  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
+
+  # ========================================================================= #
+  # === 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_topic?
+  # ========================================================================= #
+  def exam_topic?
+    @exam_topic
+  end; alias exam_title?  exam_topic? # === exam_title?
+       alias which_topic? exam_topic? # === which_topic?
+       alias topic?       exam_topic? # === topic?
+       alias topic        exam_topic? # === topic
+       alias title        exam_topic? # === title
+       alias title?       exam_topic? # === title?
+       alias category?    exam_topic? # === category?
+
+  # ========================================================================= #
+  # === load_the_dataset_based_on_the_exam_topic
+  #
+  # Determine the @dataset variable.
+  # ========================================================================= #
+  def load_the_dataset_based_on_the_exam_topic(i = exam_file?)
+    @dataset = File.readlines(i)
+  end; alias determine_the_dataset load_the_dataset_based_on_the_exam_topic # === determine_the_dataset
+
+  # ========================================================================= #
+  # === 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
+
+  # ========================================================================= #
+  # === 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)
+    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
+    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.
+    # ======================================================================= #
+    # === 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".
+    # ======================================================================= #
+    i = Studium.find_corresponding_exam_topic(i)
+    @exam_topic = i
+  end; alias set_this_topic set_exam_topic # === set_this_topic
+
+  # ========================================================================= #
+  # === n_questions?
+  #
+  # Return how many questions are available in the given dataset at hand.
+  # ========================================================================= #
+  def n_questions?
+    @dataset.size
+  end
+
+  # ========================================================================= #
+  # === determine_the_exam_pool
+  # ========================================================================= #
+  def determine_the_exam_pool(
+      array = @dataset
+    )
+    # ======================================================================= #
+    # Get rid of files that end with "[]\n" tokens, but only if a certain
+    # instance variable is set to true.
+    # ======================================================================= #
+    if @reject_lines_that_end_with_a_done_token
+      array = array.reject {|line|
+        line.end_with?(" []#{N}")
+      }
+    end
+    @exam_pool = array
+  end
+
+  # ========================================================================= #
+  # === n_questions_already_answered?
+  # ========================================================================= #
+  def n_questions_already_answered?
+    @exam_pool.size
+  end
+
+  # ========================================================================= #
+  # === line?
+  # ========================================================================= #
+  def line?
+    @line
+  end; alias line                line? # === line
+       alias full_question_line? line? # === full_question_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
+    write_what_into(what, into)
+  end
+
+  # ========================================================================= #
+  # === determine_the_exam_topic
+  # ========================================================================= #
+  def determine_the_exam_topic
+    use_this_topic = first_argument?
+    case use_this_topic
+    when nil, ''
+      use_this_topic = :random
+    end
+    set_exam_topic(use_this_topic)
+    store_last_topic_into_file(use_this_topic)
+  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
+
+  # ========================================================================= #
+  # === set_line
+  #
+  # Set the line via this method. The line is a full line from the
+  # file that contains all questions and answers of a specific
+  # topic at hand.
+  #
+  # Note that this setter does NOT modify anything; the reason why it
+  # shall not modify anything is because we will store that line into
+  # a local file too.
+  # ========================================================================= #
+  def set_line(i)
+    i = i.first if i.is_a? Array # We only want the first entry, if it is an Array.
+    @line = i
+  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
+
+  require 'studium/toplevel_methods/filter_away_invalid_questions.rb'
+  # ========================================================================= #
+  # === filter_away_invalid_questions
+  # ========================================================================= #
+  def filter_away_invalid_questions(i)
+    Studium.filter_away_invalid_questions(i)
+  end
+
+  # ========================================================================= #
+  # === do_ask_a_random_question_before_showing_the_answer
+  # ========================================================================= #
+  def do_ask_a_random_question_before_showing_the_answer
+    determine_the_exam_pool
+    if @exam_pool.empty?
+      notify_the_user_that_all_questions_have_been_answered_already
+      exit_program
+    else
+      use_this_sample = @exam_pool.sample
+      set_line(use_this_sample)
+      try_to_save_the_line(@line)
+      # ======================================================================= #
+      # Next, we must determine the "split" position in that question-answer
+      # line. This will vary depending on the particular line, as we allow
+      # for different formats to be used therein.
+      # ======================================================================= #
+      @question_answer.set_line(@line) { :then_determine_the_split_position }
+      @question_answer.determine_the_question_and_the_answer
+      ask_this_question(@question_answer.question?)
+      start_default_sleep
+      show_this_answer(@question_answer.answer?)
+    end
+  end; alias ask_question_then_show_the_answer_after_a_delay do_ask_a_random_question_before_showing_the_answer # === ask_question_then_show_the_answer_after_a_delay
+       alias show_question_then_sleep_then_show_answer       do_ask_a_random_question_before_showing_the_answer # === show_question_then_sleep_then_show_answer
+       alias ask_sleep_show                                  do_ask_a_random_question_before_showing_the_answer # === ask_sleep_show
+       alias ask_the_question_then_reveal_the_answer         do_ask_a_random_question_before_showing_the_answer # === ask_the_question_then_reveal_the_answer
+
+end; end; end