friends 0.51 → 0.55

data/RELEASING.md

@@ -2,7 +2,7 @@
 
 These are steps for the maintainer to take to release a new version of this gem.
 
-1.  On the `master` branch, update the `VERSION` constant in
+1.  On the `main` branch, update the `VERSION` constant in
     `lib/friends/version.rb`.
 2.  Commit the change (`git add -A && git commit -m 'Bump to vX.X'`).
 3.  Add a tag (`git tag -am "vX.X" vX.X`).

data/bin/friends

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-if ENV["TRAVIS"] == "true" && ENV["CODE_COVERAGE"] == "true"
+if ENV["CI"] == "true" && ENV["CODE_COVERAGE"] == "true"
   require "simplecov"
   SimpleCov.print_error_status = false
   SimpleCov.formatter = SimpleCov::Formatter::SimpleFormatter
@@ -34,7 +34,7 @@ class Tag
   # conversions for arguments.
   # See: https://github.com/davetron5000/gli/issues/241
   def self.convert_to_tag(str)
-    str = str.strip
+    str = str.to_s.strip
     !str.empty? && str[0] == "@" ? str : "@#{str}"
   end
 end

data/lib/friends/commands/add.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-desc "Adds a friend (or nickname), activity, note, or location"
+desc "Adds a friend (or nickname), activity, note, or location (or alias)"
 command :add do |add|
   add.desc "Adds a friend"
   add.arg_name "NAME"
@@ -35,7 +35,16 @@ command :add do |add|
   add.arg_name "NAME NICKNAME"
   add.command :nickname do |add_nickname|
     add_nickname.action do |_, _, args|
-      @introvert.add_nickname(name: args.first.strip, nickname: args[1].strip)
+      @introvert.add_nickname(name: args.first.to_s.strip, nickname: args[1].to_s.strip)
+      @dirty = true # Mark the file for cleaning.
+    end
+  end
+
+  add.desc "Adds an alias to a location"
+  add.arg_name "LOCATION ALIAS"
+  add.command :alias do |add_alias|
+    add_alias.action do |_, _, args|
+      @introvert.add_alias(name: args.first.to_s.strip, nickname: args[1].to_s.strip)
       @dirty = true # Mark the file for cleaning.
     end
   end
@@ -46,7 +55,7 @@ command :add do |add|
     add_tag.action do |_, _, args|
       @introvert.add_tag(
         name: args[0..-2].join(" "),
-        tag: Tag.convert_to_tag(args.last.strip)
+        tag: Tag.convert_to_tag(args.last.to_s.strip)
       )
       @dirty = true # Mark the file for cleaning.
     end

data/lib/friends/commands/list.rb

@@ -19,11 +19,23 @@ command :list do |list|
                         negatable: false,
                         desc: "Output friend nicknames, locations, and tags"
 
+    list_friends.flag :sort,
+                      default_value: "alphabetical",
+                      arg_name: "ATTRIBUTE",
+                      must_match: %w[alphabetical n-activities recency],
+                      desc: "Sort output by one of: alphabetical, n-activities, recency"
+
+    list_friends.switch :reverse,
+                        negatable: false,
+                        desc: "Reverse the sort order"
+
     list_friends.action do |_, options|
       @introvert.list_friends(
         location_name: options[:in],
         tagged: options[:tagged],
-        verbose: options[:verbose]
+        verbose: options[:verbose],
+        sort: options[:sort],
+        reverse: options[:reverse]
       )
     end
   end
@@ -73,8 +85,26 @@ command :list do |list|
 
   list.desc "List all locations"
   list.command :locations do |list_locations|
-    list_locations.action do
-      @introvert.list_locations
+    list_locations.switch [:verbose],
+                          negatable: false,
+                          desc: "Output location aliases"
+
+    list_locations.flag :sort,
+                        default_value: "alphabetical",
+                        arg_name: "ATTRIBUTE",
+                        must_match: %w[alphabetical n-activities recency],
+                        desc: "Sort output by one of: alphabetical, n-activities, recency"
+
+    list_locations.switch :reverse,
+                          negatable: false,
+                          desc: "Reverse the sort order"
+
+    list_locations.action do |_, options|
+      @introvert.list_locations(
+        verbose: options[:verbose],
+        sort: options[:sort],
+        reverse: options[:reverse]
+      )
     end
   end
 
@@ -89,21 +119,4 @@ command :list do |list|
       @introvert.list_tags(from: options[:from])
     end
   end
