pennyworth

Created By: Brooke Kuhlmann, 7 Stars, Last Updated: 25/11/21 18:52:40

Love this? Please consider supporting its creator by starring or sponsoring this project on GitHub!

From the project's README:

(toc) macro (toclevels) 5 :figure-caption!:

(frum_link) link:https://github.com/tako8ki/frum[Frum]

= 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]

Pennyworth is a command line interface and the perfect companion to link:https://www.alfredapp.com[Alfred]. With Pennyworth, you can unlock the full potential of the Ruby language by leveraging modern versions of Ruby through Alfred Workflows. Perfect for when you want to advance beyond the basic workflows Alfred provides by default.

toc::[]

== Features

== Screencast

video::https://www.alchemists.io/videos/projects/pennyworth/demo.mp4[poster=https://www.alchemists.io/images/projects/pennyworth/demo.png,width=700,height=636,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.ruby-lang.org[Ruby]

While using a Ruby version manager -- like {frum_link} -- is not a hard requirement, it is strongly encouraged since a version manager will give you the freedom to toggle between different Ruby versions since this gem has strict Ruby version requirements (especially in regards to using a modern version of Ruby).

I would also like to point out that all of the workflows, scripts, examples for this gem use Bash syntax. That said, if you are comfortable with translating Bash syntax to your shell syntax of choice, you can make this gem work in different shells too. That is beyond the scope of this document, though, so leave that exercise up to you.

== 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"
  • "Tty Box": "TTY Box"
  • "Tty Color": "TTY Color"
  • "Tty Command": "TTY Command"
  • "Tty Config": "TTY Config"
  • "Tty Cursor": "TTY Cursor"
  • "Tty Editor": "TTY Editor"
  • "Tty File": "TTY File"
  • "Tty Font": "TTY Font"
  • "Tty Link": "TTY Link"
  • "Tty Logger": "TTY Logger"
  • "Tty Markdown": "TTY Markdown"
  • "Tty Option": "TTY Option"
  • "Tty Pager": "TTY Pager"
  • "Tty Pie": "TTY Pie"
  • "Tty Platform": "TTY Platform"
  • "Tty Progressbar": "TTY ProgressBar"
  • "Tty Prompt": "TTY Prompt"
  • "Tty Reader": "TTY Reader"
  • "Tty Screen": "TTY Screen"
  • "Tty Spinner": "TTY Spinner"
  • "Tty Table": "TTY Table"
  • "Tty Tree": "TTY Tree"
  • "Tty Which": "TTY Which"
  • "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=706,height=632,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 (see the Other section below for details). 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 {frum_link}, which ensures Ruby is on your load path. As mentioned in the Requirements section above, this is not a hard requirement so if you have the correct version of Ruby required by this gem on your path, that'll work too.

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:

==== 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/alfred/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/alfred/workflows/dry.alfredworkflow[Download] and double click to install.
  2. Type dry to activate general information and dryx for project list.

💡 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/alfred/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/alfred/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.

===== Gems

image:https://www.alchemists.io/images/projects/pennyworth/screenshots/ruby-gems.png[Gems,width=706,height=362,role=focal_point]

Provides access to the RubyGems ecosystem.

Type gems to activate. Use the arrow keys to navigate options and ENTER to use.

===== 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.

===== Links

image:https://www.alchemists.io/images/projects/pennyworth/screenshots/ruby-links.png[Links,width=706,height=632,role=focal_point]

This keyword allows you to navigate to additional Ruby related information and resources.

Type rb plus SPACE to activate, then fuzzy type to filter the list to what you are looking for, and hit ENTER to visit the link in your default browser.

===== 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 any 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.

===== Acronyms

Expands acronyms so you can think and type in terms of an acronym but appear as if you typed out the full definition each time.

  1. link:https://www.alchemists.io/public/alfred/workflows/acronyms.alfredworkflow[Download] and double click to install.
  2. Use any of the macros provided by the workflow to expand acronyms for legibility.

===== Alpine

image:https://www.alchemists.io/images/projects/pennyworth/screenshots/alpine.png[Alpine Linux workflow screenshot.,width=706,height=632,role=focal_point]

Provides link:https://www.alpinelinux.org[Alpine Linux] resources.

  1. link:https://www.alchemists.io/public/alfred/workflows/alpine.alfredworkflow[Download] and double click to install.
  2. Type al to activate.

