htty 1.0.0 → 1.1.0

data/History.markdown

@@ -0,0 +1,21 @@
+Version history for the _htty_ project
+======================================
+
+v1.1.0, Tue 9/28/2010
+---------------------
+
+* Added HTTP Secure support
+* Added HTTP Basic Authentication support
+* Added support for arrow keys and Emacs key bindings [[rbxbx](http://github.com/rbxbx "rbxbx at GitHub")]
+* Added support for Ctrl-D for terminating input [[bofrede](http://github.com/bofrede "bofrede at GitHub")]
+* Enhanced the _userinfo-set_ command to:
+  - Permit separate entry of username and (optional) password
+  - Permit colon-separated “username:password” entry
+  - Automatically URL-escape _@_ symbols to avoid invalid URLs
+* Fixed various bugs
+* Corrected and expanded built-in help content
+
+v1.0.0, Mon 9/06/2010
+---------------------
+
+(First release)

data/MIT-LICENSE.markdown

@@ -0,0 +1,10 @@
+The MIT License
+===============
+
+Source code for _htty_ is Copyright © 2010 [Nils Jonsson](mailto:htty@nilsjonsson.com).
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS,” WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,238 @@
+
+                     s         s
+      .uef^"        :8        :8      ..
+    :d88E          .88       .88     @L
+    `888E         :888ooo   :888ooo 9888i   .dL
+     888E .z8k -*8888888 -*8888888 `Y888k:*888.
+     888E~?888L  8888      8888      888E  888I
+     888E  888E  8888      8888      888E  888I
+     888E  888E  8888      8888      888E  888I
+     888E  888E .8888Lu=  .8888Lu=   888E  888I
+     888E  888E ^%888*    ^%888*    x888N><888'
+    m888N= 888>   'Y"       'Y"      "88"  888
+     `Y"   888   __  .__                  88F
+          J88" _/  |_|  |__   ____       98"
+          @%   \   __\  |  \_/ __ \    ./"
+        :"      |  | |   Y  \  ___/   ~`
+                |__| |___|  /\___  >
+                __________\/_____\/____________________
+               /   |   \__    ___/\__    ___/\______   \
+              /    ~    \|    |     |    |    |     ___/
+              \    Y    /|    |     |    |    |    |
+               \___|_  / |____|     |____|    |____|
+               ______\/___________________.___.
+               \__    ___/\__    ___/\__  |   |
+                 |    |     |    |    /   |   |
+                 |    |     |    |    \____   |
+                 |____|     |____|    / ______|
+                                      \/
+
+[htty](http://htty.github.com) is a console application for interacting with HTTP servers. It’s something of a cross between _curl_ and the Lynx browser.
+
+See what’s changed lately by reading the [project history](file.History.html).
+
+Installation
+============
+
+It couldn’t be much easier.
+
+    $ gem install htty
+
+You’ll need Ruby and RubyGems. It’s known to work well under OS X against Ruby v1.8.7 and v1.9.2.
+
+Features
+========
+
+* Intuitive commands and command aliases
+* Support for familiar HTTP methods _GET_, _POST_, _PUT_, and _DELETE_, as well as _HEAD_, _OPTIONS_ and _TRACE_
+* Support for HTTP Secure connections and HTTP Basic Authentication
+* Automatic URL-encoding of userinfo, paths, query-string parameters, and page fragments
+* Transcripts, both verbose and summary
+* Scripting via _stdin_
+* Dead-simple cookie handling and redirect following
+* Built-in help
+
+The things you can do with _htty_ are:
+
+* **Build a request** — you can tweak the address, headers, cookies, and body at will
+* **Send the request to the server** — after the request is sent, it remains unchanged in your session history
+* **Inspect the server’s response** — you can look at the status, headers, cookies, and body in various ways
+* **Review history** — a normal and a verbose transcript of your session are available at all times (destroyed when you quit _htty_)
+* **Reuse previous requests** — you can refer to prior requests and copy them
+
+Examples
+========
+
+Here are a few annotated _htty_ session transcripts to get you started.
+
+Querying a web service
+----------------------
+
+This simple example shows how to explore a read-only web service with _htty_.
+
+![ESV Bible Web Service example #1](http://htty.github.com/images/esvapi1.png)
+
+You can point _htty_ at a complete or partial web URL. If you don’t supply a URL, http://0.0.0.0/ (port 80) will be used. You can vary the protocol scheme, userinfo, host, port, path, query string, and fragment as you wish.
+
+The _htty_ shell prompt shows the address of the current request.
+
+The `get` command is one of seven HTTP request methods supported. A concise summary of the response is shown when you issue a request.
+
+You can follow redirects using the `follow` command. No request is made until you type a request command such as `get` or `post`.
+
+![ESV Bible Web Service example #2](http://htty.github.com/images/esvapi2.png)
+
+You can tweak segments of the address at will. Here we are navigating the site’s path hierarchy, which you can do with relative as well as absolute pathspecs.
+
+![ESV Bible Web Service example #3](http://htty.github.com/images/esvapi3.png)
+
+Here we add query-string parameters. Notice that characters that require URL encoding are automatically URL-encoded (unless they are part of a URL-encoded expression).
+
+The `headers-response` and `body-response` commands reveal the details of a response.
+
+![ESV Bible Web Service example #4](http://htty.github.com/images/esvapi4.png)
+
+There was some cruft in the web service’s response (a horizontal line, a passage reference, verse numbers, a copyright stamp, and line breaks). We eliminate it by using API options provided by the web service we’re talking to.
+
+We do a Julia Child maneuver and use the `address` command to change the entire URL, rather than add individual query-string parameters one by one.
+
+Exit your session at any time by typing `quit`.
+
+Working with cookies
+--------------------
+
+The next example demonstrates _htty_’s HTTP Secure support and cookies features, as well as how to review and revisit past requests.
+
+![Google example #1](http://htty.github.com/images/google1.png)
+
+The _https://_ scheme and port 443 imply each other, just as the _http://_ scheme and port 80 imply each other. If you omit the scheme or the port, it will default to the appropriate value.
+
+Notice that when cookies are offered in a response, a bold asterisk (it looks like a cookie) appears in the response summary. The same cookie symbol appears next to the _Set-Cookie_ header when you display response headers.
+
+![Google example #2](http://htty.github.com/images/google2.png)
+
+The `cookies-use` command copies cookies out of the response into the next request. The cookie symbol appears next to the _Cookie_ header when you display request headers.
+
+![Google example #3](http://htty.github.com/images/google3.png)
+
+An abbreviated history is available through the `history` command. Information about requests in the history includes request method, URL, number of headers (and a cookie symbol, if cookies were sent), and the size of the body. Information about responses in the history includes response code, number of headers (and a cookie symbol, if cookies were received), and the size of the body.
+
+Note that history contains only numbered HTTP request and response pairs, not a record of all the commands you enter.
+
+The `reuse` command makes a copy of the headers and body of an earlier request for you to build on.
+
+Understanding complex HTTP conversations at a glance using history
+------------------------------------------------------------------
+
+Now we’ll look at _htty_’s HTTP Basic Authentication support and learn how to display unabbreviated transcripts of _htty_ sessions.
+
+Assume that we have the following Sinatra application listening on Sinatra’s default port, 4567.
+
+    require 'sinatra'
+
+    get '/all-good' do
+      [200, [['Set-Cookie', 'foo=bar; baz']], 'Hello World!']
+    end
+
+    put '/huh' do
+      [404, 'What?']
+    end
+
+    delete '/hurl' do
+      [500, 'Barf!']
+    end
+
+    post '/submit-novel' do
+      redirect '/all-good'
+    end
+
+This application expects _GET_ and _POST_ requests and responds in various contrived ways.
+
+![Sinatra application example #1](http://htty.github.com/images/sinatra1.png)
+
+When you change the userinfo portion of the address, or the entire address, the appropriate HTTP Basic Authentication header is created for you automatically. Notice that characters that require URL encoding are automatically URL-encoded (unless they are part of a URL-encoded expression).
+
+When userinfo is supplied in a request, a bold mercantile symbol (_@_) appears next to the resulting _Authorization_ header when you display request headers (see below).
+
+Type `body-set` to enter body data, and terminate it by typing Return three times consecutively. The body will only be sent for _POST_ and _PUT_ requests. The appropriate _Content-Length_ header is created for you automatically (see below).
+
+Different response codes are rendered with colors that suggest their meaning:
+
+* Response codes between 200 and 299 appear <span style="background-color: green; color: black; font-weight: bold; padding: 0 0.25em 0 0.25em;">black on green</span> to indicate success
+* Response codes between 300 and 399 appear <span style="background-color: blue; color: white; font-weight: bold; padding: 0 0.25em 0 0.25em;">white on blue</span> to indicate redirection
+* Response codes between 400 and 499 appear <span style="background-color: red; color: white; font-weight: bold; padding: 0 0.25em 0 0.25em;">white on red</span> to indicate failure
+* Response codes between 500 and 599 appear <span style="background-color: yellow; color: black; font-weight: bold; padding: 0 0.25em 0 0.25em; text-decoration: blink;">flashing black on yellow</span> to indicate a server error
+
+![Sinatra application example #2](http://htty.github.com/images/sinatra2.png)
+
+As with the abbreviated history demonstrated earlier, verbose history shows a numbered list of requests and the responses they elicited. All information exchanged between client and server is shown.
+
+Getting help
+------------
+
+You can learn how to use _htty_ commands from within _htty_.
+
+![htty’s built-in help](http://htty.github.com/images/help.png)
+
+The `help` command takes an optional argument of the abbreviated or full name of a command.
+
+Coming soon
+===========
+
+Here are some features that are coming down the pike.
+
+Commands for streamlining web form submission
+---------------------------------------------
+
+These features will make _htty_ better at screen-scraping.
+
+Using any of the forthcoming `form` commands will clear any non-form content in the body of the request. Adding at least one URL-encoded form parameter to the request will set the _Content-Type_ header to _application/x-www-form-urlencoded_. Removing all URL-encoded form parameters will remove this header.
+
+* `form` — display all form parameters offered in the response
+* `form-fill` — prompt in turn for a value for each of the form inputs in the response
+* <code>form-add _name_ _value_</code> — add a URL-encoded form parameter for the request, using the specified name and value
+* <code>form-remove _name_</code> — remove a URL-encoded form parameter from the request, using the specified name
+* `form-remove-all` — remove all URL-encoded form parameters from the request
+
+You will also be able to pop open a browser window containing request and response bodies.
+
+Shiny autocomplete goodness
+---------------------------
+
+We’ll have command command autocompletion, and possibly also Tab key navigation of forms.
+
+Custom command aliases and shell emulation of _http-console_
+------------------------------------------------------------
+
+You should be able to make your own command aliases.
+
+_http-console_ has a nice command-line. We should have an _http-console_ skin for _htty_.
+
+Contributing
+============
+
+Report defects and feature requests on [GitHub Issues](http://github.com/htty/htty/issues).
+
+Your patches are welcome, and you will receive attribution here for good stuff. Fork [the official _htty_ repository](http://github.com/htty/htty "htty’s ‘htty’ repository at GitHub") and send a pull request.
+
+News and information
+====================
+
+Stay in touch with the _htty_ project by following [@get_htty](http://twitter.com/get_htty "get_htty at Twitter") on Twitter.
+
+You can also get help in the [#htty channel on Freenode](http://webchat.freenode.net/?channels=htty).
+
+Credits
+=======
+
+The author, [Nils Jonsson](mailto:htty@nilsjonsson.com), owes a debt of inspiration to the [_http-console_](http://github.com/cloudhead/http-console) project.
+
+Thanks to contributors:
+
+* Bo Frederiksen ([bofrede](http://github.com/bofrede "bofrede at GitHub")) for work on the CLI
+* Robert Pitts ([rbxbx](http://github.com/rbxbx "rbxbx at GitHub")) for work on the CLI and on RSpec specs
+
+License
+=======
+
+Released under the [MIT License](file.MIT-LICENSE.html).

data/VERSION

@@ -1 +1 @@
-1.0.0
+1.1.0

data/bin/htty

@@ -1,5 +1,5 @@
 #!/usr/bin/env ruby
 
-require File.expand_path("#{File.dirname __FILE__}/../app/htty")
+require File.expand_path("#{File.dirname __FILE__}/../lib/htty")
 
 HTTY::CLI.new(ARGV).run!

data/{app → lib}/htty.rb

@@ -1,5 +1,3 @@
-# Loads constants defined within HTTY.
-
 # Contains the implementation of _htty_.
 module HTTY
 

data/{app → lib}/htty/cli.rb

@@ -1,5 +1,4 @@
-# Defines HTTY::CLI and loads constants defined within HTTY::CLI.
-
+require 'readline'
 require File.expand_path("#{File.dirname __FILE__}/cli/commands")
 require File.expand_path("#{File.dirname __FILE__}/cli/commands/help")
 require File.expand_path("#{File.dirname __FILE__}/cli/commands/quit")
@@ -39,6 +38,10 @@ class HTTY::CLI
                         strong(HTTY::CLI::Commands::Help.command_line))
             next
           end
+          if command == :unclosed_quote
+            $stderr.puts notice('Unclosed quoted expression -- try again')
+            next
+          end
           if ARGV.include?('--debug')
             command.perform
           else
@@ -63,8 +66,12 @@ private
   def prompt_for_command
     command_line = ''
     while command_line.empty? do
-      print strong(session.requests.last.uri) + normal('> ')
-      command_line = $stdin.gets.chomp.strip
+      prompt = prompt(session.requests.last)
+      if (command_line = Readline.readline(prompt, true)).nil?
+        raise Interrupt
+      end
+      command_line.chomp!
+      command_line.strip!
     end
     HTTY::CLI::Commands.build_for command_line, :session => session
   end

data/{app → lib}/htty/cli/command.rb

@@ -1,5 +1,3 @@
-# Defines HTTY::CLI::Command.
-
 require 'abbrev'
 require 'shellwords'
 require File.expand_path("#{File.dirname __FILE__}/display")
@@ -31,7 +29,12 @@ class HTTY::CLI::Command
     if (match = (command_line_regexp.match(command_line)))
       all_attributes = attributes
       if (arguments = match.captures[0])
-        return new(attributes.merge(:arguments => arguments.strip.shellsplit))
+        begin
+          split_arguments = arguments.strip.shellsplit
+        rescue ArgumentError
+          return :unclosed_quote
+        end
+        return new(attributes.merge(:arguments => split_arguments))
       end
       return new(attributes)
     end
@@ -119,6 +122,25 @@ class HTTY::CLI::Command
     Array(alias_for)
   end
 
+protected
+
+  # Displays a notice if cookies are cleared on the specified _request_ in the
+  # course of the block.
+  def self.notify_if_cookies_cleared(request)
+    had_cookies = cookies?(request)
+    changed_request = yield
+    puts notice('Cookies cleared') if had_cookies && !cookies?(changed_request)
+    changed_request
+  end
+
+private
+
+  def self.cookies?(request)
+    !request.cookies.empty?
+  end
+
+public
+
   # Returns the arguments provided to the command.
   attr_reader :arguments
 

data/{app → lib}/htty/cli/commands.rb

@@ -1,5 +1,3 @@
-# Loads constants defined within HTTY::CLI::Commands.
-
 module HTTY; end
 
 class HTTY::CLI; end

data/{app → lib}/htty/cli/commands/address.rb

@@ -1,9 +1,11 @@
-# Defines HTTY::CLI::Commands::Address.
-
 require File.expand_path("#{File.dirname __FILE__}/../command")
-require File.expand_path("#{File.dirname __FILE__}/../cookie_clearing_command")
+require File.expand_path("#{File.dirname __FILE__}/fragment_set")
+require File.expand_path("#{File.dirname __FILE__}/host_set")
+require File.expand_path("#{File.dirname __FILE__}/path_set")
 require File.expand_path("#{File.dirname __FILE__}/port_set")
+require File.expand_path("#{File.dirname __FILE__}/query_set")
 require File.expand_path("#{File.dirname __FILE__}/scheme_set")
+require File.expand_path("#{File.dirname __FILE__}/userinfo_set")
 
 module HTTY; end
 
@@ -14,8 +16,6 @@ module HTTY::CLI::Commands; end
 # Encapsulates the _address_ command.
 class HTTY::CLI::Commands::Address < HTTY::CLI::Command
 
-  include HTTY::CLI::CookieClearingCommand
-
   # Returns the name of a category under which help for the _address_ command
   # should appear.
   def self.category
@@ -35,7 +35,7 @@ class HTTY::CLI::Commands::Address < HTTY::CLI::Command
   # Returns the extended help text for the _address_ command.
   def self.help_extended
     'Changes the address used for the request. Does not communicate with the ' +
-    "endpoint.\n"                                                              +
+    "host.\n"                                                                  +
     "\n"                                                                       +
     'The URL you supply can be partial. At a minimum, you must specify a '     +
     'host. The optional and required elements of an address are illustrated '  +
@@ -62,20 +62,26 @@ class HTTY::CLI::Commands::Address < HTTY::CLI::Command
     'If (4) is omitted, port 80 is used, except if (1) is specified as '       +
     "HTTPS, in which case port 443 is used.\n"                                 +
     "\n"                                                                       +
-    "If (5) is omitted, the root path (i.e., \"/\") is used.\n"                +
+    "If (5) is omitted, the root path (i.e., '/') is used.\n"                  +
     "\n"                                                                       +
     'The console prompt shows the address for the current request.'
   end
 
   # Returns related command classes for the _address_ command.
   def self.see_also_commands
-    [HTTY::CLI::Commands::SchemeSet, HTTY::CLI::Commands::PortSet]
+    [HTTY::CLI::Commands::SchemeSet,
+     HTTY::CLI::Commands::UserinfoSet,
+     HTTY::CLI::Commands::HostSet,
+     HTTY::CLI::Commands::PortSet,
+     HTTY::CLI::Commands::PathSet,
+     HTTY::CLI::Commands::QuerySet,
+     HTTY::CLI::Commands::FragmentSet]
   end
 
   # Performs the _address_ command.
   def perform
     add_request_if_has_response do |request|
-      notify_if_cookies_cleared request do
+      self.class.notify_if_cookies_cleared request do
         request.address(*arguments)
       end
     end

data/{app → lib}/htty/cli/commands/body_clear.rb

@@ -1,5 +1,3 @@
-# Defines HTTY::CLI::Commands::BodyClear.
-
 require File.expand_path("#{File.dirname __FILE__}/../command")
 require File.expand_path("#{File.dirname __FILE__}/body_unset")
 

data/{app → lib}/htty/cli/commands/body_request.rb

@@ -1,5 +1,3 @@
-# Defines HTTY::CLI::Commands::BodyRequest.
-
 require File.expand_path("#{File.dirname __FILE__}/../command")
 require File.expand_path("#{File.dirname __FILE__}/body_response")
 require File.expand_path("#{File.dirname __FILE__}/body_set")
@@ -29,7 +27,7 @@ class HTTY::CLI::Commands::BodyRequest < HTTY::CLI::Command
   # Returns the extended help text for the _body-request_ command.
   def self.help_extended
     'Displays the body content used for the request. Does not communicate ' +
-    'with the endpoint.'
+    'with the host.'
   end
 
   # Returns related command classes for the _body-request_ command.