standup_md 1.0.0 → 2.0.0

data/lib/standup_md/config/post.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "standup_md/post"
+
+module StandupMD
+  class Config
+    ##
+    # The configuration class for chat posting.
+    class Post
+      ##
+      # The default posting options.
+      #
+      # @return [Hash]
+      DEFAULTS = {
+        default_adapter: :slack,
+        title: nil
+      }.freeze
+
+      ##
+      # Attributes copied into request-scoped config snapshots.
+      #
+      # @return [Array<Symbol>]
+      CONFIG_ATTRIBUTES = DEFAULTS.keys.freeze
+
+      ##
+      # The adapter used when `standup --post` is called without a platform.
+      #
+      # @return [Symbol]
+      attr_accessor :default_adapter
+
+      ##
+      # Format string for posted entry titles.
+      #
+      # This only affects messages sent through chat posting adapters. It does
+      # not change stored standup markdown files. Use `%s` as a placeholder for
+      # the normal entry title, such as the entry date. This is useful when chat
+      # clients post through workspace apps or bots with shared names like
+      # "StandupMD", but the message should still identify whose standup it is.
+      #
+      # @example Include the person's name after the entry date
+      #   StandupMD.config.post.title = "%s - Evan Gray"
+      #
+      # @return [String, nil]
+      attr_accessor :title
+
+      ##
+      # Registered adapter classes or instances.
+      #
+      # @return [Hash]
+      attr_reader :adapters
+
+      ##
+      # Non-secret adapter options.
+      #
+      # @return [Hash]
+      attr_reader :adapter_options
+
+      ##
+      # Initializes the config with default values.
+      def initialize
+        reset
+      end
+
+      ##
+      # Sets all config values back to their defaults.
+      #
+      # @return [Hash]
+      def reset
+        DEFAULTS.each { |k, v| instance_variable_set("@#{k}", v) }
+        @adapters = {}
+        @adapter_options = Hash.new { |hash, key| hash[key] = {} }
+        register_adapter(:slack, StandupMD::Post::Adapters::Slack)
+        DEFAULTS
+      end
+
+      ##
+      # Copies values from another post config.
+      #
+      # @param [StandupMD::Config::Post] config
+      #
+      # @return [StandupMD::Config::Post]
+      def copy_from(config)
+        CONFIG_ATTRIBUTES.each do |attribute|
+          instance_variable_set("@#{attribute}", config.public_send(attribute))
+        end
+        @adapters = config.adapters.dup
+        @adapter_options = Hash.new { |hash, key| hash[key] = {} }
+        config.adapter_options.each do |name, options|
+          @adapter_options[name] = options.dup
+        end
+        self
+      end
+
+      ##
+      # Registers a posting adapter.
+      #
+      # @param name [String, Symbol]
+      # @param adapter [Class, Object]
+      #
+      # @return [Class, Object]
+      def register_adapter(name, adapter)
+        adapters[name.to_sym] = adapter
+      end
+
+      ##
+      # Configures non-secret adapter options.
+      #
+      # @param name [String, Symbol]
+      # @param options [Hash]
+      #
+      # @return [Hash]
+      def configure_adapter(name, options = {})
+        options_for(name).merge!(symbolize_keys(options))
+      end
+
+      ##
+      # Returns non-secret options for an adapter.
+      #
+      # @param name [String, Symbol]
+      #
+      # @return [Hash]
+      def options_for(name)
+        adapter_options[name.to_sym]
+      end
+
+      ##
+      # Builds the adapter requested by name.
+      #
+      # @param name [String, Symbol, nil]
+      #
+      # @return [Object]
+      def build_adapter(name = nil)
+        adapter_name = (name || default_adapter).to_sym
+        adapter = adapters.fetch(adapter_name) do
+          raise StandupMD::Post::UnknownAdapter, "No post adapter registered for #{adapter_name}"
+        end
+        return adapter unless adapter.respond_to?(:new)
+        return adapter.new if adapter.instance_method(:initialize).arity.zero?
+
+        adapter.new(options_for(adapter_name))
+      end
+
+      private
+
+      def symbolize_keys(hash)
+        hash.each_with_object({}) do |(key, value), result|
+          result[key.to_sym] = value
+        end
+      end
+    end
+  end
+end