===== Applications

image:https://www.alchemists.io/images/projects/pennyworth/screenshots/applications.png[Applications workflow screenshot.,width=706,height=362,role=focal_point]

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.

  1. link:https://www.alchemists.io/public/alfred/workflows/applications.alfredworkflow[Download] and double click to install.
  2. Type work to activate.

===== Browsers

image:https://www.alchemists.io/images/projects/pennyworth/screenshots/browsers.png[Browsers workflow screenshot.,width=706,height=470,role=focal_point]

Provides browser related utilities.

  1. link:https://www.alchemists.io/public/alfred/workflows/browsers.alfredworkflow[Download] and double click to install.
  2. Type open to activate.

===== Bundler

image:https://www.alchemists.io/images/projects/pennyworth/screenshots/bundler.png[Bundler workflow screenshot.,width=706,height=524,role=focal_point]

Provides quick access to link:https://bundler.io[Bundler] related resources.

  1. link:https://www.alchemists.io/public/alfred/workflows/bundler.alfredworkflow[Download] and double click to install.
  2. Type bundler to activate.

===== Elm

image:https://www.alchemists.io/images/projects/pennyworth/screenshots/elm.png[Elm workflow screenshot.,width=706,height=470,role=focal_point]

A link:https://elm-lang.org[Elm] workflow for quick access to Elm resources.

  1. link:https://www.alchemists.io/public/alfred/workflows/elm.alfredworkflow[Download] and double click to install.
  2. Type elm to view general information, arrow keys to navigate, and ENTER to view information.

===== Hanami

image:https://www.alchemists.io/images/projects/pennyworth/screenshots/hanami.png[Hanami workflow screenshot.,width=706,height=632,role=focal_point]

Provides link:https://hanamirb.org[Hanami] resources.

  1. link:https://www.alchemists.io/public/alfred/workflows/hanami.alfredworkflow[Download] and double click to install.
  2. Type h to activate.

===== chi.li

image:https://www.alchemists.io/images/projects/pennyworth/screenshots/chili.png[chi.li workflow screenshot.,width=706,height=200,role=focal_point]

Shortens URLs using link:https://chl.li[chl.li].

  1. link:https://www.alchemists.io/public/alfred/workflows/chlli.alfredworkflow[Download] and double click to install.
  2. Type surl to activate.

===== Docker

image:https://www.alchemists.io/images/projects/pennyworth/screenshots/docker.png[Docker workflow screenshot.,width=706,height=524,role=focal_point]

Provides link:https://www.docker.com[Docker] resources.

  1. link:https://www.alchemists.io/public/alfred/workflows/docker.alfredworkflow[Download] and double click to install.
  2. Type dr to activate.

===== macOS

Provides macOS utilities.

  1. link:https://www.alchemists.io/public/alfred/workflows/mac_os.alfredworkflow[Download] and double click to install.
  2. Open the workflow to see all available keywords.

===== Terraform

image:https://www.alchemists.io/images/projects/pennyworth/screenshots/terraform.png[Terraform workflow screenshot.,width=706,height=632,role=focal_point]

Provides link:https://www.terraform.io[Terraform] resources.

  1. link:https://www.alchemists.io/public/alfred/workflows/terraform.alfredworkflow[Download] and double click to install.
  2. Type tf to activate.

===== Text

Provides general text manipulation utilities beyond the Pennyworth powered text keyword (mentioned earlier).

  1. link:https://www.alchemists.io/public/alfred/workflows/text.alfredworkflow[Download] and double click to install.
  2. Use any of the following global hotkeys to activate: CONTROL + OPTION + COMMAND + o - Open selected URL in default browser. CONTROL + OPTION + COMMAND + d - View selected word in macOS dictionary. CONTROL + OPTION + COMMAND + t - View selected text as Large Type. CONTROL + OPTION + COMMAND + h - Syntax highlight selected code.

== Architecture

The following documents the workfow used to process all actions from Alfred.

image::https://www.alchemists.io/images/projects/pennyworth/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, please upgrade to Psych 4.0.1 for the fix.
  • 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.

== Community

Feel free to link:https://www.alchemists.io/community[join the commmunity] for discussions related to this project and much more.

== License

Read link:LICENSE.adoc[LICENSE] for details.

== Changes

Read link:CHANGES.adoc[CHANGES] for details.

== Credits