Awesome Command Line Applications in Ruby

Ruby

David Copeland

@davetron5000

#command-line-interface-cli

#ruby

#behavior-driven-development-bdd

#testing

#rubygems

#user-experience-ux

Awesome Command Line Applications in Ruby

by David Copeland

The video titled Awesome Command Line Applications in Ruby, presented by David Copeland at the LoneStarRuby Conf 2010, focuses on creating effective command-line applications using the Ruby programming language. Copeland emphasizes the importance of usability, clear outputs, and the significance of adhering to UNIX conventions in command line tools.

Key points discussed throughout the video include:
- Understanding Command-Line Outputs: Misleading outputs and error codes often lead to confusion, e.g., UNIX exit codes where 0 indicates success, complicating error detection.
- Subversion as an Example: Copeland uses Subversion to highlight how effective command line applications handle conflicts by providing straightforward outputs, allowing users to resolve issues quickly without excessive interaction.
- UNIX Output Philosophy: The expectation that the output of one program can be used as input for another underlines the need for simple, machine-readable formats. Developers should avoid cluttering output, ensuring it is clear and parsable.
- Enhancing User Experience with Cucumber: Cucumber is presented as an example of a command line tool that provides a pleasant user experience through visual elements like colors, while maintaining standard outputs for automated processes.
- Return Codes and Debugging: Emphasis is placed on using standard error for debug information and maintaining proper return codes to represent error states.
- Ruby Features for Command-Line Applications: Copeland discusses Ruby modules like FileUtils for file operations, and the system and exec methods for executing commands and capturing outputs effectively.
- Option Parsers for User-Friendly Interfaces: The video covers how to utilize Ruby’s built-in option parser and other libraries like Trollop for managing command-line options clearly and succinctly.
- Frameworks for Scalable Applications: Several frameworks including Commander and Thor are mentioned for building robust command line applications, focusing on maintaining organized help messages and outputs as applications grow.

The conclusions drawn emphasize that command line applications should be designed with the same diligence as any software application, focusing on user experience and efficient interactions. Key takeaways include:
- Prioritize user experience in command line utilities.
- Embrace the conventions of UNIX for better integration and usability.
- Utilize Ruby’s strengths to create effective, maintainable command line tools that foster collaboration within the Ruby community.
- Encourage the development of user-friendly interfaces that reduce complexity and enhance usability.

00:00:10.010 On the next page, there’s more information. There are more enterprising-looking outputs that, frankly, are completely meaningless. However, we do see an error buried here if you look very closely. Fortunately, if you use Maven more than once, you'll know that this error always happens and it doesn't matter; just sort of ignore it. Finally, we get to the results of what we're trying to do, which is this quasi-human-readable format. You can always tell a command-line user interface failure by these arbitrary lines of dashes, as it is clear the developer could agree with you. It's outputting some status here, and it's hard to figure out what's going on. In this case, the test fails, so we see the build failure right there.

00:00:30.210 This is not very good. Unfortunately, in UNIX, an exit code of 0 means success, so a build failure means success. This makes it very difficult to describe anything in a larger system. The opposite of that is Subversion. Subversion is not my favorite version control system, but it's a pretty awesome command line application. Here’s some output where I've got some conflicts with some files, and visually, you can imagine having, say, 20 of them; you’ve got to sort this out. I’m way too lazy to copy and paste all that stuff, and since the version controls play well with others, I can gradually use tactics and commands so that I can list out what's in conflict. This helps get rid of those stupid conflicts, so I have the entire list of files to understand where I can go fix everything.

00:01:04.949 After I fix everything, I can then say I resolved the conflicts, and we're good to go. The creators of Subversion didn't have a meeting about how to get a list of conflicted files to go to the user interface and then get back to the result. What they did is they made their application play well with others so that it could be used in ways that were not intended without having to jump through a lot of hoops. This is all kind of boiling down to the UNIX way of interacting. In fact, this is best summarized in the quote that we expect the output of every program to become an input for another, as yet unknown program. Don't clutter the output—we expect information in plain text or binary formats and we don’t insist on interactive input. Many of the programs you click today have a lot of rules and what this means specifically is that your input and output should be machine parsable and clear.

