furi 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 62a4088dd18cb4ac9857d1512d78497ea28edd82
-  data.tar.gz: 3603fa3688b41b7b2ba700676db29f930bb11bf3
+  metadata.gz: 6b454ab79a6ac9b95fc85b8b8b2381c8e93715af
+  data.tar.gz: d84272345cd55a7aad224ce2b124423806f38301
 SHA512:
-  metadata.gz: 762e38c65d27a36323bf0ed410b25633e95788ce10a8a97163195918a47e038610defe4fe8f7f5b635d554c42b09cc3c5d4fbc1974dee9ec5d4e645d646923c1
-  data.tar.gz: 59f5e066fb0f09bcac768b99b11589d4257f391352e27d4d6874c2ae1d2d783f8bc56fde491906669b5aed5d22f16c17a8f424cbab486bd2b3123243c7b38873
+  metadata.gz: cc4227555a121e3c25d7c4ba32765659fa78678ff7aa2b500f0f6cbe384f9507e11bac3828bfd9eae097879e786395ac9b8113049447b5d1a1aff6a834a91108
+  data.tar.gz: 4b8d902ab961bff2d68a369da05c96f1cc142e6d71980a3cd24691de930807057b65016aa9ec16e8d7e52e2cdd5173068d108ac2d0128ced4ac9d497e671adbb

data/README.md

@@ -1,6 +1,9 @@
 # Furi
 
-TODO: Write a gem description
+Furi is a Friendly URI parsing library.
+Furi's philosophy is to make any operation possible in ONE LINE OF CODE.
+
+If there is an operation that takes more than one line of code to do with Furi, this is considered a terrible bug and you should create an issue.
 
 ## Installation
 
