friends 0.16 → 0.17

data/lib/friends/friend.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 # Friend represents a friend. You know, a real-life friend!
 
+require "friends/regex_builder"
 require "friends/serializable"
 
 module Friends
@@ -14,7 +15,7 @@ module Friends
     def self.deserialization_regex
       # Note: this regex must be on one line because whitespace is important
       # rubocop:disable Metrics/LineLength
-      /(#{SERIALIZATION_PREFIX})?(?<name>[^\(]+)(\((?<nickname_str>#{NICKNAME_PREFIX}.+)\))?/
+      /(#{SERIALIZATION_PREFIX})?(?<name>[^\(\[]+)(\((?<nickname_str>#{NICKNAME_PREFIX}.+)\))?\s?(\[(?<location_name>[^\]]+)\])?/
       # rubocop:enable Metrics/LineLength
     end
 
@@ -24,14 +25,16 @@ module Friends
     end
 
     # @param name [String] the name of the friend
-    def initialize(name:, nickname_str: nil)
+    def initialize(name:, nickname_str: nil, location_name: nil)
       @name = name.strip
       @nicknames = nickname_str &&
                    nickname_str.split(NICKNAME_PREFIX)[1..-1].map(&:strip) ||
                    []
+      @location_name = location_name
     end
 
     attr_accessor :name
+    attr_accessor :location_name
 
     # @return [String] the file serialization text for the friend
     def serialize
@@ -40,10 +43,16 @@ module Friends
 
     # @return [String] a string representing the friend's name and nicknames
     def to_s
-      return name if @nicknames.empty?
+      unless @nicknames.empty?
+        nickname_str =
+          " (" +
+          @nicknames.map { |n| "#{NICKNAME_PREFIX}#{n}" }.join(" ") +
+          ")"
+      end
+
+      location_str = " [#{@location_name}]" unless @location_name.nil?
 
-      nickname_str = @nicknames.map { |n| "#{NICKNAME_PREFIX}#{n}" }.join(" ")
-      "#{name} (#{nickname_str})"
+      "#{@name}#{nickname_str}#{location_str}"
     end
 
     # Adds a nickname, avoiding duplicates and stripping surrounding whitespace.
@@ -53,13 +62,6 @@ module Friends
       @nicknames.uniq!
     end
 
-    # Renames a friend, avoiding duplicates and stripping surrounding
-    # whitespace.
-    # @param new_name [String] the friend's new name
-    def rename(new_name)
-      @name = new_name
-    end
-
     # @param nickname [String] the nickname to remove
     # @return [Boolean] true if the nickname was present, false otherwise
     def remove_nickname(nickname)
@@ -97,36 +99,10 @@ module Friends
       # We generously allow any amount of whitespace between parts of a name.
       splitter = "\\s+"
 
-      # We don't want to match names that are "escaped" with a leading
-      # backslash.
-      no_leading_backslash = "(?<!\\\\)"
-
-      # We don't want to match names that are directly touching double asterisks
-      # as these are treated as sacred by our program.
-      # NOTE: Technically we don't need this check here, since we perform a more
-      # complex asterisk check in the Activity#description_matches method, but
-      # this class shouldn't need to know about the internal implementation of
-      # another class.
-      no_leading_asterisks = "(?<!\\*\\*)"
-      no_ending_asterisks = "(?!\\*\\*)"
-
-      # We don't want to match names that are part of other words.
-      no_leading_alphabeticals = "(?<![A-z])"
-      no_ending_alphabeticals = "(?![A-z])"
-
       # Create the list of regexes and return it.
       chunks = name.split(Regexp.new(splitter))
-
       [chunks, [chunks.first], *@nicknames.map { |n| [n] }].map do |words|
-        Regexp.new(
-          no_leading_backslash +
-          no_leading_asterisks +
-          no_leading_alphabeticals +
-          words.join(splitter) +
-          no_ending_alphabeticals +
-          no_ending_asterisks,
-          Regexp::IGNORECASE
-        )
+        Friends::RegexBuilder.regex(words.join(splitter))
       end
     end
 

data/lib/friends/introvert.rb

@@ -5,6 +5,7 @@
 
 require "friends/activity"
 require "friends/friend"
+require "friends/location"
 require "friends/friends_error"
 
 module Friends
@@ -12,6 +13,7 @@ module Friends
     DEFAULT_FILENAME = "./friends.md".freeze
     ACTIVITIES_HEADER = "### Activities:".freeze
     FRIENDS_HEADER = "### Friends:".freeze
+    LOCATIONS_HEADER = "### Locations:".freeze
     GRAPH_DATE_FORMAT = "%b %Y".freeze # Used as the param for date.strftime().
 
     # @param filename [String] the name of the friends Markdown file
@@ -25,22 +27,21 @@ module Friends
 
     # Write out the friends file with cleaned/sorted data.
     def clean
-      descriptions = @activities.sort.map(&:serialize)
-      names = @friends.sort.map(&:serialize)
-
-      # Write out the cleaned file.
       File.open(@filename, "w") do |file|
         file.puts(ACTIVITIES_HEADER)
-        descriptions.each { |desc| file.puts(desc) }
-        file.puts # Blank line separating friends from activities.
+        @activities.sort.each { |act| file.puts(act.serialize) }
+        file.puts # Blank line separating activities from friends.
         file.puts(FRIENDS_HEADER)
-        names.each { |name| file.puts(name) }
+        @friends.sort.each { |friend| file.puts(friend.serialize) }
+        file.puts # Blank line separating friends from locations.
+        file.puts(LOCATIONS_HEADER)
+        @locations.sort.each { |location| file.puts(location.serialize) }
       end
 
       @filename
     end
 
-    # Add a friend and write out the new friends file.
+    # Add a friend.
     # @param name [String] the name of the friend to add
     # @raise [FriendsError] when a friend with that name is already in the file
     # @return [Friend] the added friend
@@ -60,7 +61,7 @@ module Friends
       friend # Return the added friend.
     end
 
-    # Add an activity and write out the new friends file.
+    # Add an activity.
     # @param serialization [String] the serialized activity
     # @return [Activity] the added activity
     def add_activity(serialization:)
@@ -70,30 +71,91 @@ module Friends
         raise FriendsError, e
       end
 
-      activity.highlight_friends(introvert: self) if activity.description
+      activity.highlight_description(introvert: self) if activity.description
       @activities.unshift(activity)
 
       activity # Return the added activity.
     end
 
-    # Rename an existing added friend.
+    # Add a location.
+    # @param name [String] the serialized location
+    # @return [Location] the added location
+    # @raise [FriendsError] if a location with that name already exists
+    def add_location(name:)
+      if @locations.any? { |location| location.name == name }
+        raise FriendsError, "Location \"#{name}\" already exists"
+      end
+
+      begin
+        location = Location.deserialize(name)
+      rescue Serializable::SerializationError => e
+        raise FriendsError, e
+      end
+
+      @locations << location
+
+      location # Return the added location.
+    end
+
+    # Set a friend's location.
+    # @param name [String] the friend's name
+    # @param location_name [String] the name of an existing location
+    # @raise [FriendsError] if 0 or 2+ friends match the given name
+    # @raise [FriendsError] if 0 or 2+ locations match the given location name
+    # @return [Friend] the modified friend
+    def set_location(name:, location_name:)
+      friend = friend_with_name_in(name)
+      location = location_with_name_in(location_name)
+      friend.location_name = location.name
+      friend
+    end
+
+    # Rename an existing friend.
     # @param old_name [String] the name of the friend
     # @param new_name [String] the new name of the friend
-    # @raise [FriendsError] if 0 of 2+ friends match the given name
+    # @raise [FriendsError] if 0 or 2+ friends match the given name
     # @return [Friend] the existing friend
     def rename_friend(old_name:, new_name:)
-      friend = friend_with_name_in(old_name.strip)
+      old_name.strip!
+      new_name.strip!
+
+      friend = friend_with_name_in(old_name)
       @activities.each do |activity|
-        activity.update_name(old_name: friend.name, new_name: new_name.strip)
+        activity.update_friend_name(old_name: friend.name, new_name: new_name)
       end
-      friend.rename(new_name.strip)
+      friend.name = new_name
       friend
     end
 
-    # Add a nickname to an existing friend and write out the new friends file.
+    # Rename an existing location.
+    # @param old_name [String] the name of the location
+    # @param new_name [String] the new name of the location
+    # @raise [FriendsError] if 0 or 2+ friends match the given name
+    # @return [Location] the existing location
+    def rename_location(old_name:, new_name:)
+      old_name.strip!
+      new_name.strip!
+
+      loc = location_with_name_in(old_name)
+
+      # Update locations in activities.
+      @activities.each do |activity|
+        activity.update_location_name(old_name: loc.name, new_name: new_name)
+      end
+
+      # Update locations of friends.
+      @friends.select { |f| f.location_name == loc.name }.each do |friend|
+        friend.location_name = new_name
+      end
+
+      loc.name = new_name # Update location itself.
+      loc
+    end
+
+    # Add a nickname to an existing friend.
     # @param name [String] the name of the friend
     # @param nickname [String] the nickname to add to the friend
-    # @raise [FriendsError] if 0 of 2+ friends match the given name
+    # @raise [FriendsError] if 0 or 2+ friends match the given name
     # @return [Friend] the existing friend
     def add_nickname(name:, nickname:)
       friend = friend_with_name_in(name)
@@ -105,7 +167,7 @@ module Friends
     #   file.
     # @param name [String] the name of the friend
     # @param nickname [String] the nickname to remove from the friend
-    # @raise [FriendsError] if 0 of 2+ friends match the given name
+    # @raise [FriendsError] if 0 or 2+ friends match the given name
     # @return [Friend] the existing friend
     def remove_nickname(name:, nickname:)
       friend = friend_with_name_in(name)
@@ -114,9 +176,19 @@ module Friends
     end
 
     # List all friend names in the friends file.
+    # @param location_name [String] the name of a location to filter by, or nil
+    #   for unfiltered
     # @return [Array] a list of all friend names
-    def list_friends
-      @friends.map(&:name)
+    def list_friends(location_name:)
+      fs = @friends
+
+      # Filter by location if a name is passed.
+      if location_name
+        location = location_with_name_in(location_name)
+        fs = fs.select { |friend| friend.location_name == location.name }
+      end
+
+      fs.map(&:name)
     end
 
     # List your favorite friends.
@@ -150,9 +222,11 @@ module Friends
     #   limit
     # @param with [String] the name of a friend to filter by, or nil for
     #   unfiltered
+    # @param location_name [String] the name of a location to filter by, or nil
+    #   for unfiltered
     # @return [Array] a list of all activity text values
-    # @raise [FriendsError] if 0 of 2+ friends match the given `with` text
-    def list_activities(limit:, with:)
+    # @raise [FriendsError] if 0 or 2+ friends match the given `with` text
+    def list_activities(limit:, with:, location_name:)
       acts = @activities
 
       # Filter by friend name if argument is passed.
@@ -161,24 +235,39 @@ module Friends
         acts = acts.select { |act| act.includes_friend?(friend: friend) }
       end
 
+      # Filter by location name if argument is passed.
+      unless location_name.nil?
+        location = location_with_name_in(location_name)
+        acts = acts.select { |act| act.includes_location?(location: location) }
+      end
+
       # If we need to, trim the list.
       acts = acts.take(limit) unless limit.nil?
 
       acts.map(&:display_text)
     end
 
-    # Find data points for graphing a given friend's relationship over time.
-    # @param name [String] the name of the friend to use
-    # @return [Hash] with the following format:
+    # List all location names in the friends file.
+    # @return [Array] a list of all location names
+    def list_locations
+      @locations.map(&:name)
+    end
+
+    # Find data points for graphing activities over time.
+    # Optionally filter by a friend to see a given relationship over time.
+    #
+    # The returned hash uses the following format:
     #   {
-    #     "Jan 2015" => 3,  # The month and number of activities with that
-    #     "Feb 2015" => 0, # friend during that month.
+    #     "Jan 2015" => 3, # The number of activities during each month.
+    #     "Feb 2015" => 0,
     #     "Mar 2015" => 9
     #   }
-    #   The keys of the hash are all of the months (inclusive) between the first
-    #   and last month in which activities for the given friend have been
-    #   recorded.
-    # @raise [FriendsError] if 0 of 2+ friends match the given name
+    # The keys of the hash are all of the months (inclusive) between the first
+    # and last month in which activities have been recorded.
+    #
+    # @param name [String] the name of the friend to use
+    # @return [Hash{String => Fixnum}]
+    # @raise [FriendsError] if 0 or 2+ friends match the given name
     def graph(name: nil)
       if name
         friend = friend_with_name_in(name) # Find the friend by name.
@@ -204,17 +293,27 @@ module Friends
       act_table
     end
 
-    # @return [Hash] of the format:
+    # Suggest friends to do something with.
+    #
+    # The returned hash uses the following format:
     #   {
     #     distant: ["Distant Friend 1 Name", "Distant Friend 2 Name", ...],
     #     moderate: ["Moderate Friend 1 Name", "Moderate Friend 2 Name", ...],
     #     close: ["Close Friend 1 Name", "Close Friend 2 Name", ...]
     #   }
-    def suggest
+    #
+    # @param location_name [String] the name of a location to filter by, or nil
+    #   for unfiltered
+    # @return [Hash{String => Array<String>}]
+    def suggest(location_name:)
       set_n_activities! # Set n_activities for all friends.
 
+      # Filter our friends by location if necessary.
+      fs = @friends
+      fs = fs.select { |f| f.location_name == location_name } if location_name
+
       # Sort our friends, with the least favorite friend first.
-      sorted_friends = @friends.sort_by(&:n_activities)
+      sorted_friends = fs.sort_by(&:n_activities)
 
       output = Hash.new { |h, k| h[k] = [] }
 
@@ -255,9 +354,17 @@ module Friends
       end
     end
 
-    # @return [Hash] of the form { /regex/ => [list of friends matching regex] }
-    #   This hash is sorted (because Ruby's hashes are ordered) by decreasing
-    #   regex key length, so the key /Jacob Evelyn/ appears before /Jacob/.
+    # Get a regex friend map.
+    #
+    # The returned hash uses the following format:
+    #   {
+    #     /regex/ => [list of friends matching regex]
+    #   }
+    #
+    # This hash is sorted (because Ruby's hashes are ordered) by decreasing
+    # regex key length, so the key /Jacob Evelyn/ appears before /Jacob/.
+    #
+    # @return [Hash{Regexp => Array<Friends::Friend>}]
     def regex_friend_map
       @friends.each_with_object(Hash.new { |h, k| h[k] = [] }) do |friend, hash|
         friend.regexes_for_name.each do |regex|
@@ -266,6 +373,23 @@ module Friends
       end.sort_by { |k, _| -k.to_s.size }.to_h
     end
 
+    # Get a regex location map.
+    #
+    # The returned hash uses the following format:
+    #   {
+    #     /regex/ => [list of friends matching regex]
+    #   }
+    #
+    # This hash is sorted (because Ruby's hashes are ordered) by decreasing
+    # regex key length, so the key /Paris, France/ appears before /Paris/.
+    #
+    # @return [Hash{Regexp => Array<Friends::Location>}]
+    def regex_location_map
+      @locations.each_with_object({}) do |location, hash|
+        hash[location.regex_for_name] = location
+      end.sort_by { |k, _| -k.to_s.size }.to_h
+    end
+
     # Sets the likelihood_score field on each friend in `possible_matches`. This
     # score represents how likely it is that an activity containing the friends
     # in `matches` and containing a friend from each group in `possible_matches`
@@ -285,9 +409,9 @@ module Friends
                      combination(2).
                      reject do |friend1, friend2|
                        (matches & [friend1, friend2]).size == 2 ||
-                       possible_matches.any? do |group|
-                         (group & [friend1, friend2]).size == 2
-                       end
+                         possible_matches.any? do |group|
+                           (group & [friend1, friend2]).size == 2
+                         end
                      end
 
       @activities.each do |activity|
@@ -326,44 +450,65 @@ module Friends
     def read_file
       @friends = []
       @activities = []
+      @locations = []
 
       return unless File.exist?(@filename)
 
-      state = :initial
-      line_num = 0
+      state = :unknown
 
       # Loop through all lines in the file and process them.
-      File.foreach(@filename) do |line|
-        line_num += 1
+      File.foreach(@filename).with_index(1) do |line, line_num|
         line.chomp! # Remove trailing newline from each line.
 
-        case state
-        when :initial
-          bad_line(ACTIVITIES_HEADER, line_num) unless line == ACTIVITIES_HEADER
+        # Parse the line and update the parsing state.
+        state = parse_line!(line, line_num: line_num, state: state)
+      end
+    end
 
-          state = :reading_activities
-        when :reading_friends
-          begin
-            @friends << Friend.deserialize(line)
-          rescue FriendsError => e
-            bad_line(e, line_num)
-          end
-        when :done_reading_activities
-          state = :reading_friends if line == FRIENDS_HEADER
-        when :reading_activities
-          if line == ""
-            state = :done_reading_activities
-          else
-            begin
-              @activities << Activity.deserialize(line)
-            rescue FriendsError => e
-              bad_line(e, line_num)
-            end
+    # Parse the given line, adding to the various internal data structures as
+    # necessary.
+    # @param line [String]
+    # @param line_num [Integer] the 1-indexed file line number we're parsing
+    # @param state [Symbol] the state of the parsing, one of:
+    #   [:unknown, :reading_activities, :reading_friends, :reading_locations]
+    # @return [Symbol] the updated state after parsing the given line
+    def parse_line!(line, line_num:, state:)
+      return :unknown if line == ""
+
+      # If we're in an unknown state, look for a header to tell us what we're
+      # parsing next.
+      if state == :unknown
+        PARSING_STAGES.each do |stage|
+          if line == self.class.const_get("#{stage.id.to_s.upcase}_HEADER")
+            return "reading_#{stage.id}".to_sym
           end
         end
+
+        # If we made it here, we couldn't recognize a header.
+        bad_line("Couldn't parse line.", line_num)
       end
+
+      # If we made it this far, we're parsing objects in a class.
+      stage = PARSING_STAGES.find { |s| state == "reading_#{s.id}".to_sym }
+
+      begin
+        instance_variable_get("@#{stage.id}") << stage.klass.deserialize(line)
+      rescue FriendsError => e
+        bad_line(e, line_num)
+      end
+
+      state
     end
 
+    # Used internally by the parse_line! method above to associate stages with
+    # the class to create.
+    ParsingStage = Struct.new(:id, :klass)
+    PARSING_STAGES = [
+      ParsingStage.new(:activities, Activity),
+      ParsingStage.new(:friends, Friend),
+      ParsingStage.new(:locations, Location)
+    ].freeze
+
     # @param name [String] the name of the friend to search for
     # @return [Friend] the friend whose name exactly matches the argument
     # @raise [FriendsError] if more than one friend has the given name
@@ -379,9 +524,10 @@ module Friends
 
     # @param text [String] the name (or substring) of the friend to search for
     # @return [Friend] the friend that matches
-    # @raise [FriendsError] if 0 of 2+ friends match the given text
+    # @raise [FriendsError] if 0 or 2+ friends match the given text
     def friend_with_name_in(text)
-      friends = friends_with_name_in(text)
+      regex = Regexp.new(text, Regexp::IGNORECASE)
+      friends = @friends.select { |friend| friend.name.match(regex) }
 
       case friends.size
       when 1
@@ -395,11 +541,23 @@ module Friends
       end
     end
 
-    # @param text [String] the name (or substring) of the friends to search for
-    # @return [Array] a list of all friends that match the given text
-    def friends_with_name_in(text)
+    # @param text [String] the name (or substring) of the location to search for
+    # @return [Location] the location that matches
+    # @raise [FriendsError] if 0 or 2+ location match the given text
+    def location_with_name_in(text)
       regex = Regexp.new(text, Regexp::IGNORECASE)
-      @friends.select { |friend| friend.name.match(regex) }
+      locations = @locations.select { |location| location.name.match(regex) }
+
+      case locations.size
+      when 1
+        # If exactly one location matches, use that location.
+        return locations.first
+      when 0 then raise FriendsError, "No location found for \"#{text}\""
+      else
+        raise FriendsError,
+              "More than one location found for \"#{text}\": "\
+                "#{locations.map(&:name).join(', ')}"
+      end
     end
 
     # Raise an error that a line in the friends file is malformed.