00:02:11.110 You should think of formats like comma-delimited or tab-delimited. For example, the Maven lock file has info in square brackets, which not only contains special characters but also makes it harder to process. You want to make things simple for whatever your application does. It should output other things that can be easily handled. One thing to remember is that it's very easy using UNIX tools or a small amount of Ruby code to parse that out and deal with it. In terms of exit codes, I believe everything has a return code of 0 if everything's good. If anything fails, you should make sure to provide a return code that represents the error condition. If you need to message the user about errors that occurred, or to provide debug information, use standard error because you can redirect that wherever you want — be it a log file or elsewhere. Whatever output your application produces should go to standard output.

00:03:10.060 This might seem obvious, but there are many command line applications that do not do things this way. Here’s a little bit of Ruby code: it's the world's most inflexible graphic. We're only looking for things with 'foo' in the line; we print it out and keep a count. We helpfully send our debugging information to standard error so you can redirect it to where you want. In our case, if we don’t find 'foo' it is considered an error, returning 1, and we return 0 if everything's good. Checking here, you can see that there are only about three extra lines of code needed to make it easily interoperable with other programs. We're playing well with others through the UNIX way that I've described.

00:05:04.169 Now, I’m going to talk about the Cucumber way, which is a tool for behavior-driven design. Cucumber is the first app that I can say has a real user experience, and it doesn't irritate the user. There are many heavily bearded UNIX aficionados who are horrified by it introducing colors and bold text into their command prompts, but I think Cucumber does a really good job here. You can see, for example, that the things that aren't completed are in red, and the things that are broken are also in red, while yellow signifies unfinished tasks. When everthing is running correctly, you are rewarded with a lovely green display. It made me so happy the first time I saw it — it's possible to have a good user experience in command line applications. It’s completely fine to consider this, provided it fits the situation.

00:05:40.000 What this means is that we're still having our exit codes; we don’t mess around with that. We still want to have a user-friendly option. You might say, 'Well, I need to run this in cron', and cron doesn’t care about bold texts. We can provide normal output which will be useful, while still including our colored output for standard interaction. Here are a couple of Ruby gems that make it really easy to add methods to strings to create all kinds of fancy colors and bold text in command line applications. However, you have to fully embrace this way of working; you cannot just sprinkle a few colors here and there. It should be a complete user experience, which is essential for effective usability.

00:06:04.889 If you don't embrace the command line culture then nothing will be much clearer. But, if your application is complex enough to warrant a real user experience, Ruby has very easy tools to achieve this. Remember that everything I have mentioned so far can be used easily to create great command-line applications in Ruby. You might wonder why we should care about this; well, there are really easy ways to interact with the system, as we’ve seen. The system provides methods like 'system' and 'exec' which allows you to run internal functions and return the output as a string. This way, you can check the exit code and if everything is in order, it enhances the functionality.

00:06:49.890 Furthermore, the FileUtils module allows you to work with files in a way that resembles UNIX command line tools, facilitating the creation of system automation scripts that work across platforms. This means you won’t need to worry if you're working on Windows or UNIX; your code can run seamlessly without issues. Ruby is a great language in general, equipped with many higher-level abstractions for developing applications, be it web, desktop or mobile apps. With all the object-oriented programming lessons you’ve learned from regular programming, you can easily apply them to your Ruby command-line scripts.

00:08:16.439 The process of packaging and distributing gems is straightforward, particularly for more sophisticated tasks beyond basic tasks like managing version control. The startup time remains minimal without complicated overheads. Recalling the earlier mention of Maven and its outputs, you will see the ease it brings during testing and commitment checks. It is worth noting that the Ruby community thrives on command line tools. Each gem you obtain comes with command-line tools, which makes it a vital component of Ruby's ethos.

