standup_md 0.3.15 → 0.3.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b95cee87e34194f847a9830ccf56694e1c450c0bdbae04b8b0af0df7716daaaa
-  data.tar.gz: 2d8466163ca2687ca156e62c12399b01a65454e57eb3d7376931908e0e39a61c
+  metadata.gz: f155bb0cdeacfcf00716bfd5cfbc67a9e5d6d1d8be2b89c35d0f148ec782b264
+  data.tar.gz: fa9f7a3d971f45f79f2f819fcaa05c761bdf2cd3d9b4de3abc942b320ca4765d
 SHA512:
-  metadata.gz: 522d4e0c57d9887456210fb79ac5fd4920350ffd7265f8dd2bc40369405ed4ef624cd29425dae92e480b1e694ad9ff5e5733e36c0800527f8c692f3335128ee8
-  data.tar.gz: 1229afe074eacb10dcf0b84dabd80d3a41695c604ade83e175739548bdebdf4d84fd5161f6f50bb9931239816fa885c78ff217b7950fdf31f4498919fccaee0a
+  metadata.gz: b22a137af1ae2a03cead81ffce5b46f517721dd22f5364318e595ebe7e22d6b9eb7e2ed05021acaec9a3f5d0f76769c98d73a898ee908be58656c4d7f01a60f8
+  data.tar.gz: 5cbbf132c3cbec6e1b6290c1d1b13f8c7f8f25aa6b02d0e51052964b4688dcad7350488cc17810b1f87a9098bdcba21824e752c9fd7bbc71e21d3edeb86ab112

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    standup_md (0.3.15)
+    standup_md (0.3.17)
 
 GEM
   remote: https://rubygems.org/
@@ -115,7 +115,7 @@ CHECKSUMS
   standard (1.54.0) sha256=7a4b08f83d9893083c8f03bc486f0feeb6a84d48233b40829c03ef4767ea0100
   standard-custom (1.0.2) sha256=424adc84179a074f1a2a309bb9cf7cd6bfdb2b6541f20c6bf9436c0ba22a652b
   standard-performance (1.9.0) sha256=49483d31be448292951d80e5e67cdcb576c2502103c7b40aec6f1b6e9c88e3f2
-  standup_md (0.3.15)
+  standup_md (0.3.17)
   stringio (3.2.0) sha256=c37cb2e58b4ffbd33fe5cd948c05934af997b36e0b6ca6fdf43afa234cf222e1
   test-unit (3.7.8) sha256=689d1ca53f4d46f678b4e5d68d8e4294f87fc5e8b9238cc4de7c5727e8d65943
   tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f

data/README.md

@@ -6,10 +6,11 @@
 
 > The cure for all your standup woes.
 
-A highly customizable and automated way to keep track of daily standups in
-markdown files.
+An automated, customizable way to keep track of daily standups in markdown
+files.
 
