docfolio 0.0.0 → 0.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 99d2c5789c65b55841fd11b71cfb29448e1ea722
-  data.tar.gz: d4221138fa97f72c806a8aaabd04f3881f0e4c76
+  metadata.gz: e45dbe3f14a1a7135af5c0172af46430bd17a683
+  data.tar.gz: 33c879f96cc800b3b1e7a264cb1903b08536d408
 SHA512:
-  metadata.gz: f6afcea04d4231186c8ac92f138637f75fa447073668603d83fbc9f285771d68e5fb83b7872d3466710a742751018063e52d8c4cfe389d69cd9a84fadb3e8bea
-  data.tar.gz: 27134b0e2c0d9151a33716307325fc8076a8994056776bef3c4abd197ce355e0e4d6e769a1d1d0373e7c61ed37bca1f2eb71062525ca1dddef86bb266c8e9a6b
+  metadata.gz: eef722b2f0ed517071307ed25ded7fa97faba77242cde022ad4681dcf90a8e27d628be498c902e8b62ef50a9abcc0e8370cc4c721bf2626e1466488cd9d8d52d
+  data.tar.gz: 208e402157fc17576d3578160afce37edeca054db9a6687ad01a1a008cb6b3f931476af32e85e494c5db96c59f15ca6fd359386290c987e1fc645ade1fb04900

data/lib/docfolio/date_format.rb

@@ -41,6 +41,7 @@ module DateFormat
       [day, month, year]
     end
 