data/lib/standup_md/config.rb

@@ -3,7 +3,7 @@
 require "standup_md/config/cli"
 require "standup_md/config/file"
 require "standup_md/config/entry"
-require "standup_md/config/entry_list"
+require "standup_md/config/post"
 
 module StandupMD
   ##
@@ -28,10 +28,10 @@ module StandupMD
     attr_reader :entry
 
     ##
-    # Reader for EntryList config.
+    # Reader for Post config.
     #
-    # @return [StandupMD::Config::EntryList]
-    attr_reader :entry_list
+    # @return [StandupMD::Config::Post]
+    attr_reader :post
 
     ##
     # Builds the links to the configuration classes.
@@ -39,7 +39,20 @@ module StandupMD
       @cli = StandupMD::Config::Cli.new
       @file = StandupMD::Config::File.new
       @entry = StandupMD::Config::Entry.new
-      @entry_list = StandupMD::Config::EntryList.new
+      @post = StandupMD::Config::Post.new
+    end
+
+    ##
+    # Builds an independent snapshot of the current configuration.
+    #
+    # @return [StandupMD::Config]
+    def copy
+      self.class.new.tap do |config|
+        config.cli.copy_from(cli)
+        config.file.copy_from(file)
+        config.entry.copy_from(entry)
+        config.post.copy_from(post)
+      end
     end
   end
 end

data/lib/standup_md/entry.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "json"
 require "standup_md/section"
 
 module StandupMD
@@ -10,6 +9,10 @@ module StandupMD
   class Entry
     include Comparable
 
+    ##
+    # Section identifiers supported by each standup entry.
+    #
+    # @return [Array<Symbol>]
     SECTION_TYPES = %i[current previous impediments notes].freeze
 
     ##
@@ -17,7 +20,7 @@ module StandupMD
     #
     # @return [StandupMD::Config::Entry]
     def self.config
-      @config ||= StandupMD.config.entry
+      StandupMD.config.entry
     end
 
     ##
@@ -32,14 +35,33 @@ module StandupMD
     # Creates a generic entry. Default values can be set via configuration.
     # Yields the entry if a block is passed so you can change values.
     #
+    # @param [StandupMD::Config::Entry] config
+    #
+    # @param [Date] date
+    #
+    # @param [Array, nil] current
+    #
+    # @param [Array, nil] previous
+    #
+    # @param [Array, nil] impediments
+    #
+    # @param [Array, nil] notes
+    #
     # @return [StandupMD::Entry]
-    def self.create
+    def self.create(
+      config: StandupMD.config.entry,
+      date: Date.today,
+      current: nil,
+      previous: nil,
+      impediments: nil,
+      notes: nil
+    )
       new(
-        Date.today,
-        config.current,
-        config.previous,
-        config.impediments,
-        config.notes
+        date,
+        current || config.current,
+        previous || config.previous,
+        impediments || config.impediments,
+        notes || config.notes
       ).tap { |entry| yield entry if block_given? }
     end
 
@@ -58,7 +80,6 @@ module StandupMD
     def initialize(date, current, previous, impediments, notes = [])
       raise unless date.is_a?(Date)
 
-      @config = self.class.config
       @date = date
       @sections = {}
       self.current = current
@@ -106,7 +127,7 @@ module StandupMD
     end
 
     ##
-    # Entry as a hash .
+    # Entry as a hash.
     #
     # @return [Hash]
     def to_h
@@ -120,14 +141,6 @@ module StandupMD
       }
     end
 
-    ##
-    # Entry as a json object.
-    #
-    # @return [String]
-    def to_json
-      to_h.to_json
-    end
-
     private
 
     def set_section(type, tasks)

data/lib/standup_md/entry_list.rb

