methadone 1.0.0.rc2 → 1.0.0.rc3

data/tutorial/3_ui.md

@@ -0,0 +1,349 @@
+# UI
+
+We're taking an [outside-in][outsidein] approach to our app.  This means that we start with the user interface, and work our way
+down to make that interface a reality.  I highly recommend this approach, since it forces you to focus on the user of your app
+first.   Doing this will result in an app that's easier to use, and thus easier for you to maintain and enhance over time.
+
+Before we dive into our Cucumber features, let's take a moment to think about how our app might work.  Essentially, we want it to
+clone a git repository somewhere on disk, and then symlink all of those files and directories in the top level of that repo into
+our home directory.  If we did this in `bash` on the command line, it might be something like this:
+
+```sh
+$ cd ~
+$ git clone git@github.com:davetron5000/dotfiles.git
+$ for file in `ls -a dotfiles`; do
+> ln -s dotfiles/$file .
+> done
+```
+
+It's worth understanding why we don't just make this entire thing a `bash` script.  Our app is going to need more smarts than the
+above code: for example, it will need to be able to check if the repo is cloned already, and update it instead of cloning.  It
+will need good error handling so the user knows if they did something wrong.  It might need more complex logic as we use the app
+over time.  Implementing these in `bash` is painful.  `bash` is not a very powerful language, and we'll quickly hit a wall.
+Although `bash` is "close to the metal", we'll see that Ruby + Methadone can provide a *very* similar programming experience.
+
+Now, let's think about how our app will work.  We can summarize our app's interface as having two main features at this point:
+
+* It should accept a required argument that is the URL of the repo to clone
+* It should otherwise be a well-behaved and polished command-line app:
+  * It should have online help.
+  * Getting help is not an error and the app should exit zero when you get help.
+  * There should be a usage statement for the app's invocation syntax.
+  * The app should document what it does.
+  * The app should indicate what options and arguments it takes.
+
+Aruba and Methadone provide all the steps we need to test for these aspects of our app's user interface.  Here's the feature
+we'll use to test this.  We can replace the contents of `features/fullstop.feature` with this:
+
+```cucumber
+Feature: Checkout dotfiles
+  In order to get my dotfiles onto a new computer
+  I want a one-command way to keep them up to date
+  So I don't have to do it myself
+
+  Scenario: Basic UI
+    When I get help for "fullstop"
+    Then the exit status should be 0
+    And the banner should be present
+    And there should be a one line summary of what the app does
+    And the banner should include the version
+    And the banner should document that this app takes options
+    And the banner should document that this app's arguments are:
+      |repo_url|which is required|
+```
+
+This scenario describes getting help for our app and the basic user interface that we need.  This is how we "test-drive" the
+development of the user interface portion of our app.  Let's run the scenario and see what happens.
+
+```sh
+$ rake features
+Feature: Checkout dotfiles
+  In order to get my dotfiles onto a new computer
+  I want a one-command way to keep them up to date
+  So I don't have to do it myself
+
+  Scenario: Basic UI
+    When I get help for "fullstop"
+    Then the exit status should be 0
+    And the banner should be present
+    And there should be a one line summary of what the app does
+      expected "v0.0.1" to match /^\w\w+\s+\w\w+/ (RSpec::Expectations::ExpectationNotMetError)
+      features/fullstop.feature:10:in `And there should be a one line summary of what the app does'
+    And the banner should include the version
+    And the banner should document that this app takes options
+    And the banner should document that this app's arguments are:
+      | repo_url | which is required |
+
+Failing Scenarios:
+cucumber features/fullstop.feature:6
+
+1 scenario (1 failed)
+7 steps (1 failed, 3 skipped, 3 passed)
+0m0.126s
+rake aborted!
+Cucumber failed
+
+Tasks: TOP => features
+(See full trace by running task with --trace)
+```
+
+We have a failing test!  Note that cucumber knows about all of these steps; between Aruba and Metahdone, they are all already
+defined.  We'll see some custom steps later, that are specific to our app, but for now, we haven't had to write any testing code,
+which is great!
+  
+You'll also notice that some steps are already passing, despite the fact that we've done no coding.  Also notice that
+cucumber didn't complain about unknown steps.  Methadone provides almost all of these cucumber steps for us.  The rest are
+provided by Aruba.  Since Methadone generated an executable for us when we ran the `methadone` command, it already provides the
+ability to get help, and exits with the correct exit status.
+
+Let's fix things one step at a time, so we can see exactly what we need to do.  The current scenario is failing because our app
+doesn't have a one line summary.  This summary is important so that we can remember what the app does later on (despite how
+clever our name is, it's likely we'll forget a few months from now and the description will jog our memory).
+
+Let's have a look at our executable.  A Methadone app is made up of four parts: the setup where we require necessary libraries, a "main" block containing the primary logic of our code, a block of code that declares the app's UI, and a call to `go!`, which runs our app.
+
+```ruby
+#!/usr/bin/env ruby
+
+# setup
+require 'optparse'
+require 'methadone'
+require 'fullstop'
+
+class App
+  include Methadone::Main
+  include Methadone::CLILogging
+
+# the main block
+  main do
+
+  end
+
+# declare UI
+  version Fullstop::VERSION
+
+  use_log_level_option
+
+# call go!
+  go!
+end
+```
+
+There's not much magic going on here; you could think of this code as being roughly equivalent to:
+
+```ruby
+def main
+end
+
+opts = OptionParser.new
+opts.banner = "usage: $0 [options]\n\nversion: #{Fullstop::VERSION}"
+opts.parse!
+
+main
+```
+
+We'll see later that Methadone does a lot more than this, but this should help you understand the control flow.  We now need to
+add a one-line description for our app.
+
+In a vanilla Ruby application, we'd use the `banner` method of an `OptionParser` to add this description (much as we do with the
+version in the above, non-Methadone code).  Methadone actually manages an
+`OptionParser` instance that we can use, available via the `opts` method.  We could call `banner` on that to set our description, but Methadone provides a convenience method to do it for us: `description`.
+
+`description` takes a single argument: a one-line description of our app.  Methadone will then include this in the online help 
+output of our app when the user uses `-h` or `--help`.  We'll add a call to it in the "declare UI" portion of our code:
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'optparse'
+require 'methadone'
+require 'fullstop'
+
+class App
+  include Methadone::Main
+  include Methadone::CLILogging
+
+  main do 
+  end
+
+  version Fullstop::VERSION
+
+  # vvv
+  description 'Manages dotfiles from a git repo'
+  # ^^^
+
+  use_log_level_option
+
+  go!
+end
+```
+
+Now, let's run our scenario again:
+
+```sh
+$ rake features
+Feature: Checkout dotfiles
+  In order to get my dotfiles onto a new computer
+  I want a one-command way to keep them up to date
+  So I don't have to do it myself
+
+  Scenario: Basic UI
+    When I get help for "fullstop"
+    Then the exit status should be 0
+    And the banner should be present
+    And there should be a one line summary of what the app does
+    And the banner should include the version
+    And the banner should document that this app takes options
+    And the banner should document that this app's arguments are:
+      | repo_url | which is required |
+      expected "Usage: fullstop [options]\n\nManages dotfiles from a git repo\n\nv0.0.1\n\nOptions:\n        --version                    Show help/version info\n        --log-level LEVEL            Set the logging level (debug|info|warn|error|fatal)\n                                     (Default: info)\n" to include "repo_url"
+      Diff:
+      @@ -1,2 +1,11 @@
+      -["repo_url"]
+      +Usage: fullstop [options]
+      +
+      +Manages dotfiles from a git repo
+      +
+      +v0.0.1
+      +
+      +Options:
+      +        --version                    Show help/version info
+      +        --log-level LEVEL            Set the logging level (debug|info|warn|error|fatal)
+      +                                     (Default: info)
+       (RSpec::Expectations::ExpectationNotMetError)
+      features/fullstop.feature:13:in `And the banner should document that this app's arguments are:'
+
+Failing Scenarios:
+cucumber features/fullstop.feature:6
+
+1 scenario (1 failed)
+7 steps (1 failed, 6 passed)
+0m0.132s
+rake aborted!
+Cucumber failed
+
+Tasks: TOP => features
+(See full trace by running task with --trace)
+```
+
+We got farther this time.  Our step for checking that we have a one-line summary is passing.  Further, the next two following steps are also passing, despite the fact that we did nothing to explicitly make them pass.  Like the preceding steps ("Then the exit status should be 0" and "And the banner should be present"), the two steps following the one we just fixed pass because Methadone has bootstrapped our app in a way that they are already passing.  
+
+The call to Methadone's `version` method ensures that the version of our app appears in the online help.  The other step, "And the banner should document that this app takes options" passes because we are allowing Methadone to manage the banner.  Methadone knows that our app takes options (namely `--version`), and inserts the string `"[options]"` into the usage statement.
+
+The last step in our scenario is still failing, so let's fix that to finish up our user interface.
+What Methadone is looking for is for the string `repo_url` (the name of our only,
+required, argument) to be in the usage string, in other words, Methadone is expecting to see this:
+
+```
+Usage: fullstop [option] repo_url
+```
+
+Right now, our app's usage string looks like this:
+
+```
+Usage: fullstop [option]
+```
+
+Again, if we were using `OptionParser`, we would need to modify the argument given to `banner` to include this string.  Methadone
+provides a method, `arg` that will do this automatically for us.  We'll add it right after the call to `description` in the
+"declare UI" section of our app:
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'optparse'
+require 'methadone'
+require 'fullstop'
+
+class App
+  include Methadone::Main
+  include Methadone::CLILogging
+
+  main do 
+  end
+
+  version Fullstop::VERSION
+
+  description 'Manages dotfiles from a git repo'
+
+  # vvv
+  arg :repo_url, "URL to the git repository containing your dotfiles"
+  # ^^^
+
+  use_log_level_option
+
+  go!
+end
+```
+
+Now, when we run our features again, we can see that everything passes:
+
+```sh
+$ rake features
+Feature: Checkout dotfiles
+  In order to get my dotfiles onto a new computer
+  I want a one-command way to keep them up to date
+  So I don't have to do it myself
+
+  Scenario: Basic UI
+    When I get help for "fullstop"
+    Then the exit status should be 0
+    And the banner should be present
+    And there should be a one line summary of what the app does
+    And the banner should include the version
+    And the banner should document that this app takes options
+    And the banner should document that this app's arguments are:
+      | repo_url | which is required |
+
+1 scenario (1 passed)
+7 steps (7 passed)
+0m0.129s
+```
+
+Nice!  If our UI should ever change, we'll notice the regression, and we also have an easy way to use TDD to enhance our
+application's UI in the future.  Let's take a look at it ourselves to see what it's like:
+
+```sh
+$ bundle exec bin/fullstop --help
+Usage: fullstop [options] repo_url
+
+Manages dotfiles from a git repo
+
+v0.0.1
+
+Options:
+  --version          Show help/version info
+  --log-level LEVEL  Set the logging level (debug|info|warn|error|fatal)
+                     (Default: info)
+```
+
+Not to bad for having written two lines of code!  We can also see that `fullstop` will error out if we omit our required
+argument, `repo_url`:
+
+```sh
+$ bundle exec bin/fullstop 
+parse error: 'repo_url' is required
+
+Usage: fullstop [options] repo_url
+
+Manages dotfiles from a git repo
+
+v0.0.1
+
+Options:
+  --version          Show help/version info
+  --log-level LEVEL  Set the logging level (debug|info|warn|error|fatal)
+                     (Default: info)
+$ echo $?
+64
+```
+
+We see an error message, and exited nonzero (64 is a somewhat standard exit code for errors in command-line invocation).
+
+It's also worth pointing out that Methadone is taking a very light touch.  We could completely re-implement `bin/fullstop` using
+`OptionParser` and still have our scenario pass.  As we'll see, few of Methadone's parts really rely on each other, and many can
+be used piecemeal, if that's what you want.
+
+Now that we have our UI, the next order of business is to actually implement something.
+
+[outsidein]: http://en.wikipedia.org/wiki/Outside%E2%80%93in_software_development