ronin-web 0.1.3 → 0.2.0

data/lib/ronin/web/server/proxy.rb

@@ -0,0 +1,116 @@
+#
+# Ronin Web - A Ruby library for Ronin that provides support for web
+# scraping and spidering functionality.
+#
+# Copyright (c) 2006-2009 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+#
+
+require 'ronin/web/server/helpers/proxy'
+
+module Ronin
+  module Web
+    module Server
+      module Proxy
+        def self.included(base)
+          base.module_eval do
+            #
+            # Proxies requests to a given path.
+            #
+            # @param [String] path
+            #   The path to proxy requests for.
+            #
+            # @param [Hash] options
+            #   Additional options.
+            # 
+            # @yield [(response), body]
+            #   If a block is given, it will be passed the optional
+            #   response of the proxied request and the body received
+            #   from the proxied request.
+            #
+            # @yieldparam [Net::HTTP::Response] response
+            #   The response.
+            #
+            # @yieldparam [String] body
+            #   The body from the response.
+            #
+            # @example
+            #   proxy '/login.php' do |body|
+            #     body.gsub(/https/,'http')
+            #   end
+            #
+            # @example
+            #   proxy '/login*' do |response,body|
+            #   end
+            #
+            # @since 0.2.0
+            #
+            def self.proxy(path,options={},&block)
+              any(path) do
+                proxy(options,&block)
+              end
+            end
+
+            #
+            # Proxies requests to a given path.
+            #
+            # @param [String] path
+            #   The path to proxy requests for.
+            #
+            # @param [Hash] options
+            #   Additional options.
+            # 
+            # @yield [(response), page]
+            #   If a block is given, it will be passed the optional
+            #   response of the proxied request and the page from the
+            #   proxied request.
+            #
+            # @yieldparam [Net::HTTP::Response] response
+            #   The response.
+            #
+            # @yieldparam [Nokogiri::HTML, Nokogiri::XML] page
+            #   The page from the response.
+            #
+            # @example
+            #   proxy '/login.php' do |page|
+            #     body.search('@action').each do |action|
+            #       action.inner_text = action.inner_text.gsub(
+            #         /https/, 'http'
+            #       )
+            #     end
+            #   end
+            #
+            # @example
+            #   proxy '/login*' do |response,body|
+            #   end
+            #
+            # @since 0.2.0
+            #
+            def self.proxy_page(path,options={},&block)
+              any(path) do
+                proxy_page(options,&block)
+              end
+            end
+
+            protected
+
+            helpers Ronin::Web::Server::Helpers::Proxy
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ronin/web/server/web.rb

@@ -0,0 +1,62 @@
+#
+# Ronin Web - A Ruby library for Ronin that provides support for web
+# scraping and spidering functionality.
+#
+# Copyright (c) 2006-2009 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+#
+
+require 'ronin/web/server/app'
+
+module Ronin
+  module Web
+    #
+    # Returns the Ronin Web Server.
+    #
+    # @param [Hash] options
+    #   Additional options.
+    #
+    # @yield [server]
+    #   If a block is given, it will be passed the current web server.
+    #
+    # @yieldparam [Server::App]
+    #   The current web server class.
+    #
+    # @return [Server::App]
+    #   The current web server class.
+    #
+    # @example
+    #   Web.server do
+    #     get '/hello' do
+    #       'world'
+    #     end
+    #   end
+    #
+    # @see Server::Base.run!
+    # @since 0.2.0
+    #
+    def Web.server(options={},&block)
+      unless class_variable_defined?('@@ronin_web_server')
+        @@ronin_web_server = Server::App
+        @@ronin_web_server.run!(options.merge(:background => true))
+      end
+
+      @@ronin_web_server.class_eval(&block)
+
+      return @@ronin_web_server
+    end
+  end
+end

data/lib/ronin/web/spider.rb

@@ -1,5 +1,4 @@
 #
-#--
 # Ronin Web - A Ruby library for Ronin that provides support for web
 # scraping and spidering functionality.
 #
@@ -18,11 +17,10 @@
 # You should have received a copy of the GNU General Public License
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
-#++
 #
 
 require 'ronin/web/web'
