During the late fall of 2019, I was in the process of developing a small command-line interface (CLI) to make navigating between project directories faster. To do this, I was using Crystal’s
OptionParser API - a CLI building tool bundled with the standard library. However, I found myself unsatisfied with the amount of control it provided - it could not natively support subcommands (think
git add ...) or provide autocorrection (understanding
git ad as
git add). As a result, I ended up taking a substantial detour to develop Phreak, a CLI builder library which provided far more features than OptionParser did at the time.
Here’s an example from the documentation showing what Phreak can do.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 require "phreak" Phreak.parse! do |root| root.bind(word: "wifi", description: "Configure or control wireless connections.") do |wifi| wifi.banner = "Manage wireless connections. Invocation: cli wifi [subcommand]" wifi.bind(word: "status", description: "Get the current status of the modem.") do # Reponds to "nested wifi status" end wifi.bind(word: "set", description: "Set the the wifi state.") do |set| # Responds to "nested wifi set" end wifi.bind(word: "help", description: "display specific help about the `wifi` subcommand.") do |help| puts wifi end end root.bind(word: "help", description: "display this help menu.") do |help| puts root end end
To pull off semantics like that using (2019’s version of)
OptionParser, you would have had to manually detect the subcommands by parsing
ARGV, then delegate only the final step (parsing flags) to one of many
OptionParser instances. I was really happy with how much Phreak improved my productivity when working on test projects.
Conclusion & Phreak’s Future
Phreak is currently my most popular open source project - It has 25 stars on github at the time of writing, and I have heard from several people who have, at the very least, played around with it.
Although I’ll likely be the only one to tell you this, I also believe that Phreak has left it’s fingerprints on the Crystal ecosystem. RX14, a Crystal maintainer, left a comment sharing her support of how Phreak handled subcommands. She convinced me to open an issue on the Crystal repository, which garnered mostly positive reactions. That issue is open to this day, but RX14 and others have since rewritten OptionParser to use Phreak-like idioms, and to implement Phreak-like features. Of course, I do not claim to be the sole cause of this, and I certainly can’t attribute any of that skillful work to my hand. However, as a teenager dipping their toes into the waters of open source for the first time, I was really excited to have left an impression on a project that I love and believe in so dearly.
With a stronger Crystal standard library now in place, Phreak is now mostly irrelevant. Still, it will always have a special place in my heart. It helped my build my confidence with OSS, taught me how to document code for people I would never meet, and encouraged me to work on bigger and better things.