@@ -10,15 +10,7 @@ module StandupMD
     include Enumerable
 
     ##
-    # Access to the class's configuration.
-    #
-    # @return [StandupMD::Config::EntryList]
-    def self.config
-      @config ||= StandupMD.config.entry_list
-    end
-
-    ##
-    # Contruct a list. Can pass any amount of +StandupMD::Entry+ instances.
+    # Construct a list. Can pass any amount of +StandupMD::Entry+ instances.
     #
     # @param [Entry] entries
     #
@@ -26,7 +18,6 @@ module StandupMD
     def initialize(*entries)
       entries.each { |entry| validate_entry(entry) }
 
-      @config = self.class.config
       @entries = entries
     end
 
@@ -35,7 +26,7 @@ module StandupMD
     #
     # @param [StandupMD::Entry] entry
     #
-    # @return [Array]
+    # @return [StandupMD::EntryList]
     def <<(entry)
       validate_entry(entry)
 
@@ -100,9 +91,9 @@ module StandupMD
     #
     # @param [Date] end_date
     #
-    # @return [Array]
+    # @return [StandupMD::EntryList]
     def filter!(start_date, end_date)
-      @entries = filter(start_date, end_date)
+      @entries = filter(start_date, end_date).to_a
       self
     end
 
@@ -124,18 +115,10 @@ module StandupMD
       end.to_h
     end
 
-    ##
-    # The entry list as a json object.
-    #
-    # @return [String]
-    def to_json
-      to_h.to_json
-    end
-
     # :section: Delegators
 
     ##
-    # The following are forwarded to @entries, which is the underly array of
+    # The following are forwarded to @entries, which is the underlying array of
     # entries.
     #
     # +each+:: Iterate over each entry.

data/lib/standup_md/file.rb

@@ -8,68 +8,59 @@ module StandupMD
   ##
   # Class for handling reading and writing standup files.
   class File
+    ##
+    # Raised when a standup file or directory is missing and creation is off.
+    class NotFoundError < StandardError; end
+
     class << self
       ##
       # Access to the class's configuration.
       #
-      # @return [StandupMD::Config::EntryList]
+      # @return [StandupMD::Config::File]
       def config
-        @config ||= StandupMD.config.file
+        StandupMD.config.file
       end
 
       ##
-      # Convenience method for calling File.find(file_name).load
+      # Convenience method for calling File.find(file_name).load.
       #
       # @param [String] file_name
+      # @param [StandupMD::Config::File] config
       #
       # @return [StandupMD::File]
-      def load(file_name)
-        unless ::File.directory?(config.directory)
-          raise "Dir #{config.directory} not found." unless config.create
-
-          FileUtils.mkdir_p(config.directory)
-        end
-        new(file_name).load
+      def load(file_name, config: StandupMD.config.file)
+        new(file_name, config: config).load
       end
 
       ##
       # Find standup file in directory by file name.
       #
-      # @param [String] File_naem
-      def find(file_name)
-        unless ::File.directory?(config.directory)
-          raise "Dir #{config.directory} not found." unless config.create
-
-          FileUtils.mkdir_p(config.directory)
-        end
-        file_path = ::File.join(config.directory, file_name)
-        unless ::File.file?(file_path) || config.create
-          raise "File #{file_name} not found."
-        end
-
-        new(file_name)
+      # @param [String] file_name
+      # @param [StandupMD::Config::File] config
+      #
+      # @return [StandupMD::File]
+      def find(file_name, config: StandupMD.config.file)
+        new(file_name, config: config)
       end
 
       ##
       # Find standup file in directory by Date object.
       #
       # @param [Date] date
-      def find_by_date(date)
+      # @param [StandupMD::Config::File] config
+      #
+      # @return [StandupMD::File]
+      def find_by_date(date, config: StandupMD.config.file)
         raise ArgumentError, "Must be a Date object" unless date.is_a?(Date)
 