-
-  list.desc "List favorite friends and locations"
-  list.command :favorite do |list_favorite|
-    list_favorite.desc "List favorite friends"
-    list_favorite.command :friends do |list_favorite_friends|
-      list_favorite_friends.action do
-        @introvert.list_favorite_friends
-      end
-    end
-
-    list_favorite.desc "List favorite locations"
-    list_favorite.command :locations do |list_favorite_locations|
-      list_favorite_locations.action do
-        @introvert.list_favorite_locations
-      end
-    end
-  end
 end

data/lib/friends/commands/remove.rb

@@ -11,6 +11,15 @@ command :remove do |remove|
     end
   end
 
+  remove.desc "Removes an alias from a location"
+  remove.arg_name "LOCATION ALIAS"
+  remove.command :alias do |remove_alias|
+    remove_alias.action do |_, _, args|
+      @introvert.remove_alias(name: args.first.to_s.strip, nickname: args[1].to_s.strip)
+      @dirty = true # Mark the file for cleaning.
+    end
+  end
+
   remove.desc "Removes a tag from a friend"
   remove.arg_name "NAME @TAG"
   remove.command :tag do |remove_tag|

data/lib/friends/introvert.rb

@@ -203,6 +203,7 @@ module Friends
     # @param nickname [String] the nickname to add to the friend
     # @raise [FriendsError] if 0 or 2+ friends match the given name
     def add_nickname(name:, nickname:)
+      raise FriendsError, "Expected \"[Friend Name]\" \"[Nickname]\"" if name.empty?
       raise FriendsError, "Nickname cannot be blank" if nickname.empty?
 
       friend = thing_with_name_in(:friend, name)
@@ -211,11 +212,37 @@ module Friends
       @output << "Nickname added: \"#{friend}\""
     end
 
+    # Add an alias to an existing location.
+    # @param name [String] the name of the location
+    # @param nickname [String] the alias to add to the location
+    # @raise [FriendsError] if 0 or 2+ locations match the given name
+    # @raise [FriendsError] if the alias is already taken
+    def add_alias(name:, nickname:)
+      raise FriendsError, "Expected \"[Location Name]\" \"[Alias]\"" if name.empty?
+      raise FriendsError, "Alias cannot be blank" if nickname.empty?
+
+      collision = @locations.find do |loc|
+        loc.name.casecmp(nickname).zero? || loc.aliases.any? { |a| a.casecmp(nickname).zero? }
+      end
+
+      if collision
+        raise FriendsError,
+              "The location alias \"#{nickname}\" is already taken by "\
+              "\"#{collision}\""
+      end
+
+      location = thing_with_name_in(:location, name)
+      location.add_alias(nickname)
+
+      @output << "Alias added: \"#{location}\""
+    end
+
     # Add a tag to an existing friend.
     # @param name [String] the name of the friend
     # @param tag [String] the tag to add to the friend, of the form: "@tag"
     # @raise [FriendsError] if 0 or 2+ friends match the given name
     def add_tag(name:, tag:)
+      raise FriendsError, "Expected \"[Friend Name]\" \"[Tag]\"" if name.empty?
       raise FriendsError, "Tag cannot be blank" if tag == "@"
 
       friend = thing_with_name_in(:friend, name)
@@ -248,6 +275,21 @@ module Friends
       @output << "Nickname removed: \"#{friend}\""
     end
 
+    # Remove an alias from an existing location.
+    # @param name [String] the name of the location
+    # @param nickname [String] the alias to remove from the location
+    # @raise [FriendsError] if 0 or 2+ locations match the given name
+    # @raise [FriendsError] if the location does not have the given alias
+    def remove_alias(name:, nickname:)
+      raise FriendsError, "Expected \"[Location Name]\" \"[Alias]\"" if name.empty?
+      raise FriendsError, "Alias cannot be blank" if nickname.empty?
+
+      location = thing_with_name_in(:location, name)
+      location.remove_alias(nickname)
+
+      @output << "Alias removed: \"#{location}\""
+    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
@@ -255,7 +297,11 @@ module Friends
     #   unfiltered
     # @param verbose [Boolean] true iff we should output friend names with
     #   nicknames, locations, and tags; false for names only
-    def list_friends(location_name:, tagged:, verbose:)
+    # @param sort [String] one of:
+    #   ["alphabetical", "n-activities", "recency"]
+    # @param reverse [Boolean] true iff we should reverse the sorted order of
+    #   our output
+    def list_friends(location_name:, tagged:, verbose:, sort:, reverse:)
       fs = @friends
 
       # Filter by location if a name is passed.
@@ -271,18 +317,11 @@ module Friends
         end
       end
 
-      (verbose ? fs.map(&:to_s) : fs.map(&:name)).each { |line| @output << line }
+      list_things(type: :friend, arr: fs, verbose: verbose, sort: sort, reverse: reverse)
     end
 