+    # A hash of text months and their corresponding month number
     MONTHS = {
       'jan' => 1,
       'feb' => 2,
@@ -68,6 +69,9 @@ module DateFormat
       '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
@@ -75,6 +79,9 @@ module DateFormat
     end
   end
 
+  # 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
   def format_date(date)
     DateExtractor.new.format_date(date)
   end

data/lib/docfolio/docfolio.rb

@@ -1,5 +1,4 @@
 require_relative 'learning_diary.rb'
-# require 'stringio'
 require_relative 'views/collater_console_view.rb'
 
 # collection class for Learning Diarys / logs
@@ -25,6 +24,7 @@ class Logs
     log_file(file_or_directory) if File.file?(file_or_directory)
   end
 
+  # Implements Enumerable by iterating through each learning diary
   def each(&block)
     @logs.each { |p| block.call(p) }
   end
@@ -68,6 +68,7 @@ class Docfolio
     true
   end
 
+  # print all parsed logs to the console
   def print_logs
     @view.print_logs(@logs)
   end

data/lib/docfolio/learning_diary.rb

@@ -7,16 +7,27 @@ require_relative 'views/diary_console_view.rb'
 class LearningDiary
   include Enumerable
 
+  # Array of paragraphs representing the parsed DSL from one file
   attr_reader :paragraphs
 
-  # @param [String] file name of a text file containing text in docfile DSL
+  # @param [String] file name of a text file containing text in docfolio DSL
   def initialize(file)
     # preparation
     # @todo extract to an initialize_vars function, as in the paragraph class
     Paragraph.reset
     @console_view = DiaryConsoleView.new
+
+    # Array of paragraphs representing the parsed DSL from one file
     @paragraphs = []
-    @standard_credits_array = []
+    
+    # Array of elements of type [start_time, end_time, duration], one for
+    # each tag in all the paragraphs that earns standard credit
+    # @todo this perhaps would be better as a ||= in the corresponding function
+    @standard_credits_array = []    
+
+    # Array of elements of type [start_time, end_time, duration], one for
+    # each tag in all the paragraphs that earns impact credit
+    # @todo this perhaps would be better as a ||= in the corresponding function
     @impact_credits_array = []
 
     # read the whole txt file in one go
@@ -31,36 +42,52 @@ class LearningDiary
     calc_impact_credits
   end
 
+  # Implements Enuemerable module by iterating through each paragraph in the
+  # learning diary
   def each(&block)
     @paragraphs.each { |p| block.call(p) }
   end
 
+  # Implements [] by indexing the @paragraphs instance variable
   def [](index)
     @paragraphs[index]
   end
 
+  # @return [Integer] The sum of the standard credits in minutes
   def standard_credits_total
     @standard_credits_array.reduce(0) { |a, e| a + e[2] }
   end
 
+  # @return [Array] The array of standard credits, each element of 
+  #  type [start_time, end_time, duration]
   def standard_credits
     @standard_credits_array
   end
 
+  # @return [Integer] The sum of the impact credits in minutes
   def impact_credits_total
     @impact_credits_array.reduce(0) { |a, e| a + e[2] }
   end
 
-  def credits_total
-    impact_credits_total + standard_credits_total
-  end
-
+  # @return [Array] The array of impact credits, each element of 
+  #  type [start_time, end_time, duration]
   def impact_credits
     @impact_credits_array
   end
 
+  # @return [Integer] The sum of the impact and standard credits in minutes
+  def credits_total
+    impact_credits_total + standard_credits_total
+  end
+
   private
 
+  # @todo Deal with edge case where the start and end times of different 
+  # elements overlap to avoid claiming credit for the same moments in
+  # time more than once
+  # @return [Array] Array of elements of type 
+  #  [start_time, end_time, duration], one for each tag in all the paragraphs 
+  #  that earns standard credit
   def calc_standard_credits
     @paragraphs.each do |p|
       next unless p.creditable?
@@ -72,11 +99,12 @@ class LearningDiary
     @standard_credits_array.uniq!
   end
 
+  # @return [Array] Array of elements of type 
+  #  [start_time, end_time, duration], one for each tag in all the paragraphs 
+  #  that earns impact credit
   def calc_impact_credits
-
     @paragraphs.each do |p|
       next unless p.impact_creditable?
-      # p p
       start     = p.start_time
       finish    = p.end_time
       duration  = p.period

data/lib/docfolio/paragraph.rb

@@ -29,7 +29,6 @@ module MyTime
     end
 
     private
-    
 
     # @param [Number] f_hour From hours
     # @param [Number] f_min From minutes
@@ -41,6 +40,11 @@ module MyTime
       has(@start_time) && (!has @end_time) ? true : start_t(f_hour, f_min)
     end
 
+    # 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
       @end_time = extract_time_object(t_hour, t_min, @date)
@@ -108,10 +112,19 @@ class Paragraph
 
   # initialize class date, start and class end time class instance variables
   @cst = @cet = @date = nil
-  @section = @id = 0 # :TITLE
 
+
+  # initialize the section class instance variable. The section is an integer
+  # that is an index to the array of tags called SECTIONS declared in the
+  # module Tags
+  @section = 0 # :TITLE
+
+  @id = 0 
+
+  # Declaration of class instance variables
   class << self
-    # class starttime and class end time
+    # class starttime and class end time, date, section 
+    # @todo find out what id is and does!
     attr_accessor :st, :et, :date, :section, :id
   end
 
@@ -172,19 +185,37 @@ class Paragraph
   end
 
   # @todo should this be private?
+  # Initialize the paragraph variables. 
   def initialize_vars
     @date_specified = @end_time_specified = @start_time_specified = false
     @start_time = @end_time = nil
+
+    # Array of tagged content. e.g.
+    # @tags
+    # => [:TITLE, 'My Title']
+    #  @tags
+    # => [:INTRO, 'My introduction.']
+    # @tags
+    # => [:LP, 'Something I have learnt']
     @tags = []
+
+    # Give the instance instance an id number that is kept track of by a
+    # class instance id, then increment the class instance id
     @id = Paragraph.id
     Paragraph.id += 1
   end
 
-  # each on paragraph iterates through the tags
+  # Iterates through the instance tags
+  # @todo Find out if this is the tags for the paragraph or the whole 
+  #  document. Common sense says just the paragraph as this is just an 
+  #  instance instance variable
   def each(&block)
     @tags.each { |t| block.call(t) }
   end
 
+  # Implements [] for paragraph
+  # @return [Array] an element of the tags array, itself an element 
+  #  of type [:tag, 'content']
   def [](index)
     tags[index]
   end
@@ -195,17 +226,20 @@ class Paragraph
     false
   end
 
-  # true is the paragraph contains a tag that can earn impact credit
+  # 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
 
+  # @return [Integer] the interval in minutes between start and end times
   def period
     return 0 if @end_time.nil? || @start_time.nil?
     (@end_time - @start_time).to_i / 60
   end
 
+  # @return end time if exists or failing that the start time if exists 
+  #  or failing that nil
   def latest_time
     return @end_time unless @end_time.nil?
     return @start_time unless @start_time.nil?
@@ -214,9 +248,15 @@ class Paragraph
 
   private
 
+  # Indexes for the elements of a tabbed array. Elements are of 
+  # type [:tag, 'content']
   TAG = 0
+
+  # Content index number
   CONTENT = 1
 
+  # Setter for the class instance variables for the start time, end time
+  # and date
   def assign_class_dates(array)
     Paragraph.st, Paragraph.et, Paragraph.date = array
   end
@@ -227,28 +267,54 @@ class Paragraph
     [Paragraph.st, Paragraph.et, Paragraph.date]
   end
 
+  # @todo split/rename the actions of this function
+  # Extracts all the tag for the paragraph
+  # @param [String] str Paragraph from which tags are to be extracted
+  # @return [Boolean] True if any tags have been extracted
   def tags_extracted?(str)
     (@tags.count) < (@tags += extract_tags(str)).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
+  # @param [String] str the content to tag
   def tag_section(str)
     tag_it(SECTIONS[Paragraph.section], str)
   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 = '')
     @tags.each { |t| str << t[CONTENT] + ' ' if t[TAG] == tag }
     str
   end
 