-        unless ::File.directory?(config.directory)
-          raise "Dir #{config.directory} not found." unless config.create
-
-          FileUtils.mkdir_p(config.directory)
-        end
-        find(date.strftime(config.name_format))
+        find(date.strftime(config.name_format), config: config)
       end
     end
 
     ##
     # The list of entries in the file.
     #
-    # @return [StandupMP::EntryList]
+    # @return [StandupMD::EntryList]
     attr_reader :entries
 
     ##
@@ -82,29 +73,20 @@ module StandupMD
     # Constructs the instance.
     #
     # @param [String] file_name
+    # @param [StandupMD::Config::File] config
     #
-    # @return [StandupMP::File]
-    def initialize(file_name)
-      @config = self.class.config
+    # @return [StandupMD::File]
+    def initialize(file_name, config: StandupMD.config.file)
+      @config = config
       @parser = StandupMD::Parsers::Markdown.new(@config)
       if file_name.include?(::File::SEPARATOR)
         raise ArgumentError,
-          "#{file_name} contains directory. Please use `StandupMD.config.file.directory=`"
-      end
-
-      unless ::File.directory?(@config.directory)
-        raise "Dir #{@config.directory} not found." unless @config.create
-
-        FileUtils.mkdir_p(@config.directory)
+          "#{file_name} contains directory. Configure the file directory separately."
       end
 
+      ensure_directory
       @name = ::File.expand_path(::File.join(@config.directory, file_name))
-
-      unless ::File.file?(@name)
-        raise "File #{@name} not found." unless @config.create
-
-        FileUtils.touch(@name)
-      end
+      ensure_file
 
       @new = ::File.zero?(@name)
       @loaded = false
@@ -137,28 +119,49 @@ module StandupMD
     ##
     # Loads the file's contents.
     #
-    # @return [StandupMD::FileList]
+    # @return [StandupMD::File]
     def load
-      raise "File #{name} does not exist." unless ::File.file?(name)
+      raise NotFoundError, "File #{name} does not exist." unless ::File.file?(name)
 
       @loaded = true
-      @entries = @parser.read(name)
+      @entries = @parser.parse(::File.read(name))
       self
     end
 
     ##
-    # Writes a new entry to the file if the first entry in the file isn't today.
-    # This method is destructive; if a file for entries in the date range
-    # already exists, it will be clobbered with the entries in the range.
+    # Writes entries to disk. This method is destructive; existing file contents
+    # are replaced by the rendered entries in the requested date range.
     #
     # @param [Hash] {start_date: Date, end_date: Date}
     #
     # @return [Boolean] true if successful
     def write(**dates)
+      raise ArgumentError, "No entries loaded for #{name}" if entries.nil? || entries.empty?
+
       sorted_entries = entries.sort
       start_date = dates.fetch(:start_date, sorted_entries.first.date)
       end_date = dates.fetch(:end_date, sorted_entries.last.date)
-      @parser.write(name, sorted_entries, start_date: start_date, end_date: end_date)
+      ::File.write(
+        name,
+        @parser.render(sorted_entries, start_date: start_date, end_date: end_date)
+      )
+      true
+    end
+
+    private
+
+    def ensure_directory
+      return if ::File.directory?(@config.directory)
+      raise NotFoundError, "Dir #{@config.directory} not found." unless @config.create
+
+      FileUtils.mkdir_p(@config.directory)
+    end
+
+    def ensure_file
+      return if ::File.file?(@name)
+      raise NotFoundError, "File #{@name} not found." unless @config.create
+
+      FileUtils.touch(@name)
     end
   end
 end

data/lib/standup_md/parsers/markdown.rb

@@ -5,13 +5,18 @@ require "standup_md/entry"
 require "standup_md/entry_list"
 require "standup_md/section"
 require "standup_md/task"
-require "standup_md/title"
 
 module StandupMD
+  ##
+  # Namespace for standup file parsers and renderers.
   module Parsers
     ##
     # Parser and renderer for the markdown standup format.
     class Markdown
