studium 0.18.7

data/lib/studium/ects/search_for_n_ects/search_for_n_ects.rb

@@ -0,0 +1,719 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# === Studium::ECTS::SearchFor_nECTS
+#
+# This class will simply output which lectures have exactly n ECTS points,
+# such as "1.5".
+#
+# It will first show it for lectures that were completed successfully,
+# if applicable; and if not, the class here will search for other lectures
+# stored in the file "lecture_information". It will NOT report duplicate
+# entries, but it will in general show if a lecture is in bachelor
+# or master - but also bachelor AND master.
+#
+# Usage example from within Ruby code:
+#
+#   Studium::SearchFor_nECTS.new
+#
+# Usage example from the commandline:
+#
+#   nects 2.0 --prüfungsimmanent
+#
+# =========================================================================== #
+# require 'studium/ects/search_for_n_ects/search_for_n_ects.rb'
+# Studium::ECTS::SearchFor_nECTS[1.5]
+# =========================================================================== #
+require 'studium/base/base.rb'
+
+module Studium
+
+module ECTS
+
+class SearchFor_nECTS < Base # === Studium::ECTS::SearchFor_nECTS
+
+  # ========================================================================= #
+  # === initialize
+  # ========================================================================= #
+  def initialize(
+      i           = ARGV,
+      run_already = true
+    )
+    reset
+    set_commandline_arguments(i)
+    run if run_already
+  end
+
+  # ========================================================================= #
+  # === reset                                                     (reset tag)
+  # ========================================================================= #
+  def reset
+    super()
+    infer_the_namespace
+    # ======================================================================= #
+    # === :show_numbers
+    #
+    # If this variable is set to true then the leading LVA ID numbers
+    # will be shown as well on the commandline. This is especially
+    # useful if the user has to copy/paste these numbers to other
+    # programs.
+    #
+    # Since as of 31.01.2020 the default is to set this to true.
+    # ======================================================================= #
+    @internal_hash[:show_numbers] = true
+    # ======================================================================= #
+    # === :apply_these_filters
+    #
+    # This variable (as Array) keeps track of all filters we desire to
+    # apply.
+    # ======================================================================= #
+    @internal_hash[:apply_these_filters] = []
+    # ======================================================================= #
+    # === :index_counter
+    # ======================================================================= #
+    @internal_hash[:index_counter] = 0 # ← Is valid for the whole class.
+    # ======================================================================= #
+    # === :original_dataset
+    # ======================================================================= #
+    @internal_hash[:original_dataset] = dataset_from_file_lecture_information
+    # ======================================================================= #
+    # === :have_we_found_any_lecture_that_fits
+    # ======================================================================= #
+    @internal_hash[:have_we_found_any_lecture_that_fits] = false
+  end
+
+  # ========================================================================= #
+  # === select_for_n_ects_points?
+  # ========================================================================= #
+  def select_for_n_ects_points?
+    @internal_hash[:select_for_n_ects_points]
+  end; alias seeking_n_ects_points? select_for_n_ects_points? # === seeking_n_ects_points?
+       alias n_ects_points?         select_for_n_ects_points? # === n_ects_points?
+
+  # ========================================================================= #
+  # === we_have_found_a_lecture_that_fits
+  # ========================================================================= #
+  def we_have_found_a_lecture_that_fits
+    @internal_hash[:have_we_found_any_lecture_that_fits] = true
+  end
+
+
+  # ========================================================================= #
+  # === colourized_display_of_this_matching_lecture
+  #
+  # The second argument to this method is the Hash that contains
+  # all the useful information from the file "lecture_information.yml". 
+  # ========================================================================= #
+  def colourized_display_of_this_matching_lecture(
+      name,
+      inner_hash,
+      &block
+    )
+    curricula_entry    = inner_hash['curricula']
+    at_this_university = inner_hash[:university]
+    lecture_type       = inner_hash[:type]
+    # ======================================================================= #
+    # The shorter_name_of_the_lecture variable in particular does NOT
+    # include the leading LVA ID number.
+    # ======================================================================= #
+    shorter_name_of_the_lecture = name.split(' ')[1..-1].join(' ').strip
+    if show_numbers?
+      shorter_name_of_the_lecture = name
+    end
+    padded_index = ("#{index_counter?.to_s})").rjust(4)
+    colourized_and_padded_index = slateblue(padded_index)
+    # ======================================================================= #
+    # Next display that information to the user:
+    # ======================================================================= #
+    result = colourized_and_padded_index+' '+
+             sfancy(shorter_name_of_the_lecture.ljust(88))+' '+ # <- Report the individual name.
+             colourize_the_lecture_type_in_crimson_or_in_brown(
+               report_bachelor_or_master_curricula(curricula_entry).ljust(5)
+             )+
+             mediumseagreen(at_this_university.center(12))+' '+
+             mediumturquoise("[#{lecture_type.to_s}]")
+    if block_given?
+      yielded = yield
+      case yielded
+      # ===================================================================== #
+      # === :use_the_unicode_checkmark_symbol
+      # ===================================================================== #
+      when :use_the_unicode_checkmark_symbol
+        result = result.dup if result.frozen?
+        result << lightskyblue(" #{UNICODE_CHECKMARK}")
+      end
+    end
+    e result
+  end
+
+  # ========================================================================= #
+  # === apply_filters_should_they_exist
+  #
+  # The filters that are applied here will always modify the current
+  # dataset.
+  # ========================================================================= #
+  def apply_filters_should_they_exist(
+      apply_these_filters = apply_these_filters?
+    )
+    if apply_these_filters
+      apply_these_filters.each {|this_filter|
+        case this_filter
+        # ================================================================= #
+        # === :only_solved
+        # ================================================================= #
+        when :only_solved
+          set_current_dataset return_only_solved_lectures_from_this_dataset(current_dataset?)
+        # ================================================================= #
+        # === :only_BOKU_lectures
+        # ================================================================= #
+        when :only_BOKU_lectures
+          set_current_dataset return_only_BOKU_lectures_from_this_dataset(current_dataset?)
+        # ================================================================= #
+        # === :only_vetmed_lectures
+        # ================================================================= #
+        when :only_vetmed_lectures
+          set_current_dataset return_only_vetmed_lectures_from_this_dataset(current_dataset?)
+        # ================================================================= #
+        # === :only_master_lectures
+        # ================================================================= #
+        when :only_master_lectures
+          set_current_dataset return_only_master_lectures_from_this_dataset(current_dataset?)
+        # ================================================================= #
+        # === :only_bachelor_lectures
+        # ================================================================= #
+        when :only_bachelor_lectures
+          set_current_dataset return_only_bachelor_lectures_from_this_dataset(current_dataset?)
+        else
+          if is_on_roebe?
+            opne tomato('Warning: unhandled symbol '+
+                 steelblue(':'+this_filter.to_s))
+          end
+        end
+      }
+    end
+  end
+
+  # ========================================================================= #
+  # === return_only_solved_lectures_from_this_dataset
+  # ========================================================================= #
+  def return_only_solved_lectures_from_this_dataset(
+      i = current_dataset?
+    )
+    selection = i.select {|name, hash|
+      already_solved = hash[:already_solved]
+      (already_solved == true) # Select lectures that were solved already here.
+    }
+    return selection
+  end
+
+  # ========================================================================= #
+  # === select_all_entries_that_match_the_criterium
+  #
+  # This is a general filter where we obtain the lectures that can match
+  # to the given n ECTS criterium, first and foremost.
+  # ========================================================================= #
+  def select_all_entries_that_match_the_criterium(
+      select_for_n_ects_points = select_for_n_ects_points?,
+      apply_these_filters      = apply_these_filters?
+    )
+    # ======================================================================= #
+    # We have to go through the original dataset next, in order to determine
+    # the current dataset:
+    # ======================================================================= #
+    set_current_dataset(
+      original_dataset?.select {|name_of_the_lecture, inner_hash|
+        n_ects_points = inner_hash[:ects]
+        curricula     = inner_hash['curricula']
+        # ===================================================================== #
+        # Apply another round of filtering, if the user instructed us to do so.
+        # This will handle only-bachelor and only-master lectures.
+        # ===================================================================== #
+        if    apply_these_filters and apply_these_filters.include? :only_master_lectures
+          (select_for_n_ects_points == n_ects_points) and has_a_master_curriculum?(curricula)
+        elsif apply_these_filters and apply_these_filters.include? :only_bachelor_lectures
+          (select_for_n_ects_points == n_ects_points) and has_a_bachelor_curriculum?(curricula)
+        else
+          select_for_n_ects_points == n_ects_points
+        end
+      }
+    )
+  end
+
+  # ========================================================================= #
+  # === is_a_bachelor_lecture?
+  #
+  # Input to this method must be an Array.
+  #
+  # This method will return a boolean depending on whether the given
+  # input is a bachelor-curriculum or whether it is not.
+  #
+  # The lecture is assumed to be a bachelor curriculum if it starts
+  # with any of the following input:
+  #
+  #   '033'
+  #   '193'
+  #   '198'
+  #
+  # ========================================================================= #
+  def is_a_bachelor_lecture?(i)
+    result = false
+    if i
+      result = i.any? {|entry|
+        entry.start_with?('033') or
+        entry.start_with?('193') or
+        entry.start_with?('198')
+      }
+    else
+      e 'No value was supplied. Call stack is:'; print '  '
+      pp caller()
+    end
+    return result
+  end; alias has_a_bachelor_lecture? is_a_bachelor_lecture? # === has_a_bachelor_lecture?
+
+  # ========================================================================= #
+  # === current_dataset?
+  #
+  # This is the dataset we are working with.
+  # ========================================================================= #
+  def current_dataset?
+    @internal_hash[:current_dataset]
+  end
+
+  # ========================================================================= #
+  # === set_current_dataset
+  # ========================================================================= #
+  def set_current_dataset(i)
+    @internal_hash[:current_dataset] = i
+  end
+
+  # ========================================================================= #
+  # === do_show_the_numbers
+  # ========================================================================= #
+  def do_show_the_numbers
+    @internal_hash[:show_numbers] = true
+  end
+
+  # ========================================================================= #
+  # === menu                                                      (menu tag)
+  # ========================================================================= #
+  def menu(
+      i = commandline_arguments?
+    )
+    if i.is_a? Array
+      i.each {|entry| menu(entry) }
+    else
+      case i # case tag
+      # ===================================================================== #
+      # === nECTS 1.0 --only-solved
+      #
+      # This can also be combined, of course:
+      #
+      #   nECTS 1.0 --only-solved --only-bachelor
+      #
+      # ===================================================================== #
+      when /^-?-?only(-|_)?solved$/i,
+           /^-?-?solved$/i
+        append_to_the_filter :only_solved
+      # ===================================================================== #
+      # === --only-master
+      # ===================================================================== #
+      when /^-?-?only(-|_)?master$/,
+           /^-?-?master$/
+        append_to_the_filter :only_master_lectures
+      # ===================================================================== #
+      # === nects 2.0 --prüfungsimmanent?
+      # ===================================================================== #
+      when /^-?-?prüfungsimmanent\??/i,
+           /^-?-?mandatory\??/i
+        # =================================================================== #
+        # Do another selection on the main dataset next:
+        # =================================================================== #
+        current_dataset?.select! {|name_of_the_lecture, inner_dataset|
+          type = inner_dataset[:type]
+          is_prüfungsimmanent? type # The actual check.
+        }
+      # ===================================================================== #
+      # === --only-bachelor
+      # ===================================================================== #
+      when /^-?-?only(-|_)?bachelor$/,
+           /^-?-?bachelor$/
+        append_to_the_filter :only_bachelor_lectures
+      # ===================================================================== #
+      # === nECTS 2.0 --BOKU
+      # ===================================================================== #
+      when /^-?-?BOKU$/i
+        append_to_the_filter :only_BOKU_lectures
+      # ===================================================================== #
+      # === nECTS 2.0 --vetmed
+      # ===================================================================== #
+      when /^-?-?vetmed/
+        append_to_the_filter :only_vetmed_lectures
+      # ===================================================================== #
+      # === --show-numbers
+      # ===================================================================== #
+      when /^-?-?show(-|_)?numbers$/i,
+           /^-?-?numbers$/i
+        do_show_the_numbers
+      # ===================================================================== #
+      # === help
+      #
+      # Invocation example:
+      #
+      #   nects --help
+      #
+      # ===================================================================== #
+      when /^-?-?help$/i
+        show_help
+        exit
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === try_to_report_unfinished_bachelor_entries_that_match
+  # ========================================================================= #
+  def try_to_report_unfinished_bachelor_entries_that_match
+    return if apply_these_filters?.include? :only_master_lectures
+    selection = current_dataset?.select {|name, inner_hash|
+      curricula = inner_hash['curricula']
+      is_a_bachelor_lecture?(curricula)
+    }
+    if selection.empty?
+    else
+      we_have_found_a_lecture_that_fits
+      e rev+'The following '+sfancy(selection.size.to_s)+
+        ' '+return_lecture_is_or_lecture_are(selection.keys.size)+
+        ' part of a '+mediumpurple('bachelor curriculum')+'.'
+      e
+      selection.each {|name, inner_hash| increment_the_index_counter # Increment the index counter.
+        colourized_display_of_this_matching_lecture(name, inner_hash)
+      }
+      e
+      # ===================================================================== #
+      # Also remove these entries.
+      # ===================================================================== #
+      current_dataset?.reject! {|name, inner_hash|
+        curricula = inner_hash['curricula']
+        is_a_bachelor_lecture?(curricula)
+      }
+    end
+  end
+
+  # ========================================================================= #
+  # === return_lecture_is_or_lecture_are
+  # ========================================================================= #
+  def return_lecture_is_or_lecture_are(i)
+    if i > 1
+      'lectures are'
+    else
+      'lecture is'
+    end
+  end
+
+  # ========================================================================= #
+  # === return_only_vetmed_lectures_from_this_dataset
+  # ========================================================================= #
+  def return_only_vetmed_lectures_from_this_dataset(i)
+    selection = i.select {|name, hash|
+      this_university = hash[:university].to_s
+      this_university == 'Vetmed' # Select lectures at the Vetmed here.
+    }
+    return selection
+  end
+
+  # ========================================================================= #
+  # === notify_the_user_if_we_have_not_found_any_lecture_that_fits
+  # ========================================================================= #
+  def notify_the_user_if_we_have_not_found_any_lecture_that_fits
+    unless @internal_hash[:have_we_found_any_lecture_that_fits]
+      e "No result was found for #{sfancy(n_ects_points?)} ECTS points."
+    end
+  end
+
+  # ========================================================================= #
+  # === colourize_the_lecture_type_in_crimson_or_in_brown
+  # ========================================================================= #
+  def colourize_the_lecture_type_in_crimson_or_in_brown(i)
+    case i.strip
+    when 'B'
+      crimson(i)
+    else
+      brown(i)
+    end
+  end
+
+  # ========================================================================= #
+  # === report_bachelor_or_master_curricula
+  #
+  # The input to this method should be an Array holding the
+  # dataset for the Curricula (Bachelor or Master).
+  #
+  # If it is part of a bachelor curriculum then a 'B' will be appended
+  # to the resulting string; if it is a master curriculum then a 'M'
+  # will be appended.
+  # ========================================================================= #
+  def report_bachelor_or_master_curricula(i)
+    result = ''.dup
+    if i
+      if i.any? {|entry|
+          entry.start_with?('033')
+        }
+        result << 'B'
+      end
+      if i.any? {|entry|
+          entry.start_with?('066')
+        }
+        unless result.empty?
+          result << '/' # Add a separator in this case.
+        end
+        result << 'M'
+      end
+    else
+      e 'No value was supplied. Call stack is:'
+      pp caller()
+    end
+    return result
+  end
+
+  # ========================================================================= #
+  # === original_dataset?
+  #
+  # This will return the original dataset from the file called
+  # lecture_information.yml.
+  # ========================================================================= #
+  def original_dataset?
+    @internal_hash[:original_dataset]
+  end
+
+  # ========================================================================= #
+  # === return_only_BOKU_lectures_from_this_dataset
+  # ========================================================================= #
+  def return_only_BOKU_lectures_from_this_dataset(i)
+    selection = i.select {|name, hash|
+      this_university = hash[:university].to_s
+      this_university == 'BOKU' # Select lectures at the BOKU here.
+    }
+    return selection
+  end
+
+  # ========================================================================= #
+  # === return_only_bachelor_lectures_from_this_dataset
+  # ========================================================================= #
+  def return_only_bachelor_lectures_from_this_dataset(i)
+    i.select {|name, hash|
+      curricula = hash['curricula']
+      curricula.any? {|most_inner_entry|
+        most_inner_entry.start_with? '033'
+      }
+    }
+  end
+
+  # ========================================================================= #
+  # === return_only_master_lectures_from_this_dataset
+  # ========================================================================= #
+  def return_only_master_lectures_from_this_dataset(i)
+    i.select {|name, hash|
+      curricula = hash['curricula']
+      curricula.any? {|most_inner_entry|
+        most_inner_entry.start_with? '066'
+      }
+    }
+  end
+
+  # ========================================================================= #
+  # === apply_these_filters?
+  # ========================================================================= #
+  def apply_these_filters?
+    @internal_hash[:apply_these_filters]
+  end; alias filters? apply_these_filters? # === filters?
+
+  # ========================================================================= #
+  # === increment_the_index_counter
+  # ========================================================================= #
+  def increment_the_index_counter(by = 1)
+    @internal_hash[:index_counter] += by
+  end
+
+  # ========================================================================= #
+  # === index_counter?
+  # ========================================================================= #
+  def index_counter?
+    @internal_hash[:index_counter]
+  end
+
+  # ========================================================================= #
+  # === show_numbers?
+  # ========================================================================= #
+  def show_numbers?
+    @internal_hash[:show_numbers]
+  end
+
+  # ========================================================================= #
+  # === append_to_the_filter
+  # ========================================================================= #
+  def append_to_the_filter(i)
+    @internal_hash[:apply_these_filters] << i
+  end
+
+  # ========================================================================= #
+  # === show_help                                                  (help tag)
+  # ========================================================================= #
+  def show_help
+    e
+    e '  --only-bachelor      # show only bachelor-lectures'
+    e '  --only-master        # show only master-lectures'
+    e '  --only-solved        # show only solevd lectures, aka '\
+      'which were already passed successfully'
+    e '  --prüfungsimmanent?  # show only "prüfungsimmanente" '\
+      'lectures (== mandatoy presence courses)'
+    e '  --show-numbers       # If this flag is used then the '\
+      'leading LVA ID numbers are shown as well.'
+    e
+  end
+
+  # ========================================================================= #
+  # === set_select_for_n_ects_points
+  # ========================================================================= #
+  def set_select_for_n_ects_points(i = '')
+    i = [i] unless i.is_a? Array
+    i = i.first.to_s.to_f
+    @internal_hash[:select_for_n_ects_points] = i
+  end
+
+  # ========================================================================= #
+  # === parse_the_commandline_arguments
+  # ========================================================================= #
+  def parse_the_commandline_arguments
+    _ = commandline_arguments?.reject {|entry| entry.start_with?('--') }.first
+    set_select_for_n_ects_points(_)
+  end
+
+  # ========================================================================= #
+  # === try_to_report_those_entries_first_that_were_already_passed
+  # ========================================================================= #
+  def try_to_report_those_entries_first_that_were_already_passed
+    _ = current_dataset?.select {|name, inner_hash|
+      inner_hash[:already_solved]
+    }
+    if _.empty?
+    else
+      we_have_found_a_lecture_that_fits
+      e
+      # ===================================================================== #
+      # Apply a filter if the user set one.
+      # ===================================================================== #
+      if apply_these_filters?
+        apply_these_filters?.each {|this_filter|
+          case this_filter
+          # ================================================================= #
+          # === :only_solved
+          # ================================================================= #
+          when :only_solved
+            _ = return_only_solved_lectures_from_this_dataset(_)
+          # ================================================================= #
+          # === :only_BOKU_lectures
+          # ================================================================= #
+          when :only_BOKU_lectures
+            _ = return_only_BOKU_lectures_from_this_dataset(_)
+          # ================================================================= #
+          # === :only_vetmed_lectures
+          # ================================================================= #
+          when :only_vetmed_lectures
+            _ = return_only_vetmed_lectures_from_this_dataset(_)
+          # ================================================================= #
+          # === :only_master_lectures
+          # ================================================================= #
+          when :only_master_lectures
+            _ = return_only_master_lectures_from_this_dataset(_)
+          # ================================================================= #
+          # === :only_bachelor_lectures
+          # ================================================================= #
+          when :only_bachelor_lectures
+            _ = return_only_bachelor_lectures_from_this_dataset(_)
+          end
+        }
+      end
+      # ===================================================================== #
+      # In this case, report these.
+      # ===================================================================== #
+      result = ("#{rev}The following #{sfancy(_.size.to_s)}").dup
+      if _.size > 1
+        result << ' lectures have '
+      else
+        result << ' lecture has '
+      end
+      result << lightskyblue(seeking_n_ects_points?.to_s)+' ECTS point '\
+                'and '
+      if _.size > 1
+        result << 'were'
+      else
+        result << 'was'
+      end
+      result << ' already passed:'
+      e result
+      e
+      _.each {|name, inner_hash| increment_the_index_counter # Increment the index counter.
+        colourized_display_of_this_matching_lecture(name, inner_hash) { :use_the_unicode_checkmark_symbol }
+      }
+      e
+      # ===================================================================== #
+      # And get rid of them too, since we already reported them.
+      # ===================================================================== #
+      current_dataset?.reject! {|name, inner_hash|
+        inner_hash[:already_solved]
+      }
+    end
+  end
+
+  # ========================================================================= #
+  # === try_to_report_unfinished_master_entries_that_match
+  # ========================================================================= #
+  def try_to_report_unfinished_master_entries_that_match
+    _ = current_dataset?
+    return if apply_these_filters?.include? :only_bachelor_lectures
+    if _.empty?
+    else
+      we_have_found_a_lecture_that_fits
+      e "#{rev}The following #{sfancy(_.size.to_s)}"\
+        " #{return_lecture_is_or_lecture_are(_.size)}"\
+        " part of a #{mediumpurple('master curriculum')} only."
+      e
+      _.each {|name, inner_hash| increment_the_index_counter # Increment the index counter.
+        colourized_display_of_this_matching_lecture(name, inner_hash)
+      }
+      e
+    end
+  end
+
+  # ========================================================================= #
+  # === run                                                         (run tag)
+  # ========================================================================= #
+  def run
+    parse_the_commandline_arguments # First, make sense of the commandline-arguments given to this class.
+    select_all_entries_that_match_the_criterium # <- Next, obtain the entries that match.
+    menu
+    apply_filters_should_they_exist
+    try_to_report_those_entries_first_that_were_already_passed
+    try_to_report_unfinished_bachelor_entries_that_match
+    try_to_report_unfinished_master_entries_that_match
+    notify_the_user_if_we_have_not_found_any_lecture_that_fits
+  end
+
+  # ========================================================================= #
+  # === Studium::SearchFor_nECTS[]
+  #
+  # Usage example:
+  #
+  #   Studium::SearchFor_nECTS[1.5]
+  #
+  # ========================================================================= #
+  def self.[](i = ARGV)
+    new(i)
+  end
+
+end; end; end
+
+if __FILE__ == $PROGRAM_NAME
+  Studium::ECTS::SearchFor_nECTS.new(ARGV)
+end # nECTS 1.5 --only-solved