00:09:38.210 So how can we achieve this smoothly? For simple applications, the option parser might be a familiar tool to many. It is included with Ruby and is available in various libraries. The RDoc serves as a wonderful aid in demonstrating its usage. For instance, we can start it with a safe option parser by initializing a new instance and passing a block that allows us to specify options. The expected behavior can follow along seamlessly, giving the expected output as well as a user-friendly command line interface. The parser allows for capturing arguments, along with error management and feedback, making sure the user gets a proper interface without any hassle.

00:10:44.960 Continuing with the example mentioned, we can set up the option parser with ease. Users may use various styles or syntax for passing flags and additional details. While option parser is incredibly easy to use, it also returns clear results that can be understood effortlessly. However, when it comes to creating more complex command-line applications, such as having multiple subcommands with numerous options, the process becomes slightly convoluted.

00:11:17.760 Another option for these implementations is Trollop, which simplifies the setting of options to just one line per command. It does not require a gem installation, making it a breeze for distribution in scripts. Although this approach makes it easier, it can be a bit verbose because it isn't built into the standard library. When we look at more sophisticated command-line style applications, we see how the subcommands should be constructed. This goes hand in hand with ensuring that the help messages are maintained appropriately, similar to how they are handled in built-in applications.

00:12:12.580 It’s essential to manage the expected output effectively, with attention to every detail. For example, a command like ‘showoff’ can have subcommands that are described succinctly with the help messages combined. Unfortunately, hand-jamming entire command messages becomes complex, resulting in an application that is difficult to extend as it matures. As your application grows, the need for help messages and error management will require more organized handling.

00:12:49.420 These could be simplified if you implement frameworks designed for clearer command-line implementation. I found myself forced to create a better system after noticing the numerous hacks around — I ended up designing a custom command parser, Goli, which is meant to streamline command-line interface experiences. It helps to polish user interactions and reduce developmental work in synthesizing command outputs and help embedded functionalities effectively.

00:13:01.680 In this design, we achieve clean outputs, and through proper structure frameworks with help sections that have clear formatting. When the user requests help on a particular command, it generates the proper usage guidelines on demand. This system allows for different command inputs and offers users an easy way to navigate through if they need to look up commands or available options in detail.

00:14:12.650 Furthermore, if ever, we need a configuration file, this can be user-specific so that users can set their own default values for options or specify desired defaults. This eases the initial setup or when updating existing applications to ensure they comply with user standards. Continuing on, if I had searched a little more effectively a year ago, I would have discovered that commander offers similar functionalities in a user-friendly manner.

00:15:01.990 Commander does not only cover the command interface but is designed with many dependencies that would benefit from community input and support. It allows you to interact across different gems that may be necessary while creating command line applications. Other notable frameworks like Thor provide robust methodologies essential to building scalable command line applications due to its capacity to execute code and maintain functionality across implementations.

00:16:25.239 In conclusion, the main point is that you should approach the development of your command line applications with the same professionalism, rigor, and design considerations you would apply to regular applications. Creating user-friendly applications is not as laborious as it appears, especially with Ruby, which offers many conveniences to elevate your applications. It is all about cultivating a user experience that will feel rewarding not only for you as the developer but also for the future user interacting with these applications. In doing so, you equip your applications to work better within shared environments, ensuring other developers can use them without encountering unnecessary barriers.

00:17:36.320 If you focus on building clean and efficient command line tools, you can greatly decrease future difficulties. The key takeaway from this talk is to embrace the opportunities Ruby provides to enhance your application development processes, crafting efficient, user-focused, and maintainable tools that can be integrated seamlessly with other systems. This presentation will reinforce the value of considerate development practices and empower you to not only build effective command line applications but also foster a community spirit among Ruby users. Thank you for your time.

00:20:03.000 And now onto the question and answer session after the presentation. It's a chance for further exploration of the topics discussed, where participants can pose inquiries or elaborate on particular concepts introduced during the talk. This portion can deepen understanding and engagement, making the experience more interactive and rewarding for everyone involved. I look forward to hearing your insights and questions!

LoneStarRuby Conf 2010