friends 0.0.1 → 0.0.2

data/lib/friends/friend.rb

@@ -1,11 +1,40 @@
 # Friend represents a friend. You know, a real-life friend!
 
+require "friends/serializable"
+
 module Friends
   class Friend
+    extend Serializable
+
+    SERIALIZATION_PREFIX = "- "
+
+    # @return [Regexp] the regex for capturing groups in deserialization
+    def self.deserialization_regex
+      /(#{SERIALIZATION_PREFIX})?(?<name>.+)/
+    end
+
+    # @return [Regexp] the string of what we expected during deserialization
+    def self.deserialization_expectation
+      "[Friend Name]"
+    end
+
+    # @param name [String] the name of the friend
     def initialize(name:)
       @name = name
     end
 
     attr_accessor :name
+
+    # @return [String] the file serialization text for the friend
+    def serialize
+      "#{SERIALIZATION_PREFIX}#{name}"
+    end
+
+    private
+
+    # Default sorting for an array of friends is alphabetical.
+    def <=>(other)
+      name <=> other.name
+    end
   end
 end

data/lib/friends/friends_error.rb

@@ -0,0 +1,4 @@
+module Friends
+  class FriendsError < StandardError
+  end
+end

data/lib/friends/introvert.rb

@@ -1,29 +1,169 @@
-# Introvert is the internal handler for the friends script.
+# Introvert is the internal handler for the friends script. It is designed to be
+# able to be used directly within another Ruby program, without needing to call
+# the command-line script explicitly.
 
+require "friends/activity"
 require "friends/friend"
+require "friends/friends_error"
 
 module Friends
   class Introvert
+    DEFAULT_FILENAME = "./friends.md"
+    ACTIVITIES_HEADER = "### Activities:"
     FRIENDS_HEADER = "### Friends:"
 
-    # @return [String] the name of the friends.md file
-    def filename
-      "friends.md"
+    # @param filename [String] the name of the friends Markdown file
+    def initialize(filename: DEFAULT_FILENAME)
+      @filename = filename
+      @cleaned_file = false # Switches to true when the file is cleaned.
+
+      # Read in the input file. It's easier to do this now and optimize later
+      # than try to overly be clever about what we read and write.
+      read_file(filename: @filename)
     end
 
-    # @return [Array] the list of all Friends
-    def friends
-      return @friends if @friends
+    attr_reader :filename
+    attr_reader :activities
+
+    # Write out the friends file with cleaned/sorted data.
+    def clean
+      # Short-circuit if we've already cleaned the file so we don't write it
+      # twice.
+      return filename if @cleaned_file
+
+      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.
+        file.puts(FRIENDS_HEADER)
+        names.each { |name| file.puts(name) }
+      end
+
+      @cleaned_file = true
+
+      filename
+    end
+
+    # List all friend names in the friends file.
+    # @return [Array] a list of all friend names
+    def list_friends
+      friends.map(&:name)
+    end
 
-      read_file(filename: filename, friends_only: true)
+    # Add a friend and write out the new friends file.
+    # @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
+    def add_friend(name:)
+      if friend_with_exact_name(name)
+        raise FriendsError, "Friend named #{name} already exists"
+      end
+
+      begin
+        friend = Friend.deserialize(name)
+      rescue Serializable::SerializationError => e
+        raise FriendsError, e
+      end
+
+      friends << friend
+      clean # Write a cleaned file.
+
+      friend # Return the added friend.
+    end
+
+    # List all activity details.
+    # @param [String] the name of a friend to filter by, or nil for unfiltered
+    # @return [Array] a list of all activity text values
+    def list_activities(with:)
+      acts = activities
+
+      # Filter by friend name if argument is passed.
+      unless with.nil?
+        friends = friends_with_name_in(with)
+
+        case friends.size
+        when 1
+          # If exactly one friend matches, use that friend to filter.
+          acts = acts.select { |a| a.friend_names.include? friends.first.name }
+        when 0 then raise FriendsError, "No friend found for \"#{with}\""
+        else
+          raise FriendsError,
+                "More than one friend found for \"#{with}\": "\
+                  "#{friends.map(&:name).join(', ')}"
+        end
+      end
+
+      acts.map(&:display_text)
+    end
+
+    # Add an activity and write out the new friends file.
+    # @param serialization [String] the serialized activity
+    # @return [Activity] the added activity
+    def add_activity(serialization:)
+      begin
+        activity = Activity.deserialize(serialization)
+      rescue Serializable::SerializationError => e
+        raise FriendsError, e
+      end
+
+      activity.highlight_friends(friends: friends)
+      activities << activity
+      clean # Write a cleaned file.
+
+      activity # Return the added activity.
+    end
+
+    # List your favorite friends.
+    # @param num [Integer] the number of favorite friends to return, or nil if
+    #   unlimited
+    # @return [Array] a list of the favorite friends' names and activity
+    #   counts
+    def list_favorites(limit:)
+      if !limit.nil? && limit < 1
+        raise FriendsError, "Favorites limit must be positive or unlimited"
+      end
+
+      # Construct a hash of friend name to frequency of appearance.
+      freq_table = Hash.new { |h, k| h[k] = 0 }
+      activities.each do |activity|
+        activity.friend_names.each do |friend_name|
+          freq_table[friend_name] += 1
+        end
+      end
+
+      # Remove names that are not in the friends list.
+      freq_table.select! { |name, _| friend_with_exact_name(name) }
+
+      # Sort the results, with the most favorite friend first.
+      results = freq_table.sort_by { |_, count| -count }
+
+      # If we need to, trim the list.
+      results = results.take(limit) unless limit.nil?
+
+      results.map(&:first)
+    end
+
+    private
+
+    # Gets the list of friends as read from the file.
+    # @return [Array] a list of all friends
+    def friends
       @friends
     end
 
     # Process the friends.md file and store its contents in internal data
     # structures.
     # @param filename [String] the name of the friends file
-    # @param friends_only [Boolean] true if we should only read the friends list
-    def read_file(filename:, friends_only: false)
+    def read_file(filename:)
+      @friends = []
+      @activities = []
+
+      return unless File.exist?(filename)
+
       state = :initial
       line_num = 0
 
@@ -34,43 +174,57 @@ module Friends
 
         case state
         when :initial
-          bad_line(FRIENDS_HEADER, line_num) unless line == FRIENDS_HEADER
+          bad_line(ACTIVITIES_HEADER, line_num) unless line == ACTIVITIES_HEADER
 
-          state = :reading_friends
-          @friends = []
+          state = :reading_activities
         when :reading_friends
-          if line == "### Events:"
-            state = :reading_events
+          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
-            match = line.match(/- (?<name>.+)/)
-            bad_line("- [Friend Name]", line_num) unless match && match[:name]
-            @friends << Friend.new(name: match[:name])
+            begin
+              @activities << Activity.deserialize(line)
+            rescue FriendsError => e
+              bad_line(e, line_num)
+            end
           end
         end
       end
     end
 
-    # Write out the friends file with cleaned/sorted data.
-    def clean
-      names = friends.sort_by(&:name).map { |friend| "- #{friend.name}" }
-      File.open(filename, "w") do |file|
-        file.puts(FRIENDS_HEADER)
-        names.each { |name| file.puts(name) }
+    # @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
+    def friend_with_exact_name(name)
+      results = friends.select { |friend| friend.name == name }
+
+      case results.size
+      when 0 then nil
+      when 1 then results.first
+      else raise FriendsError, "More than one friend named #{name}"
       end
     end
 
-    private
+    # @param name [String] the name of the friends to search for
+    # @return [Array] a list of all friends that match the given text
+    def friends_with_name_in(text)
+      regex = Regexp.new(text, Regexp::IGNORECASE)
+      friends.select { |friend| friend.name.match(regex) }
+    end
 
     # Raise an error that a line in the friends file is malformed.
     # @param expected [String] the expected contents of the line
     # @param line_num [Integer] the line number
+    # @raise [FriendsError] with a constructed message
     def bad_line(expected, line_num)
-      error "Expected \"#{expected}\" on line #{line_num}"
-    end
-
-    # Output the given message and exit the program.
-    def error(message)
-      Gossip.error(message)
+      raise FriendsError, "Expected \"#{expected}\" on line #{line_num}"
     end
   end
 end

data/lib/friends/serializable.rb

@@ -0,0 +1,32 @@
+# Serializable provides functionality around serialization to the classes that
+# extend it. This includes a class method to deserialize a string and create an
+# instance of the class.
+
+module Serializable
+  # @param str [String] the serialized object string
+  # @return [Object] the object represented by the serialized string
+  # Note: this method assumes the calling class provides the following methods:
+  #   - deserialization_regex
+  #       a regex for the string which includes named parameters for the
+  #       different initializer arguments
+  #   - deserialization_expectation
+  #       a string for what was expected, if the regex does not match
+  def deserialize(str)
+    match = str.match(deserialization_regex)
+
+    unless match
+      raise SerializationError,
+            "Expected \"#{deserialization_expectation}\""
+    end
+
+    args = match.names.
+           map { |name| { name.to_sym => match[name.to_sym] } }.
+           reduce(:merge).
+           select { |_, v| !v.nil? }
+
+    new(args)
+  end
+
+  class SerializationError < StandardError
+  end
+end

data/lib/friends/version.rb

@@ -1,3 +1,3 @@
 module Friends
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/test/activity_spec.rb

@@ -0,0 +1,172 @@
+require_relative "helper"
+
+describe Friends::Activity do
+  let(:date) { Date.today }
+  let(:date_s) { date.to_s }
+  let(:friend1) { Friends::Friend.new(name: "Elizabeth Cady Stanton") }
+  let(:friend2) { Friends::Friend.new(name: "John Cage") }
+  let(:description) { "Lunch with **#{friend1.name}** and **#{friend2.name}**" }
+  let(:activity) do
+    Friends::Activity.new(date_s: date_s, description: description)
+  end
+
+  describe ".deserialize" do
+    subject { Friends::Activity.deserialize(serialized_str) }
+
+    describe "when string is well-formed" do
+      let(:serialized_str) { "#{date_s}: #{description}" }
+
+      it "creates an activity with the correct date and description" do
+        new_activity = subject
+        new_activity.date.must_equal date
+        new_activity.description.must_equal description
+      end
+    end
+
+    describe "when no date is present" do
+      let(:serialized_str) { description }
+
+      it "defaults to today" do
+        today = Date.today
+
+        # We stub out Date.today to guarantee that it is always the same even
+        # when the date changes in the middle of the test's execution.
+        Date.stub(:today, today) { subject.date.must_equal today }
+      end
+    end
+
+    describe "when string is malformed" do
+      let(:serialized_str) { "" }
+
+      it { proc { subject }.must_raise Serializable::SerializationError }
+    end
+  end
+
+  describe "#new" do
+    subject { activity }
+
+    it { subject.date.must_equal date }
+    it { subject.description.must_equal description }
+  end
+
+  describe "#display_text" do
+    subject { activity.display_text }
+
+    it do
+      subject.
+        must_equal "\e[1m#{date_s}\e[0m: "\
+          "Lunch with \e[1m#{friend1.name}\e[0m and \e[1m#{friend2.name}\e[0m"
+    end
+  end
+
+  describe "#serialize" do
+    subject { activity.serialize }
+
+    it do
+      subject.
+        must_equal "#{Friends::Activity::SERIALIZATION_PREFIX}#{date_s}: "\
+          "#{description}"
+    end
+  end
+
+  describe "#highlight_friends" do
+    let(:friend1) { Friends::Friend.new(name: "Elizabeth Cady Stanton") }
+    let(:friend2) { Friends::Friend.new(name: "John Cage") }
+    let(:friends) { [friend1, friend2] }
+    let(:description) { "Lunch with #{friend1.name} and #{friend2.name}." }
+    subject { activity.highlight_friends(friends: friends) }
+
+    it "finds all friends" do
+      subject
+      activity.description.
+        must_equal "Lunch with **#{friend1.name}** and **#{friend2.name}**."
+    end
+
+    it "matches friends' first names" do
+      activity = Friends::Activity.new(
+        date_s: Date.today.to_s,
+        description: "Lunch with Elizabeth and John."
+      )
+      activity.highlight_friends(friends: friends)
+      activity.description.
+        must_equal "Lunch with **#{friend1.name}** and **#{friend2.name}**."
+    end
+
+    it "matches without case sensitivity" do
+      activity = Friends::Activity.new(
+        date_s: Date.today.to_s,
+        description: "Lunch with elizabeth cady stanton."
+      )
+      activity.highlight_friends(friends: friends)
+      activity.description.
+        must_equal "Lunch with **Elizabeth Cady Stanton**."
+    end
+
+    it "ignores when there are multiple matches" do
+      friend2.name = "Elizabeth II"
+      activity = Friends::Activity.new(
+        date_s: Date.today.to_s,
+        description: "Dinner with Elizabeth."
+      )
+      activity.highlight_friends(friends: friends)
+      activity.description.must_equal "Dinner with Elizabeth." # No match found.
+    end
+
+    it "does not match with leading asterisks" do
+      activity = Friends::Activity.new(
+        date_s: Date.today.to_s,
+        description: "Dinner with **Elizabeth Cady Stanton."
+      )
+      activity.highlight_friends(friends: friends)
+
+      # No match found.
+      activity.description.must_equal "Dinner with **Elizabeth Cady Stanton."
+    end
+
+    it "does not match with ending asterisks" do
+      activity = Friends::Activity.new(
+        date_s: Date.today.to_s,
+
+        # Note: for now we can't guarantee that "Elizabeth Cady Stanton**" won't
+        # match, because the Elizabeth isn't surrounded by asterisks.
+        description: "Dinner with Elizabeth**."
+      )
+      activity.highlight_friends(friends: friends)
+
+      # No match found.
+      activity.description.must_equal "Dinner with Elizabeth**."
+    end
+  end
+
+  describe "#friend_names" do
+    subject { activity.friend_names }
+
+    it "returns a list of friend names" do
+      names = subject
+
+      # We don't assert that the output must be in a specific order because we
+      # don't care about the order and it is subject to change.
+      names.size.must_equal 2
+      names.must_include "Elizabeth Cady Stanton"
+      names.must_include "John Cage"
+    end
+
+    describe "when a friend is mentioned more than once" do
+      let(:description) { "Lunch with **John Cage**. **John Cage** can eat!" }
+
+      it "removes duplicate names" do
+        subject.must_equal ["John Cage"]
+      end
+    end
+  end
+
+  describe "#<=>" do
+    it "sorts by reverse-date" do
+      yesterday = (Date.today - 1).to_s
+      tomorrow = (Date.today + 1).to_s
+      past_act = Friends::Activity.new(date_s: yesterday, description: "Dummy")
+      future_act = Friends::Activity.new(date_s: tomorrow, description: "Dummy")
+      [past_act, future_act].sort.must_equal [future_act, past_act]
+    end
+  end
+end