@@ -20,12 +23,107 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+I'll say it again: any operation should take exacly one line of code!
+Here are basic: 
+
+### Utility Methods
+
+
+``` ruby
+Furi.host("http://gusiev.com") # => "gusiev.com"
+Furi.port("http://gusiev.com") # => nil
+Furi.port!("http://gusiev.com") # => 80
+
+Furi.update("http://gusiev.com", protocol: '') # => "//gusiev.com"
+Furi.update("http://gusiev.com?source=google", query: {email: "a@b.com"}) 
+    # => "http://gusiev.com?email=a@b.com"
+Furi.merge("http://gusiev.com?source=google", query: {email: "a@b.com"}) 
+    # => "http://gusiev.com?source=google&email=a@b.com"
+
+Furi.build(protocol: '//', host: 'gusiev.com', path: '/assets/application.js') 
+    # => "//gusiev.com/assets/application.js"
+
+Furi.defaults("http://gusiev.com", subdomain: 'www') # => "http://www.gusiev.com"
+```
+
+### Working with Object
+
+``` ruby
+uri = Furi.parse("gusiev.com") 
+    # => #<Furi::Uri "gusiev.com"> 
+
+uri.port     # => nil
+uri.port!    # => 80
+uri.path     # => nil
+uri.path!    # => '/'
+uri.subdomain ||= 'www'
+uri.protocol = "//" # protocol abstract URL
+```
+
+### Processing Query String
+
+``` ruby
+uri = Furi.parse("/?person[first_name]=Bogdan&person[last_name]=Gusiev")
+
+uri.query_string # => "person[first_name]=Bogdan&person[last_name]=Gusiev"
+uri.query_tokens # => [person[first_name]=Bogdan, person[last_name]=Gusiev]
+uri.query # => {person: {first_name: Bogdan, last_name: 'Gusiev'}}
+
+uri.merge_query(person: {email: 'a@b.com'})
+    # => {person: {email: 'a@b.com', first_name: Bogdan, last_name: 'Gusiev'}}
+
+uri.merge_query(person: {email: 'a@b.com'})
+    # => {person: {email: 'a@b.com', first_name: Bogdan, last_name: 'Gusiev'}}
+```
+
+## Reference
+
+```
+                location                                            resource       
+                    |                                                ___|___     
+             _______|_______                                        /       \     
+            /               \                                      /         \    
+           /             authority                             request        \   
+          /        __________|_________                           |            \  
+         /        /                    \                    ______|______       \
+        /    userinfo                hostinfo              /             \       \
+       /       __|___                ___|___              /               \       \
+      /       /      \              /       \            /                 \       \
+     /   username  password       host      port       path               query   anchor
+    /      __|___   __|__    ______|______   |  _________|__________     ____|____   |
+   /      /      \ /     \  /             \ / \/                    \   /         \ / \
+   http://username:zhongguo@www.example.com:80/hello/world/article.html?name=bogdan#info
+    \_/                     \_/  \___/  \_/    \__________/ \       \_/
+     |                       |     |     |           |       \       |
+  protocol             subdomain   | domainzone  directory    \  extension
+                                   |     |                     \_____/  
+                             domainname  /                        |     
+                                    \___/                     filename 
+                                      |                                 
+                                    domain                   
+```
+
+
+Originated from [URI.js](http://medialize.github.io/URI.js/about-uris.html) parsing library.
+Giving credit...
+
+
+## TODO
+
+* rfc3986 validation
+* mailto protocol
+* escaping in path
+* case insensetivity:
+  * domain
+  * protocol
+* case sensitivity:
+  * path
+  * query
+  * anchor
+  * basic auth data ?
 
 ## Contributing
 
-1. Fork it ( https://github.com/[my-github-username]/furi/fork )
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request
+Contribute in the way you want. Branch names and other bla-bla-bla do not matter.
+
+

data/lib/furi.rb

@@ -3,18 +3,30 @@ require "uri"
 
 module Furi
 
-  PARTS =  [
+  autoload :QueryToken, 'furi/query_token'
+  autoload :Uri, 'furi/uri'
+  autoload :Utils, 'furi/utils'
+
+  ESSENTIAL_PARTS =  [
     :anchor, :protocol, :query_tokens,
     :path, :host, :port, :username, :password
   ]
+  COMBINED_PARTS = [
+    :hostinfo, :userinfo, :authority, :ssl, :domain, :domainname,
+    :domainzone, :request, :location, :query,
+    :extension, :filename
+  ]
+  PARTS = ESSENTIAL_PARTS + COMBINED_PARTS
+
   ALIASES = {
     protocol: [:schema, :scheme],
     anchor: [:fragment],
     host: [:hostname],
     username: [:user],
+    request: [:request_uri]
   }
 
-  DELEGATES = [:port!, :host!]
+  DELEGATES = [:port!, :host!, :path!, :home_page?]
 
   PROTOCOLS = {
     "http" => {port: 80, ssl: false},
@@ -32,6 +44,7 @@ module Furi
     "prospero" => {port: 1525},
   }
 
+
   SSL_MAPPING = {
     'http' => 'https',
     'ftp' => 'sftp',
@@ -42,22 +55,15 @@ module Furi
 
   ROOT = '/'
 
-  class Expressions
-    attr_accessor :protocol
-
-    def initialize
-      @protocol = /^[a-z][a-z0-9.+-]*$/i
-    end
-  end
-
-  def self.expressions
-    Expressions.new
-  end
-
+  # Parses a given string and return an URL object
   def self.parse(argument)
     Uri.new(argument)
   end
 
+  # Builds an URL from given parts
+  #
+  #   Furi.build(path: "/dashboard", host: 'example.com', protocol: "https")
+  #     # => "https://example.com/dashboard"
   def self.build(argument)
     Uri.new(argument).to_s
   end
@@ -65,19 +71,99 @@ module Furi
   class << self
     (PARTS + ALIASES.values.flatten + DELEGATES).each do |part|
       define_method(part) do |string|
-        Uri.new(string).send(part)
+        Uri.new(string)[part]
       end
     end
   end
 
+  # Replaces a given URL string with given parts
+  #
+  #   Furi.update("http://gusiev.com", protocol: 'https', subdomain: 'www')
+  #     # => "https://www.gusiev.com"
   def self.update(string, parts)
     parse(string).update(parts).to_s
   end
 
+  # Puts the default values for given URL that are not defined
+  #
+  #   Furi.defaults("gusiev.com/hello.html", protocol: 'http', path: '/index.html')
+  #     # => "http://gusiev.com/hello.html"
+  def self.defaults(string, parts)
+    parse(string).defaults(parts).to_s
+  end
+
+  # Replaces a given URL string with given parts.
+  # Same as update but works different for URL query parameter:
+  # merges newly specified parameters instead of replacing existing ones
+  #
+  #   Furi.merge("/hello.html?a=1", host: 'gusiev.com', query: {b: 2})
+  #     # => "gusiev.com/hello.html?a=1&b=2"
+  #
   def self.merge(string, parts)
     parse(string).merge(parts).to_s
   end
 
+
+  # Parses a query into nested paramters hash using a rack convension with square brackets.
+  #
+  #   Furi.parse_query("a[]=1&a[]=2")       # => {a: [1,2]}
+  #   Furi.parse_query("p[email]=a&a[two]=2") # => {a: {one: 1, two: 2}}
+  #   Furi.parse_query("p[one]=1&a[two]=2") # => {a: {one: 1, two: 2}}
+  #   Furi.serialize({p: {name: 'Bogdan Gusiev', email: 'bogdan@example.com', data: {one: 1, two: 2}}})
+  #     # => "p%5Bname%5D=Bogdan&p%5Bemail%5D=bogdan%40example.com&p%5Bdata%5D%5Bone%5D=1&p%5Bdata%5D%5Btwo%5D=2"
+  def self.parse_query(query)
+    return Furi::Utils.stringify_keys(query) if query.is_a?(Hash)
+
+    params = {}
+    query_tokens(query).each do |token|
+      parse_query_token(params, token.name, token.value)
+    end
+
+    return params
+  end
+
+  # Parses query key/value pairs from query string and returns them raw
+  # without organising them into hashes and without normalising them.
+  #
+  #   Furi.query_tokens("a=1&b=2").map {|k,v| "#{k} -> #{v}"}  # => ['a -> 1', 'b -> 2']
+  #   Furi.query_tokens("a=1&a=1&a=2").map {|k,v| "#{k} -> #{v}"}  # => ['a -> 1', 'a -> 1', 'a -> 2']
+  #   Furi.query_tokens("name=Bogdan&email=bogdan%40example.com") # => [name=Bogdan, email=bogdan@example.com]
+  #   Furi.query_tokens("a[one]=1&a[two]=2") # => [a[one]=1, a[two]=2]
+  def self.query_tokens(query)
+    case query
+    when Enumerable, Enumerator
+      query.map do |token|
+        QueryToken.parse(token)
+      end
+    when nil, ''
+      []
+    when String
+      query.gsub(/\A\?/, '').split(/[&;] */n, -1).map do |p|
+        QueryToken.parse(p)
+      end
+    else
+      raise ArgumentError, "Can not parse #{query.inspect} query tokens"
+    end
+  end
+
+  # Serializes query parameters into query string.
+  # Optionaly accepts a basic name space.
+  #
+  #   Furi.serialize({a: 1, b: 2}) # => "a=1&b=2"
+  #   Furi.serialize({a: [1,2]}) # => "a[]=1&a[]=2"
+  #   Furi.serialize({a: {b: 1, c:2}}) # => "a[b]=1&a[c]=2"
+  #   Furi.serialize({name: 'Bogdan', email: 'bogdan@example.com'}, "person")
+  #     # => "person[name]=Bogdan&person[email]=bogdan%40example.com"
+  #
+  def self.serialize(query, namespace = nil)
+    serialize_tokens(query, namespace).join("&")
+  end
+
+  class FormattingError < StandardError
+  end
+
+  protected
+
   def self.serialize_tokens(query, namespace = nil)
     case query
     when Hash
@@ -112,42 +198,6 @@ module Furi
     end
   end
 
-  def self.parse_nested_query(qs)
-
-    params = {}
-    query_tokens(qs).each do |token|
-      parse_query_token(params, token.name, token.value)
-    end
-
-    return params
-  end
-
-  def self.query_tokens(query)
-    case query
-    when Enumerable, Enumerator
-      query.map do |token|
-        case token
-        when QueryToken
-          token
-        when String
-          QueryToken.parse(token)
-        when Array
-          QueryToken.new(*token)
-        else
-          raise ArgumentError, "Can not parse query token #{token.inspect}"
-        end
-      end
-    when nil, ''
-      []
-    when String
-      query.gsub(/\A\?/, '').split(/[&;] */n).map do |p|
-        QueryToken.parse(p)
-      end
-    else
-      raise ArgumentError, "Can not parse #{query.inspect} query tokens"
-    end
-  end
-
   def self.parse_query_token(params, name, value)
     name =~ %r(\A[\[\]]*([^\[\]]+)\]*)
     namespace = $1 || ''
@@ -187,327 +237,4 @@ module Furi
     return params
   end
 
-  def self.serialize(query, namespace = nil)
-    serialize_tokens(query, namespace).join("&")
-  end
-
-  class QueryToken
-    attr_reader :name, :value
-
-    def self.parse(token)
-      k,v = token.split('=', 2).map { |s| ::URI.decode_www_form_component(s) }
-      new(k,v)
-    end
-
-    def initialize(name, value)
-      @name = name
-      @value = value
-    end
-
-    def to_a
-      [name, value]
-    end
-
-    def ==(other)
-      to_s == other.to_s
-    end
-
-    def to_s
-      "#{::URI.encode_www_form_component(name.to_s)}=#{::URI.encode_www_form_component(value.to_s)}"
-    end
-
-    def inspect
-      [name, value].join('=')
-    end
-  end
-
-  class Uri
-
-    attr_reader(*PARTS)
-
-    ALIASES.each do |origin, aliases|
-      aliases.each do |aliaz|
-        define_method(aliaz) do
-          send(origin)
-        end
-
-        define_method(:"#{aliaz}=") do |*args|
-          send(:"#{origin}=", *args)
-        end
-      end
-    end
-
-    def initialize(argument)
-      @query_tokens = []
-      case argument
-      when String
-        parse_uri_string(argument)
-      when Hash
-        update(argument)
-      end
-    end
-
-    def update(parts)
-      parts.each do |part, value|
-        send(:"#{part}=", value)
-      end
-      self
-    end
-
-    def merge(parts)
-      parts.each do |part, value|
-        case part.to_sym
-        when :query
-          merge_query(value)
-        else
-          send(:"#{part}=", value)
-        end
-      end
-      self
-    end
-
-    def merge_query(query)
-      case query
-      when Hash
-        self.query = self.query.merge(Furi::Utils.stringify_keys(query))
-      when String, Array
-        self.query_tokens += Furi.query_tokens(query)
-      when nil
-      else
-        raise ArgumentError, "#{query.inspect} can not be merged"
-      end
-    end
-
-    def userinfo
-      if username
-        [username, password].compact.join(":")
-      elsif password
-        raise FormattingError, "can not build URI with password but without username"
-      else
-        nil
-      end
-    end
-    
-    def host=(host)
-      @host = host
-    end
-
-    def to_s
-      result = []
-      if protocol
-        result.push(protocol.empty? ? "//" : "#{protocol}://")
-      end
-      if userinfo
-        result << userinfo
-      end
-      result << host if host
-      result << ":" << port if explicit_port
-      result << (host ? path : path!)
-      if query_tokens.any?
-        result << "?" << query_string
-      end
-      if anchor
-        result << "#" << anchor
-      end
-      result.join
-    end
-
-    
-    def request
-      result = []
-      result << path!
-      result << "?" << query_string if query_tokens.any?
-      result.join
-    end
-
-    def request_uri
-      request
-    end
-
-    def query
-      return @query if query_level?
-      @query = Furi.parse_nested_query(query_tokens)
-    end
-
-
-    def query=(value)
-      @query = nil
-      @query_tokens = []
-      case value
-      when String, Array
-        @query_tokens = Furi.query_tokens(value)
-      when Hash
-        @query = value
-        @query_tokens = Furi.serialize_tokens(value)
-      when nil
-      else
-        raise ArgumentError, 'Query can only be Hash or String'
-      end
-    end
-
-    def port=(port)
-      if port != nil
-        @port = port.to_i
-        if @port == 0
-          raise ArgumentError, "port should be an Integer > 0"
-        end
-      else
-        @port = nil
-      end
-      @port
-    end
-
-    def query_tokens=(tokens)
-      @query = nil
-      @query_tokens = tokens
-    end
-
-    def username=(username)
-      @username = username.nil? ? nil : username.to_s
-    end
-
-    def password=(password)
-      @password = password.nil? ? nil : password.to_s
-    end
-
-    def path=(path)
-      @path = path.to_s
-    end
-
-    def protocol=(protocol)
-      @protocol = protocol ? protocol.gsub(%r{:/?/?\Z}, "") : nil
-    end
-
-    def query_string
-      if query_level?
-        Furi.serialize(@query)
-      else
-        query_tokens.join("&")
-      end
-    end
-
-    def expressions
-      Furi.expressions
-    end
-
-    def port!
-      port || default_port
-    end
-
-    def default_port
-      protocol && PROTOCOLS[protocol] ? PROTOCOLS[protocol][:port] : nil
-    end
-
-    def ssl?
-      !!(protocol && PROTOCOLS[protocol][:ssl])
-    end
-
-    def ssl
-      ssl?
-    end
-
-    def ssl=(ssl)
-      self.protocol = find_protocol_for_ssl(ssl)
-    end
-
-    def filename
-      path.split("/").last
-    end
-
-    def default_web_port?
-      WEB_PROTOCOL.any? do |web_protocol|
-        PROTOCOLS[web_protocol][:port] == port!
-      end
-    end
-
-    def web_protocol?
-      WEB_PROTOCOL.include?(protocol)
-    end
-    
-    def resource
-      [request, anchor].compact.join("#")
-    end
-
-    def path!
-      path || ROOT
-    end
-
-    def host!
-      host || ""
-    end
-
-    def ==(other)
-      to_s == other.to_s
-    end
-    
-    protected
-
-    def query_level?
-      !!@query
-    end
-
-    def explicit_port
-      port == default_port ? nil : port
-    end
-
-    def parse_uri_string(string)
-      string, *@anchor = string.split("#")
-      @anchor = @anchor.empty? ? nil : @anchor.join("#")
-      if string.include?("?")
-        string, query_string = string.split("?", 2)
-        self.query_tokens = Furi.query_tokens(query_string)
-      end
-
-      if string.include?("://")
-        @protocol, string = string.split(":", 2)
-        @protocol = '' if @protocol.empty?
-      end
-      if string.start_with?("//")
-        @protocol ||= ''
-        string = string[2..-1]
-      end
-      parse_authority(string)
-    end
-
-    def parse_authority(string)
-      if string.include?("/")
-        string, @path = string.split("/", 2)
-        @path = "/" + @path
-      end
-
-      if string.include?("@")
-        userinfo, string = string.split("@", 2)
-        @username, @password = userinfo.split(":", 2)
-      end
-      host, port = string.split(":", 2)
-      self.host = host if host
-      self.port = port if port
-    end
-
-    def find_protocol_for_ssl(ssl)
-      if SSL_MAPPING.key?(protocol)
-        ssl ? SSL_MAPPING[protocol] : protocol
-      elsif SSL_MAPPING.values.include?(protocol)
-        ssl ? protocol : SSL_MAPPING.invert[protocol]
-      else
-        raise ArgumentError, "Can not specify ssl for #{protocol.inspect} protocol"
-      end
-    end
-
-  end
-
-  class FormattingError < StandardError
-  end
-
-  class Utils
-    class << self
-      def stringify_keys(hash)
-        result = {}
-        hash.each_key do |key|
-          result[key.to_s] = hash[key]
-        end
-        result
-      end
-    end
-  end
 end