hookapp 0.0.7 → 2.0.7

data/bin/hook

@@ -1,25 +1,40 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require 'gli'
 require 'hook'
+require 'shellwords'
 
 # Main class for GLI app
 class App
   extend GLI::App
 
   program_desc 'CLI interface for Hook.app (macOS)'
+  program_long_desc 'Hook.app is a productivity tool for macOS <https://hookproductivity.com/>.
+    This gem includes a `hook` binary that allows interaction with the features of Hook.app.'
+  default_command 'help'
+  autocomplete_commands = true
+  synopsis_format(:terminal)
 
   version Hook::VERSION
 
   subcommand_option_handling :normal
   arguments :strict
 
-  hooker = nil
+  hookapp = nil
+  stdin = nil
 
   desc 'List hooks on a file or url'
+  long_desc %{
+Output a list of all hooks attached to given url(s) or file(s) in the specified format (default "paths").
+
+Run `hook list` with no file/url argument to list all bookmarks.}
+
   arg_name 'FILE_OR_URL [FILE_OR_URL...]'
   command %i[list ls] do |c|
+    c.desc 'Generate a menu to select hook(s) for opening'
+    c.long_desc 'This option is a shortcut to `hook select` and overrides any other arguments.'
+    c.switch %i[s select]
+
     c.desc 'Output only bookmarks with file paths (exclude e.g. emails)'
     c.switch %i[f files_only], { negatable: false, default_value: false }
 
@@ -32,10 +47,13 @@ class App
     c.flag %i[o output_format], { arg_name: 'format', default_value: 'paths' }
 
     c.action do |_global_options, options, args|
-      valid_format = hooker.validate_format(options[:o], valid_formats)
-      raise 'Invalid output format' unless valid_format
+      if options[:s]
+        return hookapp.open_linked(args[0])
+      end
+      valid_format = hookapp.validate_format(options[:o], valid_formats)
+      exit_now!("Invalid output format: \"#{options[:o]}\"", 6) unless valid_format
 
