studium 0.16.9

data/lib/studium/exams/ask_random_question.rb

@@ -0,0 +1,195 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# === Studium::AskRandomQuestion
+#
+# This class can be used to ask a random question from some dataset.
+# This dataset can typically be a local file, which will then be read
+# in by this class.
+#
+# In the future this class may have to be integrated into QuestionAnswer
+# or something like this.
+#
+# Usage example:
+#
+#   Studium::AskRandomQuestion.new(ARGV)
+#
+# =========================================================================== #
+# require 'studium/exams/ask_random_question.rb'
+# =========================================================================== #
+require 'studium/base/base.rb'
+
+module Studium
+
+class AskRandomQuestion < Base # === Studium::AskRandomQuestion
+
+  # ========================================================================= #
+  # === DEFAULT_DELAY
+  # ========================================================================= #
+  DEFAULT_DELAY = 2.0
+
+  # ========================================================================= #
+  # === initialize
+  # ========================================================================= #
+  def initialize(
+      commandline_arguments = nil,
+      run_already           = true
+    )
+    reset
+    set_commandline_arguments(
+      commandline_arguments
+    )
+    run if run_already
+  end
+
+  # ========================================================================= #
+  # === reset                                                     (reset tag)
+  # ========================================================================= #
+  def reset
+    super()
+    # ======================================================================= #
+    # === @work_in_batch_mode
+    #
+    # If true then this class will operate in a batch-mode.
+    # ======================================================================= #
+    @work_in_batch_mode = true
+    # ======================================================================= #
+    # === @delay
+    # ======================================================================= #
+    @delay = DEFAULT_DELAY
+  end
+
+  # ========================================================================= #
+  # === menu                                                       (menu tag)
+  # ========================================================================= #
+  def menu(
+      i = return_commandline_arguments_with_leading_hyphens
+    )
+    if i.is_a? Array
+      i.each {|entry| menu(entry) }
+    else
+      case i # case tag
+      # ===================================================================== #
+      # === proz --one
+      # ===================================================================== #
+      when /^-?-?one$/i
+        run_only_once
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === set_use_this_as_exam_dataset
+  #
+  # This method can be used to specify the exam-dataset that is to be
+  # used.
+  # ========================================================================= #
+  def set_use_this_as_exam_dataset(i)
+    i = [i].flatten.compact.reject {|line|
+      stripped_line = line.to_s.strip
+      stripped_line.empty? or 
+      stripped_line.start_with?('# ') or
+      stripped_line.end_with?('[]')
+    }
+    @exam_dataset = i
+  end; alias set_dataset set_use_this_as_exam_dataset # === set_dataset
+
+  # ========================================================================= #
+  # === determine_which_line_is_to_be_asked
+  # ========================================================================= #
+  def determine_which_line_is_to_be_asked
+    @random_line = @exam_dataset.sample
+  end
+
+  # ========================================================================= #
+  # === try_to_read_in_the_dataset                                (read tag)
+  # ========================================================================= #
+  def try_to_read_in_the_dataset
+    first = first?
+    if first and File.file?(first)
+      # Read in locally existing files here.
+      set_dataset(
+        File.readlines(first)
+      )
+    end
+  end
+
+  # ========================================================================= #
+  # === do_all_the_necessary_steps_and_then_ask_a_single_question
+  # ========================================================================= #
+  def do_all_the_necessary_steps_and_then_ask_a_single_question
+    determine_which_line_is_to_be_asked
+    ask_question
+    sleep_default_time
+    reveal_answer
+  end
+
+  # ========================================================================= #
+  # === sleep_default_time
+  # ========================================================================= #
+  def sleep_default_time
+    sleep @delay
+  end
+
+  # ========================================================================= #
+  # === ask_question                                           (question tag)
+  # ========================================================================= #
+  def ask_question
+    this_question = @random_line.split(':').first.to_s
+    print rev
+    cliner { :unicode }
+    e rev+'What does this mean? '+
+      seagreen(this_question)
+  end
+
+  # ========================================================================= #
+  # === add_this_to_the_default_delay
+  # ========================================================================= #
+  def add_this_to_the_default_delay(i = 1.5)
+    @delay += i
+  end
+
+  # ========================================================================= #
+  # === reveal_answer                                (answer tag, reveal tag)
+  # ========================================================================= #
+  def reveal_answer
+    answer = @random_line.split(':')[1 .. -1].join.to_s.strip
+    e "\n  #{steelblue(answer)}."
+    e
+  end
+
+  # ========================================================================= #
+  # === run_only_once
+  # ========================================================================= #
+  def run_only_once
+    @work_in_batch_mode = false
+  end
+
+  # ========================================================================= #
+  # === run                                                         (run tag)
+  # ========================================================================= #
+  def run
+    try_to_read_in_the_dataset
+    if @work_in_batch_mode # This is the default entry point.
+      add_this_to_the_default_delay 1.5
+      loop {
+        do_all_the_necessary_steps_and_then_ask_a_single_question
+      }
+    else # else ask only one question.
+      do_all_the_necessary_steps_and_then_ask_a_single_question
+    end
+  end
+
+  # ========================================================================= #
+  # === Studium::AskRandomQuestion[]
+  # ========================================================================= #
+  def self.[](i = '')
+    new(i)
+  end
+
+end; end
+
+if __FILE__ == $PROGRAM_NAME
+  Studium::AskRandomQuestion.new(ARGV)
+end # askrandomquestion dataset.md