+      ##
+      # Raised when markdown cannot be parsed into standup entries.
+      class Error < StandardError; end
+
       ##
       # Access to file configuration.
       #
@@ -27,17 +32,17 @@ module StandupMD
       end
 
       ##
-      # Reads entries from a markdown standup file.
+      # Parses entries from markdown text.
       #
-      # @param [String] file_name
+      # @param [String] text
       #
       # @return [StandupMD::EntryList]
-      def read(file_name)
+      def parse(text)
         entry_list = EntryList.new
         record = nil
         section = nil
 
-        ::File.foreach(file_name) do |line|
+        text.to_s.each_line do |line|
           line.chomp!
           next if line.strip.empty?
 
@@ -57,42 +62,40 @@ module StandupMD
         entry_list << entry(record) if record
         entry_list.sort
       rescue => e
-        raise "File malformation: #{e}"
+        raise Error, "Markdown malformation: #{e.message}"
       end
 
       ##
-      # Writes entries to a markdown standup file.
+      # Renders entries as markdown text.
       #
-      # @param [String] file_name
       # @param [StandupMD::EntryList] entries
       # @param [Date] start_date
       # @param [Date] end_date
       #
-      # @return [Boolean]
-      def write(file_name, entries, start_date:, end_date:)
-        ::File.open(file_name, "w") do |f|
-          entries.filter(start_date, end_date).sort_reverse.each do |entry|
-            f.puts Title.new(entry.date).to_markdown
-            config.sub_header_order.each do |attr|
-              section = Section.new(attr, entry.public_send("#{attr}_tasks"))
-              next if section.empty?
-
-              f.puts section.to_markdown
-            end
-            f.puts
-          end
-        end
-        true
+      # @return [String]
+      def render(entries, start_date:, end_date:)
+        entries.filter(start_date, end_date).sort_reverse.map do |entry|
+          render_entry(entry)
+        end.join
       end
 
       ##
-      # Renders a task as a markdown list item.
+      # Renders a single entry as markdown text.
       #
-      # @param [String, StandupMD::Task] task
+      # @param [StandupMD::Entry] entry
       #
       # @return [String]
-      def task_line(task)
-        build_task(task).to_markdown
+      def render_entry(entry)
+        lines = [entry_header(entry)]
+        config.sub_header_order.each do |type|
+          section = Section.new(type, entry.public_send("#{type}_tasks"))
+          next if section.empty?
+
+          lines << section_header(type)
+          section.tasks.each { |task| lines << task_line(task) }
+        end
+        lines << ""
+        lines.join("\n") + "\n"
       end
 
       private
@@ -121,11 +124,19 @@ module StandupMD
         Section.new(type)
       end
 
+      def entry_header(entry)
+        "#{"#" * config.header_depth} #{entry.date.strftime(config.header_date_format)}"
+      end
+
+      def section_header(type)
+        "#{"#" * config.sub_header_depth} #{config.public_send("#{type}_header")}"
+      end
+
       def section_type(line)
         sub_header = line.sub(/^\#{#{config.sub_header_depth}}\s*/, "")
         Entry::SECTION_TYPES.each do |type|
           header = config.public_send("#{type}_header")
-          return type if sub_header.include?(header)
+          return type if sub_header == header
         end
         raise "Unrecognized header [#{sub_header}]"
       end
@@ -144,6 +155,11 @@ module StandupMD
         /\A(?<indent>\s*)#{Regexp.escape(config.bullet_character)}\s*(?<text>.*)\z/
       end
 
+      def task_line(task)
+        indent = " " * config.indent_width * task.indent_level
+        "#{indent}#{config.bullet_character} #{task.text}"
+      end
+
       def entry(record)
         Entry.new(
           Date.strptime(record[:title], config.header_date_format),
@@ -157,12 +173,6 @@ module StandupMD
       def tasks(record, type)
         record[:sections].fetch(type, Section.new(type)).tasks
       end
-
-      def build_task(task)
-        return task if task.is_a?(Task)
-
-        Task.new(task)
-      end
     end
   end
 end