README.adoc in pennyworth-11.0.0 vs README.adoc in pennyworth-11.0.1

- old
+ new

@@ -9,28 +9,32 @@ [link=https://www.alchemists.io/projects/code_quality] image::https://img.shields.io/badge/code_style-alchemists-brightgreen.svg[Alchemists Style Guide] [link=https://circleci.com/gh/bkuhlmann/pennyworth] image::https://circleci.com/gh/bkuhlmann/pennyworth.svg?style=svg[Circle CI Status] -A command line interface that enhances Alfred with Ruby support. +A command line interface that augments link:https://www.alfredapp.com[Alfred] workflows. + + toc::[] == Features -* Adds Ruby support to link:https://www.alfredapp.com/help/workflows/inputs/script-filter/json[Alfred]. +* Adds Ruby support to link:https://www.alfredapp.com[Alfred]. +* Supports building advanced link:https://www.alfredapp.com/help/workflows[Workflows] for personal + augmentation. == Screencast -video::https://www.alchemists.io/videos/projects/pennyworth/demo.mp4[width=1062,height=1194,role=focal_point] +video::https://www.alchemists.io/videos/projects/pennyworth/demo.mp4[poster=https://www.alchemists.io/images/projects/pennyworth/demo.png,width=1062,height=1194,role=focal_point] == Requirements . link:https://www.apple.com/macos[macOS] +. link:https://www.gnu.org/software/bash[Bash] . link:https://www.alfredapp.com[Alfred] . link:https://www.alfredapp.com/purchase[Alfred Powerpack] -. link:https://www.gnu.org/software/bash[Bash] . link:https://github.com/postmodern/chruby[chruby] . link:https://www.ruby-lang.org[Ruby] == Setup @@ -39,12 +43,13 @@ [source,bash] ---- gem install pennyworth ---- -When using the `-\-git_hub` CLI option, you'll want to supply your login and personal access token -with at least _read_ access via the following environment variables: +When using the `--git_hub` CLI option, you'll want to supply your GitHub login and +link:https://github.com/settings/tokens[Personal Access Token] with at least _read_ access via the +following environment variables: [source,bash] ---- GITHUB_API_LOGIN= GITHUB_API_TOKEN= @@ -52,15 +57,19 @@ You can configure these environment variables via link:https://direnv.net[direnv] if using the CLI or through the link:https://www.alfredapp.com/help/workflows/advanced/variables/#environment[Alfred Workflow Environment]. +⚠️ When using Alfred Workflow environment variables, please ensure you check the _Don't Export_ +option for these variables so you don't expose your credentials when exporting/sharing workflows +with others. + == Usage === Command Line Interface (CLI) -From the command line, type `pennyworth` to render usage: +From the command line, type `pennyworth` to view usage: .... USAGE: -c, --config ACTION Manage gem configuration. Actions: edit || view. --encodings Render Alfred encodings script filter. @@ -79,11 +88,11 @@ RUBYGEMS OPTIONS: --owner [HANDLE] Set owner. Default: "". .... -The following demonstrates how to use Pennyworth from the CLI or within an Alfred script filter: +The following demonstrates how to use Pennyworth from the CLI or within an Alfred Script Filter: [source,bash] ---- pennyworth --config edit pennyworth --config view @@ -131,12 +140,12 @@ - "Flacsmith": "FLACsmith" - "Git Plus": "Git+" - "Mac Os Config": "macOS Configuration" - "Mac Os": "MacOS" - "Prawn Plus": "Prawn+" - - "Rubocop Ast": "Rubocop AST" - - "Rubocop Md": "Rubocop Markdown" + - "Rubocop Ast": "Rubocop AST" + - "Rubocop Md": "Rubocop Markdown" - "Rubocop Rspec": "Rubocop RSpec" - "Xdg": "XDG" :git_hub: :api_url: "https://api.github.com" :organization: @@ -152,125 +161,233 @@ Feel free to take this default configuration, modify, and save as your own custom `configuration.yml`. === Themes -image:https://www.alchemists.io/images/projects/pennyworth/screenshots/alfred/alchemists-theme.png[Alchemists Theme,width=634,height=121,role=focal_point] +image:https://www.alchemists.io/images/projects/pennyworth/screenshots/alchemists-theme.png[Alchemists Theme,width=634,height=121,role=focal_point] -To use the -link:https://www.alchemists.io/public/aflred/themes/alchemists.alfredappearance[Alchemists Theme], -used for all screenshots, follow these steps: +The above is shared as the link:https://www.alfredapp.com/extras/theme/FSz9kjN1wX[Alchemists Alfred +Theme] which can be +link:alfred://theme/?t=eyJhbGZyZWR0aGVtZSI6eyJyZXN1bHQiOnsidGV4dFNwYWNpbmciOjEwLCJzdWJ0ZXh0Ijp7InNpemUiOjEyLCJjb2xvclNlbGVjdGVkIjoiI0Q2RDZENkZGIiwiZm9udCI6IkhlbHZldGljYSIsImNvbG9yIjoiI0Q2RDZENkZGIn0sInNob3J0Y3V0Ijp7InNpemUiOjE2LCJjb2xvclNlbGVjdGVkIjoiI0ZGRkZGRkZGIiwiZm9udCI6IkhlbHZldGljYSIsImNvbG9yIjoiI0ZFRkNGRkZGIn0sImJhY2tncm91bmRTZWxlY3RlZCI6IiNBMDI2MThGRiIsInRleHQiOnsic2l6ZSI6MTYsImNvbG9yU2VsZWN0ZWQiOiIjRkZGRkZGRkYiLCJmb250IjoiSGVsdmV0aWNhIiwiY29sb3IiOiIjRTFERURFRkYifSwiaWNvblBhZGRpbmdIb3Jpem9udGFsIjo1LCJyb3VuZG5lc3MiOjAsInBhZGRpbmdWZXJ0aWNhbCI6NiwiaWNvblNpemUiOjQwfSwic2VhcmNoIjp7ImJhY2tncm91bmRTZWxlY3RlZCI6IiNCMkQ3RkZGRiIsInBhZGRpbmdIb3Jpem9udGFsIjo4LCJzcGFjaW5nIjoxMCwidGV4dCI6eyJzaXplIjozNiwiY29sb3JTZWxlY3RlZCI6IiMwMDAwMDBGRiIsImZvbnQiOiJIZWx2ZXRpY2EiLCJjb2xvciI6IiNGRkZGRkZGRiJ9LCJiYWNrZ3JvdW5kIjoiIzEyMTIxMkZGIiwicm91bmRuZXNzIjowLCJwYWRkaW5nVmVydGljYWwiOjJ9LCJ3aW5kb3ciOnsiY29sb3IiOiIjNzAwQTAwRkYiLCJwYWRkaW5nSG9yaXpvbnRhbCI6MTAsIndpZHRoIjo2MjAsImJvcmRlclBhZGRpbmciOjEwLCJib3JkZXJDb2xvciI6IiMwMDAwMDAzRiIsImJsdXIiOjAsInJvdW5kbmVzcyI6MTIsInBhZGRpbmdWZXJ0aWNhbCI6MTB9LCJjcmVkaXQiOiJCcm9va2UgS3VobG1hbm4iLCJzZXBhcmF0b3IiOnsiY29sb3IiOiIjMDAwMDAwNjYiLCJ0aGlja25lc3MiOjJ9LCJzY3JvbGxiYXIiOnsiY29sb3IiOiIjMDAwMDAwNjYiLCJ0aGlja25lc3MiOjJ9LCJuYW1lIjoiQWxjaGVtaXN0cyJ9fQ==[installed +directly]. -1. link:https://www.alchemists.io/public/aflred/themes/alchemists.alfredappearance[Download] (right - click) theme. -1. Double click to install. - === Workflows Not all workflows require Pennyworth to run properly. For the workflows that _do_ require Pennyworth support, the following assumptions are made: -1. Your link:https://www.alchemists.io/projects/dotfiles[Dotfiles] are configured to use Bash and - load your environment appropriately. -1. You have the latest version of Ruby and Pennyworth installed. +1. Your link:https://www.alchemists.io/projects/dotfiles[Dotfiles] are configured to use + link:https://www.gnu.org/software/bash[Bash] and load your environment appropriately. Bash is not + a hard requirement, though. You can use _any shell_ you are comfortable with as long as you teach + Alfred to load your development environment before running the Alfred Workflow. +2. You have the latest version of Alfred, Ruby, and Pennyworth installed. +3. You are using a Ruby version manager, like link:https://github.com/postmodern/chruby[chruby], + which ensures Ruby is on your load path. -With the above requirements in mind, you should only need to build an Alfred Script Filter that -looks something like this: +With the above requirements in mind, the following sections document how to download and install all +Pennyworth workflows that are compatible with Alfred. Should you want to tweak any of these +workflows, you'd only need to edit an existing workflow or build your own with these settings: -image:https://www.alchemists.io/images/projects/pennyworth/screenshots/alfred/script_filter.png[Script Filter,width=776,height=635,role=focal_point] +image:https://www.alchemists.io/images/projects/pennyworth/screenshots/script_filter.png[Script Filter,width=776,height=635,role=focal_point] -That's all it takes to use Pennyworth as an Alfred script filter. 🎉 You don't have to do any of this -work yourself. I've already built the corresponding workflows. The following sections will allow you -to download and use the corresponding Alfred Workflows that are powered by Pennyworth. +Before diving into each workflow, I want to highlight that the following capabilities are available +to all workflows depending on what kind of item is currently selected within the Alfred UI: -Before diving into each workflow, the following capabilties are mostly available to all workflows -depending on what kind of item is selected in the script filter: - -* `SHIFT` or `COMMAND + y` will launch quick look for any URL based workflow. -* `ENTER` or `COMMAND + c` will copy non-URL selections to clipboard. -* `COMMAND + l` will launch large type of current selection. +* `SHIFT` or `COMMAND + y` will launch + link:https://www.alfredapp.com/help/features/previews[Quicklook] for any URL based workflow. +* `ENTER` or `COMMAND + c` will copy selections to clipboard (depends on context, though). +* `COMMAND + l` will launch link:https://www.alfredapp.com/help/features/large-type[Large Type] of + current selection. * `ENTER` Will either copy selection to clipboard or launch URL in default web browser. ==== Alchemists -image:https://www.alchemists.io/images/projects/pennyworth/screenshots/alfred/alchemists-projects.png[Alchemists Projects,width=706,height=622,role=focal_point] +image:https://www.alchemists.io/images/projects/pennyworth/screenshots/alchemists-projects.png[Alchemists Projects,width=706,height=632,role=focal_point] -1. link:https://www.alchemists.io/public/aflred/workflows/alchemists.alfredworkflow[Download] (right - click). -1. Type `ax` to activate. +The official link:https://www.alchemists.io[Alchemists] workflow for site navigation. -💡 Use `ENTER` to view site, `CONTROL` to view changes, `OPTION` to view source, and `COMMAND` to +1. link:https://www.alchemists.io/public/aflred/workflows/alchemists.alfredworkflow[Download] and + double click to install. +2. Type `ax` to activate. + +💡 Use `ENTER` to view site, `CONTROL` to view changes, `OPTION` to view source, or `COMMAND` to view issues. ==== Dry RB -image:https://www.alchemists.io/images/projects/pennyworth/screenshots/alfred/dry-gems.png[Dry Gems,width=706,height=622,role=focal_point] +image:https://www.alchemists.io/images/projects/pennyworth/screenshots/dry-gems.png[Dry Gems,width=706,height=632,role=focal_point] -1. link:https://www.alchemists.io/public/aflred/workflows/dry.alfredworkflow[Download] (right click). -1. Type `dry` to activate. +A link:https://dry-rb.org[Dry RB] workflow for navigating all of the Dry RB site. -💡 Use `ENTER` to visit site, `CONTROL` to view changes, `OPTION` to view source, and `COMMAND` to +1. link:https://www.alchemists.io/public/aflred/workflows/dry.alfredworkflow[Download] and double + click to install. +2. Type `dry` to activate. + +💡 Use `ENTER` to visit site, `CONTROL` to view changes, `OPTION` to view source, or `COMMAND` to view issues. -==== Encodings +==== Rubocop -image:https://www.alchemists.io/images/projects/pennyworth/screenshots/alfred/encodings.png[Encodings,width=706,height=622,role=focal_point] +image:https://www.alchemists.io/images/projects/pennyworth/screenshots/rubocop-projects.png[Rubocop Projects,width=706,height=632,role=focal_point] -1. link:https://www.alchemists.io/public/aflred/workflows/ruby.alfredworkflow[Download] (right click). -1. Type `encodings` to activate. +A link:https://docs.rubocop.org/rubocop[Rubocop] workflow for quick access to documentation, +learning about project changes, viewing source code, etc. -💡 Use `ENTER` to copy label and `OPTION` to copy aliases to clipboard. +1. link:https://www.alchemists.io/public/aflred/workflows/rubocop.alfredworkflow[Download] and + double click to install. +2. Type `cop` to activate. -==== HTTP Statuses +💡 Use `ENTER` to view site, `CONTROL` to view changes, `OPTION` to view source, or `COMMAND` to +view issues. -image:https://www.alchemists.io/images/projects/pennyworth/screenshots/alfred/http_statuses.png[HTTP Statuses,width=706,height=622,role=focal_point] +==== Ruby -1. link:https://www.alchemists.io/public/aflred/workflows/ruby.alfredworkflow[Download] (right click). -1. Type `https` to activate. +This workflow is feature packed and only requires a +link:https://www.alchemists.io/public/aflred/workflows/ruby.alfredworkflow[single download]. Once +downloaded, double click to install, and then continue reading to learn all of the +capabilities this single workflow provides. -💡 Use `ENTER` to copy symbol, `CONTROL` to copy code, `OPTION` to copy label, and `COMMAND` to view -documentation. +===== Bytes -==== Rubocop +image:https://www.alchemists.io/images/projects/pennyworth/screenshots/ruby-bytes.png[Bytes,width=706,height=200,role=focal_point] -image:https://www.alchemists.io/images/projects/pennyworth/screenshots/alfred/rubocop-projects.png[Rubocop Projects,width=706,height=622,role=focal_point] +This keyword allows you to generate random bytes. -1. link:https://www.alchemists.io/public/aflred/workflows/rubocop.alfredworkflow[Download] (right - click). -1. Type `cop` to activate. +Type `bytes` to activate and `ENTER` generate. You can supply an optional number for specific +length. -💡 Use `ENTER` to view site, `CONTROL` to view changes, `OPTION` to view source, and `COMMAND` to -view issues. +===== Encodings -==== System Errors +image:https://www.alchemists.io/images/projects/pennyworth/screenshots/ruby-encodings.png[Encodings,width=706,height=632,role=focal_point] -image:https://www.alchemists.io/images/projects/pennyworth/screenshots/alfred/system_errors.png[System Errors,width=706,height=622,role=focal_point] +This keyword allows you to quickly search for various encodings and/or their associated aliases to +use in your own code. -1. link:https://www.alchemists.io/public/aflred/workflows/ruby.alfredworkflow[Download] (right click). -1. Type `syserr` to activate. +Type `encodings` to activate. Use `ENTER` to copy label or `OPTION` to copy associated aliases to +clipboard. -💡 Use `ENTER` to copy constant/class, `CONTROL` to copy ID, `OPTION` to copy description, and -`COMMAND` to copy ID, name, and description. +===== Hex -==== System Signals +image:https://www.alchemists.io/images/projects/pennyworth/screenshots/ruby-hex.png[Hex,width=706,height=200,role=focal_point] -image:https://www.alchemists.io/images/projects/pennyworth/screenshots/alfred/system_signals.png[System Signals,width=706,height=622,role=focal_point] +This keyword allows you to generate a random hex string. -1. link:https://www.alchemists.io/public/aflred/workflows/ruby.alfredworkflow[Download] (right - click). -1. Type `signals` to activate. +Type `hex` to activate and `ENTER` generate. You can supply an optional number for specific length. -💡 Use `ENTER` to copy name, `OPTION` to copy ID, and `COMMAND` to copy ID and name. +===== HTTP Statuses -==== Text +image:https://www.alchemists.io/images/projects/pennyworth/screenshots/ruby-http_statuses.png[HTTP Statuses,width=706,height=632,role=focal_point] -image:https://www.alchemists.io/images/projects/pennyworth/screenshots/alfred/text.png[Text,width=706,height=622,role=focal_point] +This keyword allows you to look up statuses by code with quick access to the associated symbol for +use in your own code. Includes associated documentation for sharing or learning more. All HTTP +statuses are sourced from `Rack::Utils::HTTP_STATUS_CODES` which is why +link:https://rubygems.org/gems/rack[Rack] is a dependency of this gem and also why some codes might +not be present like these +link:https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#Unofficial_codes[unofficial codes]. -1. link:https://www.alchemists.io/public/aflred/workflows/ruby.alfredworkflow[Download] (right - click). -1. Type `text` plus your text to transform to activate. +Type `https` to activate. Use `ENTER` to copy symbol, `CONTROL` to copy code, `OPTION` to copy +label, or `COMMAND` to view documentation. -💡 Use `ENTER` to copy text to clipboard. +===== Number + +image:https://www.alchemists.io/images/projects/pennyworth/screenshots/ruby-number.png[Hex,width=706,height=200,role=focal_point] + +This keyword allows you to generate a random number. + +Type `number` to activate and `ENTER` generate. You can supply an optional number for specific +length. + +===== Repeat + +image:https://www.alchemists.io/images/projects/pennyworth/screenshots/ruby-repeat.png[Hex,width=706,height=200,role=focal_point] + +This keyword allows you to generate a repeating sequence of the same character(s). + +Type `repeat` to activate and `ENTER` generate. You must supply the character(s) you want to repeat +followed by a number indicating how many times you want the character(s) to repeat. + +===== System Errors + +image:https://www.alchemists.io/images/projects/pennyworth/screenshots/ruby-system_errors.png[System Errors,width=706,height=632,role=focal_point] + +This keyword allows you to search low-level system errors. Depending on which operating system you +are on, these errors will differ. Error IDs are provided for fuzzy searching since they are what +you'll most likely see in your stack dumps. The associated constant can be copied to clipboard for +use in your Ruby code. + +Type `syserr` to activate. Use `ENTER` to copy constant, `CONTROL` to copy ID, `OPTION` to copy +description, or `COMMAND` to copy ID, name, and description. + +===== System Signals + +image:https://www.alchemists.io/images/projects/pennyworth/screenshots/ruby-system_signals.png[System Signals,width=706,height=632,role=focal_point] + +This keyword is for searching and acquiring the system signal you want to `trap` in your Ruby code. + +Type `signals` to activate. Use `ENTER` to copy name, `OPTION` to copy ID, or `COMMAND` to copy ID +and name. + +===== Text + +image:https://www.alchemists.io/images/projects/pennyworth/screenshots/ruby-text.png[Text,width=706,height=632,role=focal_point] + +This keyword is for is for basic text manipulation. Supply a string, phrase, or sentence and let +Pennyworth calculate all transformations and information you might need. + +Type `text` to activate plus andy string or phrase to transform. Use `ENTER` to copy text to +clipboard. + +===== UUID + +image:https://www.alchemists.io/images/projects/pennyworth/screenshots/ruby-uuid.png[Hex,width=706,height=200,role=focal_point] + +This keyword allows you to generate a random Universally Unique IDentifier (UUID). + +Type `uuid` to activate and `ENTER` generate. + +==== Other + +The following workflows don't require Pennyworth support but are provided for convenience in case +they are of interest/aid to your own productivity. Click each link to download and then double click +to install: + +* link:https://www.alchemists.io/public/aflred/workflows/acronyms.alfredworkflow[Acronyms] - Expands + acronyms into full explanations so you can think and type in terms of an acronym but appear as if + you typed out the full definition each time. +* https://www.alchemists.io/public/aflred/workflows/alpine.alfredworkflow[Alpine] - Provides + link:https://www.alpinelinux.org[Alpine Linux] resources. +* link:https://www.alchemists.io/public/aflred/workflows/applications.alfredworkflow[Applications] - + Launches development environment but can be tweaked for your preferences. Using Alfred in this + manner ensures your machine boots or restarts quickly and gives you more control over what is + launched. +* link:https://www.alchemists.io/public/aflred/workflows/browsers.alfredworkflow[Browsers] - + Provides browser related utilities. +* link:https://www.alchemists.io/public/aflred/workflows/hanami.alfredworkflow[Hanami] - Provides + link:https://hanamirb.org[Hanami] resources. +* link:https://www.alchemists.io/public/aflred/workflows/chlli.alfredworkflow[chi.li] - Shortens + URLs. +* link:https://www.alchemists.io/public/aflred/workflows/docker.alfredworkflow[Docker] - Provides + link:https://www.docker.com[Docker] resources. +* link:https://www.alchemists.io/public/aflred/workflows/mac_os.alfredworkflow[macOS] - Provides + macOS utilities. +* link:https://www.alchemists.io/public/aflred/workflows/terraform.alfredworkflow[Terraform] - + Provides link:https://www.terraform.io[Terraform] resources. +* link:https://www.alchemists.io/public/aflred/workflows/text.alfredworkflow[Text] - Provides + general text manipulation utilities beyond the Pennyworth powered _text_ keyword (mentioned + earlier). + +== Troubleshooting + +* link:https://github.com/ruby/psych[Psych] 4.0.0 has a + link:https://github.com/ruby/psych/issues/490[bug] which prevents loading of YAML configurations + that use symbols as keys. If you get caught by this, uninstall Psych 4.0.0 and fall back to 3.x.x + instead. +* When your Alfred Workflow yields no output, you might want to open the + link:https://www.alfredapp.com/help/workflows/utilities/debug[Alfred Debugger], rerun your + workflow, and check for errors. You can also jump to the CLI and run Pennyworth directly. +* If you get GitHub authorization errors, make sure you have defined the appropriate credentials + (mentioned earlier) for both within your shell where you are running Pennyworth or within the + Alfred Workflow environment. == Development To contribute, run: