hookapp 0.0.6 → 2.0.5

data/bin/hook

@@ -1,7 +1,6 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require 'gli'
 require 'hook'
 
 # Main class for GLI app
@@ -9,17 +8,30 @@ 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
 
   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 +44,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 +58,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 +147,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 +173,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,52 +199,68 @@ 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.action do |_global_options, options, args|
-      result = hooker.delete_hooks(args, { all: options[:r] })
+      result = hookapp.delete_hooks(args, { all: options[:a] })
       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
 
@@ -154,7 +270,7 @@ class App
     # chosen command
     # Use skips_pre before a command to skip this block
     # on that command only
-    hooker = Hooker.new(global)
+    hookapp = HookApp.new
     true
   end
 

data/buildnotes.md

@@ -0,0 +1,29 @@
+# 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)

data/hook.rdoc

@@ -1,6 +1,8 @@
 == 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.3
 
 === Global Options
 === --help
@@ -17,7 +19,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 +39,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 +100,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 +121,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 +142,35 @@ 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>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
 
 
 
+==== 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')
-  s.add_development_dependency('rdoc')
-  s.add_development_dependency('aruba')
-  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/html/App.html

@@ -0,0 +1,107 @@
+<!DOCTYPE html>
+
+<html>
+<head>
+<meta charset="UTF-8">
+
+<title>class App - hookapp</title>
+
+<script type="text/javascript">
+  var rdoc_rel_prefix = "./";
+  var index_rel_prefix = "./";
+</script>
+
+<script src="./js/navigation.js" defer></script>
+<script src="./js/search.js" defer></script>
+<script src="./js/search_index.js" defer></script>
+<script src="./js/searcher.js" defer></script>
+<script src="./js/darkfish.js" defer></script>
+
+<link href="./css/fonts.css" rel="stylesheet">
+<link href="./css/rdoc.css" rel="stylesheet">
+
+
+<body id="top" role="document" class="class">
+<nav role="navigation">
+  <div id="project-navigation">
+    <div id="home-section" role="region" title="Quick navigation" class="nav-section">
+  <h2>
+    <a href="./index.html" rel="home">Home</a>
+  </h2>
+
+  <div id="table-of-contents-navigation">
+    <a href="./table_of_contents.html#pages">Pages</a>
+    <a href="./table_of_contents.html#classes">Classes</a>
+    <a href="./table_of_contents.html#methods">Methods</a>
+  </div>
+</div>
+
+    <div id="search-section" role="search" class="project-section initially-hidden">
+  <form action="#" method="get" accept-charset="utf-8">
+    <div id="search-field-wrapper">
+      <input id="search-field" role="combobox" aria-label="Search"
+             aria-autocomplete="list" aria-controls="search-results"
+             type="text" name="search" placeholder="Search" spellcheck="false"
+             title="Type to search, Up and Down to navigate, Enter to load">
+    </div>
+
+    <ul id="search-results" aria-label="Search Results"
+        aria-busy="false" aria-expanded="false"
+        aria-atomic="false" class="initially-hidden"></ul>
+  </form>
+</div>
+
+  </div>
+
+  
+
+  <div id="class-metadata">
+    
+    
+<div id="parent-class-section" class="nav-section">
+  <h3>Parent</h3>
+
+  <p class="link">Object
+</div>
+
+    
+    
+<div id="extends-section" class="nav-section">
+  <h3>Extended With Modules</h3>
+
+  <ul class="link-list">
+    <li><span class="extend">GLI::App</span>
+  </ul>
+</div>
+
+    
+  </div>
+</nav>
+
+<main role="main" aria-labelledby="class-App">
+  <h1 id="class-App" class="class">
+    class App
+  </h1>
+
+  <section class="description">
+    
+<p>Main class for <a href="GLI.html"><code>GLI</code></a> app</p>
+
+  </section>
+
+  <section id="5Buntitled-5D" class="documentation-section">
+
+
+
+
+
+  </section>
+</main>
+
+
+<footer id="validator-badges" role="contentinfo">
+  <p><a href="https://validator.w3.org/check/referer">Validate</a>
+  <p>Generated by <a href="https://ruby.github.io/rdoc/">RDoc</a> 6.3.2.
+  <p>Based on <a href="http://deveiate.org/projects/Darkfish-RDoc/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>.
+</footer>
+

data/html/GLI/Commands/Doc.html

@@ -0,0 +1,91 @@
+<!DOCTYPE html>
+
+<html>
+<head>
+<meta charset="UTF-8">
+
+<title>module GLI::Commands::Doc - hookapp</title>
+
+<script type="text/javascript">
+  var rdoc_rel_prefix = "../../";
+  var index_rel_prefix = "../../";
+</script>
+
+<script src="../../js/navigation.js" defer></script>
+<script src="../../js/search.js" defer></script>
+<script src="../../js/search_index.js" defer></script>
+<script src="../../js/searcher.js" defer></script>
+<script src="../../js/darkfish.js" defer></script>
+
+<link href="../../css/fonts.css" rel="stylesheet">
+<link href="../../css/rdoc.css" rel="stylesheet">
+
+
+<body id="top" role="document" class="module">
+<nav role="navigation">
+  <div id="project-navigation">
+    <div id="home-section" role="region" title="Quick navigation" class="nav-section">
+  <h2>
+    <a href="../../index.html" rel="home">Home</a>
+  </h2>
+
+  <div id="table-of-contents-navigation">
+    <a href="../../table_of_contents.html#pages">Pages</a>
+    <a href="../../table_of_contents.html#classes">Classes</a>
+    <a href="../../table_of_contents.html#methods">Methods</a>
+  </div>
+</div>
+
+    <div id="search-section" role="search" class="project-section initially-hidden">
+  <form action="#" method="get" accept-charset="utf-8">
+    <div id="search-field-wrapper">
+      <input id="search-field" role="combobox" aria-label="Search"
+             aria-autocomplete="list" aria-controls="search-results"
+             type="text" name="search" placeholder="Search" spellcheck="false"
+             title="Type to search, Up and Down to navigate, Enter to load">
+    </div>
+
+    <ul id="search-results" aria-label="Search Results"
+        aria-busy="false" aria-expanded="false"
+        aria-atomic="false" class="initially-hidden"></ul>
+  </form>
+</div>
+
+  </div>
+
+  
+
+  <div id="class-metadata">
+    
+    
+    
+    
+    
+  </div>
+</nav>
+
+<main role="main" aria-labelledby="module-GLI::Commands::Doc">
+  <h1 id="module-GLI::Commands::Doc" class="module">
+    module GLI::Commands::Doc
+  </h1>
+
+  <section class="description">
+    
+  </section>
+
+  <section id="5Buntitled-5D" class="documentation-section">
+
+
+
+
+
+  </section>
+</main>
+
+
+<footer id="validator-badges" role="contentinfo">
+  <p><a href="https://validator.w3.org/check/referer">Validate</a>
+  <p>Generated by <a href="https://ruby.github.io/rdoc/">RDoc</a> 6.3.2.
+  <p>Based on <a href="http://deveiate.org/projects/Darkfish-RDoc/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>.
+</footer>
+