Historical errata for Build Awesome Command-Line Applications in Ruby

On note 1 In the footer: s/There/Their/

Introduction, first paragraph, third sentence: “Even then, you will hit a the limits…”. The “a” should be removed.

Top of page “…will leave with all the skills..” should be “…will leave you with all the skills…”

First paragraph “…make a command-line-interface than can parse…” should be “…make a command line interface that can parse…”

In the Introduction link pdf, “Even then, you will hit a the limits of productivity and efficiency” should be “Even then, you will hit the limits of productivity and efficiency”

Next to last paragraph, last sentence: “Users get to user…” should be “Users get to use…”

Last paragraph, first line: “…STDOUT, which a constant…” should be “…STDOUT, which is a constant…”

Last paragraph, last sentence: “…standard output stream is trivial.” should be “…standard error stream is trivial.”

First paragraph, second sentence: “…we saw our subject design decisions can be…” is garbled. Might have meant something like: “…we saw how subjective our design decisions can be…”?

First paragraph, example code: the regular expression “/^.\\..$/” does not strictly follow the intended first.last pattern but allows any number of periods; that is bill.george…sam is valid. A more restrictive regular expression that allowed only one period would be something like “/^[.]\\.[^.]$/”

3rd paragraph, last line: “…need a tool…” should be “…need is a tool….”

First paragraph, last line: “…machine-friend output.” should be “…machine-friendly output.”

Code section, erroneous “new line” flagging: line #2 is flagged as new but is not; line #5 is new but is not flagged.

3rd paragraph, heading: “User the standard…” should be “Use the standard…”

Missing space after comma. “career,the” Should be “career, the”

3rd paragraph, 3rd line: “might seem that simplest…” should be “might seem that the simplest…”

2nd paragraph, 2nd line: “is the same as it we’ve already…” should be “is the same as we’ve already…”

Text following 2nd example code: “We can now is todo’s…” should be “We can now use todo’s…”

4th para, 3rd line: “you may find thatthe name…” should be “you may find that the name…”

Top of page, item #4: “check the box to active it….” should be “check the box to activate it….”

3rd para, 4th line: “A scenario exercises on aspect…” should be “A scenario exercises an aspect…”

Paragraph following ‘rake features’ example, 1st line: “that the output of green…” should be “that the output is green…”

