From 10219ff6216c9d6459026e9e89ed788e2d440dc5 Mon Sep 17 00:00:00 2001 From: drbrain Date: Fri, 13 May 2011 20:03:21 +0000 Subject: [PATCH] * lib/uri.rb: Add toplevel documentation. Patch by Vincent Batts. [Ruby 1.9 - Bug #4690] git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@31555 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- ChangeLog | 5 +++ lib/uri.rb | 90 +++++++++++++++++++++++++++++++++++++++++++--- lib/uri/common.rb | 7 ++-- lib/uri/ftp.rb | 3 +- lib/uri/generic.rb | 4 +-- lib/uri/http.rb | 3 +- lib/uri/https.rb | 3 +- lib/uri/ldap.rb | 3 +- lib/uri/ldaps.rb | 7 ++++ lib/uri/mailto.rb | 3 +- 10 files changed, 115 insertions(+), 13 deletions(-) diff --git a/ChangeLog b/ChangeLog index ffdb43b399..7340259d53 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +Sat May 14 05:02:58 2011 Eric Hodel + + * lib/uri.rb: Add toplevel documentation. Patch by Vincent Batts. + [Ruby 1.9 - Bug #4690] + Sat May 14 04:19:06 2011 Martin Bosslet * NEWS: Describe altered behaviour for RSA and DSA public key diff --git a/lib/uri.rb b/lib/uri.rb index 41bb09b467..2e136eb682 100644 --- a/lib/uri.rb +++ b/lib/uri.rb @@ -1,15 +1,97 @@ +# URI is a module providing classes to handle Uniform Resource Identifiers +# (RFC2396[http://tools.ietf.org/html/rfc2396]) # -# URI support for Ruby +# == Features +# +# * Uniform handling of handling URIs +# * Flexibility to introduce custom URI schemes +# * Flexibility to have an alternate URI::Parser (or just different patterns +# and regexp's) +# +# == Basic example +# +# require 'uri' +# +# uri = URI("http://foo.com/posts?id=30&limit=5#time=1305298413") +# #=> # +# uri.scheme +# #=> "http" +# uri.host +# #=> "foo.com" +# uri.path +# #=> "/posts" +# uri.query +# #=> "id=30&limit=5" +# uri.fragment +# #=> "time=1305298413" +# +# uri.to_s +# #=> "http://foo.com/posts?id=30&limit=5#time=1305298413" +# +# == Adding custom URIs +# +# module URI +# class RSYNC < Generic +# DEFAULT_PORT = 873 +# end +# @@schemes['RSYNC'] = RSYNC +# end +# #=> URI::RSYNC +# +# URI.scheme_list +# #=> {"FTP"=>URI::FTP, "HTTP"=>URI::HTTP, "HTTPS"=>URI::HTTPS, +# "LDAP"=>URI::LDAP, "LDAPS"=>URI::LDAPS, "MAILTO"=>URI::MailTo, +# "RSYNC"=>URI::RSYNC} +# +# uri = URI("rsync://rsync.foo.com") +# #=> # +# +# == RFC References +# +# A good place to view an RFC spec is http://www.ietf.org/rfc.html +# +# Here is a list of all related RFC's. +# - RFC822[http://tools.ietf.org/html/rfc822] +# - RFC1738[http://tools.ietf.org/html/rfc1738] +# - RFC2255[http://tools.ietf.org/html/rfc2255] +# - RFC2368[http://tools.ietf.org/html/rfc2368] +# - RFC2373[http://tools.ietf.org/html/rfc2373] +# - RFC2396[http://tools.ietf.org/html/rfc2396] +# - RFC2732[http://tools.ietf.org/html/rfc2732] +# - RFC3986[http://tools.ietf.org/html/rfc3986] +# +# == Class tree +# +# - URI::Generic (in uri/generic.rb) +# - URI::FTP - (in uri/ftp.rb) +# - URI::HTTP - (in uri/http.rb) +# - URI::HTTPS - (in uri/https.rb) +# - URI::LDAP - (in uri/ldap.rb) +# - URI::LDAPS - (in uri/ldaps.rb) +# - URI::MailTo - (in uri/mailto.rb) +# - URI::Parser - (in uri/common.rb) +# - URI::REGEXP - (in uri/common.rb) +# - URI::REGEXP::PATTERN - (in uri/common.rb) +# - URI::Util - (in uri/common.rb) +# - URI::Escape - (in uri/common.rb) +# - URI::Error - (in uri/common.rb) +# - URI::InvalidURIError - (in uri/common.rb) +# - URI::InvalidComponentError - (in uri/common.rb) +# - URI::BadURIError - (in uri/common.rb) +# +# == Copyright Info # # Author:: Akira Yamada -# Documentation:: Akira Yamada , Dmitry V. Sabanin +# Documentation:: +# Akira Yamada +# Dmitry V. Sabanin +# Vincent Batts # License:: # Copyright (c) 2001 akira yamada # You can redistribute it and/or modify it under the same term as Ruby. # Revision:: $Id$ # -# See URI for documentation -# module URI # :stopdoc: diff --git a/lib/uri/common.rb b/lib/uri/common.rb index a8786b01f5..8d4e8c6d41 100644 --- a/lib/uri/common.rb +++ b/lib/uri/common.rb @@ -1,3 +1,4 @@ +#-- # = uri/common.rb # # Author:: Akira Yamada @@ -5,6 +6,8 @@ # License:: # You can redistribute it and/or modify it under the same term as Ruby. # +# See URI for general documentation +# module URI # @@ -634,7 +637,7 @@ module URI DEFAULT_PARSER.unescape(*arg) end alias decode unescape - end + end # module Escape extend Escape include REGEXP @@ -978,7 +981,7 @@ module URI end ary end -end +end # module URI module Kernel diff --git a/lib/uri/ftp.rb b/lib/uri/ftp.rb index a6ef692d53..53e3b28645 100644 --- a/lib/uri/ftp.rb +++ b/lib/uri/ftp.rb @@ -1,10 +1,11 @@ -# # = uri/ftp.rb # # Author:: Akira Yamada # License:: You can redistribute it and/or modify it under the same term as Ruby. # Revision:: $Id$ # +# See URI for general documentation +# require 'uri/generic' diff --git a/lib/uri/generic.rb b/lib/uri/generic.rb index a5121001e2..1bf4bcb080 100644 --- a/lib/uri/generic.rb +++ b/lib/uri/generic.rb @@ -1,11 +1,11 @@ - -# # = uri/generic.rb # # Author:: Akira Yamada # License:: You can redistribute it and/or modify it under the same term as Ruby. # Revision:: $Id$ # +# See URI for general documentation +# require 'uri/common' diff --git a/lib/uri/http.rb b/lib/uri/http.rb index 7d63ff52f9..3b108a4878 100644 --- a/lib/uri/http.rb +++ b/lib/uri/http.rb @@ -1,10 +1,11 @@ -# # = uri/http.rb # # Author:: Akira Yamada # License:: You can redistribute it and/or modify it under the same term as Ruby. # Revision:: $Id$ # +# See URI for general documentation +# require 'uri/generic' diff --git a/lib/uri/https.rb b/lib/uri/https.rb index 767f3338ab..7d242e7e79 100644 --- a/lib/uri/https.rb +++ b/lib/uri/https.rb @@ -1,10 +1,11 @@ -# # = uri/https.rb # # Author:: Akira Yamada # License:: You can redistribute it and/or modify it under the same term as Ruby. # Revision:: $Id$ # +# See URI for general documentation +# require 'uri/http' diff --git a/lib/uri/ldap.rb b/lib/uri/ldap.rb index c7ae83732c..56d748e59e 100644 --- a/lib/uri/ldap.rb +++ b/lib/uri/ldap.rb @@ -1,4 +1,3 @@ -# # = uri/ldap.rb # # Author:: @@ -9,6 +8,8 @@ # You can redistribute it and/or modify it under the same term as Ruby. # Revision:: $Id$ # +# See URI for general documentation +# require 'uri/generic' diff --git a/lib/uri/ldaps.rb b/lib/uri/ldaps.rb index bfea6ce5e7..42bbfe86ba 100644 --- a/lib/uri/ldaps.rb +++ b/lib/uri/ldaps.rb @@ -1,3 +1,10 @@ +# = uri/ldap.rb +# +# License:: You can redistribute it and/or modify it under the same term as Ruby. +# +# See URI for general documentation +# + require 'uri/ldap' module URI diff --git a/lib/uri/mailto.rb b/lib/uri/mailto.rb index 1e8f2da063..765528fb7f 100644 --- a/lib/uri/mailto.rb +++ b/lib/uri/mailto.rb @@ -1,10 +1,11 @@ -# # = uri/mailto.rb # # Author:: Akira Yamada # License:: You can redistribute it and/or modify it under the same term as Ruby. # Revision:: $Id$ # +# See URI for general documentation +# require 'uri/generic'