+  # Safely increments the class instance section invariable 
   def next_section
     Paragraph.section += 1 unless Paragraph.section == (SECTIONS.count - 1)
   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]
     next_section if Paragraph.section == 0 # :TITLE
   end
 
+  # Acts and a getter and setter for tagged content. Adds a getter and setter
+  # methods for each tag with the name of the tag. For example:
+  #  paragraph.intro('my intro')
+  # Would and an :INTRO tag with the text content of 'my intro'
+  #  paragraph.intro
+  # Returns all content with a tag of :INTRO
   def method_missing(n, *args, &block)
     if args[0].nil? # tag getter
       ALL_TAGS.include?(n) ? content(n) : super(n, *args, &block)

data/lib/docfolio/tags.rb

@@ -1,13 +1,24 @@
 require_relative 'date_format.rb'
 require 'English'
 
-# handles extraction of tagged or other significant content
+# handles extraction of tagged or other significant content. 
+# Interface:  extract_date, extract_tags
 module Tags
-  # interface:  extract_date, extract_tags
-  TAGS = [:LP, :R, :DEN, :NOTE, :I] # recognized in text
-  CREDITABLE = [:LP, :R, :I] # can earn cpd credit
-  SECTIONS = [:TITLE, :INTRO, :NOTE] # assumed from position in document
+
+  # Tags that are part of the DSL and are recognized in text
+  TAGS = [:LP, :R, :DEN, :NOTE, :I] 
+
+  # Tags that can earn CPD credit
+  CREDITABLE = [:LP, :R, :I]
+
+  # Tags that are applied to content based on the position in the document
+  SECTIONS = [:TITLE, :INTRO, :NOTE] 
+
+  # Tags that are internal and which have no meaning derived from the DSL or
+  # the position in the document.
   SPECIAL = [:DATE] # internal tags with no meaning from content or position
+
+  # A combined array of all tags
   ALL_TAGS = SECTIONS + TAGS + SPECIAL
 
   # extracts and formats tags and pertaining text from a plain text paragraph
@@ -19,7 +30,9 @@ module Tags
     # 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 of this paragraph. May be nil if not known.
+    # @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
@@ -45,6 +58,12 @@ module Tags
       [paragraph_text, time_array, date]
     end
 
+    # 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
@@ -117,11 +136,25 @@ module Tags
       nil
     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 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)
       tags = []
       tag_count = (a.count - 1) / 2
@@ -133,12 +166,18 @@ module Tags
       tags
     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
   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
@@ -148,10 +187,29 @@ module Tags
     Time.at(from.to_i + seconds)
   end
 
+  # 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)
     TagFriend.new.extract_tags(paragraph_text)
   end
 
+  # Defined in the Tags module
+  # @todo move function to one of the date or time handling classes
+  # 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)
     TagFriend.new.extract_date(paragraph_text, date)
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docfolio
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.0.1
 platform: ruby
 authors:
 - Nick Bulmer
@@ -9,7 +9,21 @@ autorequire:
 bindir: bin
 cert_chain: []
 date: 2015-12-10 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: colorize
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.7.7
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.7.7
 description: A domain specific language to aid recording of a personal learning portfolio
   for UK General Practitioners.
 email: n.bulmer@live.co.uk
@@ -38,7 +52,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.1.5
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="