Code example that updates $: and paragraph following. Description states: “All we’re doing is placing our lib directory first in the load path…”. Actually, the code give ($: << File…" places the lib directory last in the load path, at the end of the array of entries.

Section 8.3, 1st line: “We’ve build our…” should be “We’ve built our…”

The link to the OptionParser documentation on the 7th note of the 2nd chapter is wrong. I have the correct link here but i not able to put in this description (i’m readind the mobi version, so i don’t have a page number. The number on the page field is the Location).

In the first sentence of the second paragraph, “Since our app will mostly be used for making daily backups, we’ll that its default behavior” is missing the word “make” (“we’ll make that its default behavior”).

“Building an Easy-to-Use Command Suite Interface” initially talks about “complete” command, but in examples and later it uses “done” command

Second and third examples for todo, don’t contain “new” command. I.e. we have:
todo -f /home/davec/work.txt “Refactor database”
todo -f /home/davec/work.txt “Do design review” -f

But should be

todo -f /home/davec/work.txt new “Refactor database”
todo -f /home/davec/work.txt new -f “Do design review”

“We’ll us it to bootstrap our app’s UI” but should be
“We’ll use it to bootstrap our app’s UI” (“use” instead of “us”)

In the second paragraph, third sentence, “programming” should be “programmer”.

In the last paragraph, “well” should be “we’ll”.

In the last paragraph, second sentence, the word “database” should be plural.

In the code listing, there should no longer be a “do” loop.

Change
(unparsed switches and flags
to
(unrecognized switches and flags

(Suggestion #2: Get rid of the parentheses. The sentence stands on its own.)

misspelled “myriad”

Suggest clarifying that when you use parentheses (grouping) in a regex to validate an argument, OptionParser will return an array (of the matching text and captured groups) and not the argument itself.

In code listing, in the declaration of hash “databases” there is a comma missing between :big_client and :small_client.

Problem 2: Task Management • 5
The second ‘else’ must be ‘end’.
Having also this error :
db_backup.rb:16:in `

I don’t think that this comparison with Perl is fair one. First, you could use `cpan XML::LibXML` to install module which is shorter than `gem install nokogiri`. Second - latest versions of CPAN.pm allow skipping all these questions at first time run. Third - there is `cpanminus` which is zero-conf and dependency free.

Last sentence on the page:

“maintenance of a a “quick hack” script you wrote that has lived long past"

“a” is duplicated.

“What Makes and Awesome Command-Line App”

‘if a switch is in the long-form (for example —foo), which turns “onF” some behavior’

“Global options affect the affect global behavior”

Probably the correct sentence is
“Global options affect the global behavior”

Documenting Command Line Arguments, first paragraph third sentence has double “is”.

“This is is called…”

The very first word:
Grapical user interfaces
It should be:
Graphical user interfaces

“as well as access to a myraid of other…”
should be myriad

I may be mistaken but following along I think the information about gem packaging rake tasks is a bit out of date.

In the text, the first snippet on pg 98 says RubyGems creates a task for you:

require ‘rake/gempackagetask’
spec = eval(File.read(‘todo.gemspec’))
Rake::GemPackageTask.new(spec) do |pkg|
end

However in following along i noticed that this has now been deprecated. rubygems/package_task is now used instead of gempackagetask, and I believe that the default package task is built in implicitly instead of being generated in your rake file.

Part of #48056:

In addition to rubygems/gempackagetask being deprecated in favor of rubygems/package_task, the rake task itself has been changed from “rake package” to “rake build”. In addition “rake install” is available to run the package task as well as add the packaged gem to your path.

Program at the end of section 1.1 is clearly wrong.

• Second ‘else’ on line 21 should be ‘end’
• databases.each do … end doesn’t make sense in this version.

Should I even continue reading?

On line 7:
become a better programming
Should be
become a better programmer

In the first line, first paragraph : “The second line tells chonto run” must be cron.

Fist line reads “The primary way to do give an”

6th line down reads “interface than can parse” which should be “interface that can parse”

“there was a some overlap”

Missing a space in this sentence: “For example, almost every gitcommand”

Figure title should be
Completed …
not
Competed …

You missed ’ (’ at ‘painthttps’

The shebang line of the (only) script listed on this page reads “Ruby” with an upper-case “R” instead of lower-case one:

#!/usr/bin/env Ruby

The shebang line at the top of db_backup_initial.rb reads “#!/usr/bin/env Ruby” instead of “#!/usr/bin/env ruby” (small ‘r’ on ruby instead of capital ‘R’).

Running it as is on my OS X machine gives the error “Ruby: no Ruby script found in input (LoadError)”

The code written to add a banner is:

executable_name = File.basename($PROGRAM_NAME)
opts.banner = “Usage: #{executable_name} [options] database_name”

This is however wrong, because opts is part of the loop. The correct code should read:

executable_name = File.basename($PROGRAM_NAME)
option_parser.banner = “Usage: #{executable_name} [options] database_name”

… and being executed of course after creating the object.

The error repeats in page 37. (PDF page 51).

Best wishes,
Guillermo

In the first line of the second code snippet, “Backup on or more…” should be “Backup one or more…”

In the second sentence of the third paragraph, “…which an instance…” should be “…which is an instance…”

the “rake test” fails on provide code. Need to update todo.gemspec removing the “.rb” from the todo.rb entries. This would also be a good place to add the “mocha” development dependency.

From a reader:

“Sorry if this is a “noob” question, but is there a reason for the redundant “def new_task(filename,task_names)” method on page 137-138?"

highling —> highline on first line of high line description

I find this book very hard to follow. When asked to implement the tab completion. It is unclear as to where the .bashrc file lives or if we need to create one. Furthermore, the page right after runs the command todo help -c. Even though, I have followed everything exactly as described. The command does not work. To run the command it is needed to run bin/todo help -c.

Please throughly explain the process here and also… please do not jump from one cli app to the other. It becomes very confusing.

In section 3.3 ‘Including a Man Page’, second paragraph, first sentence reads ‘(such as an explanation of the “iteration backup” concept, or why they username must be in “first.last” format)’

Should probably be “the username” or “their username” instead of “they username”

Suggest showing that flags and switches for GLI can have multiple forms (e.g., -n and —dry-run) like shown on your cheat sheet at github. I almost passed up trying GLI before learning that!

Typo “the” (or “its”) in “Documenting Everything Else”, the very last section of 3.4 “Writing Good Help Text and Documentation”, the first sentence:

“… and how its various options and arguments affect the its behavior.”

(The page number may be wrong since I only have the ebook)

In Section 8.2, p.1, “and the force us to organize” - “the” should be changed to “they” - so it should read “and they force us to organize”

“we how to do this” isn’t English!

For apps with the suffix .rb, you will need to associate the file exception

should read

For apps with the suffix .rb, you will need to associate the file extension

As currently foratted the following two items can be confusing. the ‘—blah’ version has the dashes split across a line break which is a little hard to read.

===-
Flag with re- quired argument
“-v”
“—verbose”
“—[no-]verbose”
“-n NAME” or “- -name NAME”

==—=—=
Flag with option- al argument
“-n [NAME]” or “- -name [NAME]”

`gli scaffold to-do new list done` creates a to-do directory but the given example output and further example commands are sans hyphen.

I don’t see where the documentation for the global -f flag is added. Back on page 28 the flag itself is added to the todo app and then on page 39 the help is printed and it’s already listed. It’s revised on this page (41), but I don’t see where `desc` and `arg_name` were added to global `flag :f`.

I’m writing a command line test wrapper that runs a test suite, does some other things and eventually needed to return the status of the tests suite in the form of a exit status. Page 59 shows how to exit with an error, but not simply exit with a designated return value (we don’t want a backtrace or error message). I was able to get what I need by issuing exit! –1 which did not throw an error in ruby 1.9.2. Others may find this info useful. Thanks for writing this by the way ^_

Code listings don’t show the needed require ‘aruba/cucumber’ in env.rb

First paragraph underneath the code example: “That’s all there is too it…”

“Are there any standard error codeS?” sidebar - MacOS X, based as it is on FreeBSD, also includes the sysexits recommendations. Might be useful to mention for Mac developers.

First paragraph doesn’t have a close parentheses. (See beginning of paragraph on previous page.)

The command ‘gli scaffold to-do new list done’ should read ‘gli scaffold todo new list done’. If the command is entered as is, you see errors when you try to run subsequent commands.

On the example of Format Output One Record per Line, Delimiting Fields:
$ todo list
1,Clean kitchen,2011-06-03 13:45,
2,Rake leaves,2011-06-03 17:31,2011-06-03 18:34
3,Take out garbage,2011-06-02 15:48,
4,Clean bathroom,2011-06-01 12:00,

The out here does not have the complete_flag as indicated in the code:
play_well/todo/bin/todo
complete_flag = completed ? “C” : “U”
printf(“%d,%s,%s,%s,%s\
”,index,name,complete_flag,created,completed)

In doc-sample be_helpful/db_backup/man/db_backup.1.ronn, under section “## DESCRIPTION”, second paragraph (top of page 45): “My default, `db_backup.rb’ makes a daily backup…” should read “By default, …”

(Beneath the sidebar “ARGF:…”, first paragraph: Missing period after “…standard input to the app)” before start of next sentence “In Ruby, the standard input is available via the constant STDIN.”

First sentence, first paragraph (after code example): “You can then view the RDoc be opening…” should read “You can then view the RDoc by opening…”

Last paragraph, second-to-last sentence: “This is a great alternative to hosing it yourself,…” should read “This is a great alternative to hosting it yourself…” [and may be the funniest typo in the whole book!]

2nd paragraph from bottom. “An alterantive…”, should be “alternative”.

if $?.exitstatus & 0b0002

Shouldn’t that be: 0b0010 ?

Hi.

“On UNIX systems, this is done via the first line of code, commonly referred to as the shebang. The shebang starts with a number sign (#), followed by an exclamation point (!), followed by the path to an interpreter that will be used to execute the program.”

All other definitions I found, including the Wikipedia definition linked to below this text box, define the ‘shebang’ (#!) as the first two bytes only, not the entire first line of code. Your two sentences seem to expand it to include the path, etc that follow the shebang.

Hope this is helpful.

Thanks,

WB

I typed in the code for db_backup_initial.rb.
Your instructions say to run it like this:
db_backup_initial.rb

1. => creates big_client_20110103.sql.gz
2. => creates small_client_20110103.sql.gz

When I do that, I get this:
(master)⚡ [1] % ruby db_backup_initial.rb ~/Developer/git/db_backup/bin
sh: mysqldump: command not found

I’m sure this has something to do with the fact that I’m not using mysqldump and have never used it before, so I don’t know if it is installed or not.

It would be good here to either make sure all the dependencies are intact, or, use another example that doesn’t have extraneous dependencies.

I’m looking forward to reading this book and learning, but right now, I’m frustrated because the very first piece of code doesn’t work.

Thanks.

Link to rdoc for OptionParser at the bottom of the page has changed to: ruby-doc.org/stdlib-1.9.3/libdoc/optparse/rdoc/OptionParser.html#method-i-make_switch

Re the sample file media.pragprog.com/titles/dccar/code/be_easy_to_use/db_backup/bin/db_backup.rb
The sample file contains all three versions of the “-u USER” block.
Running with the second (ArgumentError) version produces the desired result.
Running with the third (regex as argument) version simply fails when the username is not formatted correctly. There is no error message.
I’m a bit of a Ruby noob, so I may be missing something obvious, but how can you supply an error message for validation failure?

The URL to the documentation of OptionParser#make_switch leads to a 404.

davetron5000.github.com/gli/classes/GLI.html leads to 404

Not really a great nuisance, but it seems to me that it’s hard to make this work on my system with a dash in the command name:

(00:10:46) jaws@Ferintosh:~/Dropbox/Devel$ ruby —version
ruby 1.9.3p194 (2012-04-20 revision 35410) [x86_64-linux]
(00:10:49) jaws@Ferintosh:~/Dropbox/Devel$ gli scaffold to-do kom gikk new list entry hours done
Creating dir ./to-do/lib…
Creating dir ./to-do/bin…
Creating dir ./to-do/test…
Created ./to-do/bin/to-do
Created ./to-do/README.rdoc
Created ./to-do/to-do.rdoc
Created ./to-do/to-do.gemspec
Created ./to-do/test/default_test.rb
Created ./to-do/test/test_helper.rb
Created ./to-do/Rakefile
Created ./to-do/Gemfile
Created ./to-do/features
Created ./to-do/lib/to-do/version.rb
Created ./to-do/lib/to-do.rb
(00:10:55) jaws@Ferintosh:~/Dropbox/Devel$ cd to-do/
(00:10:57) jaws@Ferintosh:~/Dropbox/Devel/to-do$ bin/to-do
bin/to-do:16: syntax error, unexpected keyword_do_block
version To-do::VERSION
^
(00:11:04) jaws@Ferintosh:~/Dropbox/Devel/to-do$ gli
NAME
gli - create scaffolding for a GLI-powered application

SYNOPSIS
gli [global options] command [command options] [arguments…]

VERSION
2.4.1

….

If I call the command/script todo instead of to-do, it works.

In both the source code and the book, the line for the global option filename should be `flag [:f,:filename]` instead of just `flag :f`

The example of the book says that this should be displayed; “f, —filename=todo_file Path to the todo file (default: ~/.todo.txt)
” which can only happen if you include `flag [:f,:filename]`

Last paragraph: “but there’s a usability concern here” should be “but there’s an usability concern here”

First paragraph “cronto” should be “cron to”

“The second line tells cronto run our” should be “The second line tells cron to run our”

An easier approach is:

opts.banner += " database_name"

Type on the first line:

“My default…” should read “By default…”

“it allows you to execute arbitrary Ruby code, one command
and a time.”

Should read “…at a time”.