:toc: macro :toclevels: 5 :figure-caption!: = Pennyworth [link=http://badge.fury.io/rb/pennyworth] image::https://badge.fury.io/rb/pennyworth.svg[Gem Version] [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 augments link:https://www.alfredapp.com[Alfred] workflows. toc::[] == Features * 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[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://github.com/postmodern/chruby[chruby] . link:https://www.ruby-lang.org[Ruby] == Setup To install, run: [source,bash] ---- gem install pennyworth ---- 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= ---- 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 view usage: .... USAGE: -c, --config ACTION Manage gem configuration. Actions: edit || view. --encodings Render Alfred encodings script filter. --git_hub Render Alfred GitHub repositories script filter. -h, --help Show this message. --http_statuses Render Alfred HTTP statuses script filter. --ruby_gems Render Alfred RubyGems script filter. --system_errors Render Alfred system errors script filter. --system_signals Render Alfred system signals script filter. --text CONTENT Render Alfred text script filter. -v, --version Show gem version. GITHUB OPTIONS: --organization [HANDLE] Set organization. Default: "". --user [HANDLE] Set user. Default: "". RUBYGEMS OPTIONS: --owner [HANDLE] Set owner. Default: "". .... The following demonstrates how to use Pennyworth from the CLI or within an Alfred Script Filter: [source,bash] ---- pennyworth --config edit pennyworth --config view pennyworth --encodings pennyworth --git_hub --organization alchemists pennyworth --git_hub --user bkuhlmann pennyworth --http_statuses pennyworth --ruby_gems --owner bkuhlmann pennyworth --system_errors pennyworth --system_signals pennyworth --text demo pennyworth --text "An Example" ---- While the command line options are nice, the real power comes from using Pennyworth in conjunction with link:https://www.alfredapp.com/help/workflows/inputs/script-filter/json[Alfred Script Filters]. Without having Alfred wired up to consume the CLI output, you'll only get a JSON in your console. To explain better, continue reading or skip ahead to the _Workflows_ section. === Customization This gem can be configured via a global configuration: .... ~/.config/pennyworth/configuration.yml .... It can also be configured via link:https://www.alchemists.io/projects/xdg[XDG] environment variables. The default configuration is as follows: [source,yaml] ---- :alfred: :preferences: :inflections: - "Bkuhlmann": "bkuhlmann" - "Dry Auto Inject": "Dry AutoInject" - "Dry Cli": "Dry CLI" - "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 Rspec": "Rubocop RSpec" - "Xdg": "XDG" :git_hub: :api_url: "https://api.github.com" :organization: :user: :http: :statuses: :url: "https://httpstatuses.com" :ruby_gems: :api_url: "https://rubygems.org/api/v1" :owner: ---- 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/alchemists-theme.png[Alchemists Theme,width=634,height=121,role=focal_point] 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]. === 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 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, 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/script_filter.png[Script Filter,width=776,height=635,role=focal_point] 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: * `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/alchemists-projects.png[Alchemists Projects,width=706,height=632,role=focal_point] The official link:https://www.alchemists.io[Alchemists] workflow for site navigation. 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/dry-gems.png[Dry Gems,width=706,height=632,role=focal_point] A link:https://dry-rb.org[Dry RB] workflow for navigating all of the Dry RB site. 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. ==== Rubocop image:https://www.alchemists.io/images/projects/pennyworth/screenshots/rubocop-projects.png[Rubocop Projects,width=706,height=632,role=focal_point] A link:https://docs.rubocop.org/rubocop[Rubocop] workflow for quick access to documentation, learning about project changes, viewing source code, etc. 1. link:https://www.alchemists.io/public/aflred/workflows/rubocop.alfredworkflow[Download] and double click to install. 2. Type `cop` to activate. 💡 Use `ENTER` to view site, `CONTROL` to view changes, `OPTION` to view source, or `COMMAND` to view issues. ==== Ruby 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. ===== Bytes image:https://www.alchemists.io/images/projects/pennyworth/screenshots/ruby-bytes.png[Bytes,width=706,height=200,role=focal_point] This keyword allows you to generate random bytes. Type `bytes` to activate and `ENTER` generate. You can supply an optional number for specific length. ===== Encodings image:https://www.alchemists.io/images/projects/pennyworth/screenshots/ruby-encodings.png[Encodings,width=706,height=632,role=focal_point] This keyword allows you to quickly search for various encodings and/or their associated aliases to use in your own code. Type `encodings` to activate. Use `ENTER` to copy label or `OPTION` to copy associated aliases to clipboard. ===== Hex image:https://www.alchemists.io/images/projects/pennyworth/screenshots/ruby-hex.png[Hex,width=706,height=200,role=focal_point] This keyword allows you to generate a random hex string. Type `hex` to activate and `ENTER` generate. You can supply an optional number for specific length. ===== HTTP Statuses image:https://www.alchemists.io/images/projects/pennyworth/screenshots/ruby-http_statuses.png[HTTP Statuses,width=706,height=632,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]. Type `https` to activate. Use `ENTER` to copy symbol, `CONTROL` to copy code, `OPTION` to copy label, or `COMMAND` to view documentation. ===== Number image:https://www.alchemists.io/images/projects/pennyworth/screenshots/ruby-number.png[Number,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[Repeat,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[UUID,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. ===== Version image:https://www.alchemists.io/images/projects/pennyworth/screenshots/ruby-version.png[Version,width=706,height=254,role=focal_point] This keyword allows you obtain Ruby version information. Type `version` to activate and `ENTER` generate. Optionally, you can press `OPTION` when selected to answer the Ruby version used by Alfred since Alfred defaults to using whatever version is supplied by macOS. ==== 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). == Architecture The following documents the workfow used to process all actions from Alfred. image::/doc/architecture.svg[Architecture Diagram] == 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: [source,bash] ---- git clone https://github.com/bkuhlmann/pennyworth.git cd pennyworth bin/setup ---- You can also use the IRB console for direct access to all objects: [source,bash] ---- bin/console ---- == Tests To test, run: [source,bash] ---- bundle exec rake ---- == Versioning Read link:https://semver.org[Semantic Versioning] for details. Briefly, it means: * Major (X.y.z) - Incremented for any backwards incompatible public API changes. * Minor (x.Y.z) - Incremented for new, backwards compatible, public API enhancements/fixes. * Patch (x.y.Z) - Incremented for small, backwards compatible, bug fixes. == Code of Conduct Please note that this project is released with a link:CODE_OF_CONDUCT.adoc[CODE OF CONDUCT]. By participating in this project you agree to abide by its terms. == Contributions Read link:CONTRIBUTING.adoc[CONTRIBUTING] for details. == License Read link:LICENSE.adoc[LICENSE] for details. == History Read link:CHANGES.adoc[CHANGES] for details. == Credits Engineered by link:https://www.alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].