docfolio 0.0.1 → 0.0.2

data/lib/docfolio/paragraph_modules/date_times.rb

@@ -0,0 +1,10 @@
+require_relative 'dates'
+require_relative 'times'
+
+# @param [Array] time_array updated start and end times in hours and minutes
+# @param [Array] times_and_dates current start and end times and date
+# @return [Array] returns the new times_and_dates array for use going forwards
+module DateTimes
+  include Times
+  include Dates
+end

data/lib/docfolio/paragraph_modules/dates.rb

@@ -0,0 +1,169 @@
+# convert the date from 'dd-Oct-yy' to seconds past UNIX epoc
+# accepts dd_Mmm-yy  dd-Mmmmmmm-yy  dd-MMM-yy and other similar
+module Dates
+  # Extracts a date in seconds past UNIX epoc from a string date. The result
+  # can be used for other date operations. Converts from dd-mmm-yy and similar
+  # formats as commonly found in csv files
+  class DateFormatter
+    def format_date(date)
+      day, month, year = components(date)
+      begin
+        Time.new(year, month, day).to_i
+      rescue ArgumentError => e
+        print_argument_error_msg(e)
+        return nil
+      rescue => e
+        raise e
+      end
+    end
+
+    private
+
+    def print_argument_error_msg(e)
+      puts "\n#{e.to_s.upcase}"
+      puts "date  : #{date.inspect}"
+      puts "day   : #{day}"
+      puts "month : #{month}"
+      puts "year  : #{year}"
+      puts e.backtrace
+    end
+
+    # splits date into is component day month and time
+    def components(date)
+      date = date.split('-')
+      day = date[0].to_i
+      month = convert_month_to_number(date[1])
+      year = date[2].to_i
+      if year < 100 # no century
+        year > Time.now.year % 1000 ? century = 1900 : century = 2000
+        year += century
+      end
+      [day, month, year]
+    end
+
+    # A hash of text months and their corresponding month number
+    MONTHS = {
+      'jan' => 1,
+      'feb' => 2,
+      'mar' => 3,
+      'apr' => 4,
+      'may' => 5,
+      'jun' => 6,
+      'jul' => 7,
+      'aug' => 8,
+      'sep' => 9,
+      'oct' => 10,
+      'nov' => 11,
+      'dec' => 12,
+      'january' => 1,
+      'february' => 2,
+      'march' => 3,
+      'april' => 4,
+      'june' => 6,
+      'july' => 7,
+      'august' => 8,
+      'september' => 9,
+      'october' => 10,
+      'november' => 11,
+      'december' => 12,
+      'sept' => 9
+    }
+
+    # Takes a text month to its corresponding number, case insensitive
+    # @param [String] month Month of year in text
+    # @return [Integer] Number of month in calander e.g. Feb is 2
+    def convert_month_to_number(month)
+      return month.to_i if month.to_i > 0 # already a number
+      month = month.downcase
+      MONTHS[month]
+    end
+  end
+
+  class DateExtractor
+    # The $LAST_MATCH_INFO global is equivalent to Rexexp.last_match and
+    # returns a MatchData object. This can be used as an array, where indices
+    # 1 - n are the matched backreferences of the last successful match
+    # @param [String] paragraph_text a paragraph from a DSL text file
+    # @param [Time] date Date of this paragraph. May be nil if not known.
+    #  This date is taken from the Date class instance variable of the
+    #  paragraph class.
+    # @return [Array<String, Array, Time>] Array of values to be returned
+    # [String return value] 'paragraph_text' the same paragraph that was passed to the function but without the matched date character if there were any.
+    # [Array return value] 'time_array' array of 4 integer representing the hours and minutes of the from and to times
+    # [Time return value] 'date' the date in (day month year) of this paragraph taken from the matched date_regex if there was one. Will be nil if there was no match and if the date passed to the function was also nil.
+    def extract_date(paragraph_text, date)
+      time_array = []
+
+      # if text contains a date match
+      if date_regex =~ paragraph_text
+        # $POSTMATCH (or $'), contains the characters after the match position
+        paragraph_text = $POSTMATCH
+
+        # strip whitespace if any remaining match or set to empty string
+        # if no match. If there is just white space after the match then
+        # this is truncated to an empty string
+        paragraph_text.nil? ? paragraph_text = '' : paragraph_text.strip!
+
+        # extracts the 'from' and 'to' times from the last match above. the
+        # time_array contains from_hour, from_min, to_hour, to_min, the
+        # date parameter is updated if the match found a new date
+        time_array, date = date_from_globals($LAST_MATCH_INFO, date)
+      end
+      [paragraph_text, time_array, date]
+    end
+
+    private
+
+    # Extracts a particular parameter from the MatchData object return when the
+    # paragraph was matched with the date regex. Treats the MatchData
+    # as an array, iterating through each index represented in the i_a
+    # array to find and return a value if there is one.
+    # @param [Array] i_a Array of integers representing positions to test in
+    #  array glob_a
+    # @param [MatchData] glob_a Array of matched backreferences of the last
+    #  successful regular expression match
+    # @return the first element in MatchData that is not nil. Returns
+    #  nil if there are no elements in MatchData at the indices in i_a that
+    #  are not nil.
+    def glob(i_a, glob_a)
+      i_a.each { |n| return glob_a[n] unless glob_a[n].nil? }
+      nil
+    end
+
+    # returns a date from the 26 globals returned by date_regex
+    # @param [MatchData] glob_a the MatchData object return when the date_regex
+    #  was matched to the paragraph
+    # @param [Time] date the date of the paragraph; may be nil if not known
+    # @return [Array] array of 4 integer representing the
+    #  hours and minutes of the from and to times
+    # @return [Time] 'date' the date (day month year) of this paragraph
+    def date_from_globals(glob_a, date)
+      from_hour = glob([1, 23], glob_a)
+      from_min  = glob([2, 24], glob_a)
+      to_hour   = glob([3, 25], glob_a)
+      to_min    = glob([4, 26], glob_a)
+      day       = glob([5, 8, 12, 14, 17, 21], glob_a)
+      month     = glob([6, 9, 11, 15, 18, 20], glob_a)
+      year      = glob([7, 10, 13, 16, 19, 22], glob_a)
+      date = Time.at(DateFormatter.new.format_date("#{day}-#{month}-#{year}")) unless day.nil?
+      [[from_hour, from_min, to_hour, to_min], date]
+    end
+
+    # Returns a regular expression to be used to match dates and times of
+    # the paragraph.
+    # @return [Regex] a regular expression to use to match dates and times
+    #  in the paragraph
+    def date_regex
+      dy      = /(?<day>\d{1,2})/
+      mt      = /(?<month>\w+)/
+      yr      = /(?<year>\d{2,4})/
+      time    = /(?<hour>\d{1,2}):(?<min>\d{2})/
+      period  = /#{time}( ?(?:-|–|to) ?#{time})?/
+      date1   = %r{#{dy}/#{dy}/#{yr}}     # d/m/y
+      date2   = /#{dy},? #{mt},? #{yr}/   # d Month Year
+      date3   = /#{mt},? #{dy},? #{yr}/   # Month d Year
+      date    = /#{date1}|#{date2}|#{date3}/
+      /^(#{period} ?#{date}?|#{date} ?#{period}?)/
+    end
+  end
+end

data/lib/docfolio/paragraph_modules/tags.rb

@@ -0,0 +1,194 @@
+require 'English'
+
+# handles extraction of tagged or other significant content.
+module TaggedContent
+  class TagExtractor
+    attr_reader :tags
+
+    def initialize
+      @tags =  []
+    end
+
+    # Declaration of the class instance variable 'section'. The section is
+    # the tag applied to content if no user tag is detect. It changes depending
+    # on the position in the document.
+    class << self
+      attr_accessor :section
+    end
+
+    # resets the class variables so that a new file can be parsed
+    # is called by LearningDiary (through Paragraph) when preparing
+    # to parse a new txt file
+    def self.reset
+      TagExtractor.section = 0 # :TITLE
+    end
+
+    def self.all_tags
+      SECTIONS + TAGS
+    end
+
+    def extract_content(rest_of_str)
+      # if a new date or time has not been found then return
+      return if rest_of_str == ''
+
+      @old_tags = @tags
+      @tags += extract_tags(rest_of_str)
+
+      if tags_extracted?
+        # As soon as tags are extracted, there can only be note internal
+        # paragraph sections
+        TagExtractor.section = 2 #:NOTE
+      else
+        # No tags have been extracted from the str, so use the paragraphs
+        # current section
+        tag_as_section(rest_of_str)
+      end
+    end
+
+    # returns true if any tags are of type tag
+    # @param [Array] tag An array of tags
+    def tag?(tag)
+      @tags.each { |t| return true if t[0] == tag }
+      false
+    end
+
+    # Joins all content in @tags of with a tag of type tag
+    # @param [Symbol] tag The tag for which content that should be selected.
+    # @param [String] str An optional string that can be passed to the function
+    #  to which selected content will be appended.
+    def content(tag, str = '')
+      tag_index = 0
+      content_index = 1
+      @tags.each { |t| str << t[content_index] + ' ' if t[tag_index] == tag }
+      str
+    end
+
+    # true if the paragraph contains a tag that can earn credit
+    def creditable?
+      tags.each { |t| return true if CREDITABLE.include?(t[0]) }
+      false
+    end
+
+    # true if the paragraph contains a tag used in significant events
+    # i.e. is the learning diary a significant event?
+    def significant_event?
+      tags.each { |t| return true if SIG_EVENT.include?(t[0]) }
+      false
+    end
+
+    # true if the paragraph contains a tag that can earn impact credit
+    def impact_creditable?
+      tags.each { |t| return true if t[0] == :I }
+      false
+    end
+
+    private
+
+    # Tags that are used in significant events
+    SIG_EVENT = [:SEA, :INVOLVED, :WHAT, :WHY, :FEELINGS, :WELL, :DIFFERENT, :CHANGE, :CHANGED]
+
+    # Tags that are used in learning logs
+    LEARNING_LOG = [:LP, :R, :DEN, :NOTE, :I]
+
+    # Tags that are part of the DSL and are recognized in text
+    TAGS = LEARNING_LOG + SIG_EVENT
+
+    # Tags that can earn CPD credit
+    CREDITABLE = [:LP, :R, :I, :HF, :WW, :WD]
+
+    # Tags that are applied to content based on the position in the document
+    SECTIONS = [:TITLE, :INTRO, :NOTE]
+
+    # Extracts a paragraph string to a tagged array with elements of type
+    # [:tag, 'content']. Called after the date/time info has been removed. If
+    # called before, will result in date info at the start being tagged as
+    # a :NOTE
+    # @param [String] paragraph_text Paragraph string after date info removed
+    # @return [Array] Tagged array
+    def extract_tags(paragraph_text)
+      tag_regex =~ paragraph_text ? extract_tag(paragraph_text) : []
+    end
+
+    # Add a single tagged content element of type
+    # [:symbol (tag), String (content)] to the @tags instance instance variable
+    # . Move the section class instance variable up one (to current :INTRO) if
+    # it is at position 0 (currently :TITLE)
+    # @param [String] p the content to tag
+    # @param [Symbol] tag the tag to use
+    def tag_it(tag, p)
+      @tags << [tag, p]
+      if  TagExtractor.section == 0 &&
+          TagExtractor.section != (SECTIONS.count - 1)
+        TagExtractor.section += 1
+      end
+    end
+
+    # Creates a regex that can be used to match for tags that are recognized
+    # as part of the DSL, currently :LP, :R, :DEN, :NOTE and :I
+    def tag_regex
+      /\b(#{ TAGS.join '|' }): ?/
+    end
+
+    # Paragraphs are broken down into a tagged array, with elements of type
+    # [:tag, 'text']. The first element of an array is of type string. If the
+    # paragraph begins with text before any tags, then this first element will
+    # contain this text, otherwise it will be an empty string. This function
+    # tests this string and returns it tagged as :NOTE unless empty in which
+    # case it returns an empty array []
+    # @param [Array] a An array of tagged content of the paragraph
+    # @return [Array] Another tagged array which is either empty, or just
+    #  contains a single tagged content of the text at the beginning if there
+    #  was any.
+    def preface_with_note(a)
+      str = a[0].strip
+      str == '' ? [] : [[:NOTE, str]]
+    end
+
+    # Turns an array of strings into a tagged array. Ignores the string
+    # variable at position [0]. This first string is turned into a tagged
+    # array element by the function
+    # #preface_with_note and appended in #extract_tag
+    # @param [Array] a Array of strings from splitting the paragraph
+    # @return [Array] A tagged array with elements of the form
+    #  [:tag, 'content']
+    def tags_array(a)
+      taggs = []
+      tag_count = (a.count - 1) / 2
+      1.upto(tag_count) do |i|
+        tag = a[(i * 2) - 1].to_sym
+        content = a[i * 2].strip
+        taggs << [tag, content]
+      end
+      taggs
+    end
+
+    # Splits the paragraph into an array of tags of type [:tag, 'content']
+    # @param [String] paragraph_text String text of the paragraph with any
+    #  date and time info at the beginning, removed
+    # @return [Array] Tagged array of content with elements of type
+    #  [:tag, 'content']
+    def extract_tag(paragraph_text)
+      a = paragraph_text.split(tag_regex)
+      preface_with_note(a) + tags_array(a)
+    end
+
+    # @return [Boolean] True if any tags have been extracted
+    def tags_extracted?
+      @old_tags.count < @tags.count
+    end
+
+    # Add a single tagged content element of type
+    # [:symbol (tag), String (content)] to the @tags instance instance variable
+    # using the current value of the section class instance variable as an
+    # index to reference the correct section tag symbol from the SECTIONS
+    # array. Does not tags content identified in the TAGS array.
+    # @param [String] str the content to tag
+    def tag_as_section(str)
+      tag_it(section_tag, str)
+    end
+
+    def section_tag
+      SECTIONS[TagExtractor.section]
+    end
+  end
+end

data/lib/docfolio/paragraph_modules/times.rb

@@ -0,0 +1,74 @@
+module Times
+  # processes new times and dates with current times and dates
+  class TimeProcesser
+    # Takes class start end times and dates as Time objects and amends the
+    # times, advancing the date if the start time has crossed midnight.
+    # @param [Array] new_times An array containing the from hour, from min,
+    #  to hour, to min
+    def process_times(new_times)
+      f_hour, f_min, t_hour, t_min = new_times
+      to_start_time(f_hour, f_min) if has f_hour
+      to_end_time(t_hour, t_min) if has t_hour
+    end
+
+    class << self
+      attr_accessor :st, :et, :date
+    end
+
+    # resets the class variables so that a new file can be parsed
+    # is called by LearningDiary (through Paragraph) when preparing
+    # to parse a new txt file
+    def self.reset
+      TimeProcesser.date = TimeProcesser.st = TimeProcesser.et = nil
+    end
+
+    private
+
+    # Set the end time to the current paragraph date at t_hour and t_min.
+    # If the end time is before the start time, assume the end time is for the
+    # next day and add a day.
+    # @param [Number] t_hour To hours
+    # @param [Number] t_min To minutes
+    def to_end_time(t_hour, t_min)
+      # extract_time_object simply adds hours and mins to date
+      TimeProcesser.et = extract_time_object(t_hour, t_min, TimeProcesser.date)
+      # if end_time before start_time, assume it is the following day
+      TimeProcesser.et += a_day if TimeProcesser.et < TimeProcesser.st
+    end
+
+    # Adds hours and mins to date (Time). Then adds a day if the start time is
+    # before the end time. Finally, makes end time nil
+    def to_start_time(hour, min)
+      # extract_time_object simply adds hours and mins to date
+      TimeProcesser.st = extract_time_object(hour, min, TimeProcesser.date)
+    end
+
+    # Improves readability of boolean condition statements. Is used from Time
+    # objects and integer hour component, but it works for any object
+    # @param [Object] time_date_component Any object
+    # @return [Boolean] true if the parameter is not nil
+    def has(time_date_component)
+      !time_date_component.nil?
+    end
+
+    # returns one day in seconds and adds a day to the @date
+    def a_day
+      if TimeProcesser.date.nil?
+        fail('needs date')
+      else
+        TimeProcesser.date += 86_400
+      end
+      86_400
+    end
+
+    # Adds a given number and hours and minutes to a Time object
+    # @param [Time] from time to which hours and minutes are added
+    # @param [Number] hour hours to add to from
+    # @param [Number] min minutes to add to from
+    # @return [Time] the result of hours and minutes after from
+    def extract_time_object(hour, min, from)
+      seconds = (hour.to_i * 3600) + (min.to_i * 60)
+      Time.at(from.to_i + seconds)
+    end
+  end
+end