howzit 2.0.8 → 2.0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a199c0d74513fee2be1dcd71390927d7776cecf50bd6b075504f9ed82fc548b0
-  data.tar.gz: d3668793cf618dc1d785cab3a7c87b93c3f5cc4edc546ab20b0c10de8986f7a1
+  metadata.gz: e11e4e9f19c26666de0d9dbfbfd0ab1b3c1bee495575fe0962ab5157a185e613
+  data.tar.gz: 7430c1da6d45f7dc873e01a8c1e6618da2dab503659921b9b72d690ad7aff181
 SHA512:
-  metadata.gz: cdc109a75df7f9757c3870092b3d3550dba228d4ddc9ff0d58befc5cb1174676808f4a29c8e0805b3e5150bf2c425b8f1d5ccebef226b6fffc96085562094f07
-  data.tar.gz: 394947ec4f9a437af899a4806e2daa60a1ffbd040785ff249dffe258030e88426a594a0b1afbea413839a72173daaf4cfbda4ef8643049296627c7928677fd68
+  metadata.gz: 739879dd1a53689e005511745003dd9b9d2ff5a8fa964cec3cb1754ef78e740c488d0a9040cee6b6de5e5eaf62a4a9c50dcc74a236db732e1c78ef4f9c8978cd
+  data.tar.gz: '009601634be888e709ee5709fc2bb990b5dff1a274144469621a9b23dc5108778fec2f8838fc46f03999df8c31d9872f3ad8b9de57afb6bb534035a8f8070c25'

data/CHANGELOG.md

@@ -1,3 +1,18 @@
+### 2.0.9
+
+2022-08-05 07:29
+
+#### IMPROVED
+
+- Avoid error trace on interrupt
+- Better stty settings for y/n prompt
+- Better coloring of default options in dialogs
+
+#### FIXED
+
+- Encoding issues with older ruby versions
+- Globbing for build notes was picking up files that contained "build" but not at the beginning of the filename
+
 ### 2.0.8
 
 2022-08-04 13:28

data/README.md

@@ -37,350 +37,9 @@ You can install `howzit` by running:
 
     gem install howzit
 
-## Anatomy of a Build Notes File
+### Usage
 