-    # List your favorite friends.
-    def list_favorite_friends
-      list_favorite_things(:friend)
-    end
-
-    # List your favorite friends.
-    def list_favorite_locations
-      list_favorite_things(:location)
-    end
+    NA_STR = "N/A"
+    private_constant :NA_STR
 
     # See `list_events` for all of the parameters we can pass.
     def list_activities(**args)
@@ -295,8 +334,14 @@ module Friends
     end
 
     # List all location names in the friends file.
-    def list_locations
-      @locations.each { |location| @output << location.name }
+    # @param verbose [Boolean] true iff we should output location names with
+    #   aliases; false for names only
+    # @param sort [String] one of:
+    #   ["alphabetical", "n-activities", "recency"]
+    # @param reverse [Boolean] true iff we should reverse the sorted order of
+    #   our output
+    def list_locations(verbose:, sort:, reverse:)
+      list_things(type: :location, verbose: verbose, sort: sort, reverse: reverse)
     end
 
     # @param from [Array] containing any of: ["activities", "friends", "notes"]
@@ -427,16 +472,16 @@ module Friends
     #
     # The returned hash uses the following format:
     #   {
-    #     /regex/ => [list of friends matching regex]
+    #     /regex/ => location
     #   }
     #
     # 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>}]
+    # @return [Hash{Regexp => location}]
     def regex_location_map
       @locations.each_with_object({}) do |location, hash|
-        hash[location.regex_for_name] = location
+        location.regexes_for_name.each { |regex| hash[regex] = location }
       end.sort_by { |k, _| -k.to_s.size }.to_h
     end
 
@@ -495,6 +540,49 @@ module Friends
 
     private
 
+    # List either friends or activities
+    # @param arr [Array<Friend|Activity>] a filtered list to print
+    # @param verbose [Boolean] true iff we should output names with
+    #   aliases/nicknames/etc.; false for names only
+    # @param sort [String] one of:
+    #   ["alphabetical", "n-activities", "recency"]
+    # @param reverse [Boolean] true iff we should reverse the sorted order of
+    #   our output
+    def list_things(type:, arr: instance_variable_get("@#{type}s"), verbose:, sort:, reverse:)
+      case sort
+      when "alphabetical"
+        arr = stable_sort(arr) # In case the input file was not already sorted.
+      when "n-activities"
+        arr = stable_sort_by(arr) { |thing| -thing.n_activities }
+      when "recency"
+        today = Date.today
+
+        most_recent_activity_by_thing = @activities.each_with_object({}) do |activity, output|
+          activity.send("#{type}_names").each do |thing_name|
+            output[thing_name] = (today - activity.date).to_i unless output.key?(thing_name)
+          end
+        end
+
+        arr = stable_sort_by(arr) do |thing|
+          most_recent_activity_by_thing[thing.name] || -Float::INFINITY
+        end
+      end
+
+      (reverse ? arr.reverse : arr).each do |thing|
+        case sort
+        when "n-activities"
+          prefix = "#{Paint[thing.n_activities, :bold, :red]} "\
+                   "activit#{thing.n_activities == 1 ? 'y' : 'ies'}: "
+        when "recency"
+          n_days = most_recent_activity_by_thing[thing.name] || NA_STR
+          prefix = "#{Paint[n_days, :bold, :red]} "\
+                   "day#{'s' unless n_days == 1} ago: "
+        end
+
+        @output << "#{prefix}#{verbose ? thing.to_s : thing.name}"
+      end
+    end
+
     # @param from [Array] containing any of: ["activities", "friends", "notes"]
     #   If not empty, limits the tags returned to only those from either
     #   activities, notes, or friends.
@@ -544,6 +632,13 @@ module Friends
       arr.sort_by.with_index { |x, idx| [x, idx] }
     end
 
+    # @param arr [Array] an unsorted array
+    # @param &block [block] used to return a value for each element's sort position
+    # @return [Array] a stably-sorted array
+    def stable_sort_by(arr)
+      arr.sort_by.with_index { |x, idx| [yield(x), idx] }
+    end
+
     # Filter activities by friend, location and tag
     # @param events [Array<Event>] the base events to list, either @activities or @notes
     # @param with [Array<String>] the names of friends to filter by, or empty for
@@ -586,49 +681,6 @@ module Friends
       events
     end
 
