Build awesome command-line applications in Ruby : control your computer, simplify your life

As Ruby pro David Copeland explains, writing a command-line application that is self-documenting, robust, adaptable and forever useful is easier than you might think. Ruby is particularly suited to this task, since it combines high-level abstractions with "close to the metal" system interaction wrapped up in a concise, readable syntax. Moreover, Ruby has the support of a rich ecosystem of open-source tools and libraries. Ten insightful chapters each explain and demonstrate a command-line best practice. You'll see how to use these tools to elevate the lowliest automation script to a maintainable, polished application. You'll learn how to use free, open source parsers to create user-friendly command-line interfaces as well as command suites. You'll see how to use defaults to keep options simple for everyday users, while giving advanced users options for more complex tasks. There's no reason a command-line application should lack documentation, whether it's part of a help command or a man page; you'll find out when and how to use both. Your journey from command-line novice to pro ends with a look at valuable approaches to testing your apps, and includes some fun techniques for outside-the-box, colorful interfaces that will delight your users. With Ruby, the command line is not dead. Long live the command line. **What You Need:** All you'll need is Ruby, and the ability to install a few gems along the way. Examples written for Ruby 1.9.2, but 1.8.7 should work just as well. Cover......Page 1 Table of Contents......Page 6 Introduction......Page 8 How This Book Is Organized......Page 10 What You'll Need......Page 12 Conventions Used in the Book......Page 13 Online Resources......Page 15 Acknowledgments......Page 16 1. Have a Clear and Concise Purpose......Page 18 Problem 1: Backing Up Data......Page 19 Problem 2: Managing Tasks......Page 22 What Makes an Awesome Command-Line App......Page 27 Moving On......Page 28 Understanding the Command Line: Options, Arguments, and Commands......Page 29 Building an Easy-to-Use Command-Line Interface......Page 34 Building an Easy-to-Use Command-Suite Interface......Page 39 Moving On......Page 47 Documenting a Command-Line Interface......Page 48 Documenting a Command Suite......Page 53 Including a Man Page......Page 57 Writing Good Help Text and Documentation......Page 62 Moving On......Page 65 4. Play Well with Others......Page 67 Using Exit Codes to Report Success or Failure......Page 68 Using the Standard Output and Error Streams Appropriately......Page 73 Formatting Output for Use As Input to Another Program......Page 77 Trapping Signals Sent from Other Apps......Page 82 Moving On......Page 83 5. Delight Casual Users......Page 85 Choosing Names for Options and Commands......Page 86 Choosing Default Values for Flags and Arguments......Page 90 Deciding Default Behavior......Page 96 Moving On......Page 100 Why External Configuration?......Page 102 Reading External Configuration from Files......Page 103 Using Configuration Files with Command Suites......Page 107 Design Considerations When Using Configuration......Page 111 Moving On......Page 112 Distributing with RubyGems......Page 113 Distributing Without RubyGems......Page 120 Collaborating with Other Developers......Page 121 Moving On......Page 127 8. Test, Test, Test......Page 128 Testing User Behavior with Acceptance Tests......Page 129 Testing in Isolation with Unit Tests......Page 142 Moving On......Page 150 Dividing Code into Multiple Files......Page 151 Designing Code for Maintainability......Page 156 Moving On......Page 161 10. Add Color, Formatting, and Interactivity......Page 162 Adding Color Using ANSI Escape Sequences......Page 163 Formatting Output with Tables......Page 168 Providing Interactive User Input with readline......Page 173 Moving On......Page 182 A1. Common Command-Line Gems and Libraries......Page 183 Alternatives for Simple Command-Line Apps......Page 184 Alternatives for Command Suites......Page 192 Other Relevant Libraries......Page 197 A2. Bibliography......Page 200 Index......Page 201 Cover 1 Table of Contents 6 Introduction 8 How This Book Is Organized 10 Who This Book Is For 12 What You'll Need 12 Conventions Used in the Book 13 Online Resources 15 Acknowledgments 16 1. Have a Clear and Concise Purpose 18 Problem 1: Backing Up Data 19 Problem 2: Managing Tasks 22 What Makes an Awesome Command-Line App 27 Moving On 28 2. Be Easy to Use 29 Understanding the Command Line: Options, Arguments, and Commands 29 Building an Easy-to-Use Command-Line Interface 34 Building an Easy-to-Use Command-Suite Interface 39 Moving On 47 3. Be Helpful 48 Documenting a Command-Line Interface 48 Documenting a Command Suite 53 Including a Man Page 57 Writing Good Help Text and Documentation 62 Moving On 65 4. Play Well with Others 67 Using Exit Codes to Report Success or Failure 68 Using the Standard Output and Error Streams Appropriately 73 Formatting Output for Use As Input to Another Program 77 Trapping Signals Sent from Other Apps 82 Moving On 83 5. Delight Casual Users 85 Choosing Names for Options and Commands 86 Choosing Default Values for Flags and Arguments 90 Deciding Default Behavior 96 Moving On 100 6. Make Configuration Easy 102 Why External Configuration? 102 Reading External Configuration from Files 103 Using Configuration Files with Command Suites 107 Design Considerations When Using Configuration 111 Moving On 112 7. Distribute Painlessly 113 Distributing with RubyGems 113 Distributing Without RubyGems 120 Collaborating with Other Developers 121 Moving On 127 8. Test, Test, Test 128 Testing User Behavior with Acceptance Tests 129 Testing in Isolation with Unit Tests 142 A Word About Test-Driven Development 150 Moving On 150 9. Be Easy to Maintain 151 Dividing Code into Multiple Files 151 Designing Code for Maintainability 156 Moving On 161 10. Add Color, Formatting, and Interactivity 162 Adding Color Using ANSI Escape Sequences 163 Formatting Output with Tables 168 Providing Interactive User Input with readline 173 Moving On 182 A1. Common Command-Line Gems and Libraries 183 Alternatives for Simple Command-Line Apps 184 Alternatives for Command Suites 192 Other Relevant Libraries 197 A2. Bibliography 200 Index 201 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. As Ruby pro David Copeland explains, writing a command-line application that is self-documenting, robust, adaptable and forever useful is easier than you might think. Ruby is particularly suited to this task, since it combines high-level abstractions with "close to the metal" system interaction wrapped up in a concise, readable syntax. Moreover, Ruby has the support of a rich ecosystem of open-source tools and libraries. Ten insightful chapters each explain and demonstrate a command-line best practice. You'll see how to use these tools to elevate the lowliest automation script to a maintainable, polished application. You'll learn how to use free, open source parsers to create user-friendly command-line interfaces as well as command suites. You'll see how to use defaults to keep options simple for everyday users, while giving advanced users options for more complex tasks. There's no reason a command-line application should lack documentation, whether it's part of a help command or a man page; you'll find out when and how to use both. Your journey from command-line novice to pro ends with a look at valuable approaches to testing your apps, and includes some fun techniques for outside-the-box, colorful interfaces that will delight your users. With Ruby, the command line is not dead. Long live the command line. What You All you'll need is Ruby, and the ability to install a few gems along the way. Examples written for Ruby 1.9.2, but 1.8.7 should work just as well. We live inside the GUI, but there's a more direct way to bypass the windows and menus of modern consoles and 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.