-Howzit relies on there being a file in the current directory with a name that starts with "build" or "howzit" and an extension of `.md`, `.txt`, or `.markdown`, e.g. `buildnotes.md` or `howzit.txt`. This note contains topics such as "Build" and "Deploy" with brief notes about each topic in Markdown (or just plain text) format.
-
-> Tip: Add "buildprivate.md" to your global gitignore (`git config --get core.excludesfile`). In a project where you don't want to share your build notes, just name the file "buildprivate.md" instead of "buildnotes.md" and it will automatically be ignored.
-
-If there are files that match the "build*" pattern that should not be recognized as build notes by howzit, add them to `~/.config/howzit/ignore.yaml`. This file is a simple list of patterns that should be ignored when scanning for build note files. Use `(?:i)` at the beginning of a pattern to make it case insensitive.
-
-The topics of the notes are delineated by Markdown headings, level 2 or higher, with the heading being the title of the topic. I split all of mine apart with h2s. For example, a short one from the little website I was working on yesterday:
-
-    ## Build
-
-    gulp js: compiles and minifies all js to dist/js/main.min.js
-
-    gulp css: compass compile to dist/css/
-
-    gulp watch
-
-    gulp (default): [css,js]
-
-    ## Deploy
-
-    gulp sync: rsync /dist/ to scoffb.local
-
-    ## Package management
-
-    yarn
-
-    ## Components
-
-    - UIKit
-
-Howzit expects there to only be one header level used to split topics. Anything before the first header is ignored. If your topics use h2 (`##`), you can use a single h1 (`#`) line at the top to title the project.
-
-### @Commands
-
-You can include commands that can be executed by howzit. Commands start at the beginning of a line anywhere in a topic. Only one topic's commands can be run at once, but all commands in the topic will be executed when howzit is run with `-r`. Commands can include any of:
-
-- `@run(COMMAND)`
-
-    The command in parenthesis will be executed as is from the current directory of the shell
-- `@copy(TEXT)`
-
-    On macOS this will copy the text within the parenthesis to the clipboard. An easy way to offer a shortcut to a longer build command while still allowing it to be edited prior to execution.
-- `@open(FILE|URL)`
-
-    Will open the file or URL using the default application for the filetype. On macOS this uses the `open` command, on Windows it uses `start`, and on Linux it uses `xdg-open`, which may require separate installation.
-- `@include(TOPIC)`
-
-    Includes all tasks from another topic, matching the name (partial match allowed) and returning first match.
-- `@before...@end`
-    
-    A block defined between @before and @end markers will be considered prerequisite for any task the topic can run. If one or more of these blocks exist in the topic, they will be displayed before running and a yes/no dialog will request confirmation that the prerequisites have been met. The content between these markers is still included when viewing the topic, but the tags themselves do not show up in output.
-- `@after...@end`
-
-    A block defined between @after and @end markers will be displayed after a topic is run. Use it to remind yourself of additional tasks after automated ones have been executed. The content between these markers is still included when viewing the topic, but the tags themselves do not show up in output.
-
-### Adding Titles
-
-When displaying a topic, howzit can display a title instead of the contents of a directive. Any text after the closing parenthesis will be considered the task title.
-
-```
-@run(~/scripts/deploy.sh) Deploy script
-```
-
-When the topic is displayed, it will now show "Run Deploy script" instead of the path to the script. This can be overridden with the `--show-code` flag, which will instead show the contents of the directive.
-
-For adding titles to run blocks (fenced code), see below.
-
-### Run blocks (embedded scripts)
-
-For longer scripts you can write shell scripts and then call them with `@run(myscript.sh)`. For those in-between cases where you need a few commands but aren't motivated to create a separate file, you can use fenced code blocks with `run` as the language.
-
-    ```run OPTIONAL TITLE
-    #!/bin/bash
-    # Commands...
-    ```
-
-The contents of the block will be written to a temporary file and executed with `/bin/sh -c`. This means that you need a hashbang at the beginning to tell the shell how to interpret the script. If no hashbang is given, the script will be executed as a `sh` script.
-
-Example:
-
-    ```run Just Testing
-    #!/bin/bash
-    echo "Just needed a few lines"
-    echo "To get through all these commands"
-    echo "Almost there!"
-    say "Phew, we did it."
-    ```
-
-Multiple blocks can be included in a topic. @commands take priority over code blocks and will be run first if they exist in the same topic.
-
-### Requiring Confirmation
-
-You can have howzit confirm whether to execute an @command at runtime by including a question mark to the directive, e.g. `@run?(...)`. This will present a yes/no dialog before running the directive, with a default response of "yes" if you just hit return. To make the default response "no," add an exclamation point, e.g. `@run?!(...)`. 
-
-This works for any directive, including `@include`, and run blocks, which can use `run?` as the language specifier.
-
-### Variables
-
-When running commands in a topic, you can use a double dash (`--`) in the command line (surrounded by spaces) and anything after it will be interpreted as shell arguments. These can be used in commands with `$` placeholders. `$1` represents the first argument, counting up from there. Use `$@` to pass all arguments as a shell-escaped string.
-
-For example, the topic titled "Test" could contain an @run command with placeholders:
-
-    ## Test
-    @run(./myscript.sh $@)
-
-Then you would run it on the command line using:
-
-    howzit -r test -- -x "arg 1" arg2
-
-This would execute the command as `./myscript.sh -x arg\ 1 arg2`.
-
-Placeholders can be used in both commands and run blocks. If a placeholder doesn't have an argument supplied, it's not replaced (e.g. leaves `$2` in the command).
-
-### Templates and metadata
-
-You can create templates to reuse topics in multiple build note files. Create files using the same formatting as a build note in `~/.config/howzit/templates` with `.md` extensions. Name them the way you'll reference them:
-
-    ~/.config/howzit/templates
-    - markdown.md
-    - ruby.md
-    - obj-c.md
-
-> Use `howzit --templates` for a list of templates you've created, along with the topics they'll add when included. Just in case you make a bunch and can't remember what they're called or what they do. I was just planning ahead.
-
-You can then include the topics from a template in any build note file using a `template:` key at the top of the file.
-
-Howzit allows MultiMarkdown-style metadata at the top of a build notes file. These are key/value pairs separated by a colon:
-
-    template: markdown
-    key 1: value 1
-    key 2: value 2
-
-The template key can include multiple template names separated by commas.
-
-Additional metadata keys populate variables you can then use inside of your templates (and build notes), using `[%key]`. You can define a default value for a placeholder with `[%key:default]`.
-
-For example, in the template `markdown.md` you could have:
-
-    ### Spellcheck
-
-    Check spelling of all Markdown files in git repo.
-
-    ```run
-    #!/bin/bash
-    for dir in [%dirs:.]; do
-        cd "$dir"
-        /Users/ttscoff/scripts/spellcheck.bash
-        cd -
-    done
-    ```
-
-Then, in a `buildnotes.md` file in your project, you could include at the top of the file:
-
-    template: markdown
-    dirs: . docs
-
-    # My Project...
-
-If you only want to include certain topics from a template file, use the format `template_name[topic]` or include multiple topics separated by commas: `template_name[topic 1, topic 2]`. You can also use `*` as a wildcard, where `template_name[build*]` would include topics "Build" and "Build and Run".
-
-If a topic in the current project's build note has an identical name to a template topic, the local topic takes precedence. This allows you to include a template but modify just a part of it by duplicating the topic title.
-
-Templates can include other templates with a `template:` key at the top of the template.
-
-You can define what metadata keys are required for the template using a `required:` key at the top of the template. For example, if the template `script.md` uses a placeholder `[%executable]` that can't have a default value as it's specific to each project, you can add:
-
-    required: executable 
-
-at the top of `project.md`. If the template is included in a build notes file and the `executable:` key is not defined, an error will be shown.
-
-## Using howzit
-
-Run `howzit` on its own to view the current folder's buildnotes.
-
-Include a topic name to see just that topic, or no argument to display all.
-
-    howzit build
-
-You can combine multiple topic searches by separating with a comma. When multiple results are returned, the `:multiple_results:` configuration determines how they're handled.
-
-    howzit build,deploy
-
-Use `-l` to list all topics.
-
-    howzit -l
-
-Use `-r` to execute any @copy, @run, or @open commands in the given topic. Options can come after the topic argument, so to run the commands from the last topic you viewed, just hit the up arrow to load the previous command and add `-r`.
-
-    howzit build -r
-
-Other options:
-
-    Usage: howzit [OPTIONS] [TOPIC]
-
-    Show build notes for the current project (buildnotes.md). Include a topic name to see just that topic, or no argument to display all.
-
-    Options:
-        -c, --create                     Create a skeleton build note in the current working directory
-        -e, --edit                       Edit buildnotes file in current working directory
-                    using $EDITOR
-            --grep PATTERN               Display sections matching a search pattern
-        -L, --list-completions           List topics for completion
-        -l, --list                       List available topics
-        -m, --matching TYPE              Topics matching type
-                                         (partial, exact, fuzzy, beginswith)
-            --multiple TYPE              Multiple result handling
-                                         (first, all, choose)
-        -R, --list-runnable              List topics containing @ directives (verbose)
-        -r, --run                        Execute @run, @open, and/or @copy commands for given topic
-        -s, --select                     Select topic from menu
-        -T, --task-list                  List topics containing @ directives (completion-compatible)
-        -t, --title                      Output title with build notes
-        -q, --quiet                      Silence info message
-            --verbose                    Show all messages
-        -u, --[no-]upstream              Traverse up parent directories for additional build notes
-            --show-code                  Display the content of fenced run blocks
-        -w, --wrap COLUMNS               Wrap to specified width (default 80, 0 to disable)
-            --edit-config                Edit configuration file using default $EDITOR
-            --title-only                 Output title only
-            --templates                  List available templates
-            --[no-]color                 Colorize output (default on)
-            --[no-]md-highlight          Highlight Markdown syntax (default on), requires mdless or mdcat
-            --[no-]pager                 Paginate output (default on)
-        -h, --help                       Display this screen
-        -v, --version                    Display version number
-            --default                    Answer all prompts with default response
-
-
-## Configuration
-
-Some of the command line options can be set as defaults. The first time you run `howzit`, a YAML file is written to `~/.config/howzit/howzit.yaml`. You can open it in your default editor automatically by running `howzit --edit-config`. It contains the available options:
-
-    ---
-    :color: true
-    :config_editor: subl
-    :editor: subl
-    :header_format: block
-    :highlight: true
-    :highlighter: mdcat
-    :include_upstream: true
-    :log_level: 0
-    :matching: fuzzy
-    :multiple_matches: choose
-    :output_title: false
-    :pager: auto
-    :paginate: true
-    :show_all_code: false
-    :show_all_on_error: false
-    :wrap: 0
-
-If `:color:` is false, output will not be colored, and markdown highlighting will be bypassed.
-
-If `:color:` is true and `:highlight:` is true, the `:highlighter:` option will be used to add Markdown highlighting.
-
-If `:paginate:` is true, the `:pager:` option will be used to determine the tool used for pagination. If it's false and you're using iTerm, "marks" will be added to topic titles allowing keyboard navigation.
-
-`:highlighter:` and `:pager:` can be set to `auto` (default) or a command of your choice for markdown highlighting and pagination.
-
-`:matching:` can be "partial", "beginswith", "fuzzy" or "exact" (see below).
-
-If `:include_upstream:` is true, build note files in parent directories will be included in addition to the current directory. Priority goes from current directory to root in descending order, so the current directory is top priority, and a build notes file in / is the lowest. Higher priority topics  will not be overwritten by a duplicate topic from a lower priority note.
-
-Set `:log_level:` to 0 for debug messages, or 3 to suppress superfluous info messages.
-
-`:multiple_matches:` determines how howzit will handle cases where a search results in multiple matches. It can be set to "first" (first match in notes), "best" (shortest topic match), "all" (display all results), or "choose" (displays a menu of results). Default is "choose." When grepping for results, only "all" or "choose" are valid, if the default is something else, "choose" will be used. Can be overridden with the `--multiple TYPE` flag.
-
-`:header_format:` changes the way topic titles are displayed. Setting it to "border" will add a horizontal rule and brackets around the title. Setting it to "block" will mark topic titles with a unicode block instead.
-
-### Matching
-
-All matching is case insensitive. This setting can be overridden by the `--matching TYPE` flag on the command line.
-
-- `:matching: partial`
-
-    Partial is the default, search matches any part of the topic title.
-
-    _Example:_ `howzit other` matches 'An<mark>other</mark> Topic'.
-
-- `:matching: beginswith`
-
-    Matches from the start of the title.
-
-    _Example:_ `howzit another` matches '<mark>Another</mark> Topic', but neither 'other' or 'topic' will.
-
-- `:matching: fuzzy`
-
-    Matches anything containing the search characters in order, no matter what comes between them.
-
-    _Example:_ `howzit asct` matches '<mark>A</mark>nother <mark>S</mark>e<mark>c</mark><mark>t</mark>ion'
-
-- `:matching: exact`
-
-    Case insensitive but must match the entire title.
-
-    _Example:_ Only `howzit another topic` will match 'Another Topic'
-
-### Pager
-
-If set to `auto`, howzit will look for pagers in this order, using the first one it finds available:
-
-- $GIT_PAGER
-- $PAGER
-- bat
-- less
-- more
-- cat
-- pager
-
-If you're defining your own, make sure to include any flags necessary to handle the output. If you're using howzit's coloring, for example, you need to specify any options needed to display ANSI escape sequences (e.g. `less -r`).
-
-### Highlighter
-
-If set to `auto` howzit will look for markdown highlighters in this order, using the first it finds available:
-
-- mdcat
-- mdless
-
-If you're combining a highlighter with howzit's pagination, include any flags needed to disable the highlighter's pagination (e.g. `mdless --no-pager`).
-
-### Configuring from the Command Line
-
-You can get and set config options from the command line using `--config-get` and `--config-set`. If you run `--config-get` with no argument, it will display all config options. If you add a key (exact match required) you can get just the value for that key.
-
-Using `--config-set` requires an argument in the format `key=value`. The type of the value (boolean, integer, string, symbol) will be automatically determined and converted. To change your highlighter, for example, use `howzit --config-set highlighter=mdcat`.
-
-## Shell Integration
-
-I personally like to alias `bld` to `howzit -r`. If you define a function in your shell, you can have it default to "build" but accept an alternate argument. There's an example for Fish included, and in Bash it would be as simple as `howzit -r ${1:build}`.
-
-For completion you can use `howzit -L` to list all topics, and `howzit -T` to list all "runnable" topics (topics containing an @directive or run block). Completion examples for Fish are included in the `fish` directory.
-
-## Similar Projects
-
-- [mask](https://github.com/jakedeichert/mask/)
-- [maid](https://github.com/egoist/maid)
-- [saku](https://github.com/kt3k/saku)
-
-There are a few projects that tackle the same concept (a Markdown makefile). Most of them are superior task runners, so if you're looking for a `make` replacement, I recommend exploring the links above. What I like about `howzit` (and what keeps me from switching) is that it's documentation-first, and that I can display the description for each topic on the command line. The others also don't have options for listing topics or runnable tasks, so I can't use completion (or my cool script that adds available tasks to my Macbook Pro Touch Bar...). But no, I don't think `howzit` is as good an overall task runner as `mask` or `maid`.
-
-## Roadmap
-
-- Recognize header hierarchy, allow showing/running all sub-topics
+[See the wiki](https://github.com/ttscoff/howzit/wiki) for documentation.
 
 ## Author
 
@@ -401,9 +60,11 @@ purpose.
 
 ## Documentation
 
+- [Howzit Wiki][Wiki].
 - [YARD documentation][RubyDoc] is hosted by RubyDoc.info.
 - [Interactive documentation][Omniref] is hosted by Omniref.
 
+[Wiki]: https://github.com/ttscoff/howzit/wiki
 [RubyDoc]: http://www.rubydoc.info/gems/howzit
 [Omniref]: https://www.omniref.com/ruby/gems/howzit
 

data/bin/howzit

@@ -18,28 +18,10 @@ OptionParser.new do |opts|
   opts.separator ''
   opts.separator 'Options:'
 
-  opts.on('-c', '--create', 'Create a skeleton build note in the current working directory') do
-    Howzit.buildnote.create_note
-    Process.exit 0
-  end
+  opts.separator "  Behavior:\n\n" #=================================================================== BEHAVIOR
 
-  opts.on('-e', '--edit', "Edit buildnotes file in current working directory
-          using $EDITOR") do
-    Howzit.buildnote.edit
-    Process.exit 0
-  end
-
-  opts.on('--grep PATTERN', 'Display sections matching a search pattern') do |pat|
-    Howzit.options[:grep] = pat
-  end
-
-  opts.on('-L', '--list-completions', 'List topics for completion') do
-    Howzit.options[:list_topics] = true
-    Howzit.options[:list_topic_titles] = true
-  end
-
-  opts.on('-l', '--list', 'List available topics') do
-    Howzit.options[:list_topics] = true
+  opts.on('--default', 'Answer all prompts with default response') do
+    Howzit.options[:default] = true
   end
 
   opts.on('-m', '--matching TYPE', MATCHING_OPTIONS,
@@ -52,52 +34,63 @@ OptionParser.new do |opts|
     Howzit.options[:multiple_matches] = c.to_sym
   end
 
-  opts.on('-R', '--list-runnable', 'List topics containing @ directives (verbose)') do
-    Howzit.options[:list_runnable] = true
+  opts.on('-u', '--[no-]upstream', 'Traverse up parent directories for additional build notes') do |p|
+    Howzit.options[:include_upstream] = p
   end
 
-  opts.on('-r', '--run', 'Execute @run, @open, and/or @copy commands for given topic') do
-    Howzit.options[:run] = true
-  end
+  opts.separator "\n  Listing:\n\n" #=================================================================== LISTING
 
-  opts.on('-s', '--select', 'Select topic from menu') do
-    Howzit.options[:choose] = true
+  opts.on('-L', '--list-completions', 'List topics for completion') do
+    Howzit.options[:list_topics] = true
+    Howzit.options[:list_topic_titles] = true
   end
 
-  opts.on('-T', '--task-list', 'List topics containing @ directives (completion-compatible)') do
-    Howzit.options[:list_runnable] = true
-    Howzit.options[:list_runnable_titles] = true
+  opts.on('-l', '--list', 'List available topics') do
+    Howzit.options[:list_topics] = true
   end
 
-  opts.on('-t', '--title', 'Output title with build notes') do
-    Howzit.options[:output_title] = true
+  opts.on('-R', '--list-runnable', 'List topics containing @ directives (verbose)') do
+    Howzit.options[:list_runnable] = true
   end
 
-  opts.on('-q', '--quiet', 'Silence info message') do
-    Howzit.options[:log_level] = 4
-    Howzit.console.reset_level
+  opts.on('-T', '--task-list', 'List topics containing @ directives (completion-compatible)') do
+    Howzit.options[:list_runnable] = true
+    Howzit.options[:list_runnable_titles] = true
   end
 
-  opts.on('-v', '--verbose', 'Show all messages') do
-    Howzit.options[:log_level] = 1
-    Howzit.console.reset_level
+  opts.on('--templates', 'List available templates') do
+    Dir.chdir(Howzit.config.template_folder)
+    Dir.glob('*.md').each do |file|
+      template = File.basename(file, '.md')
+      puts Howzit::Color.template("{Mk}template:{Yk}#{template}{x}")
+      puts Howzit::Color.template('{bk}[{bl}tasks{bk}]──────────────────────────────────────┐{x}')
+      metadata = file.extract_metadata
+      topics = Howzit.buildnote.read_file(file)
+      topics.each do |topic|
+        puts Howzit::Color.template(" {bk}│{bw}-{x} {bcK}#{template}:#{topic.title.sub(/^.*?:/, '')}{x}")
+      end
+      unless metadata.empty?
+        meta = []
+        meta << metadata['required'].split(/\s*,\s*/).map { |m| "*{bw}#{m}{xw}" } if metadata.key?('required')
+        meta << metadata['optional'].split(/\s*,\s*/).map(&:to_s) if metadata.key?('optional')
+        puts Howzit::Color.template('{bk}[{bl}meta{bk}]───────────────────────────────────────┤{x}')
+        puts Howzit::Color.template(" {bk}│ {xw}#{meta.join(', ')}{x}")
+      end
+      puts Howzit::Color.template(' {bk}└───────────────────────────────────────────┘{x}')
+    end
+    Process.exit 0
   end
 
-  opts.on('-d', '--debug', 'Show debug messages (and all messages)') do
-    Howzit.options[:log_level] = 0
-    Howzit.console.reset_level
+  opts.on('--title-only', 'Output title only') do
+    Howzit.options[:output_title] = true
+    Howzit.options[:title_only] = true
   end
 
-  opts.on('-u', '--[no-]upstream', 'Traverse up parent directories for additional build notes') do |p|
-    Howzit.options[:include_upstream] = p
-  end
+  opts.separator("\n  Commands:\n\n") #=================================================================== COMMANDS
 
-  opts.on('--show-code', 'Display the content of fenced run blocks') do
-    Howzit.options[:show_all_code] = true
-  end
-
-  opts.on('-w', '--wrap COLUMNS', 'Wrap to specified width (default 80, 0 to disable)') do |w|
-    Howzit.options[:wrap] = w.to_i
+  opts.on('-c', '--create', 'Create a skeleton build note in the current working directory') do
+    Howzit.buildnote.create_note
+    Process.exit 0
   end
 
   opts.on('--config-get [KEY]', 'Display the configuration settings or setting for a specific key') do |k|
@@ -133,49 +126,41 @@ OptionParser.new do |opts|
     Process.exit 0
   end
 
-  opts.on('--edit-config', 'Edit configuration file using default $EDITOR') do
+  opts.on('--edit-config', "Edit configuration file using editor (#{Howzit.options[:editor]})") do
     Howzit.config.editor
     Process.exit 0
   end
 
-  opts.on('--title-only', 'Output title only') do
-    Howzit.options[:output_title] = true
-    Howzit.options[:title_only] = true
+  desc = %(Edit buildnotes file in current working directory using editor (#{Howzit.options[:config_editor]}))
+  opts.on('-e', '--edit', desc) do
+    Howzit.buildnote.edit
+    Process.exit 0
   end
 
-  opts.on('--templates', 'List available templates') do
-    Dir.chdir(Howzit.config.template_folder)
-    Dir.glob('*.md').each do |file|
-      template = File.basename(file, '.md')
-      puts Howzit::Color.template("{Mk}template:{Yk}#{template}{x}")
-      puts Howzit::Color.template('{bk}[{bl}tasks{bk}]──────────────────────────────────────┐{x}')
-      metadata = file.extract_metadata
-      topics = Howzit.buildnote.read_file(file)
-      topics.each do |topic|
-        puts Howzit::Color.template(" {bk}│{bw}-{x} {bcK}#{template}:#{topic.title.sub(/^.*?:/, '')}{x}")
-      end
-      unless metadata.empty?
-        meta = []
-        meta << metadata['required'].split(/\s*,\s*/).map { |m| "*{bw}#{m}{xw}" } if metadata.key?('required')
-        meta << metadata['optional'].split(/\s*,\s*/).map(&:to_s) if metadata.key?('optional')
-        puts Howzit::Color.template('{bk}[{bl}meta{bk}]───────────────────────────────────────┤{x}')
-        puts Howzit::Color.template(" {bk}│ {xw}#{meta.join(', ')}{x}")
-      end
-      puts Howzit::Color.template(' {bk}└───────────────────────────────────────────┘{x}')
-    end
-    Process.exit 0
+  opts.on('--grep PATTERN', 'Display sections matching a search pattern') do |pat|
+    Howzit.options[:grep] = pat
   end
 
-  opts.on('--header-format TYPE', HEADER_FORMAT_OPTIONS,
-          "Formatting style for topic titles (#{HEADER_FORMAT_OPTIONS.join(', ')})") do |t|
-    Howzit.options[:header_format] = t
+  opts.on('-r', '--run', 'Execute @run, @open, and/or @copy commands for given topic') do
+    Howzit.options[:run] = true
+  end
+
+  opts.on('-s', '--select', 'Select topic from menu') do
+    Howzit.options[:choose] = true
   end
 
+  opts.separator("\n  Formatting:\n\n") #=================================================================== FORMATTING
+
   opts.on('--[no-]color', 'Colorize output (default on)') do |c|
     Howzit.options[:color] = c
     Howzit.options[:highlight] = false unless c
   end
 
+  opts.on('--header-format TYPE', HEADER_FORMAT_OPTIONS,
+          "Formatting style for topic titles (#{HEADER_FORMAT_OPTIONS.join(', ')})") do |t|
+    Howzit.options[:header_format] = t
+  end
+
   opts.on('--[no-]md-highlight', 'Highlight Markdown syntax (default on), requires mdless or mdcat') do |m|
     Howzit.options[:highlight] = Howzit.options[:color] ? m : false
   end
@@ -184,6 +169,37 @@ OptionParser.new do |opts|
     Howzit.options[:paginate] = p
   end
 
+  opts.on('--show-code', 'Display the content of fenced run blocks') do
+    Howzit.options[:show_all_code] = true
+  end
+
+  opts.on('-t', '--title', 'Output title with build notes') do
+    Howzit.options[:output_title] = true
+  end
+
+  opts.on('-w', '--wrap COLUMNS', 'Wrap to specified width (default 80, 0 to disable)') do |w|
+    Howzit.options[:wrap] = w.to_i
+  end
+
+  opts.separator("\n  Logging:\n\n") #=================================================================== LOGGING
+
+  opts.on('-d', '--debug', 'Show debug messages (and all messages)') do
+    Howzit.options[:log_level] = 0
+    Howzit.console.reset_level
+  end
+
+  opts.on('-q', '--quiet', 'Silence info message') do
+    Howzit.options[:log_level] = 4
+    Howzit.console.reset_level
+  end
+
+  opts.on('--verbose', 'Show all messages') do
+    Howzit.options[:log_level] = 1
+    Howzit.console.reset_level
+  end
+
+  opts.separator("\n  Misc:\n\n") #=================================================================== MISC
+
   opts.on('-h', '--help', 'Display this screen') do
     puts opts
     Process.exit 0
@@ -193,12 +209,14 @@ OptionParser.new do |opts|
     puts "how v#{Howzit::VERSION}"
     Process.exit 0
   end
-
-  opts.on('--default', 'Answer all prompts with default response') do
-    Howzit.options[:default] = true
-  end
 end.parse!(args)
 
+trap('INT') do
+  puts
+  puts 'Cancelled'
+  Process.exit 0
+end
+
 Howzit.options[:multiple_matches] = Howzit.options[:multiple_matches].to_sym
 Howzit.options[:header_format] = Howzit.options[:header_format].to_sym
 

data/howzit.gemspec

@@ -30,6 +30,7 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency 'rubocop', '~> 0.28'
   spec.add_development_dependency 'rspec', '~> 3.1'
+  spec.add_development_dependency 'cli-test', '~> 1.0'
   spec.add_development_dependency 'simplecov', '~> 0.9'
   # spec.add_development_dependency 'codecov', '~> 0.1'
   spec.add_development_dependency 'fuubar', '~> 2.0'
@@ -40,5 +41,6 @@ Gem::Specification.new do |spec|
 
   spec.add_runtime_dependency 'mdless', '~> 1.0', '>= 1.0.28'
   spec.add_runtime_dependency 'tty-screen', '~> 0.8'
+  spec.add_runtime_dependency 'tty-box', '~> 0.7'
   # spec.add_runtime_dependency 'tty-prompt', '~> 0.23'
 end

data/lib/howzit/buildnote.rb

@@ -10,7 +10,7 @@ module Howzit
     def initialize(file: nil, args: [])
       @topics = []
       create_note if note_file.nil?
-      @metadata = IO.read(note_file).split(/^#/)[0].strip.get_metadata
+      @metadata = Util.read_file(note_file).split(/^#/)[0].strip.get_metadata
 
       read_help(file)
     end
@@ -89,7 +89,7 @@ module Howzit
     # Create a buildnotes skeleton
     def create_note
       trap('SIGINT') do
-        Howzit.console.info "\nCanceled"
+        Howzit.console.info "\nCancelled"
         exit!
       end
       default = !$stdout.isatty || Howzit.options[:default]
@@ -210,9 +210,11 @@ module Howzit
       buildnotes.reverse
     end
 
-    def is_build_notes(filename)
-      return false if filename.downcase !~ /(^howzit[^.]*|build[^.]+)/
+    def build_note?(filename)
+      return false if filename.downcase !~ /^(howzit[^.]*|build[^.]+)/
+
       return false if Howzit.config.should_ignore(filename)
+
       true
     end
 
@@ -222,7 +224,7 @@ module Howzit
       # with "build" and have an extension of txt, md, or markdown.
 
       Dir.glob('*.{txt,md,markdown}').each do |f|
-        if is_build_notes(f)
+        if build_note?(f)
           filename = f
           break
         end
@@ -262,7 +264,7 @@ module Howzit
     end
 
     def ensure_requirements(template)
-      t_leader = IO.read(template).split(/^#/)[0].strip
+      t_leader = Util.read_file(template).split(/^#/)[0].strip
       if t_leader.length > 0
         t_meta = t_leader.get_metadata
         if t_meta.key?('required')
@@ -330,7 +332,7 @@ module Howzit
 
       return m[0] unless File.exist?(file)
 
-      content = IO.read(file)
+      content = Util.read_file(file)
       home = ENV['HOME']
       short_path = File.dirname(file.sub(/^#{home}/, '~'))
       prefix = "#{short_path}/#{File.basename(file)}:"
@@ -344,7 +346,7 @@ module Howzit
     end
 
     def note_title(truncate = 0)
-      help = IO.read(note_file).strip
+      help = Util.read_file(note_file)
       title = help.match(/(?:^(\S.*?)(?=\n==)|^# ?(.*?)$)/)
       title = if title
                 title[1].nil? ? title[2] : title[1]
@@ -361,7 +363,7 @@ module Howzit
 
       filename = path.nil? ? note_file : path
 
-      help = IO.read(filename)
+      help = Util.read_file(filename)
 
       @title = note_title
 

data/lib/howzit/config.rb

@@ -3,6 +3,7 @@ module Howzit
   class Config
     attr_reader :options
 
+    # Configuration defaults
     DEFAULTS = {
       color: true,
       config_editor: ENV['EDITOR'] || nil,
@@ -46,7 +47,7 @@ module Howzit
     def should_ignore(filename)
       return false unless File.exist?(ignore_file)
 
-      @ignore_patterns ||= YAML.safe_load(IO.read(ignore_file))
+      @ignore_patterns ||= YAML.safe_load(Util.read_file(ignore_file))
 
       ignore = false
 
@@ -78,6 +79,11 @@ module Howzit
 
     private
 
+    ##
+    ## Load command line options
+    ##
+    ## @return     [Hash] options with command line flags merged in
+    ##
     def load_options
       Color.coloring = $stdout.isatty
       flags = {
@@ -98,19 +104,39 @@ module Howzit
       @options = flags.merge(config)
     end
 
+    ##
+    ## Get the config directory
+    ##
+    ## @return     [String] path to config directory
+    ##
     def config_dir
       File.expand_path(CONFIG_DIR)
     end
 
+    ##
+    ## Get the config file
+    ##
+    ## @return     [String] path to config file
+    ##
     def config_file
       File.join(config_dir, CONFIG_FILE)
     end
 
+    ##
+    ## Get the ignore config file
+    ##
+    ## @return     [String] path to ignore config file
+    ##
     def ignore_file
       File.join(config_dir, IGNORE_FILE)
     end
 
-    def create_config(d)
+    ##
+    ## Create a new config file (and directory if needed)
+    ##
+    ## @param      default     [Hash] default configuration to write
+    ##
+    def create_config(default)
       unless File.directory?(config_dir)
         Howzit::ConsoleLogger.new(1).info "Creating config directory at #{config_dir}"
         FileUtils.mkdir_p(config_dir)
@@ -118,20 +144,28 @@ module Howzit
 
       unless File.exist?(config_file)
         Howzit::ConsoleLogger.new(1).info "Writing fresh config file to #{config_file}"
-        write_config(d)
+        write_config(default)
       end
       config_file
     end
 
+    ##
+    ## Load the config file
+    ##
+    ## @return     [Hash] configuration object
+    ##
     def load_config
       file = create_config(DEFAULTS)
-      config = YAML.load(IO.read(file))
+      config = YAML.load(Util.read_file(file))
       newconfig = config ? DEFAULTS.merge(config) : DEFAULTS
       write_config(newconfig)
       newconfig.dup
     end
 
-    def edit_config(d)
+    ##
+    ## Open the config in an editor
+    ##
+    def edit_config
       editor = Howzit.options.fetch(:config_editor, ENV['EDITOR'])
 
       raise 'No config_editor defined' if editor.nil?

data/lib/howzit/console_logger.rb

@@ -12,30 +12,67 @@ module Howzit
   class ConsoleLogger
     attr_accessor :log_level
 
+    ##
+    ## Init the console logging object
+    ##
+    ## @param      level  [Integer] log level
+    ##
     def initialize(level = nil)
       @log_level = level.to_i || Howzit.options[:log_level]
     end
 
+    ##
+    ## Get the log level from options
+    ##
+    ## @return     [Integer] log level
+    ##
     def reset_level
       @log_level = Howzit.options[:log_level]
     end
 
+    ##
+    ## Write a message to the console based on the urgency
+    ## level and user's log level setting
+    ##
+    ## @param      msg    [String] The message
+    ## @param      level  [Symbol] The level
+    ##
     def write(msg, level = :info)
       $stderr.puts msg if LOG_LEVELS[level] >= @log_level
     end
 
+    ##
+    ## Write a message at debug level
+    ##
+    ## @param      msg   The message
+    ##
     def debug(msg)
       write msg, :debug
     end
 
+    ##
+    ## Write a message at info level
+    ##
+    ## @param      msg   The message
+    ##
     def info(msg)
       write msg, :info
     end
 
+    ##
+    ## Write a message at warn level
+    ##
+    ## @param      msg   The message
+    ##
     def warn(msg)
       write msg, :warn
     end
 
+    ##
+    ## Write a message at error level
+    ##
+    ## @param      msg   The message
+    ##
     def error(msg)
       write msg, :error
     end

data/lib/howzit/prompt.rb

@@ -8,14 +8,15 @@ module Howzit
         return default unless $stdout.isatty
 
         return default if Howzit.options[:default]
-
-        system 'stty cbreak'
+        tty_state = `stty -g`
+        system 'stty raw -echo cbreak isig'
         yn = color_single_options(default ? %w[Y n] : %w[y N])
         $stdout.syswrite "\e[1;37m#{prompt} #{yn}\e[1;37m? \e[0m"
         res = $stdin.sysread 1
         res.chomp!
         puts
         system 'stty cooked'
+        system "stty #{tty_state}"
         res.empty? ? default : res =~ /y/i
       end
 
@@ -24,12 +25,12 @@ module Howzit
         choices.each do |choice|
           case choice
           when /[A-Z]/
-            out.push(Color.template("{bg}#{choice}{xg}"))
+            out.push(Color.template("{bw}#{choice}{x}"))
           else
-            out.push(Color.template("{w}#{choice}"))
+            out.push(Color.template("{dw}#{choice}{xg}"))
           end
         end
-        Color.template("{g}[#{out.join('/')}{g}]{x}")
+        Color.template("{xg}[#{out.join('/')}{xg}]{x}")
       end
 
       def options_list(matches)

data/lib/howzit/stringutils.rb

@@ -147,7 +147,7 @@ module Howzit
 
     def extract_metadata
       if File.exist?(self)
-        leader = IO.read(self).split(/^#/)[0].strip
+        leader = Util.read_file(self).split(/^#/)[0].strip
         leader.length > 0 ? leader.get_metadata : {}
       else
         {}

data/lib/howzit/topic.rb

@@ -9,6 +9,12 @@ module Howzit
 
     attr_reader :title, :tasks, :prereqs, :postreqs
 
+    ##
+    ## Initialize a topic object
+    ##
+    ## @param      title    [String] The topic title
+    ## @param      content  [String] The raw topic content
+    ##
     def initialize(title, content)
       @title = title
       @content = content
@@ -17,18 +23,29 @@ module Howzit
       @tasks = gather_tasks
     end
 
+    ##
+    ## Search title and contents for a pattern
+    ##
+    ## @param      term  [String] the search pattern
+    ##
     def grep(term)
       @title =~ /#{term}/i || @content =~ /#{term}/i
     end
 
-    # Handle run command, execute directives
+    # Handle run command, execute directives in topic
     def run(nested: false)
       output = []
       tasks = 0
+      cols = begin
+        TTY::Screen.columns > 60 ? 60 : TTY::Screen.columns
+      rescue StandardError
+        60
+      end
+
       if @tasks.count.positive?
         unless @prereqs.empty?
-          puts @prereqs.join("\n\n")
-          res = Prompt.yn('This topic has prerequisites, have they been met?', default: true)
+          puts TTY::Box.frame("{by}#{@prereqs.join("\n\n").wrap(cols - 4)}{x}".c, width: cols)
+          res = Prompt.yn('Have the above prerequisites been met?', default: true)
           Process.exit 1 unless res
 
         end
@@ -85,7 +102,7 @@ module Howzit
       end
       output.push("{bm}Ran #{tasks} #{tasks == 1 ? 'task' : 'tasks'}{x}".c) if Howzit.options[:log_level] < 2 && !nested
 
-      puts postreqs.join("\n\n") unless postreqs.empty?
+      puts TTY::Box.frame("{bw}#{@postreqs.join("\n\n").wrap(cols - 4)}{x}".c, width: cols) unless @postreqs.empty?
 
       output
     end

data/lib/howzit/util.rb

@@ -1,21 +1,26 @@
+# frozen_string_literal: true
+
 module Howzit
+  # Util class
   module Util
     class << self
+      def read_file(path)
+        IO.read(path).force_encoding('utf-8').strip
+      end
+
       def valid_command?(command)
         cmd = command.split(' ')[0]
         command_exist?(cmd)
       end
-      
+
       def command_exist?(command)
         exts = ENV.fetch('PATHEXT', '').split(::File::PATH_SEPARATOR)
         if Pathname.new(command).absolute?
-          ::File.exist?(command) ||
-            exts.any? { |ext| ::File.exist?("#{command}#{ext}") }
+          ::File.exist?(command) || exts.any? { |ext| ::File.exist?("#{command}#{ext}") }
         else
           ENV.fetch('PATH', '').split(::File::PATH_SEPARATOR).any? do |dir|
             file = ::File.join(dir, command)
-            ::File.exist?(file) ||
-              exts.any? { |ext| ::File.exist?("#{file}#{ext}") }
+            ::File.exist?(file) || exts.any? { |ext| ::File.exist?("#{file}#{ext}") }
           end
         end
       end

data/lib/howzit/version.rb

@@ -3,5 +3,5 @@
 # Primary module for this gem.
 module Howzit
   # Current Howzit version.
-  VERSION = '2.0.8'
+  VERSION = '2.0.9'
 end

data/lib/howzit.rb

@@ -21,6 +21,7 @@ require 'tempfile'
 require 'yaml'
 
 require 'tty/screen'
+require 'tty/box'
 # require 'tty/prompt'
 
 CONFIG_DIR = '~/.config/howzit'
@@ -30,6 +31,7 @@ MATCHING_OPTIONS = %w[partial exact fuzzy beginswith].freeze
 MULTIPLE_OPTIONS = %w[first best all choose].freeze
 HEADER_FORMAT_OPTIONS = %w[border block].freeze
 
+# Main module for howzit
 module Howzit
   class << self
     attr_accessor :arguments, :cli_args

data/spec/cli_spec.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+# https://github.com/thoiberg/cli-test
+describe 'CLI' do
+  include CliTest
+
+  it 'executes successfully' do
+    execute_script('bin/howzit', use_bundler: true)
+    expect(last_execution).to be_successful
+  end
+
+  it 'lists available topics' do
+    execute_script('bin/howzit', use_bundler: true, args: %w[-L])
+    expect(last_execution).to be_successful
+    expect(last_execution.stdout).to match(/Topic Balogna/)
+    expect(last_execution.stdout.split(/\n/).count).to eq 3
+  end
+
+  it 'lists available tasks' do
+    execute_script('bin/howzit', use_bundler: true, args: %w[-T])
+    expect(last_execution).to be_successful
+    expect(last_execution.stdout).to match(/Topic Balogna/)
+    expect(last_execution.stdout.split(/\n/).count).to eq 2
+  end
+end

data/spec/spec_helper.rb

@@ -10,6 +10,7 @@
 # end
 
 require 'howzit'
+require 'cli-test'
 
 RSpec.configure do |c|
   c.expect_with(:rspec) { |e| e.syntax = :expect }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: howzit
 version: !ruby/object:Gem::Version
-  version: 2.0.8
+  version: 2.0.9
 platform: ruby
 authors:
 - Brett Terpstra
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-08-04 00:00:00.000000000 Z
+date: 2022-08-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -136,6 +136,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: cli-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -240,6 +254,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: tty-box
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
 description: Command line project documentation and task runner
 email:
 - me@brettterpstra.com
@@ -283,6 +311,7 @@ files:
 - spec/.rubocop.yml
 - spec/buildnote_spec.rb
 - spec/buildnotes.md.bak
+- spec/cli_spec.rb
 - spec/ruby_gem_spec.rb
 - spec/spec_helper.rb
 - spec/task_spec.rb
@@ -316,6 +345,7 @@ test_files:
 - spec/.rubocop.yml
 - spec/buildnote_spec.rb
 - spec/buildnotes.md.bak
+- spec/cli_spec.rb
 - spec/ruby_gem_spec.rb
 - spec/spec_helper.rb
 - spec/task_spec.rb