-require 'ronin/ui/diagnostics'
+require 'ronin/ui/output/helpers'
 
 require 'spidr/agent'
 
@@ -30,31 +28,60 @@ module Ronin
   module Web
     class Spider < Spidr::Agent
 
-      include UI::Diagnostics
+      include UI::Output::Helpers
 
       #
-      # Creates a new Spider object with the given _options_ and
-      # _block_. If a _block_ is given, it will be passed the newly created
-      # Spider object.
-      #
-      # _options_ may contain the following keys:
-      # <tt>:proxy</tt>:: The proxy to use while spidering. Defaults to
-      #                   Web.proxy.
-      # <tt>:user_agent</tt>:: The User-Agent string to send. Defaults to
-      #                        Web.user_agent.
-      # <tt>:referer</tt>:: The referer URL to send.
-      # <tt>:delay</tt>:: Duration in seconds to pause between spidering
-      #                   each link. Defaults to 0.
-      # <tt>:host</tt>:: The host-name to visit.
-      # <tt>:hosts</tt>:: An +Array+ of host patterns to visit.
-      # <tt>:ignore_hosts</tt>:: An +Array+ of host patterns to not visit.
-      # <tt>:ports</tt>:: An +Array+ of port patterns to visit.
-      # <tt>:ignore_ports</tt>:: An +Array+ of port patterns to not visit.
-      # <tt>:links</tt>:: An +Array+ of link patterns to visit.
-      # <tt>:ignore_links</tt>:: An +Array+ of link patterns to not visit.
-      # <tt>:exts</tt>:: An +Array+ of File extension patterns to visit.
-      # <tt>:ignore_exts</tt>:: An +Array+ of File extension patterns to not
-      #                         visit.
+      # Creates a new Spider object.
+      #
+      # @param [Hash] options
+      #   Additional options.
+      #
+      # @option options [Hash] :proxy (Web.proxy)
+      #   The proxy to use while spidering.
+      #
+      # @option options [String] :user_agent
+      #   The User-Agent string to send.
+      #
+      # @option options [String] :referer
+      #   The referer URL to send.
+      #
+      # @option options [Integer] :delay (0)
+      #   Duration in seconds to pause between spidering each link.
+      #
+      # @option options [String, Regexp] :host
+      #   The host-name to visit.
+      #
+      # @option options [Array] :hosts
+      #   Patterns of host-names to visit.
+      #
+      # @option options [Array] :ignore_hosts
+      #   Patterns of host-names not to visit.
+      #
+      # @option options [Array] :ports
+      #   Ports to visit.
+      #
+      # @option options [Array] :ignore_ports
+      #   Ports not to visit.
+      #
+      # @option options [Array] :links
+      #   Patterns of links to visit.
+      #
+      # @option options [Array] :ignore_links
+      #   Patterns of links not to visit.
+      #
+      # @option options [Array] :ext
+      #   Patterns of file extensions to accept.
+      #
+      # @option options [Array] :ignore_exts
+      #   Patterns of file extensions to ignore.
+      #
+      # @yield [spider]
+      #   If a block is given, it will be passed the newly created spider.
+      #
+      # @yieldparam [Spider] spider
+      #   The newly created spider.
+      #
+      # @see http://spidr.rubyforge.org/docs/classes/Spidr/Agent.html
       #
       def initialize(options={},&block)
         options = {

data/lib/ronin/web/version.rb

@@ -1,5 +1,4 @@
 #
-#--
 # Ronin Web - A Ruby library for Ronin that provides support for web
 # scraping and spidering functionality.
 #
@@ -18,12 +17,11 @@
 # You should have received a copy of the GNU General Public License
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
-#++
 #
 
 module Ronin
   module Web
     # Ronin Web Version
-    VERSION = '0.1.3'
+    VERSION = '0.2.0'
   end
 end

data/lib/ronin/web/web.rb

@@ -1,5 +1,4 @@
 #
-#--
 # Ronin Web - A Ruby library for Ronin that provides support for web
 # scraping and spidering functionality.
 #
@@ -18,7 +17,6 @@
 # You should have received a copy of the GNU General Public License
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
-#++
 #
 
 require 'ronin/network/http'
@@ -31,8 +29,19 @@ require 'open-uri'
 module Ronin
   module Web
     #
-    # Returns a Nokogiri::HTML::Document object for the specified _body_
-    # of html.
+    # Parses the body of a document into a HTML document object.
+    #
+    # @param [String, IO] body
+    #   The body of the document to parse.
+    #
+    # @yield [doc]
+    #   If a block is given, it will be passed the newly created document
+    #   object.
+    #
+    # @yieldparam [Nokogiri::HTML::Document] doc
+    #   The new HTML document object.
+    #
+    # @return [Nokogiri::HTML::Document] The new HTML document object.
     #
     def Web.html(body,&block)
       doc = Nokogiri::HTML(body)
@@ -42,8 +51,15 @@ module Ronin
     end
 
     #
-    # Creates a new Nokogiri::HTML::Builder with the given _block_.
+    # Creates a new Nokogiri::HTML::Builder.
+    #
+    # @yield []
+    #   The block that will be used to construct the HTML document.
     #
+    # @return [Nokogiri::HTML::Builder]
+    #   The new HTML builder object.
+    #
+    # @example
     #   Web.build_html do
     #     body {
     #       div(:style => 'display:none;') {
@@ -57,8 +73,19 @@ module Ronin
     end
 
     #
-    # Returns a Nokogiri::XML::Document object for the specified _body_
-    # of xml and the given _block_.
+    # Parses the body of a document into a XML document object.
+    #
+    # @param [String, IO] body
+    #   The body of the document to parse.
+    #
+    # @yield [doc]
+    #   If a block is given, it will be passed the newly created document
+    #   object.
+    #
+    # @yieldparam [Nokogiri::XML::Document] doc
+    #   The new XML document object.
+    #
+    # @return [Nokogiri::XML::Document] The new XML document object.
     #
     def Web.xml(body,&block)
       doc = Nokogiri::XML(body)
@@ -68,8 +95,15 @@ module Ronin
     end
 
     #
-    # Creates a new Nokogiri::XML::Builder with the given _block_.
+    # Creates a new Nokogiri::XML::Builder.
     #
+    # @yield []
+    #   The block that will be used to construct the XML document.
+    #
+    # @return [Nokogiri::XML::Builder]
+    #   The new XML builder object.
+    #
+    # @example
     #  Web.build_xml do
     #    post(:id => 2) {
     #      title { text("some example) }
@@ -82,104 +116,113 @@ module Ronin
     end
 
     #
-    # Returns the default Ronin Web proxy port.
+    # Proxy information for Ronin::Web to use.
     #
-    def Web.default_proxy_port
-      Network::HTTP.default_proxy_port
-    end
-
+    # @return [Network::HTTP::Proxy]
+    #   The Ronin Web proxy information.
     #
-    # Sets the default Ronin Web proxy port to the specified _port_.
-    #
-    def Web.default_proxy_port=(port)
-      Network::HTTP.default_proxy_port = port
-    end
-
-    #
-    # Returns the +Hash+ of the Ronin Web proxy information.
+    # @see Ronin::Network::HTTP.proxy
     #
     def Web.proxy
       Network::HTTP.proxy
     end
 
     #
-    # Resets the Web proxy settings.
+    # Creates a HTTP URI based on a Hash of proxy information.
     #
-    def Web.disable_proxy
-      Network::HTTP.disable_proxy
-    end
-
+    # @param [Network::HTTP::Proxy, Hash] proxy_info
+    #   The proxy information.
     #
-    # Creates a HTTP URI based from the given _proxy_info_ hash. The
-    # _proxy_info_ hash defaults to Web.proxy, if not given.
+    # @return [URI::HTTP, nil]
+    #   The HTTP URI that represents the proxy. If the proxy is diabled,
+    #   +nil+ will be returned.
     #
     def Web.proxy_url(proxy_info=Web.proxy)
-      if Web.proxy[:host]
-        userinfo = nil
-
-        if (Web.proxy[:user] || Web.proxy[:password])
-          userinfo = "#{Web.proxy[:user]}:#{Web.proxy[:password]}"
-        end
-
-        return URI::HTTP.build(
-          :host => Web.proxy[:host],
-          :port => Web.proxy[:port],
-          :userinfo => userinfo,
-          :path => '/'
-        )
-      end
+      Network::HTTP::Proxy.new(proxy_info).url
     end
 
     #
-    # Returns the supported Web User-Agent Aliases.
+    # @return [Array]
+    #   The supported Web User-Agent Aliases.
     #
     def Web.user_agent_aliases
       WWW::Mechanize::AGENT_ALIASES
     end
 
     #
-    # Returns the Ronin Web User-Agent
+    # @return [String, nil]
+    #   The Ronin Web User-Agent
     #
     def Web.user_agent
       Network::HTTP.user_agent
     end
 
     #
-    # Sets the Ronin Web User-Agent to the specified _new_agent_.
+    # Sets the Ronin Web User-Agent.
+    #
+    # @param [String] new_agent
+    #   The User-Agent string to use.
+    #
+    # @return [String]
+    #   The new User-Agent string.
     #
     def Web.user_agent=(new_agent)
       Network::HTTP.user_agent = new_agent
     end
 
     #
-    # Sets the Ronin Web User-Agent to the specified user agent alias
-    # _name_.
+    # Sets the Ronin Web User-Agent.
+    #
+    # @param [String] name
+    #   The User-Agent alias to use.
+    #
+    # @return [String]
+    #   The new User-Agent string.
     #
     def Web.user_agent_alias=(name)
       Network::HTTP.user_agent = Web.user_agent_aliases[name.to_s]
     end
 
     #
-    # Opens the _url_ with the given _options_. The contents of the _url_
-    # will be returned.
+    # Opens a URL as a temporary file.
+    #
+    # @param [Hash] options
+    #   Additional options.
+    #
+    # @option options [String] :user_agent_alias
+    #   The User-Agent Alias to use.
+    #
+    # @option options [String] :user_agent
+    #   The User-Agent string to use.
     #
-    # _options_ may contain the following keys:
-    # <tt>:user_agent_alias</tt>:: The User-Agent Alias to use.
-    # <tt>:user_agent</tt>:: The User-Agent string to use.
-    # <tt>:proxy</tt>:: A +Hash+ of the proxy information to use.
-    # <tt>:user</tt>:: The HTTP Basic Authentication user name.
-    # <tt>:password</tt>:: The HTTP Basic Authentication password.
-    # <tt>:content_length_proc</tt>:: A callback which will be passed the
-    #                                 content-length of the HTTP response.
-    # <tt>:progress_proc</tt>:: A callback which will be passed the size
-    #                           of each fragment, once received from the
-    #                           server.
+    # @option options [Network::HTTP::Proxy, Hash] :proxy (Web.proxy)
+    #   Proxy information.
     #
+    # @option options [String] :user
+    #   The HTTP Basic Authentication user name.
+    #
+    # @option options [String] :password
+    #   The HTTP Basic Authentication password.
+    #
+    # @option options [Proc] :content_length_proc
+    #   A callback which will be passed the content-length of the HTTP
+    #   response.
+    #
+    # @option options [Proc] :progress_proc
+    #   A callback which will be passed the size of each fragment, once
+    #   received from the server.
+    #
+    # @return [File]
+    #   The contents of the URL.
+    #
+    # @example Open a given URL.
     #   Web.open('http://www.hackety.org/')
     #
+    # @example Open a given URL, using a custom User-Agent alias.
     #   Web.open('http://tenderlovemaking.com/',
     #     :user_agent_alias => 'Linux Mozilla')
     #
+    # @example Open a given URL, using a custom User-Agent string.
     #   Web.open('http://www.wired.com/', :user_agent => 'the future')
     #
     def Web.open(url,options={})
@@ -216,17 +259,41 @@ module Ronin
     end
 
     #
-    # Creates a new Mechanize agent with the given _options_.
+    # Creates a new Mechanize Agent.
+    #
+    # @param [Hash] options
+    #   Additional options.
+    #
+    # @option options [String] :user_agent_alias
+    #   The User-Agent Alias to use.
+    #
+    # @option options [String] :user_agent
+    #   The User-Agent string to use.
+    #
+    # @option options [Network::HTTP::Proxy, Hash] :proxy (Web.proxy)
+    #   Proxy information.
     #
-    # _options_ may contain the following keys:
-    # <tt>:user_agent_alias</tt>:: The User-Agent Alias to use.
-    # <tt>:user_agent</tt>:: The User-Agent string to use.
-    # <tt>:proxy</tt>:: A +Hash+ of the proxy information to use.
+    # @yield [agent]
+    #   If a block is given, it will be passed the newly created Mechanize
+    #   agent.
     #
+    # @yieldparam [WWW::Mechanize] agent
+    #   The new Mechanize agent.
+    #
+    # @return [WWW::Mechanize]
+    #   The new Mechanize agent.
+    #
+    # @example Create a new agent.
     #   Web.agent
+    #
+    # @example Create a new agent, with a custom User-Agent alias.
     #   Web.agent(:user_agent_alias => 'Linux Mozilla')
+    #
+    # @example Create a new agent, with a custom User-Agent string.
     #   Web.agent(:user_agent => 'wooden pants')
     #
+    # @see http://mechanize.rubyforge.org/mechanize/WWW/Mechanize.html
+    #
     def Web.agent(options={},&block)
       agent = WWW::Mechanize.new
 
@@ -248,22 +315,46 @@ module Ronin
     end
 
     #
-    # Gets the specified _url_ with the given _options_. If a _block_ is
-    # given, it will be passed the retrieved page.
+    # Creates a Mechanize Page for the contents at a given URL.
+    #
+    # @param [URI::Generic, String] url
+    #   The URL to request.
+    #
+    # @param [Hash] options
+    #   Additional options.
+    #
+    # @option options [String] :user_agent_alias
+    #   The User-Agent Alias to use.
+    #
+    # @option options [String] :user_agent
+    #   The User-Agent string to use.
     #
-    # _options_ may contain the following keys:
-    # <tt>:user_agent_alias</tt>:: The User-Agent Alias to use.
-    # <tt>:user_agent</tt>:: The User-Agent string to use.
-    # <tt>:proxy</tt>:: A +Hash+ of the proxy information to use.
+    # @option options [Network::HTTP::Proxy, Hash] :proxy (Web.proxy)
+    #   Proxy information.
     #
-    #   Web.get('http://www.0x000000.com') # => WWW::Mechanize::Page
+    # @yield [page]
+    #   If a block is given, it will be passed the page for the requested
+    #   URL.
     #
+    # @yieldparam [WWW::Mechanize::Page] page
+    #   The requested page.
+    #
+    # @return [WWW::Mechanize::Page]
+    #   The requested page.
+    #
+    # @example
+    #   Web.get('http://www.0x000000.com')
+    #   # => WWW::Mechanize::Page
+    #
+    # @example
     #   Web.get('http://www.rubyinside.com') do |page|
     #     page.search('div.post/h2/a').each do |title|
     #       puts title.inner_text
     #     end
     #   end
     #
+    # @see http://mechanize.rubyforge.org/mechanize/WWW/Mechanize/Page.html
+    #
     def Web.get(url,options={},&block)
       page = Web.agent(options).get(url)
 
@@ -272,17 +363,37 @@ module Ronin
     end
 
     #
-    # Gets the specified _url_ with the given _options_, returning the body
-    # of the requested page. If a _block_ is given, it will be passed the
-    # body of the retrieved page.
+    # Requests the body of the Mechanize Page created from the response
+    # of the given URL.
+    #
+    # @param [URI::Generic, String] url
+    #   The URL to request.
+    #
+    # @param [Hash] options
+    #   Additional options.
+    #
+    # @option options [String] :user_agent_alias
+    #   The User-Agent Alias to use.
+    #
+    # @option options [String] :user_agent
+    #   The User-Agent string to use.
+    #
+    # @option options [Network::HTTP::Proxy, Hash] :proxy (Web.proxy)
+    #   Proxy information.
     #
-    # _options_ may contain the following keys:
-    # <tt>:user_agent_alias</tt>:: The User-Agent Alias to use.
-    # <tt>:user_agent</tt>:: The User-Agent string to use.
-    # <tt>:proxy</tt>:: A +Hash+ of the proxy information to use.
+    # @yield [body]
+    #   If a block is given, it will be passed the body of the page.
     #
+    # @yieldparam [String] body
+    #   The requested body of the page.
+    #
+    # @return [String]
+    #   The requested body of the page.
+    #
+    # @example
     #   Web.get_body('http://www.rubyinside.com') # => String
     #
+    # @example
     #   Web.get_body('http://www.rubyinside.com') do |body|
     #     puts body
     #   end
@@ -295,16 +406,39 @@ module Ronin
     end
 
     #
-    # Posts the specified _url_ with the given _options_. If a _block_ is
-    # given, it will be passed the posted page.
+    # Posts to a given URL and creates a Mechanize Page from the response.
+    #
+    # @param [URI::Generic, String] url
+    #   The URL to request.
+    #
+    # @param [Hash] options
+    #   Additional options.
+    #
+    # @option options [Hash] :query
+    #   Additional query parameters to post with.
+    #
+    # @option options [String] :user_agent_alias
+    #   The User-Agent Alia to use.
+    #
+    # @option options [String] :user_agent
+    #   The User-Agent string to use.
+    #
+    # @option options [Network::HTTP::Proxy, Hash] :proxy (Web.proxy)
+    #   Proxy information.
+    #
+    # @yield [page]
+    #   If a block is given, it will be passed the page for the requested
+    #   URL.
     #
-    # _options_ may contain the following keys:
-    # <tt>:query</tt>:: The query parameters to post to the specified _url_.
-    # <tt>:user_agent_alias</tt>:: The User-Agent Alias to use.
-    # <tt>:user_agent</tt>:: The User-Agent string to use.
-    # <tt>:proxy</tt>:: A +Hash+ of the proxy information to use.
+    # @yieldparam [WWW::Mechanize::Page] page
+    #   The requested page.
     #
-    #   Web.post('http://www.rubyinside.com') # => WWW::Mechanize::Page
+    # @return [WWW::Mechanize::Page]
+    #   The requested page.
+    #
+    # @example
+    #   Web.post('http://www.rubyinside.com')
+    #   # => WWW::Mechanize::Page
     #
     def Web.post(url,options={},&block)
       query = {}
@@ -317,17 +451,41 @@ module Ronin
     end
 
     #
-    # Poststhe specified _url_ with the given _options_, returning the body
-    # of the posted page. If a _block_ is given, it will be passed the
-    # body of the posted page.
+    # Posts to a given URL and returns the body of the Mechanize Page
+    # created from the response.
+    #
+    # @param [URI::Generic, String] url
+    #   The URL to request.
+    #
+    # @param [Hash] options
+    #   Additional options.
+    #
+    # @option options [Hash] :query
+    #   Additional query parameters to post with.
+    #
+    # @option options [String] :user_agent_alias
+    #   The User-Agent Alias to use.
+    #
+    # @option options [String] :user_agent
+    #   The User-Agent string to use.
+    #
+    # @option options [Network::HTTP::Proxy, Hash] :proxy (Web.proxy)
+    #   Proxy information.
+    #
+    # @yield [body]
+    #   If a block is given, it will be passed the body of the page.
+    #
+    # @yieldparam [WWW::Mechanize::Page] page
+    #   The body of the requested page.
     #
-    # _options_ may contain the following keys:
-    # <tt>:user_agent_alias</tt>:: The User-Agent Alias to use.
-    # <tt>:user_agent</tt>:: The User-Agent string to use.
-    # <tt>:proxy</tt>:: A +Hash+ of the proxy information to use.
+    # @return [WWW::Mechanize::Page]
+    #   The body of the requested page.
     #
-    #   Web.post_body('http://www.rubyinside.com') # => String
+    # @example
+    #   Web.post_body('http://www.rubyinside.com')
+    #   # => String
     #
+    # @example
     #   Web.post_body('http://www.rubyinside.com') do |body|
     #     puts body
     #   end