-      result = hooker.linked_bookmarks(args, { files_only: options[:f],
+      result = hookapp.linked_bookmarks(args, { files_only: options[:f],
                                                format: valid_format,
                                                null_separator: options[:null] })
 
@@ -43,7 +61,80 @@ class App
     end
   end
 
+  # Shell completion scripts are located in lib/completion/ and named "hook_completion" with
+  # the full shell name as the extension, e.g. "hook_completion.bash".
+  desc 'Shell completion examples'
+  valid_shells = %w[bash zsh fish]
+  long_desc %{
+Output completion script example for the specified shell (#{valid_shells.join(', ')})
+  }
+  arg_name 'SHELL'
+  command %i[scripts] do |c|
+    c.action do |_global_options, _options, args|
+      if args.length > 1
+        exit_now!("Invalid number of arguments, (expected 1)", 5)
+      elsif args.nil? || args.empty?
+        exit_now!("Specify a shell (#{valid_shells.join(', ')})", 0)
+      else
+        if valid_shells.include?(args[0])
+          base_dir = File.expand_path(File.join(File.dirname(__FILE__), '../lib/completion'))
+          completion = File.join(base_dir, "hook_completion.#{args[0]}")
+          script = IO.read(completion)
+          $stdout.puts script
+        else
+          exit_now!("Invalid shell name, must be one of #{valid_shells.join(', ')}", 1)
+        end
+      end
+    end
+  end
+
+
+
+  desc 'Search bookmarks'
+  long_desc %{
+Search bookmark urls and names for a string and output in specified format (default "paths").
+
+Run `hook find` with no search argument to list all bookmarks.}
+  arg_name 'SEARCH_STRING'
+  command %i[find search] do |c|
+    c.desc 'Output only bookmarks with file paths (exclude e.g. emails)'
+    c.switch %i[f files_only], { negatable: false, default_value: false }
+
+    c.desc 'Separate results with NULL separator, only applies with "paths" output for single file argument'
+    c.switch %i[null], { negatable: false, default_value: false }
+
+    valid_formats = %w[hooks paths markdown verbose]
+    fmt_list = valid_formats.map { |fmt| fmt.sub(/^(.)(.*?)$/, '(\1)\2') }.join(', ')
+
+    c.desc "Output format [#{fmt_list}]"
+    c.flag %i[o output_format], { arg_name: 'format', default_value: 'paths' }
+
+    c.desc "Search only bookmark names"
+    c.switch %i[n names_only], { negatable: false, default_value: false }
+
+    c.action do |_global_options, options, args|
+      valid_format = hookapp.validate_format(options[:o], valid_formats)
+      exit_now!("Invalid output format: \"#{options[:o]}\"", 6) unless valid_format
+
+      result = hookapp.search_bookmarks(args.join(" "), { files_only: options[:f],
+                                               format: valid_format,
+                                               null_separator: options[:null],
+                                               names_only: options[:n] })
+
+      puts result
+    end
+  end
+
   desc 'Create bidirectional hooks between two or more files/urls'
+  long_desc %{
+If two files/urls are provided, links will be bi-directional.
+If three or more are provided, `link` defaults to creating bi-directional
+links between each file and the last file in the list. Use `-a` to create
+bi-directional links between every file in the list.
+
+If using `--paste`, the URL/hook link in the clipboard will be used as one argument,
+to be combined with one or more file/url arguments.
+  }
   arg_name 'SOURCE [SOURCE...] TARGET'
   command %i[link ln] do |c|
     c.desc 'Link every listed file or url to every other'
@@ -59,17 +150,23 @@ class App
         args.push(clipboard) if clipboard
       end
       if args.length < 2
-        raise 'At least 2 files must be specified, or one file with --paste'
+        exit_now!('Wrong number of arguments. At least 2 files must be specified, or one file with --paste', 5)
       end
       if options[:a]
-        puts hooker.link_all(args)
+        puts hookapp.link_all(args)
       else
-        puts hooker.link_files(args)
+        puts hookapp.link_files(args)
       end
     end
   end
 
   desc 'Copy Hook URL for file/url to clipboard'
+  long_desc %{
+Creates a bookmark for the specified file or URL and copies its Hook URL to the clipboard.
+
+The copied Hook URL can be used to link to other files (use `hook link --paste FILE/URL),
+or to paste into another app as a link. Use the -m flag to copy a full Markdown link.
+  }
   arg_name 'FILE_OR_URL'
   command %i[clip cp] do |c|
     c.desc 'Copy as Markdown'
@@ -79,17 +176,23 @@ class App
     c.flag %i[a app], { arg_name: 'APP_NAME' }
 
     c.action do |_global_options, options, args|
-      raise 'Wrong number of arguments. Requires a path/url or -a APP_NAME' if args.length != 1 && !options[:a]
+      exit_now!('Wrong number of arguments. Requires a path/url or -a APP_NAME', 5) if args.length != 1 && !options[:a]
 
       if options[:a]
-        puts hooker.bookmark_from_app(options[:a], { copy: true, markdown: options[:m] })
+        puts hookapp.bookmark_from_app(options[:a], { copy: true, markdown: options[:m] })
       else
-        puts hooker.clip_bookmark(args[0], { markdown: options[:m] })
+        puts hookapp.clip_bookmark(args[0], { markdown: options[:m] })
       end
     end
   end
 
   desc 'Get a Hook URL for the frontmost window of an app'
+  long_desc %{
+Specify an application by name (without '.app') to bring that app to the foreground and create a bookmark
+for the active document, note, task, etc., returning a Hook URL.
+
+Use -m to get the response as Markdown, and/or -c to copy the result directly to the clipboard.
+  }
   arg_name 'APPLICATION_NAME'
   command %i[from] do |c|
     c.desc 'Output as Markdown'
@@ -99,62 +202,122 @@ class App
     c.switch %i[c copy], { negatable: false, default_value: false }
 
     c.action do |_global_options, options, args|
-      raise "Wrong number of arguments (1 expected, #{args.length} given)" if args.length != 1
+      exit_now!("Wrong number of arguments (1 expected, #{args.length} given)", 5) if args.length != 1
 
-      puts hooker.bookmark_from_app(args[0], { copy: options[:c], markdown: options[:m] })
+      puts hookapp.bookmark_from_app(args[0], { copy: options[:c], markdown: options[:m] })
     end
   end
 
   desc 'Remove a hook between two files/urls'
+  long_desc %{
+Remove a hook between two files or URLs. If you use --all, all hooks on a given file will be removed.
+
+If --all isn't specified, exactly two arguments (Files/URLs) are required.
+  }
   arg_name 'ITEM_1 ITEM_2'
   command %i[remove rm] do |c|
     c.desc 'Remove ALL links on files, requires confirmation'
-    c.switch %i[a all]
+    c.switch %i[a all], { negatable: false, default_value: false }
+    c.switch %i[f force], { negatable: false, default_value: false }
 
     c.action do |_global_options, options, args|
-      result = hooker.delete_hooks(args, { all: options[:r] })
+      result = hookapp.delete_hooks(args, { all: options[:all], force: options[:force] })
       puts result
     end
   end
 
   desc 'Clone all hooks from one file or url onto another'
+  long_desc %{
+Copy all the files and urls that the first file is hooked to onto another file. Exactly two arguments (SOURCE, TARGET) required.
+  }
   arg_name 'SOURCE TARGET'
   command %i[clone] do |c|
     c.action do |_global_options, _options, args|
-      raise "Wrong number of arguments. Two file paths or urls required (#{args.length} given)" if args.length != 2
+      exit_now!("Wrong number of arguments. Two file paths or urls required (#{args.length} given)", 5) if args.length != 2
 
-      result = hooker.clone_hooks(args)
+      result = hookapp.clone_hooks(args)
       puts result
     end
   end
 
   desc 'Select from hooks on a file/url and open in default application'
+  long_desc %{
+If the target file/URL has hooked items, a menu will be provided. Selecting one or more files
+from this menu will open the item(s) using the default application assigned to the
+filetype by macOS. Allows multiple selections with tab key, and type-ahead fuzzy filtering of results.
+}
   arg_name 'FILE_OR_URL'
   command %i[select] do |c|
     c.action do |_global_options, _options, args|
-      raise "Wrong number of arguments. One file path or url required (#{args.length} given)" if args.length != 1
+      exit_now!("Wrong number of arguments. One file path or url required (#{args.length} given)", 5) if args.length != 1
 
-      hooker.open_linked(args[0])
+      hookapp.open_linked(args[0])
     end
   end
 
   desc 'Open the specified file or url in Hook GUI'
+  long_desc %{
+Opens Hook.app on the specified file/URL for browsing and performing actions. Exactly one argument (File/URL) required.
+  }
   arg_name 'FILE_OR_URL'
   command %i[open gui] do |c|
     c.action do |_global_options, _options, args|
-      raise "Wrong number of arguments. One file path or url required (#{args.length} given)" if args.length != 1
+      exit_now!("Wrong number of arguments. One file path or url required (#{args.length} given)", 5) if args.length != 1
 
-      hooker.open_gui(args[0])
+      hookapp.open_gui(args[0])
     end
   end
 
+  desc 'Percent encode/decode a string'
+  long_desc %{Use encode or decode to apply Hook's url encoding to a string argument. Use '-' to read input from STDIN.}
+  arg_name 'STRING'
+  command :percent do |c|
+    c.desc 'percent encode a string'
+    c.arg_name 'STRING'
+    c.command :encode do |enc|
+      enc.action do |_global_options, _options, args|
+        if stdin
+          string = stdin
+        else
+          exit_now!('no string provided') unless args.size.positive?
+
+          string = args.join(' ').strip
+        end
+
+        print hookapp.encode(string)
+      end
+    end
+
+    c.desc 'decode a percent-encoded string'
+    c.arg_name 'STRING'
+    c.command :decode do |dec|
+      dec.action do |_global_options, _options, args|
+        if stdin
+          string = stdin
+        else
+          exit_now! ('no string provided') unless args.size.positive?
+
+          string = args.join(' ').strip
+        end
+
+        print hookapp.decode(string)
+      end
+    end
+
+    # c.default_command :encode
+  end
+
   pre do |global, _command, _options, _args|
     # Pre logic here
     # Return true to proceed; false to abort and not call the
     # chosen command
     # Use skips_pre before a command to skip this block
     # on that command only
-    hooker = Hooker.new(global)
+    if !STDIN.tty?
+      stdin = STDIN.read.strip
+    end
+
+    hookapp = HookApp.new
     true
   end
 

data/buildnotes.md

@@ -0,0 +1,59 @@
+# hookapp
+
+Hook.app CLI
+
+## Editing
+
+Main executable is located in `bin/hook`. All commands are defined here.
+
+Helpers and main classes are in `lib/`.
+
+@run(subl -p hookapp.sublime-project)
+
+## Building the Gem
+
+@run(rake clobber rdoc package)
+
+## Deploy
+
+1. Bump version
+2. Commit and push to GitHub
+3. See Updating the Docs
+4. Package the gem (See Building the Gem)
+5. Push the gem with `gem push pkg/hookapp-[VERSION].gem`
+
+## Updating the Docs
+
+Update the docs with `bundle exec bin/hook _doc --format=markdown` and `bundle exec bin/hook _doc --format=rdoc`, then run `rake rerdoc`
+
+@run(bundle exec bin/hook _doc --format=rdoc && bundle exec bin/hook _doc --format=markdown && rake rerdoc)
+
+## Test
+
+Run all tests using `rake test`.
+
+Run verbose using `rake test TESTOPT="-v"`
+
+Run a single test using `rake test TEST=test/TEST_FILE.rb`
+
+This howzit task accepts an optional argument pointing to a specific test (just the test part of the filename, e.g. archive runs `test/doing_archive_test.rb`).
+
+`howzit -r test -- archive` (or `bld test archive` with the Fish function)
+
+```run
+#!/bin/bash
+if [[ -n $1 ]]; then
+    rake test TESTOPT="-v" TEST=test/hook_$1_test.rb
+    if [[ $? != 0 ]]; then
+        echo "Available tests"
+        echo -e "\033[1;32;40m"
+        FILES="test/hook_*_test.rb"
+        for file in $FILES; do
+            echo $(basename $file ".rb") | sed -E 's/hook_(.*)_test/- \1/'
+        done
+        echo -e "\033[0m"
+    fi
+else
+    rake test TESTOPT="-v"
+fi
+```

data/hook.rdoc

@@ -1,6 +1,9 @@
 == hook - CLI interface for Hook.app (macOS)
 
-v0.0.5
+Hook.app is a productivity tool for macOS <https://hookproductivity.com/>.
+    This gem includes a `hook` binary that allows interaction with the features of Hook.app.
+
+v2.0.7
 
 === Global Options
 === --help
@@ -17,7 +20,10 @@ Display the program version
 ==== Command: <tt>clip|cp  FILE_OR_URL</tt>
 Copy Hook URL for file/url to clipboard
 
+Creates a bookmark for the specified file or URL and copies its Hook URL to the clipboard.
 
+The copied Hook URL can be used to link to other files (use `hook link --paste FILE/URL),
+or to paste into another app as a link. Use the -m flag to copy a full Markdown link.
 ===== Options
 ===== -a|--app APP_NAME
 
@@ -34,11 +40,43 @@ Copy as Markdown
 ==== Command: <tt>clone  SOURCE TARGET</tt>
 Clone all hooks from one file or url onto another
 
+Copy all the files and urls that the first file is hooked to onto another file. Exactly two arguments (SOURCE, TARGET) required.
+==== Command: <tt>find|search  SEARCH_STRING</tt>
+Search bookmarks
+
+Search bookmark urls and names for a string and output in specified format (default "paths").
+
+Run `hook find` with no search argument to list all bookmarks.
+===== Options
+===== -o|--output_format format
+
+Output format [(h)ooks, (p)aths, (m)arkdown, (v)erbose]
+
+[Default Value] paths
+
+
+===== -f|--files_only
+Output only bookmarks with file paths (exclude e.g. emails)
+
+
+
+===== -n|--names_only
+Search only bookmark names
+
+
+
+===== --null
+Separate results with NULL separator, only applies with "paths" output for single file argument
+
+
 
 ==== Command: <tt>from  APPLICATION_NAME</tt>
 Get a Hook URL for the frontmost window of an app
 
+Specify an application by name (without '.app') to bring that app to the foreground and create a bookmark
+for the active document, note, task, etc., returning a Hook URL.
 
+Use -m to get the response as Markdown, and/or -c to copy the result directly to the clipboard.
 ===== Options
 ===== -c|--copy
 Copy to clipboard
@@ -63,7 +101,13 @@ List commands one per line, to assist with shell completion
 ==== Command: <tt>link|ln  SOURCE [SOURCE...] TARGET</tt>
 Create bidirectional hooks between two or more files/urls
 
+If two files/urls are provided, links will be bi-directional.
+If three or more are provided, `link` defaults to creating bi-directional
+links between each file and the last file in the list. Use `-a` to create
+bi-directional links between every file in the list.
 
+If using `--paste`, the URL/hook link in the clipboard will be used as one argument,
+to be combined with one or more file/url arguments.
 ===== Options
 ===== -a|--all
 Link every listed file or url to every other
@@ -78,7 +122,9 @@ Paste URL from clipboard
 ==== Command: <tt>list|ls  FILE_OR_URL [FILE_OR_URL...]</tt>
 List hooks on a file or url
 
+Output a list of all hooks attached to given url(s) or file(s) in the specified format (default "paths").
 
+Run `hook list` with no file/url argument to list all bookmarks.
 ===== Options
 ===== -o|--output_format format
 
@@ -97,21 +143,53 @@ Separate results with NULL separator, only applies with "paths" output for singl
 
 
 
+===== -s|--[no-]select
+Generate a menu to select hook(s) for opening
+
+This option is a shortcut to `hook select` and overrides any other arguments.
+
 ==== Command: <tt>open|gui  FILE_OR_URL</tt>
 Open the specified file or url in Hook GUI
 
+Opens Hook.app on the specified file/URL for browsing and performing actions. Exactly one argument (File/URL) required.
+==== Command: <tt>percent  STRING</tt>
+Percent encode/decode a string
+
+Use encode or decode to apply Hook's url encoding to a string argument. Use '-' to read input from STDIN.
+===== Commands
+====== Command: <tt>decode  STRING</tt>
+decode a percent-encoded string
+
+
+====== Command: <tt>encode  STRING</tt>
+percent encode a string
+
 
 ==== Command: <tt>remove|rm  ITEM_1 ITEM_2</tt>
 Remove a hook between two files/urls
 
+Remove a hook between two files or URLs. If you use --all, all hooks on a given file will be removed.
 
+If --all isn't specified, exactly two arguments (Files/URLs) are required.
 ===== Options
-===== -a|--[no-]all
+===== -a|--all
 Remove ALL links on files, requires confirmation
 
 
 
+===== -f|--force
+
+
+
+
+==== Command: <tt>scripts  SHELL</tt>
+Shell completion examples
+
+Output completion script example for the specified shell (bash, zsh, fish)
 ==== Command: <tt>select  FILE_OR_URL</tt>
 Select from hooks on a file/url and open in default application
 
-
+If the target file/URL has hooked items, a menu will be provided. Selecting one or more files
+from this menu will open the item(s) using the default application assigned to the
+filetype by macOS. Allows multiple selections with tab key, and type-ahead fuzzy filtering of results.
+[Default Command] help

data/hookapp.gemspec

@@ -1,6 +1,8 @@
+# frozen_string_literal: true
+
 # Ensure we require the local version and not one we might have installed already
 require File.join([File.dirname(__FILE__), 'lib', 'hook', 'version.rb'])
-spec = Gem::Specification.new do |s|
+Gem::Specification.new do |s|
   s.name = 'hookapp'
   s.version = Hook::VERSION
   s.author = 'Brett Terpstra'
@@ -8,15 +10,14 @@ spec = Gem::Specification.new do |s|
   s.homepage = 'https://brettterpstra.com'
   s.platform = Gem::Platform::RUBY
   s.summary = 'A CLI for Hook.app (macOS)'
-  s.files = `git ls-files`.split("
-")
+  s.files = `git ls-files`.split("\n")
   s.require_paths << 'lib'
-  s.extra_rdoc_files = ['README.rdoc','hook.rdoc']
+  s.extra_rdoc_files = ['README.rdoc', 'hook.rdoc']
   s.rdoc_options << '--title' << 'hook' << '--main' << 'README.rdoc' << '-ri'
   s.bindir = 'bin'
   s.executables << 'hook'
-  s.add_development_dependency('rake','~> 13.0.1')
-  s.add_development_dependency('rdoc','~> 6.1.2')
-  s.add_development_dependency('aruba','~> 0.14.14')
-  s.add_runtime_dependency('gli','2.19.0')
+  s.add_development_dependency('aruba', '~> 0.14.14')
+  s.add_development_dependency('rake', '~> 13.0.1')
+  s.add_development_dependency('rdoc', '~> 6.3.2')
+  s.add_runtime_dependency('gli', '~> 2.20.1')
 end

data/lib/completion/hook_completion.bash

@@ -0,0 +1,22 @@
+# Source this script from ~/.bash_profile
+_hook_targets()
+{
+    local cmds cur ff
+    if (($COMP_CWORD == 1))
+    then
+        cur="${COMP_WORDS[1]}"
+        cmds="$(hook help -c)"
+        COMPREPLY=($(compgen -W "$cmds" -- "$cur"))
+        COMPREPLY=( "${COMPREPLY[@]/%/ }" )
+    else
+        # get all matching files and directories
+        COMPREPLY=($(compgen -f  -- "${COMP_WORDS[$COMP_CWORD]}"))
+
+        for ((ff=0; ff<${#COMPREPLY[@]}; ff++)); do
+            [[ -d ${COMPREPLY[$ff]} ]] && COMPREPLY[$ff]+='/'
+            [[ -f ${COMPREPLY[$ff]} ]] && COMPREPLY[$ff]+=' '
+        done
+    fi
+}
+
+complete -o bashdefault -o default -o nospace -F _hook_targets hook

data/lib/completion/hook_completion.fish

@@ -0,0 +1,31 @@
+# Save this script in ~/.config/fish/completions/hook.fish
+function __fish_hook_needs_command
+	# Figure out if the current invocation already has a command.
+
+	set -l opts h-help v-version
+	set cmd (commandline -opc)
+	set -e cmd[1]
+	argparse -s $opts -- $cmd 2>/dev/null
+	or return 0
+	# These flags function as commands, effectively.
+	if set -q argv[1]
+		# Also print the command, so this can be used to figure out what it is.
+		echo $argv[1]
+		return 1
+	end
+	return 0
+end
+
+function __fish_hook_using_command
+	set -l cmd (__fish_hook_needs_command)
+	test -z "$cmd"
+	and return 1
+	contains -- $cmd $argv
+	and return 0
+end
+
+function __fish_hook_subcommands
+	hook help -c
+end
+
+complete -xc hook -n '__fish_hook_needs_command' -a '(__fish_hook_subcommands)'

data/lib/completion/hook_completion.zsh

@@ -0,0 +1,22 @@
+# Source this script from ~/.zshrc
+_hook_targets()
+{
+    local cmds cur ff
+    if (($COMP_CWORD == 1))
+    then
+        cur="${COMP_WORDS[1]}"
+        cmds="$(hook help -c)"
+        COMPREPLY=($(compgen -W "$cmds" -- "$cur"))
+        COMPREPLY=( "${COMPREPLY[@]/%/ }" )
+    else
+        # get all matching files and directories
+        COMPREPLY=($(compgen -f  -- "${COMP_WORDS[$COMP_CWORD]}"))
+
+        for ((ff=0; ff<${#COMPREPLY[@]}; ff++)); do
+            [[ -d ${COMPREPLY[$ff]} ]] && COMPREPLY[$ff]+='/'
+            [[ -f ${COMPREPLY[$ff]} ]] && COMPREPLY[$ff]+=' '
+        done
+    fi
+}
+
+complete -o bashdefault -o default -o nospace -F _hook_targets hook