-You can view the documentation [here](https://evanthegrayt.github.io/standup_md/).
+You can view the documentation
+[here](https://evanthegrayt.github.io/standup_md/).
 
 ## About
 I've now been at two separate companies where we post our daily standups in a
@@ -43,7 +44,7 @@ gem install standup_md
 To include in your project, add the following to your `Gemfile`.
 
 ```ruby
-gem 'standup_md'
+gem "standup_md"
 ```
 
 ### Manual Installation
@@ -58,6 +59,17 @@ cd standup_md
 rake install
 ```
 
+### Zsh Completion
+The gem ships with a zsh completion file at `completion/zsh/_standup`. RubyGems
+doesn't automatically add gem-provided completion directories to zsh's `fpath`,
+so you'll need to add the completion directory yourself after installation.
+
+For setup instructions and example, run the following.
+
+```sh
+standup --zsh-completion
+```
+
 ## Usage
 ### Command Line
 For the most basic usage, simply call the executable.
@@ -73,6 +85,14 @@ important; you may add new entries, but don't change any of the headers. Doing
 so will cause the parser to break. If you want to customize the headers, you can
 do so in the [configuration file](#available-config-file-options-and-defaults).
 
+To open a previous month's standup file, pass the date as an argument. Both
+`YYYY-MM` and `YYYY-MM-DD` are accepted, and both open the file for that month.
+
+```sh
+standup 2026-06
+standup 2026-06-18
+```
+
 ### CLI Examples
 #### Adding an entry for today via editor
 For example, if the standup entry from yesterday reads as follows:
@@ -150,36 +170,36 @@ rails project, create an initializer (`config/initializers/standup_md.rb`).
 StandupMD.configure do |c|
   # Defaults for how the file is formatted.
   # See https://evanthegrayt.github.io/standup_md/doc/StandupMD/Config/Cli.html
-  c.file.header_date_format = '%Y-%m-%d'
+  c.file.header_date_format = "%Y-%m-%d"
   c.file.header_depth       = 1
   c.file.sub_header_depth   = 2
-  c.file.current_header     = 'Current'
-  c.file.previous_header    = 'Previous'
-  c.file.impediments_header = 'Impediments'
-  c.file.notes_header       = 'Notes'
+  c.file.current_header     = "Current"
+  c.file.previous_header    = "Previous"
+  c.file.impediments_header = "Impediments"
+  c.file.notes_header       = "Notes"
   c.file.sub_header_order   = %w[previous current impediments notes]
-  c.file.directory          = ::File.join(ENV['HOME'], '.cache', 'standup_md')
-  c.file.bullet_character   = '-'
-  c.file.name_format        = '%Y_%m.md'
+  c.file.directory          = ::File.join(ENV["HOME"], ".cache", "standup_md")
+  c.file.bullet_character   = "-"
+  c.file.name_format        = "%Y_%m.md"
   c.file.create             = true
 
-  # Defaults for entries
+  # Defaults for entries.
   # See https://evanthegrayt.github.io/standup_md/doc/StandupMD/Config/Entry.html
   c.entry.current          = ["<!-- ADD TODAY'S WORK HERE -->"]
   c.entry.previous         = []
-  c.entry.impediments      = ['None']
+  c.entry.impediments      = ["None"]
   c.entry.notes            = []
 
   # Defaults for executable runtime behavior.
   # See https://evanthegrayt.github.io/standup_md/doc/StandupMD/Config/Cli.html
   c.cli.date               = Date.today
-  c.cli.editor             = 'vim' # Checks $VISUAL and $EDITOR first, in that order
+  c.cli.editor             = "vim" # Checks $VISUAL and $EDITOR first, in that order
   c.cli.verbose            = false
   c.cli.edit               = true
   c.cli.write              = true
   c.cli.print              = false
   c.cli.auto_fill_previous = true
-  c.cli.preference_file    = ::File.expand_path(::File.join(ENV['HOME'], '.standuprc'))
+  c.cli.preference_file    = ::File.expand_path(::File.join(ENV["HOME"], ".standuprc"))
 end
 ```
 
@@ -205,6 +225,7 @@ Some of these options can be changed at runtime. They are as follows.
 -a  --[no-]auto-fill-previous  Auto-generate 'previous' tasks for new entries
 -e  --[no-]edit                Open the file in the editor. Default is true
 -v, --[no-]verbose             Verbose output. Default is false.
+    --zsh-completion           Print zsh completion setup instructions
 -p, --print [DATE]             Print current entry.
                                If DATE is passed, will print entry for DATE, if it exists.
                                DATE must be in the same format as file-name-format
@@ -250,11 +271,11 @@ Your `~/.standuprc` should contain:
 StandupMD.configure do |c|
   c.file.header_depth       = 2
   c.file.sub_header_depth   = 3
-  c.file.current_header     = 'Today'
-  c.file.previous_header    = 'Yesterday'
-  c.file.impediments_header = 'Hold-ups'
-  c.file.bullet_character   = '*'
-  c.file.header_date_format = '%m/%d/%Y'
+  c.file.current_header     = "Today"
+  c.file.previous_header    = "Yesterday"
+  c.file.impediments_header = "Hold-ups"
+  c.file.bullet_character   = "*"
+  c.file.header_date_format = "%m/%d/%Y"
   c.file.sub_header_order   = %w[current previous impediments notes]
 end
 ```
@@ -270,14 +291,14 @@ new entry via code could look like the following:
 ### API Examples
 #### Adding an entry for today
 ```ruby
-require 'standup_md'
+require "standup_md"
 
 StandupMD.configure do |c|
-  c.file.current_header = 'Today',
+  c.file.current_header = "Today",
 end
 
 file = StandupMD::File.find_by_date(Date.today)
-entry = StandupMD::Entry.create { |e| e.current = ['Stuff I will do today'] }
+entry = StandupMD::Entry.create { |e| e.current = ["Stuff I will do today"] }
 file.entries << entry
 file.write
 ```
@@ -286,11 +307,11 @@ The above example was written as such to show how the different pieces of the
 API fit together. The code can actually be simplified to the following.
 
 ```ruby
-require 'standup_md'
+require "standup_md"
 
 StandupMD.configure do |c|
-  c.file.current_header = 'Today',
-  c.entry.current = ['Stuff I will do today']
+  c.file.current_header = "Today",
+  c.entry.current = ["Stuff I will do today"]
 end
 
 StandupMD::File.find_by_date(Date.today).load.write
@@ -298,7 +319,7 @@ StandupMD::File.find_by_date(Date.today).load.write
 
 #### Finding a past entry
 ```ruby
-require 'standup_md'
+require "standup_md"
 
 date = Date.new(2020, 04, 15)
 file = StandupMD::File.find_by_date(date).load

data/Rakefile

@@ -39,3 +39,48 @@ task :"standard:fix" do
 end
 
 task default: :test
+
+namespace :version do
+  desc "Print the current version from the version.rb file"
+  task :current do
+    puts StandupMD::VERSION
+  end
+
+  namespace :increment do
+    desc "Increment the version's PATCH level"
+    task :patch do
+      File.join(__dir__, "lib", "standup_md", "version.rb").then do |version_file|
+        File.write(
+          version_file,
+          File.read(version_file).sub(/(PATCH\s=\s)(\d+)/) { "#{$1}#{$2.next}" }
+        )
+      end
+      system("bundle lock")
+    end
+    desc "Increment the version's MINOR level"
+    task :minor do
+      File.join(__dir__, "lib", "standup_md", "version.rb").then do |version_file|
+        File.write(
+          version_file,
+          File.read(version_file)
+            .sub(/(PATCH\s=\s)(\d+)/) { "#{$1}0" }
+            .sub(/(MINOR\s=\s)(\d+)/) { "#{$1}#{$2.next}" }
+        )
+      end
+      system("bundle lock")
+    end
+    desc "Increment the version's MAJOR level"
+    task :major do
+      File.join(__dir__, "lib", "standup_md", "version.rb").then do |version_file|
+        File.write(
+          version_file,
+          File.read(version_file)
+            .sub(/(PATCH\s=\s)(\d+)/) { "#{$1}0" }
+            .sub(/(MINOR\s=\s)(\d+)/) { "#{$1}0" }
+            .sub(/(MAJOR\s=\s)(\d+)/) { "#{$1}#{$2.next}" }
+        )
+      end
+      system("bundle lock")
+    end
+  end
+end

data/completion/zsh/_standup

@@ -0,0 +1,80 @@
+#compdef standup
+
+_standup_array_values() {
+  _message -e values 'comma-separated list'
+}
+
+_standup_sub_header_order() {
+  local -a headers
+
+  headers=(
+    'previous:previous entry tasks'
+    'current:current entry tasks'
+    'impediments:current entry impediments'
+    'notes:current entry notes'
+  )
+
+  _values -s , 'sub-header' $headers
+}
+
+_standup_dates() {
+  local directory="${STANDUP_MD_DIR:-$HOME/.cache/standup_md}"
+  local index
+  local file
+  local -a dates
+
+  for (( index = 1; index <= $#words; index++ )); do
+    case "$words[index]" in
+      --directory=*)
+        directory="${words[index]#--directory=}"
+        ;;
+      --directory|-d)
+        if (( index < $#words )); then
+          directory="$words[index + 1]"
+        fi
+        ;;
+    esac
+  done
+
+  directory=${~directory}
+  if [[ -d "$directory" ]]; then
+    for file in "$directory"/*.md(N); do
+      file="${file:t:r}"
+      if [[ "$file" == <->_<-> ]]; then
+        dates+=("${file/_/-}:standup file ${file}.md")
+      fi
+    done
+  fi
+
+  if (( ${#dates} )); then
+    _describe -t dates 'standup date' dates
+  else
+    _message -e dates 'date (YYYY-MM or YYYY-MM-DD)'
+  fi
+}
+
+_arguments -s -S \
+  '(- *)'{-h,--help}'[show help]' \
+  '(- *)--version[show version]' \
+  '(- *)--zsh-completion[print zsh completion setup instructions]' \
+  '--current[List of current entry tasks]:tasks:_standup_array_values' \
+  '--previous[List of previous entry tasks]:tasks:_standup_array_values' \
+  '--impediments[List of impediments for current entry]:impediments:_standup_array_values' \
+  '--notes[List of notes for current entry]:notes:_standup_array_values' \
+  '--sub-header-order[The order of the sub-headers when writing the file]:sub-header order:_standup_sub_header_order' \
+  '(-f --file-name-format)-f[Date-formattable string to use for standup file name]:strftime format:' \
+  '(-f --file-name-format)--file-name-format[Date-formattable string to use for standup file name]:strftime format:' \
+  '(-E --editor)-E[Editor to use for opening standup files]:editor:_path_commands' \
+  '(-E --editor)--editor[Editor to use for opening standup files]:editor:_path_commands' \
+  '(-d --directory)-d[The directory where standup files are located]:directory:_directories' \
+  '(-d --directory)--directory[The directory where standup files are located]:directory:_directories' \
+  '(-w --write --no-write)'{-w,--write}'[write current entry if it does not exist]' \
+  '(-w --write --no-write)--no-write[do not write current entry if it does not exist]' \
+  '(-a --auto-fill-previous --no-auto-fill-previous)'{-a,--auto-fill-previous}'[auto-generate previous tasks for new entries]' \
+  '(-a --auto-fill-previous --no-auto-fill-previous)--no-auto-fill-previous[do not auto-generate previous tasks for new entries]' \
+  '(-e --edit --no-edit)'{-e,--edit}'[open the file in the editor]' \
+  '(-e --edit --no-edit)--no-edit[do not open the file in the editor]' \
+  '(-v --verbose --no-verbose)'{-v,--verbose}'[use verbose output]' \
+  '(-v --verbose --no-verbose)--no-verbose[disable verbose output]' \
+  '(-p --print)'{-p,--print}'[print current entry]::date:_standup_dates' \
+  '1:standup file date:_standup_dates'

data/lib/standup_md/cli/helpers.rb

@@ -104,6 +104,11 @@ module StandupMD
             "Verbose output. Default is false."
           ) { |v| config.cli.verbose = v }
 
+          opts.on(
+            "--zsh-completion",
+            "Print zsh completion setup instructions"
+          ) { @zsh_completion_requested = true }
+
           opts.on(
             "-p", "--print [DATE]",
             "Print current entry.",
@@ -115,6 +120,17 @@ module StandupMD
               v.nil? ? Date.today : Date.strptime(v, config.file.header_date_format)
           end
         end.parse!(options)
+        if zsh_completion_requested?
+          raise OptionParser::InvalidArgument, options.join(" ") unless options.empty?
+
+          return
+        end
+
+        unless options.empty?
+          @file_date_argument = true
+          config.cli.date = parse_file_date(options.shift)
+        end
+        raise OptionParser::InvalidArgument, options.join(" ") unless options.empty?
       end
 
       ##
@@ -123,7 +139,7 @@ module StandupMD
       # @return [StandupMD::Entry]
       def new_entry(file)
         entry = file.entries.find(config.cli.date)
-        return entry unless entry.nil? && config.cli.date == Date.today
+        return entry if read_only? || entry || config.cli.date != Date.today
 
         StandupMD::Entry.new(
           config.cli.date,
@@ -145,6 +161,25 @@ module StandupMD
         prev_entry(file.entries)
       end
 
+      ##
+      # Parses the optional file date argument.
+      #
+      # @param [String] value
+      #
+      # @return [Date]
+      def parse_file_date(value)
+        case value
+        when /\A\d{4}-\d{2}-\d{2}\z/
+          Date.strptime(value, "%Y-%m-%d")
+        when /\A\d{4}-\d{2}\z/
+          Date.strptime(value, "%Y-%m")
+        else
+          raise OptionParser::InvalidArgument, value
+        end
+      rescue ArgumentError
+        raise OptionParser::InvalidArgument, value
+      end
+
       ##
       # The previous entry.
       #

data/lib/standup_md/cli.rb

@@ -9,6 +9,10 @@ module StandupMD
   class Cli
     include Helpers
 
+    ZSH_COMPLETION_FILE = ::File.expand_path(
+      ::File.join(__dir__, "..", "..", "completion", "zsh", "_standup")
+    ).freeze
+
     ##
     # Access to the class's configuration.
     #
@@ -25,11 +29,46 @@ module StandupMD
       puts msg if config.verbose
     end
 
+    ##
+    # Prints zsh completion setup instructions.
+    #
+    # @return [String]
+    def self.zsh_completion_instructions
+      completion_dir = ::File.dirname(ZSH_COMPLETION_FILE)
+
+      <<~INSTRUCTIONS
+        Zsh completion file:
+          #{ZSH_COMPLETION_FILE}
+
+        To load it directly, add this before compinit runs:
+
+          fpath=("#{completion_dir}" $fpath)
+          autoload -Uz compinit
+          compinit
+
+        Or symlink it into your own completion directory:
+
+          mkdir -p ~/.zsh/completions
+          ln -sf "#{ZSH_COMPLETION_FILE}" ~/.zsh/completions/_standup
+
+        Then make sure that directory is in fpath before compinit runs:
+
+          fpath=(~/.zsh/completions $fpath)
+          autoload -Uz compinit
+          compinit
+      INSTRUCTIONS
+    end
+
     ##
     # Creates an instance of +StandupMD+ and runs what the user requested.
     def self.execute(options = [])
       new(options).tap do |exe|
-        exe.write_file if config.write
+        if exe.zsh_completion_requested?
+          puts zsh_completion_instructions
+          next
+        end
+
+        exe.write_file if exe.write?
         if config.print
           exe.print(exe.entry)
         elsif config.edit
@@ -56,6 +95,22 @@ module StandupMD
     # @return [StandupMD::File]
     attr_reader :file
 
+    ##
+    # Was a file date argument passed?
+    #
+    # @return [Boolean]
+    def file_date_argument?
+      @file_date_argument
+    end
+
+    ##
+    # Was zsh completion output requested?
+    #
+    # @return [Boolean]
+    def zsh_completion_requested?
+      @zsh_completion_requested
+    end
+
     ##
     # Constructor. Sets defaults.
     #
@@ -63,12 +118,18 @@ module StandupMD
     def initialize(options = [], load_config: true)
       @config = self.class.config
       @preference_file_loaded = false
+      @file_date_argument = false
+      @zsh_completion_requested = false
       @options = options
+      return if load_zsh_completion_request(options)
+
       load_preferences if load_config
       load_runtime_preferences(options)
-      @file = StandupMD::File.find_by_date(@config.date)
-      @file.load
-      @entry = new_entry(@file)
+      return if zsh_completion_requested?
+
+      @file = find_file
+      @file&.load
+      @entry = @file.nil? ? nil : new_entry(@file)
     end
 
     ##
@@ -110,6 +171,14 @@ module StandupMD
       file.write
     end
 
+    ##
+    # Should the file be written?
+    #
+    # @return [Boolean]
+    def write?
+      !!(@config.write && !read_only? && entry)
+    end
+
     ##
     # Quick access to +Cli.echo+.
     #
@@ -117,5 +186,54 @@ module StandupMD
     def echo(msg)
       self.class.echo(msg)
     end
+
+    private
+
+    ##
+    # Detects zsh completion setup requests before loading user preferences.
+    #
+    # @return [Boolean]
+    def load_zsh_completion_request(options)
+      return false unless options.include?("--zsh-completion")
+
+      invalid_options = options - ["--zsh-completion"]
+      raise OptionParser::InvalidArgument, invalid_options.join(" ") unless invalid_options.empty?
+
+      @zsh_completion_requested = true
+    end
+
+    ##
+    # Is this a read-only action?
+    #
+    # @return [Boolean]
+    def read_only?
+      @config.print || file_date_argument?
+    end
+
+    ##
+    # Finds the file, avoiding file creation for read-only actions.
+    #
+    # @return [StandupMD::File, nil]
+    def find_file
+      return StandupMD::File.find_by_date(@config.date) unless read_only?
+
+      without_file_creation { StandupMD::File.find_by_date(@config.date) }
+    rescue
+      raise unless @config.print
+
+      nil
+    end
+
+    ##
+    # Temporarily disables file creation while looking for a file.
+    #
+    # @return [StandupMD::File]
+    def without_file_creation
+      original_create = config.file.create
+      config.file.create = false
+      yield
+    ensure
+      config.file.create = original_create
+    end
   end
 end

data/lib/standup_md/version.rb

@@ -21,7 +21,7 @@ module StandupMD
     # Patch version.
     #
     # @return [Integer]
-    PATCH = 15
+    PATCH = 17
 
     ##
     # Version as +[MAJOR, MINOR, PATCH]+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standup_md
 version: !ruby/object:Gem::Version
-  version: 0.3.15
+  version: 0.3.17
 platform: ruby
 authors:
 - Evan Gray
@@ -107,6 +107,7 @@ files:
 - Rakefile
 - _config.yml
 - bin/standup
+- completion/zsh/_standup
 - lib/standup_md.rb
 - lib/standup_md/cli.rb
 - lib/standup_md/cli/helpers.rb