Permalink
Browse files

Updated documentation to use Markdown.

  • Loading branch information...
1 parent 0ac9e85 commit e73b2e40332cbb4f754b66c82dcd60fc4235a15f @sporkmonger committed Apr 10, 2011
Showing with 135 additions and 116 deletions.
  1. +20 −20 CHANGELOG
  2. +0 −60 README
  3. +76 −0 README.md
  4. +0 −3 lib/addressable/idna/pure.rb
  5. +29 −25 lib/addressable/template.rb
  6. +6 −4 lib/addressable/uri.rb
  7. +1 −1 lib/addressable/version.rb
  8. +3 −3 tasks/yard.rake
View
@@ -1,43 +1,43 @@
-=== Addressable 2.2.5
+## Addressable 2.2.5
- 'parsing' a pre-parsed URI object is now a dup operation
- introduced conditional support for libidn
- fixed normalization issue on ampersands in query strings
- added additional tests around handling of query strings
-=== Addressable 2.2.4
+## Addressable 2.2.4
- added origin support from draft-ietf-websec-origin-00
- resolved issue with attempting to navigate below root
- fixed bug with string splitting in query strings
-=== Addressable 2.2.3
+## Addressable 2.2.3
- added :flat_array notation for query strings
-=== Addressable 2.2.2
+## Addressable 2.2.2
- fixed issue with percent escaping of '+' character in query strings
-=== Addressable 2.2.1
+## Addressable 2.2.1
- added support for application/x-www-form-urlencoded.
-=== Addressable 2.2.0
+## Addressable 2.2.0
- added site methods
- improved documentation
-=== Addressable 2.1.2
+## Addressable 2.1.2
- added HTTP request URI methods
- better handling of Windows file paths
- validation_deferred boolean replaced with defer_validation block
- normalization of percent-encoded paths should now be correct
- fixed issue with constructing URIs with relative paths
- fixed warnings
-=== Addressable 2.1.1
+## Addressable 2.1.1
- more type checking changes
- fixed issue with unicode normalization
- added method to find template defaults
- symbolic keys are now allowed in template mappings
- numeric values and symbolic values are now allowed in template mappings
-=== Addressable 2.1.0
+## Addressable 2.1.0
- refactored URI template support out into its own class
- removed extract method due to being useless and unreliable
- removed Addressable::URI.expand_template
@@ -51,15 +51,15 @@
- worked around issue with freezing URIs
- improved specs
-=== Addressable 2.0.2
+## Addressable 2.0.2
- fixed issue with URI template expansion
- fixed issue with percent escaping characters 0-15
-=== Addressable 2.0.1
+## Addressable 2.0.1
- fixed issue with query string assignment
- fixed issue with improperly encoded components
-=== Addressable 2.0.0
+## Addressable 2.0.0
- the initialize method now takes an options hash as its only parameter
- added query_values method to URI class
- completely replaced IDNA implementation with pure Ruby
@@ -74,20 +74,20 @@
- updated URI Template code to match v 03 of the draft spec
- added a bunch of new specifications
-=== Addressable 1.0.4
+## Addressable 1.0.4
- switched to using RSpec's pending system for specs that rely on IDN
- fixed issue with creating URIs with paths that are not prefixed with '/'
-=== Addressable 1.0.3
+## Addressable 1.0.3
- implemented a hash method
-=== Addressable 1.0.2
+## Addressable 1.0.2
- fixed minor bug with the extract_mapping method
-=== Addressable 1.0.1
+## Addressable 1.0.1
- fixed minor bug with the extract_mapping method
-=== Addressable 1.0.0
+## Addressable 1.0.0
- heuristic parse method added
- parsing is slightly more strict
- replaced to_h with to_hash
@@ -96,16 +96,16 @@
- improved heckle rake task
- no surviving heckle mutations
-=== Addressable 0.1.2
+## Addressable 0.1.2
- improved normalization
- fixed bug in joining algorithm
- updated specifications
-=== Addressable 0.1.1
+## Addressable 0.1.1
- updated documentation
- added URI Template variable extraction
-=== Addressable 0.1.0
+## Addressable 0.1.0
- initial release
- implementation based on RFC 3986, 3987
- support for IRIs via libidn
View
@@ -1,60 +0,0 @@
-== About
-
-Homepage:: Addressable[http://addressable.rubyforge.org/]
-Authors:: Bob Aman (mailto:bob@sporkmonger.com)
-Copyright:: Copyright 2010 Bob Aman
-License:: MIT
-
-Addressable is a replacement for the URI implementation that is part of
-Ruby's standard library. It more closely conforms to the relevant RFCs and
-adds support for IRIs and URI templates. Additionally, it provides extensive
-support for URI templates.
-
-== Classes
-- {Addressable::URI}
-- {Addressable::Template}
-
-== Example usage
- require "addressable/uri"
-
- uri = Addressable::URI.parse("http://example.com/path/to/resource/")
- uri.scheme
- #=> "http"
- uri.host
- #=> "example.com"
- uri.path
- #=> "/path/to/resource/"
-
- uri = Addressable::URI.parse("http://www.詹姆斯.com/")
- uri.normalize
- #=> #<Addressable::URI:0xc9a4c8 URI:http://www.xn--8ws00zhy3a.com/>
-
- require "addressable/template"
-
- template = Addressable::Template.new("http://example.com/{-list|+|query}/")
- template.expand({
- "query" => "an example query".split(" ")
- })
- #=> #<Addressable::URI:0xc9d95c URI:http://example.com/an+example+query/>
-
- template = Addressable::Template.new(
- "http://example.com/{-join|&|one,two,three}/"
- )
- template.partial_expand({"one" => "1", "three" => 3}).pattern
- #=> "http://example.com/?one=1{-prefix|&two=|two}&three=3"
-
- template = Addressable::Template.new(
- "http://{host}/{-suffix|/|segments}?{-join|&|one,two,bogus}\#{fragment}"
- )
- uri = Addressable::URI.parse(
- "http://example.com/a/b/c/?one=1&two=2#foo"
- )
- template.extract(uri)
- #=>
- # {
- # "host" => "example.com",
- # "segments" => ["a", "b", "c"],
- # "one" => "1",
- # "two" => "2",
- # "fragment" => "foo"
- # }
View
@@ -0,0 +1,76 @@
+# Addressable
+
+<dl>
+ <dt>Homepage</dt><dd><a href="http://addressable.rubyforge.org/">addressable.rubyforge.org</a></dd>
+ <dt>Author</dt><dd><a href="mailto:bob@sporkmonger.com">Bob Aman</a></dd>
+ <dt>Copyright</dt><dd>Copyright © 2010 Bob Aman</dd>
+ <dt>License</dt><dd>Apache 2.0</dd>
+</dl>
+
+# Description
+
+Addressable is a replacement for the URI implementation that is part of
+Ruby's standard library. It more closely conforms to the relevant RFCs and
+adds support for IRIs and URI templates. Additionally, it provides extensive
+support for URI templates.
+
+# Reference
+
+- {Addressable::URI}
+- {Addressable::Template}
+
+# Example usage
+
+ require "addressable/uri"
+
+ uri = Addressable::URI.parse("http://example.com/path/to/resource/")
+ uri.scheme
+ #=> "http"
+ uri.host
+ #=> "example.com"
+ uri.path
+ #=> "/path/to/resource/"
+
+ uri = Addressable::URI.parse("http://www.詹姆斯.com/")
+ uri.normalize
+ #=> #<Addressable::URI:0xc9a4c8 URI:http://www.xn--8ws00zhy3a.com/>
+
+ require "addressable/template"
+
+ template = Addressable::Template.new("http://example.com/{-list|+|query}/")
+ template.expand({
+ "query" => "an example query".split(" ")
+ })
+ #=> #<Addressable::URI:0xc9d95c URI:http://example.com/an+example+query/>
+
+ template = Addressable::Template.new(
+ "http://example.com/{-join|&|one,two,three}/"
+ )
+ template.partial_expand({"one" => "1", "three" => 3}).pattern
+ #=> "http://example.com/?one=1{-prefix|&two=|two}&three=3"
+
+ template = Addressable::Template.new(
+ "http://{host}/{-suffix|/|segments}?{-join|&|one,two,bogus}\#{fragment}"
+ )
+ uri = Addressable::URI.parse(
+ "http://example.com/a/b/c/?one=1&two=2#foo"
+ )
+ template.extract(uri)
+ #=>
+ # {
+ # "host" => "example.com",
+ # "segments" => ["a", "b", "c"],
+ # "one" => "1",
+ # "two" => "2",
+ # "fragment" => "foo"
+ # }
+
+# Install
+
+* sudo gem install addressable
+
+You may optionally turn on native IDN support by installing libidn and the
+idn gem:
+
+* brew install libidn
+* sudo gem install idn
@@ -24,8 +24,6 @@
module Addressable
- # A pure Ruby implementation of IDNA. C was eschewed for the sake of JRuby,
- # and because performance is largely irrelevant here.
module IDNA
# This module is loosely based on idn_actionmailer by Mick Staugaard,
# the unicode library by Yoshida Masato, and the punycode implementation
@@ -40,7 +38,6 @@ module IDNA
# http://www.yoshidam.net/Ruby.html#unicode
# http://rubyforge.org/frs/?group_id=2550
- # :stopdoc:
ACE_PREFIX = "xn--"
@@ -63,7 +63,7 @@ class MatchData
#
# @param [Addressable::URI] uri
# The URI that the template was matched against.
- def initialize(uri, template, mapping) # :nodoc:
+ def initialize(uri, template, mapping)
@uri = uri.dup.freeze
@template = template
@mapping = mapping.dup.freeze
@@ -154,20 +154,22 @@ def inspect
#
# @param [#restore, #match] processor
# A template processor object may optionally be supplied.
- #
- # The object should respond to either the <tt>restore</tt> or
- # <tt>match</tt> messages or both. The <tt>restore</tt> method should take
- # two parameters: [String] name and [String] value. The <tt>restore</tt>
- # method should reverse any transformations that have been performed on the
- # value to ensure a valid URI. The <tt>match</tt> method should take a
- # single parameter: [String] name. The <tt>match</tt> method should return
- # a <tt>String</tt> containing a regular expression capture group for
- # matching on that particular variable. The default value is ".*?". The
- # <tt>match</tt> method has no effect on multivariate operator expansions.
+ #
+ # The object should respond to either the <tt>restore</tt> or
+ # <tt>match</tt> messages or both. The <tt>restore</tt> method should
+ # take two parameters: `[String] name` and `[String] value`.
+ # The <tt>restore</tt> method should reverse any transformations that
+ # have been performed on the value to ensure a valid URI.
+ # The <tt>match</tt> method should take a single
+ # parameter: `[String] name`. The <tt>match</tt> method should return
+ # a <tt>String</tt> containing a regular expression capture group for
+ # matching on that particular variable. The default value is `".*?"`.
+ # The <tt>match</tt> method has no effect on multivariate operator
+ # expansions.
#
# @return [Hash, NilClass]
- # The <tt>Hash</tt> mapping that was extracted from the URI, or
- # <tt>nil</tt> if the URI didn't match the template.
+ # The <tt>Hash</tt> mapping that was extracted from the URI, or
+ # <tt>nil</tt> if the URI didn't match the template.
#
# @example
# class ExampleProcessor
@@ -214,20 +216,22 @@ def extract(uri, processor=nil)
#
# @param [#restore, #match] processor
# A template processor object may optionally be supplied.
- #
- # The object should respond to either the <tt>restore</tt> or
- # <tt>match</tt> messages or both. The <tt>restore</tt> method should take
- # two parameters: [String] name and [String] value. The <tt>restore</tt>
- # method should reverse any transformations that have been performed on the
- # value to ensure a valid URI. The <tt>match</tt> method should take a
- # single parameter: [String] name. The <tt>match</tt> method should return
- # a <tt>String</tt> containing a regular expression capture group for
- # matching on that particular variable. The default value is ".*?". The
- # <tt>match</tt> method has no effect on multivariate operator expansions.
+ #
+ # The object should respond to either the <tt>restore</tt> or
+ # <tt>match</tt> messages or both. The <tt>restore</tt> method should
+ # take two parameters: `[String] name` and `[String] value`.
+ # The <tt>restore</tt> method should reverse any transformations that
+ # have been performed on the value to ensure a valid URI.
+ # The <tt>match</tt> method should take a single
+ # parameter: `[String] name`. The <tt>match</tt> method should return
+ # a <tt>String</tt> containing a regular expression capture group for
+ # matching on that particular variable. The default value is `".*?"`.
+ # The <tt>match</tt> method has no effect on multivariate operator
+ # expansions.
#
# @return [Hash, NilClass]
- # The <tt>Hash</tt> mapping that was extracted from the URI, or
- # <tt>nil</tt> if the URI didn't match the template.
+ # The <tt>Hash</tt> mapping that was extracted from the URI, or
+ # <tt>nil</tt> if the URI didn't match the template.
#
# @example
# class ExampleProcessor
@@ -26,6 +26,8 @@
require "addressable/version"
require "addressable/idna"
+##
+# Addressable is a library for processing links and URIs.
module Addressable
##
# This is an implementation of a URI parser based on
@@ -398,10 +400,10 @@ class << self
# is passed, the <code>String</code> must be formatted as a regular
# expression character class. (Do not include the surrounding square
# brackets.) For example, <code>"b-zB-Z0-9"</code> would cause
- # everything but the letters 'b' through 'z' and the numbers '0' through
- # '9' to be percent encoded. If a <code>Regexp</code> is passed, the
- # value <code>/[^b-zB-Z0-9]/</code> would have the same effect. A set of
- # useful <code>String</code> values may be found in the
+ # everything but the letters 'b' through 'z' and the numbers '0'
+ # through '9' to be percent encoded. If a <code>Regexp</code> is passed,
+ # the value <code>/[^b-zB-Z0-9]/</code> would have the same effect. A
+ # set of useful <code>String</code> values may be found in the
# <code>Addressable::URI::CharacterClasses</code> module. The default
# value is the reserved plus unreserved character classes specified in
# <a href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>.
@@ -25,7 +25,7 @@
# Used to prevent the class/module from being loaded more than once
if !defined?(Addressable::VERSION)
module Addressable
- module VERSION #:nodoc:
+ module VERSION
MAJOR = 2
MINOR = 2
TINY = 5
View
@@ -8,10 +8,10 @@ begin
desc "Generate Yardoc documentation"
YARD::Rake::YardocTask.new do |yardoc|
yardoc.name = "yard"
- yardoc.options = ["--verbose"]
- yardoc.files = [
+ yardoc.options = ["--verbose", "--markup", "markdown"]
+ yardoc.files = FileList[
"lib/**/*.rb", "ext/**/*.c", "README", "CHANGELOG", "LICENSE"
- ]
+ ].exclude(/idna/)
end
end

0 comments on commit e73b2e4

Please sign in to comment.