Build Awesome Command Line Applications in Ruby 2

Speak directly to your system. With its simple commands, flags, and parameters, a well-formed command-line application is the quickest way to automate a backup, a build, or a deployment and simplify your life. With this book, you’ll learn specific ways to write command-line applications that are easWhat Readers are saying aboutBuild Awesome Command-Line Applications in RubySome command-line applications save time and are a joy to use. Others just makeyou want to tear your hair out. David Copeland has written a guide to writing thekind of command-line apps that will make your users want to hug you. Fromproviding a humane command-line interface, to being self-documenting, to inte-grating seamlessly with the rest of the command-line universe-this book willshow you how to take your scripts irom adequate to awesomeAvdi grimmRuby developer, author, Exceptional ruby, and blogger, Virtuous CodeThis book proves that text mode is not the just the domain of batch scripts andglue code. Beyond the extensive survey of current Ruby ClI tools, David bringsan unmatched focus on user experience and testing. Every full-stack developershould learn how to build the kinds of apps covered in this bookWynn NetherlandCTO, Pure Charityi know of no other ruby book that covers the content in this useful work, espe-cially with its eye toward making ruby command-line applications better citizensNoel RappinSenior engineer at Groupon and author, Rails Test PrescriptionsThis well-written book teaches ideas that are really important that ruby is apowerful language for writing command-line tools; that ClI tools, unlike GUI toolscan be combined in an infinite number of ways that the effort required to automatesmall recurrent tasks pays off; and that there are time-tested best practices forsucceeding with command-line tool development. Not only are the scripts in thisvolume awesome. so is the bookStaffan NotebergAuthor, Pomodoro Technique IlustratedI want a few people on my team to have this book now. I especially cant wait toget this in the hands of our software lead, who's a whiz at shell scripts and wouldbe delighted to see how much easier and more reliable option parsing is in RubyIan DeesRuby developer and coauthor, Using JRubyThis book teaches you how to write command-line tools your mother would beproud of.Matt wynneIndependent consultant programmer, coach, and author, The Cucumber bookBuild awesome command-LineApplications in Ruby 2Control Your Computer, Simplify Your LifeDavid copelandThe Pragmatic BookshelfDallas, Texas. Raleigh, North CarolinaPragmaticBookshelfMany of the designations used by manufacturers and sellers to distinguish their productsare claimed as trademarks. Where those designations appear in this book, and The PragmaticProgrammers, LLC was aware of a trademark claim, the designations have been printed ininitial capital letters or in all capitals. The Pragmatic Starter Kit, The Pragmatic Programmer,Pragmatic Programming, Pragmatic Bookshelf, PragProg and the linking g device are trademarks of The Pragmatic Programmers, LLCEvery precaution was taken in the preparation of this book. However, the publisher assumesno responsibility for errors or omissions, or for damages that may result from the use ofinformation (including program listings)contained hereinOur Pragmatic courses, workshops, and other products can help you and your team createbetter software and have more fun. For more information, as well as the latest Pragmatictitlespleasevisitusathttp://pragprog.comThe team that produced this book includesFahmida Y. Rashid (project managerDavid J. Kelly (typesetterJanet Furlow (producer)Juliet Benda (rights)Ellie Callahan(support)Copyright o 2013 The Pragmatic Programmers, LLCAll rights reservedNo part of this publication may be reproduced, stored in a retrieval system,transmitted, in any form, or by any means, electronic, mechanical, photocopyingrecording, or otherwise, without the prior consent of the publisherrinted in the United States of americaSBN-13:978-1-937785-75-8Encoded using the finest acid-free high-entropy binary digitsBook version P1.0-November 2013ContentsIntroduction1. Have a clear and concise Purpose1.1 Problem 1: Backing Up Data1.2 Problem 2: Managing Tasks1. 3 What Makes an Awesome Command-Line App1. 4 Moving on112. Be Easy to Use132.1 Understanding the Command Line: Options, Argumentsand commands2.2 Building an Easy-to-Use Command-Line Interface182.3 Building an Easy-to-Use Command-Suite Interface232.4 Moving On313. Be Helpful333.1 Documenting a Command-Line Interface333.2 Documenting a Command suite383.3 Including a man Page423.4 Writing Good Help Text and Documentation473.5 Moving on514. Play Well with Others534.1 USing Exit Codes to Report Success or Failure544.2 USing the Standard Output and Error StreamsAppropriately594.3 Formatting Output for Use As Input to AnotherProgram634.4 Trapping Signals Sent from Other Apps674.5 Moving On69Contents·5. Delight Casual Users715.1 Choosing Names for Options and Commands5.2 Choosing Default Values for Flags and Arguments765.3 Deciding Default Behavior825. 4 Moving on866. Make Configuration Easy896.1 Why External Configuration?896.2 Reading External Configuration from Files906.3 USing Configuration Files with Command Suites946.4 Design Considerations When Using Configuration986.5 Moving on997. Distribute Painlessly1017.1 Distributing with Ruby Gems1017.2 Distributing Without Ruby Gems1087.3 Collaborating with other Developers1107.4 Moving On115Test Test. Test1178.1 Testing User Behavior with Acceptance Tests1188.2 Testing in Isolation with Unit Tests1318.3 A Word about Test-Driven Development1388. 4 Moving on1399. Be Easy to Maintain1419. 1 Dividing Code into Multiple files1419.2 Designing Code for Maintainability1469.3 Moving On15110. Add Color, Formatting, and Interactivity15310.1 Adding color Using ansi escape sequences15410.2 Formatting Output with Tables15910.3 Providing Interactive User Input with readline16410.4 Moving on173Al. Common command-Line gems and libraries175Al.1 Alternatives for Simple Command-Line Apps176a1.2 Alternatives for Command suites184Al.3 Other relevant libraries189A2. Bibliography193Index195IntroductionGraphical user interfaces (GUIs) are great for a lot of things; they are typicallymuch kinder to newcomers than the stark glow of a cold, blinking cursor.This comes at a price: you can get only so proficient at a gui before you haveto learn its esoteric keyboard shortcuts. Even then, you will hit the limits ofproductivity and efficiency. GUIs are notoriously hard to script and automateand when you can, your script tends not to be very portableThis is all beside the point; we are software developers, and we write programsWhat could be more natural than using code to get our work done? Considerthe following command sequencecd -/Projects/clichapter2. mdWhile these two commands might strike you as opaque, they are a highlyefficient means of editing a fileFor most of my career, the command line meant a uniX shell, like bash. Thebash shell provides some basic built-in commands, as well as access to manyother standard (and nonstandard) commands that are shipped with any UNIXsystem. These commands are single-purpose, require no user interactionand come with easy-to-use(but hard-to-learn user interfaces. These attributeslet you piece them together in a near-infinite number of ways. automatingsophisticated behavior, performing complicated analysis, and parsing a myriadof text files can be done easily and expediently. This was life for me early onin my career. And it was goodThen, in the mid-1990s, as Java grew in popularity, the idea of stringingtogether UNIX command-line utilities to get things done came to be seen asarchaic. Java programs eschewed simple text-based configuration and file-based input/output(/O) for complex hierarchies of XMl driven by RPC andHttp I/o. This allowed for very sophisticated systems to be built and Guitools sprang up to abstract away the complexity of building and configuringthese systems. Even the act of writing and building code got swallowed upreport erratum. discussntroduction·viby ever more complex integrated development environments (IDEs). Thesimplicity of the command line was starting to get lostThe problem is, there are too many tasks that dont fit the model of thesetools; it,'s just too darn easy to go out to the shell and get things done. So,while i never bought into the concept that IDEs and sophisticated gui toolswere an advancement of the command line, I made peace with the facts oflife and settled into a comfortable pattern: Java was for "real"code, and thecommand line (along with Perl and ruby was for automation, one-off scriptsand other things that helped me get repetitive things done quicklyIn the mid 2000s, I started to take notice of Ruby, Rails, and the amazingcommunity built up around these tools. To my surprise (and delight), almosteverything was command-line driven. Dynamic languages like Ruby dontlend themselves too well to IDEs (some even argue that an IdE makes nosense for such languages), and the burgeoning developer community wasnton the radar of any top-tier tool makers The community embraced the com-mand line and created command-line applications for everything. AlthoughPerl had been doing this for years, this was the first time I'd noticed such astrong embrace of the command line in the"post-Java"worldWhat was more interesting was the taste and polish put into these commandline apps. Most featured a full-blown help system, often with command-basednavigation of features, but still stayed true to the"UNIX way"of simplicityand interoperability. Take gem, for example. It's the command used to installother Ruby apps and libraries into your system:s gem helpRuby Gems is a sophisticated package manager for Ruby. This is abasic help message containing pointers to more informationsagegem -h/--helgem -v/--versiorgem command [arguments.] [options.]Examplesgem install rakegem list --localgem build package. gemspecgem help installFurther helpgem help commandslist all gem commandsgem help examplesshow some examples of usagegem help platformsshow information about platformsreport erratum. discuss