data/lib/studium/exams/autoinclude.rb

@@ -0,0 +1,7 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+require 'studium/exams/exam/exam.rb'
+
+Object.send :include, Studium::Exams # Include the Exams namespace.

data/lib/studium/exams/average_grade/average_grade.rb

@@ -0,0 +1,402 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# === Studium::Exams::AverageGrade
+#
+# This class will show the average grade of passed exams.
+#
+# Usage example:
+#
+#   Studium::Exams::AverageGrade.new(ARGV)
+#
+# =========================================================================== #
+# require 'studium/exams/average_grade/average_grade.rb'
+# =========================================================================== #
+require 'studium/base/base.rb'
+
+module Studium
+
+module Exams
+
+class AverageGrade < Base # === Studium::AverageGrade
+
+  # ========================================================================= #
+  # === initialize
+  # ========================================================================= #
+  def initialize(
+      i           = nil,
+      run_already = true,
+      &block
+    )
+    reset
+    set_commandline_arguments(i) unless i.is_a?(Symbol)
+    # ======================================================================= #
+    # === Handle blocks next
+    # ======================================================================= #
+    if block_given?
+      yielded = yield
+      case yielded
+      # ===================================================================== #
+      # === :be_quiet
+      # ===================================================================== #
+      when :be_quiet
+        set_be_quiet
+      end
+    end
+    case run_already
+    # ======================================================================= #
+    # === :do_not_run_yet
+    # ======================================================================= #
+    when :do_not_run_yet
+      run_already = false
+    end
+    case i
+    # ======================================================================= #
+    # === :do_not_run_yet
+    # ======================================================================= #
+    when :do_not_run_yet
+      run_already = false
+    end
+    run if run_already
+  end
+
+  # ========================================================================= #
+  # === reset                                                     (reset tag)
+  # ========================================================================= #
+  def reset
+    super()
+    infer_the_namespace
+    # ======================================================================= #
+    # === :round_to_n_positions
+    # ======================================================================= #
+    @internal_hash[:round_to_n_positions] = 2
+    # ======================================================================= #
+    # === :use_this_dataset_location
+    # ======================================================================= #
+    @internal_hash[:use_this_dataset_location] = :default
+    # ======================================================================= #
+    # === :filter_first
+    # ======================================================================= #
+    @internal_hash[:filter_first] = nil
+    # ======================================================================= #
+    # === :filter_last
+    # ======================================================================= #
+    @internal_hash[:filter_last] = nil
+    set_be_verbose
+  end
+
+  # ========================================================================= #
+  # === menu                                                       (menu tag)
+  # ========================================================================= #
+  def menu(
+      i = commandline_arguments?
+    )
+    if i.is_a? Array
+      i.each {|entry| menu(entry) }
+    else
+      case i # (case tag)
+      # ===================================================================== #
+      # === --help
+      # ===================================================================== #
+      when /-?-?help$/i
+        show_help
+        exit
+      # ===================================================================== #
+      # === --use-local-file
+      # ===================================================================== #
+      when /^-?-?use(-|_)?local(-|_)?file$/i,
+           /^-?-?local$/i
+        @internal_hash[:use_this_dataset_location] = :use_csv_file
+      # ===================================================================== #
+      # === --first=
+      #
+      # In this event the user wants to know the average grade only of
+      # the first n passed exams.
+      #
+      # Usage example:
+      #
+      #   avgrade --first=100
+      #
+      # ===================================================================== #
+      when /^-?-?first=(.+)$/i
+        @internal_hash[:filter_first] = $1.to_i
+      # ===================================================================== #
+      # === --last=
+      #
+      # In this event the user wants to know the average grade only of
+      # the last n passed exams.
+      #
+      # Usage example:
+      #
+      #   avgrade --last=50
+      #
+      # ===================================================================== #
+      when /^-?-?last=(.+)$/i
+        @internal_hash[:filter_last] = $1.to_i
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === use_local_file?
+  # ========================================================================= #
+  def use_local_file?
+    @internal_hash[:use_csv_file]
+  end
+
+  # ========================================================================= #
+  # === determine_the_average_grade_from_these_passed_exams
+  # ========================================================================= #
+  def determine_the_average_grade_from_these_passed_exams(
+      i,
+      round_to_n_positions = 2
+    )
+    # ======================================================================= #
+    # Add support for a Hash to the second argument for this method:
+    # ======================================================================= #
+    if round_to_n_positions.is_a?(Hash) and
+       round_to_n_positions.has_key?(:round_to)
+      round_to_n_positions = round_to_n_positions[:round_to]
+    end
+    hash_passed_exams_grade = {}
+    hash_passed_exams_grade.default = 0
+    if i.is_a? Hash # This is the default, if we use the dataset from file lecture_information.yml.
+      i.each_pair {|a, b|
+        grade = b[:grade].to_s # We'll store it as a String, for reasons of simplicity.
+        hash_passed_exams_grade[grade] += 1
+      }
+    elsif i.is_a? Array
+      i.each {|grade|
+        hash_passed_exams_grade[grade] += 1
+      }
+    end
+    # ======================================================================= #
+    # Now we have a Hash such as:
+    #
+    #   {"1"=>68, "2"=>59, "3"=>73, "4"=>114, "E"=>5, "+"=>16}
+    #
+    # To calculate the average grade we need to take the entries at
+    # {"1"=>68, "2"=>59, "3"=>73, "4"=>114}, count the total sum
+    # and then calculate the corresponding entry.
+    # ======================================================================= #
+    _ = hash_passed_exams_grade
+    n_exams_passed_in_total = (_['1'])+(_['2'])+(_['3'])+(_['4'])
+    average_grade = (_['1'] * 1)+
+                    (_['2'] * 2)+
+                    (_['3'] * 3)+
+                    (_['4'] * 4)
+    average_grade = average_grade.to_f / n_exams_passed_in_total  
+    @internal_hash[:average_grade] = average_grade
+    if round_to_n_positions
+      @internal_hash[:average_grade]= @internal_hash[:average_grade].round(round_to_n_positions)
+    end
+  end
+
+  # ========================================================================= #
+  # === round_to_n_positions=
+  # ========================================================================= #
+  def round_to_n_positions=(i)
+    @internal_hash[:round_to_n_positions] = i
+  end
+
+  # ========================================================================= #
+  # === use_this_dataset_location=
+  # ========================================================================= #
+  def use_this_dataset_location=(i = :default)
+    @internal_hash[:use_this_dataset_location] = i.to_sym
+  end
+
+  # ========================================================================= #
+  # === use_which_dataset_location?
+  # ========================================================================= #
+  def use_which_dataset_location?
+    @internal_hash[:use_this_dataset_location]
+  end
+
+  # ========================================================================= #
+  # === run                                                         (run tag)
+  # ========================================================================= #
+  def run
+    menu
+    _ = use_which_dataset_location?
+    case _ # case tag
+    when :automatic,
+         :determine_automatically
+      _ = :lecture_information
+    end
+    case _
+    # ======================================================================= #
+    # === :default
+    # ======================================================================= #
+    when :default, # This is now the default since as of December 2022.
+         :lecture_information
+      if ::Studium.main_dataset?
+        dataset = ::Studium.main_dataset?
+      else
+        dataset = Studium.return_sanitized_dataset_from_the_file_lecture_information
+      end
+      dataset = filter_for_all_passed_exams(dataset)
+    # ======================================================================= #
+    # === :csv
+    # ======================================================================= #
+    when :csv,
+         :csv_file,
+         :use_csv_file,
+         :local_file
+      # ===================================================================== #
+      # In this case, on my home system, make use of my local .csv file.
+      # ===================================================================== #
+      this_file = Studium.file_passed_exams_per_month
+      # ===================================================================== #
+      # In this case, we will load from the .csv file.
+      # ===================================================================== #
+      dataset = default_readlines(this_file).reject {|line|
+        line.strip.empty? or line.strip.start_with?('#')
+      }
+      dataset = dataset.map {|line|
+        line.split('|').map(&:strip)[3] # [3] is the grade.
+      }
+    else
+      opne tomato('Not registered when-entry: '+_.to_s)
+    end
+    # ======================================================================= #
+    # Next, we may have to modify the dataset, if a filter is used.
+    # ======================================================================= #
+    if @internal_hash[:filter_first]
+      if dataset.is_a? Array # this is the case for when we want to use the local file
+        dataset = dataset[0 .. (@internal_hash[:filter_first]-1)]
+      elsif dataset.is_a? Hash
+        # =================================================================== #
+        # In this case we must sort it via timestamp, and then do a cut
+        # off value. For the time being, though, we will convert it
+        # into an Array, as that seems easier.
+        # =================================================================== #
+        sorted = dataset.sort_by {|a, b| ::Time.parse(b[:already_solved_at]) }.reverse
+        dataset = []
+        sorted.each {|a, b|
+          dataset << b[:grade].to_s
+        }
+        dataset = dataset[0 .. (@internal_hash[:filter_first]-1)]
+      end
+    end
+    if filter_last?
+      # Usage example: avgrade --last=50 --local
+      if dataset.is_a? Array # this is the case for when we want to use the local file
+        dataset = dataset.last(filter_last?)
+      elsif dataset.is_a? Hash
+        # =================================================================== #
+        # In this case we must sort it via timestamp, and then do a cut
+        # off value. For the time being, though, we will convert it
+        # into an Array, as that seems easier.
+        # =================================================================== #
+        sorted = dataset.sort_by {|a, b| ::Time.parse(b[:already_solved_at]) }.reverse
+        dataset = []
+        sorted.each {|a, b|
+          dataset << b[:grade].to_s
+        }
+        dataset = dataset.last(filter_last?)
+      end
+    end
+    determine_the_average_grade_from_these_passed_exams(dataset)
+    report
+  end
+
+  # ========================================================================= #
+  # === filter_last?
+  # ========================================================================= #
+  def filter_last?
+    @internal_hash[:filter_last]
+  end
+
+  # ========================================================================= #
+  # === report                                                   (report tag)
+  # ========================================================================= #
+  def report
+    e steelblue(average_grade?) if be_verbose?
+  end
+
+  # ========================================================================= #
+  # === average_grade?
+  # ========================================================================= #
+  def average_grade?
+    @internal_hash[:average_grade]
+  end
+
+  # ========================================================================= #
+  # === show_help                                                  (help tag)
+  # ========================================================================= #
+  def show_help
+    e
+    e 'The following options have been documented:'
+    e
+    e '  --use-local-file # use the local .csv file; '\
+      'this only works on my home system'
+    e '  --first=100      # use the first 100 passed exams'
+    e '  --last=50        # use the last 50 passed exams' 
+    e
+  end
+
+  # ========================================================================= #
+  # === Studium::Exams::AverageGrade[]
+  # ========================================================================= #
+  def self.[](i = ARGV)
+    new(i)
+  end
+
+end; end
+
+# =========================================================================== #
+# === Studium.average_grade
+#
+# This method will usually return a Float value, being the average grade
+# of ALL successfully completed lectures.
+#
+# The method has two modes:
+#
+#   (a) if the file .csv exists, it will be used
+#   (b) otherwise, the method will simply make use of the file
+#      'lecture_information.yml'
+#
+# The variant in (a) is mostly used on my home system; the variant in
+# (b) will be what other people should use. In the long run, (b) is
+# the recommended way to obtain output.
+#
+# Since as of December 2022, during the re-write and addition of
+# class AverageGrade, option b) is now the default. A commandline
+# flag exists to use a .csv file, just for my home system.
+# =========================================================================== #
+def self.average_grade(
+    use_csv_file_or_lecture_information = :determine_automatically,
+    round_to_n_positions                = nil
+  )
+  _ = Studium::Exams::AverageGrade.new(:do_not_run_yet) { :be_quiet }
+  _.use_this_dataset_location = use_csv_file_or_lecture_information
+  _.round_to_n_positions = round_to_n_positions
+  _.run
+  return _.average_grade?
+end
+
+# ========================================================================= #
+# === Studium.report_average_grade
+#
+# This method will simply report the avera grade of the passed exams
+# in question.
+# ========================================================================= #
+def self.report_average_grade(
+    use_csv_file_or_lecture_information = :determine_automatically,
+    round_to_n_positions                = nil
+  )
+  puts Studium.steelblue(
+    Studium.average_grade(
+      use_csv_file_or_lecture_information, round_to_n_positions
+    )
+  )
+end
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  Studium::Exams::AverageGrade.new(ARGV)
+  # Studium.report_average_grade(:default, 2)
+end # averagegrade --help