-    # @param type [Symbol] one of: [:friend, :location]
-    # @raise [ArgumentError] if type is not one of: [:friend, :location]
-    def list_favorite_things(type)
-      unless [:friend, :location].include? type
-        raise ArgumentError, "Type must be either :friend or :location"
-      end
-
-      # Sort the results, with the most favorite thing first.
-      results = instance_variable_get("@#{type}s").sort_by do |thing|
-        -thing.n_activities
-      end
-
-      @output << "Your favorite #{type}s:"
-
-      max_str_size = results.map(&:name).map(&:size).max
-
-      grouped_results = results.group_by(&:n_activities)
-
-      rank = 1
-      first = true
-      data = grouped_results.each.with_object([]) do |(n_activities, things), arr|
-        things.each do |thing|
-          name = thing.name.ljust(max_str_size)
-          if first
-            label = n_activities == 1 ? " activity" : " activities"
-            first = false
-          end
-          str = "#{name} (#{n_activities}#{label})"
-
-          arr << [rank, str]
-        end
-        rank += things.size
-      end
-
-      # We need to use `data.last.first` instead of `rank` to determine the size
-      # of the numbering prefix because `rank` will simply be the size of all
-      # elements, which may be too large if the last element in the list is a tie.
-      num_str_size = data.last.first.to_s.size + 1 unless data.empty?
-      data.each do |ranking, str|
-        @output << "#{"#{ranking}.".ljust(num_str_size)} #{str}"
-      end
-    end
-
     # Sets the n_activities field on each thing.
     # @param type [Symbol] one of: [:friend, :location]
     # @raise [ArgumentError] if `type` is not one of: [:friend, :location]
@@ -749,11 +801,7 @@ module Friends
     # @raise [FriendsError] if 0 or 2+ friends match the given text
     def thing_with_name_in(type, text)
       things = instance_variable_get("@#{type}s").select do |thing|
-        if type == :friend
-          thing.regexes_for_name.any? { |regex| regex.match(text) }
-        else
-          thing.regex_for_name.match(text)
-        end
+        thing.regexes_for_name.any? { |regex| regex.match(text) }
       end
 
       # If there's more than one match with fuzzy regexes but exactly one thing

data/lib/friends/location.rb

@@ -10,11 +10,12 @@ module Friends
     extend Serializable
 
     SERIALIZATION_PREFIX = "- "
+    ALIAS_PREFIX = "a.k.a. "
 
     # @return [Regexp] the regex for capturing groups in deserialization
     def self.deserialization_regex
       # Note: this regex must be on one line because whitespace is important
-      /(#{SERIALIZATION_PREFIX})?(?<name>.+)/
+      /(#{SERIALIZATION_PREFIX})?(?<name>[^\(]*[^\(\s])(\s+\(#{ALIAS_PREFIX}(?<alias_str>.+)\))?/
     end
 
     # @return [Regexp] the string of what we expected during deserialization
@@ -23,21 +24,52 @@ module Friends
     end
 
     # @param name [String] the name of the location
-    def initialize(name:)
+    def initialize(name:, alias_str: nil)
       @name = name
+      @aliases = alias_str&.split(" #{ALIAS_PREFIX}") || []
     end
 
     attr_accessor :name
+    attr_reader :aliases
 
     # @return [String] the file serialization text for the location
     def serialize
-      "#{SERIALIZATION_PREFIX}#{@name}"
+      Paint.unpaint("#{SERIALIZATION_PREFIX}#{self}")
     end
 
-    # @return [Regexp] the regex used to match this location's name in an
-    #   activity description
-    def regex_for_name
-      Friends::RegexBuilder.regex(@name)
+    # @return [String] a string representing the location's name and aliases
+    def to_s
+      unless @aliases.empty?
+        alias_str = " (" +
+                    @aliases.map do |nickname|
+                      "#{ALIAS_PREFIX}#{Paint[nickname, :bold, :yellow]}"
+                    end.join(" ") + ")"
+      end
+
+      "#{Paint[@name, :bold]}#{alias_str}"
+    end
+
+    # Add an alias, ignoring duplicates.
+    # @param nickname [String] the alias to add
+    def add_alias(nickname)
+      @aliases << nickname
+      @aliases.uniq!
+    end
+
+    # @param nickname [String] the alias to remove
+    # @raise [FriendsError] if the location does not have the given alias
+    def remove_alias(nickname)
+      unless @aliases.include? nickname
+        raise FriendsError, "Alias \"#{nickname}\" not found for \"#{name}\""
+      end
+
+      @aliases.delete(nickname)
+    end
+
+    # @return [Array] a list of all regexes to match the name in a string
+    # NOTE: Only full names and aliases
+    def regexes_for_name
+      [name, *@aliases].map { |str| Friends::RegexBuilder.regex(str) }
     end
 
     # The number of activities this location is in. This is for internal use