redhead 0.0.1

data/lib/redhead.rb

@@ -0,0 +1,37 @@
+# Copyright (c) 2010 Adam Prescott
+# Licensed under the MIT license. See LICENSE.
+
+module Redhead
+  
+  # The character used to separate raw header names from their values.
+  HEADER_NAME_VALUE_SEPARATOR_CHARACTER = ":"
+  
+  # The actual pattern to split header name from value. Uses the above character.
+  HEADER_NAME_VALUE_SEPARATOR_PATTERN = /\s*#{HEADER_NAME_VALUE_SEPARATOR_CHARACTER}\s*/
+  
+  # The separator between header lines and regular body content.
+  HEADERS_SEPARATOR = "\n\n"
+  
+  # The actual pattern used to split headers from content.
+  HEADERS_SEPARATOR_PATTERN = /#{HEADERS_SEPARATOR}/m
+  
+  # The default code to convert a given key to a raw header name.
+  TO_RAW = lambda { |key| key.to_s.split(/_/).map(&:capitalize).join("-") }
+  
+  # The default code to convert a given raw header name to a key.
+  TO_KEY = lambda { |raw| raw.split(/[^a-z_]+/i).join("_").downcase.to_sym }
+  
+  # Method wrapping TO_RAW, to allow overriding for customisation.
+  def self.to_raw
+    TO_RAW
+  end
+  
+  # Method wrapping TO_KEY, to allow overriding for customisation.
+  def self.to_key
+    TO_KEY
+  end
+end
+
+require "redhead/header"
+require "redhead/header_set"
+require "redhead/redhead_string"

data/lib/redhead/header.rb

@@ -0,0 +1,83 @@
+module Redhead
+  class Header
+    attr_accessor :key, :raw, :value
+    attr_writer :to_key, :to_raw
+    
+    def initialize(key, raw, value)
+      @key = key
+      @raw = raw
+      @value = value
+    end
+    
+    # Parses a string representing a header. Uses HEADER_NAME_VALUE_SEPARATOR_PATTERN
+    # to determine the name and value parts of the string.
+    # 
+    # With a given block, the parsed raw header name is passed to the block and the result is
+    # used as the key name. If no block is given, then the default is used to create the key
+    # name.
+    def self.parse(header_string, &block)
+      header_string =~ HEADER_NAME_VALUE_SEPARATOR_PATTERN
+      raw = $`
+      value = $'
+      
+      to_key_block = block || Redhead.to_key
+      key = to_key_block[raw]
+      
+      header = new(key, raw, value)
+      
+      header
+    end
+    
+    # Returns the header as a string. If raw_name is given, this value is used as the raw header
+    # name. If raw_name is not given, do one of two things:
+    # 
+    # * If a block is given, pass #key to the block and use the result as the raw header name.
+    # * If a block is not given, use #raw as the raw header name.
+    def to_s(raw_name = nil)
+      r = raw_name || (block_given? ? yield(key) : raw)
+      "#{r}#{Redhead::HEADER_NAME_VALUE_SEPARATOR_CHARACTER} #{value}"
+    end
+    
+    # Does the same thing as #to_s, but instead of calling #raw in the last case, it calls #raw!.
+    def to_s!(raw_name = nil)
+      r = raw_name || (block_given? ? yield(key) : raw!)
+      "#{r}#{Redhead::HEADER_NAME_VALUE_SEPARATOR_CHARACTER} #{value}"
+    end
+    
+    # Calls #to_key with #raw as the argument.
+    def key!
+      to_key[raw]
+    end
+    
+    # Calls #to_raw with #key as the argument. By-passes the stored raw header name and reproduces
+    # it with #to_raw dynamically.
+    def raw!
+      to_raw[key]
+    end
+    
+    def inspect
+      "{ #{key.inspect} => #{value.inspect} }"
+    end
+    
+    # Returns true if other_header has the same raw header name and value as self.
+    def ==(other_header)
+      raw   == other_header.raw &&
+      value == other_header.value
+    end
+    
+    # Returns the Proc object used to convert keys to raw header names. Defaults to Redhead.to_raw.
+    def to_raw
+      @to_raw || Redhead.to_raw
+    end
+    
+    # Returns the Proc object used to convert keys to raw header names. Defaults to Redhead.to_raw.
+    def to_key
+      @to_key || Redhead.to_key
+    end
+    
+    # Returns true if to_raw[to_key[raw]] == raw, otherwise, false.
+    def reversible?
+      to_raw[to_key[raw]] == raw
+    end
+  end
+end

data/lib/redhead/header_set.rb

@@ -0,0 +1,134 @@
+module Redhead
+  class HeaderSet
+    include Enumerable
+    
+    # Sets the headers of the set to _headers_. _headers_ is assumed to be ordered.
+    def initialize(headers)
+      @headers = headers
+    end
+    
+    # Parses lines of header strings with Header.parse. Returns a new HeaderSet object
+    # for the parsed headers.
+    def self.parse(header_string, &block)
+      headers = []
+      header_string.split("\n").each do |str|
+        headers << Redhead::Header.parse(str, &block)
+      end
+      
+      new(headers)
+    end
+    
+    # Yields each header in the set.
+    def each
+      @headers.each { |h| yield h }
+    end
+    
+    # Returns true if the set of headers is empty.
+    def empty?
+      @headers.empty?
+    end
+    
+    # Returns the first header found which has Header#key matching _key_.
+    def [](key)
+      @headers.find { |header| header.key == key }
+    end
+    
+    # If there is a header in the set with a key matching _key_, then set its value to _value_.
+    # If there is no header matching _key_, create a new header with the given key and value,
+    # with a raw header equal to to_raw[key]. Sets the new header's to_raw to self#to_raw.
+    def []=(key, value)
+      h = self[key]      
+      if h
+        h.value = value
+      else
+        new_header = Redhead::Header.new(key, to_raw[key], value)
+        new_header.to_raw = to_raw
+        self << new_header
+      end
+    end
+    
+    # Adds _header_ to the set of headers.
+    def <<(header)
+      @headers << header
+    end
+    
+    # Similar to #[]= but allows manually setting the value of Header#raw to _raw_.
+    def add(key, value, raw = nil)
+      new_header = Redhead::Header.new(key, raw || to_raw[key], value)
+      new_header.to_raw = to_raw
+      self << new_header
+      new_header
+    end
+    
+    # Removes any headers with key names matching _key_ from the set.
+    def delete(key)
+      header = self[key]
+      @headers.reject! { |header| header.key == key } ? header : nil
+    end
+    
+    # Calls #to_s on each header in the set, joining the result with newlines.
+    # 
+    # If _hash_ has a key matching a header in the set, passes the value for that key in the hash
+    # to Header#to_s. If _hash_ has no key for the header being iterated over, passes the given
+    # block to Header#to_s instead.
+    def to_s(hash = {}, &block)
+      return @headers.map { |header| header.to_s }.join("\n") if hash.empty? && !block_given?
+      
+      @headers.map do |header|
+        if hash.has_key?(header.key)
+          header.to_s(hash[header.key])
+        else
+          header.to_s(&block)
+        end
+      end.join("\n")
+    end
+    
+    # If a block is given, passes the block to Header#to_s! otherwise passes #to_raw instead. Joins
+    # the result with newlines.
+    def to_s!(&block)
+      blk = block || to_raw
+      @headers.map { |header| header.to_s!(&blk) }.join("\n")
+    end
+    
+    # Returns true if Header#reversible? is true for each header in the set, otherwise false.
+    def reversible?
+      all? { |header| header.reversible? }
+    end
+    
+    # Returns the Proc to be used to convert key names to raw header names. Defaults to Redhead.to_raw.
+    def to_raw
+      @to_raw || Redhead.to_raw
+    end
+    
+    # Sets HeaderSet#to_raw to _new_to_raw_. Sets Header#to_raw for each header in the set to _new_to_raw_.
+    def to_raw=(new_to_raw)
+      @to_raw = new_to_raw
+      each { |header| header.to_raw = new_to_raw }
+    end
+    
+    # Returns the Proc to be used to convert raw header names to key names. Defaults to Redhead.to_key.
+    def to_key
+      @to_key || Redhead.to_key
+    end
+    
+    # Sets HeaderSet#to_raw to _new_to_raw_. Sets Header#to_raw for each header in the set to _new_to_raw_.
+    def to_key=(new_to_key)
+      @to_key = new_to_key
+      each { |header| header.to_key = new_to_key }
+    end
+    
+    def inspect
+      "{ #{@headers.map { |header| header.inspect }.join(", ")} }"
+    end
+    
+    # Returns true if, for each header in the set, there is a header in _other_ for which header#==(other_header)
+    # is true. Otherwise, returns false.
+    def ==(other)
+      @headers.all? do |header|
+        other.find do |other_header|
+          header == other_header
+        end
+      end
+    end
+  end
+end

data/lib/redhead/redhead_string.rb

@@ -0,0 +1,62 @@
+require "delegate"
+
+module Redhead
+  class String < SimpleDelegator
+    attr_reader :headers, :string
+    
+    class << self
+      alias_method :[], :new
+    end
+    
+    # Takes _string_, splits the headers from the content using HEADERS_SEPARATOR_PATTERN, then
+    # creates the headers by calling HeaderSet.parse, passing in _block_. Sets #to_key to _block_,
+    # and calls super with the main body content as an argument.
+    def initialize(string, &block)
+      string =~ HEADERS_SEPARATOR_PATTERN
+      @string = $'
+      super(@string)
+      
+      @headers = Redhead::HeaderSet.parse($`, &block)
+      @headers.to_key = block
+    end
+    
+    # Returns the main body content wrapped in the Redhead String object.
+    def to_s
+      __getobj__
+    end
+    
+    def inspect
+      "+#{string.inspect}"
+    end
+    
+    # Returns true if self.headers == other.headers and self.string == other.string.
+    def ==(other)
+      headers == other.headers && string == other.string
+    end
+    
+    # Modifies the headers in the set, using the given _hash_, which has the form
+    # 
+    #     { :some_header => { :raw => a, :key => b }, :another_header => ..., ... }
+    # 
+    # Change the header with key :some_header such that its new raw name is _a_ and its new key name
+    # is _b_. Returns a HeaderSet object containing the changed Header objects.
+    def headers!(hash)
+      changing = headers.select { |header| hash.has_key?(header.key) }
+      
+      # modifies its elements!
+      changing.each do |header|
+        new_values = hash[header.key]
+        header.raw = new_values[:raw] if new_values[:raw]
+        header.key = new_values[:key] if new_values[:key]
+      end
+      
+      Redhead::HeaderSet.new(changing)
+    end
+  end
+  
+  private
+  
+  def __getobj__
+    string
+  end
+end

data/rakefile

@@ -0,0 +1,11 @@
+require "rake"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:test) do |t|
+  t.rspec_opts = "-I test --color --format nested"
+  t.pattern = "test/**/*_spec.rb"
+  t.verbose = false
+  t.fail_on_error = true
+end
+
+task :default => :test

data/test/header_set_spec.rb

@@ -0,0 +1,344 @@
+require "test_helper"
+
+describe Redhead::HeaderSet do
+  before(:each) do
+    @headers = []
+    ("a".."c").map { |e| @headers << Redhead::Header.new(e.to_sym, "header_#{e}", "value_#{e}") }
+    @full_header_set_string = ("a".."c").map { |e| "header_#{e}: value_#{e}" }.join("\n")
+    @header = @headers.first
+    @first_header_key = :a
+    @header_set = Redhead::HeaderSet.new(@headers)
+    @default_to_raw = Redhead.to_raw
+    @default_to_key = Redhead.to_key
+    
+    @reversible_headers = Redhead::HeaderSet.parse("A-Header: one\nA-Header-Two: two")
+    @irreversible_headers = Redhead::HeaderSet.parse("a_header: one\na_header_two: two")
+  end
+    
+  context "as a class" do
+    describe ".parse" do
+      it "calls Header.parse on each header line, to create a set of headers" do
+        string = @full_header_set_string + Redhead::HEADERS_SEPARATOR + "some content goes here"
+        header_lines = @full_header_set_string.split("\n")
+        parsed_header_set = Redhead::HeaderSet.new(header_lines.map { |header_line| Redhead::Header.parse(header_line) })
+        Redhead::HeaderSet.parse(@full_header_set_string).should == parsed_header_set
+      end
+    end
+    
+    context "with a block" do
+      it "uses the given block as to_key" do
+        Redhead::HeaderSet.parse(@full_header_set_string) { :foo }.each { |h| h.key.should == :foo }
+      end
+      
+      it "does not set to_key on each parsed header object in the set" do
+        # note: Proc#== bug!
+        to_key =  proc { :foo }
+        Redhead::HeaderSet.parse(@full_header_set_string, &to_key).each { |header| header.to_key.should_not == to_key }
+      end
+    end
+  end
+  
+  it "is Enumerable and responds to #each" do
+    @header_set.is_a?(Enumerable).should be_true
+    @header_set.respond_to?(:each).should be_true
+  end
+  
+  describe "#[]" do
+    context "for a key with a corresponding header" do
+      it "takes a symbolic header name key and returns a header" do
+        @header_set[:a].is_a?(Redhead::Header).should be_true
+      end
+    end
+    
+    context "for a key with no corresponding header" do
+      it "returns nil" do
+        @header_set[:something_non_existent].should be_nil
+      end
+    end
+  end
+  
+  describe "#[]=" do
+    context "for a key with a corresponding header" do
+      it "sets a new header value" do
+        new_value = "new value"
+        @header_set[@first_header_key].should_not be_nil
+        @header_set[@first_header_key] = new_value
+        @header_set[@first_header_key].value.should == new_value
+      end
+    end
+    
+    context "for a key with no corresponding header" do
+      it "creates a new header with this value" do
+        new_value = "some brand new value"
+        @header_set[:brand_new_key] = new_value
+        @header_set[:brand_new_key].should_not be_nil
+        @header_set[:brand_new_key].value.should == new_value
+      end
+      
+      it "calls #to_raw to create the value of #raw" do
+        @header_set.to_raw = proc { "WHOA!" }
+        @header_set[:brand_new_key] = "some value"
+        @header_set[:brand_new_key].raw.should == "WHOA!"
+      end
+      
+      it "sets new_header#to_raw to header_set#to_raw" do
+        @header_set.to_raw = proc { "Whoa!" }
+        @header_set[:brand_new_key] = "some value"
+        @header_set[:brand_new_key].to_raw.should == @header_set.to_raw
+      end
+    end
+  end
+  
+  describe "#add" do
+    context "being equivalent to #[]=" do
+      def new_header(header_string)
+        @header_set[:brand_new_key].should be_nil
+        @header_set.add(:brand_new_key, "some value")
+        @header_set[:brand_new_key].should_not be_nil
+      end
+    
+      it "parses the given header string, adds the new header to self and returns that header" do
+        new_header(@header_set)
+      end
+    
+      it "creates a new header with the given value" do
+        new_header(@header_set)
+        @header_set[:brand_new_key].value.should == "some value"
+      end
+      
+      it "returns a Redhead::Header object" do
+        @header_set.add(:brand_new_key, "some value").class.should == Redhead::Header
+      end
+      
+      it "calls #to_raw to create the value of #raw" do
+        @header_set.add(:brand_new_key, "some value")
+        @header_set[:brand_new_key].raw.should == "Brand-New-Key"
+        
+        @header_set.to_raw = proc { "Nothing really" }
+        @header_set.add(:something_or_other, "something or other")
+        @header_set[:something_or_other].raw.should == "Nothing really"
+      end
+      
+      it "sets new_header#to_raw to header_set#to_raw" do
+        @header_set.to_raw = proc { "Whoa!" }
+        @header_set.add(:brand_new_key, "some value")
+        @header_set[:brand_new_key].to_raw.should == @header_set.to_raw
+      end
+    end
+    
+    it "takes an optional third argument which sets the value of the raw header" do
+      @header_set.add(:foo, "bar", "BAZ!")
+      @header_set[:foo].value.should == "bar"
+      @header_set[:foo].key.should == :foo
+      @header_set[:foo].raw.should == "BAZ!"
+      @header_set[:foo].raw!.should == "Foo"
+    end
+  end
+  
+  describe "#delete" do
+    it "removes a header from the set" do
+      @header_set[:brand_new_key].should be_nil
+      @header_set[:brand_new_key] = "something random"
+      @header_set[:brand_new_key].should_not be_nil
+      new_header = @header_set[:brand_new_key]
+      @header_set.delete(:brand_new_key)
+      @header_set[:brand_new_key].should be_nil
+    end
+    
+    it "returns the deleted header" do
+      @header_set[:brand_new_key] = "test"
+      h = @header_set[:brand_new_key]
+      @header_set.delete(:brand_new_key).should == h
+    end
+    
+    it "returns nil if there is no header corresponding to the key" do
+      @header_set[:brand_new_key].should be_nil
+      @header_set.delete(:brand_new_key).should be_nil
+    end
+  end
+  
+  describe "#to_s" do
+    it "equals the individual header to_s results, joined with newlines" do
+      @header_set.to_s.should == @headers.map { |header| header.to_s }.join("\n")
+    end
+    
+    context %Q{with a hash argument :a => "something raw"} do
+      def modified_full_header_set_string
+        str = "something raw: value_a\n"
+        str += @headers[1..-1].map { |e| "header_#{e.key}: value_#{e.key}" }.join("\n")
+        str
+      end
+      
+      it %Q{sets the header with key :a to have #raw == "one" and #value == 1} do
+        str = modified_full_header_set_string
+        
+        @header_set.to_s(:a => "something raw").should == str
+        @header_set[:a].raw.should_not == "something raw"
+        @header_set[:a].raw.should == "header_a"
+      end
+            
+      it "does not leave a side-effect" do
+        str = modified_full_header_set_string
+        
+        @header_set.to_s(:a => "something raw").should == str
+        @header_set[:a].raw.should_not == "something raw"
+        @header_set[:a].raw.should == "header_a"
+      end
+    end
+    
+    context "with a block argument" do
+      def modified_full_header_set_string
+        @headers.map { |e| "#{yield e.key}: value_#{e.key}" }.join("\n")
+      end
+      
+      it "uses the given block to convert #key to a raw header, for each header in the set" do
+        @header_set.to_s { "testing" + "testing" }.should == modified_full_header_set_string { "testing" + "testing" }
+        
+        new_to_raw = proc { |x| x.to_s.upcase.reverse }
+        
+        @header_set.to_s(&new_to_raw).should == modified_full_header_set_string(&new_to_raw)
+      end
+      
+      it "does not leave the given block as #to_raw" do
+        @header_set.to_s { "test" + "test" }
+        @header_set.to_raw.should_not == proc { "test" + "test" }
+      end
+      
+      it "follows the hash argument first, falling back to the given block" do
+        @header_set.to_s(:a => "something raw") { "NOT RAW AT ALL" }.split("\n").first.should == "something raw: value_a"
+      end
+    end
+  end
+  
+  describe "#to_s!" do
+    context "without a block" do
+      it "calls to_s! on each header in the set, passing #to_raw as a block joining the results with newlines" do
+        @header_set.to_raw = proc { "Total foo bar" }
+        @header_set.to_s!.should == @headers.map { |header| "Total foo bar: #{header.value}" }.join("\n")
+      end
+    end
+    
+    context "with a block" do
+      it "calls to_s! on each header in the set, passing the given block, joining the results with newlines" do
+        @header_set.to_s! { "Total foo bar" }.should == @headers.map { |header| "Total foo bar: #{header.value}" }.join("\n")
+      end
+      
+      it "does not leave the given block as #to_raw on existing headers" do
+        temp_to_raw = proc { "Total foo bar" }
+        @header_set.to_s!(&temp_to_raw)
+        @header_set.all? { |header| header.raw!.should_not == "Total foo bar" }
+      end
+      
+      it "does not leave the given block as #to_raw on the header set" do
+        temp_to_raw = proc { "Total foo bar" }
+        @header_set.to_s!(&temp_to_raw)
+        @header_set.to_raw.should_not == temp_to_raw
+        @header_set[:temp_foo_foo] = "what"
+        @header_set[:temp_foo_foo].raw!.should_not == "Total foo bar"
+      end
+    end
+  end
+  
+  describe "#==(other_header)" do
+    it "is sane." do
+      @header_set.should == @header_set
+      
+      Redhead::HeaderSet.parse("Test: test").should == Redhead::HeaderSet.parse("Test: test")
+    end
+    
+    it "returns true if, for every header in self, there is a corresponding header in other_header equal to it, using Header#==" do
+      one, two = @header_set.partition { |header| header.key.to_s < @header_set.to_a[1].key.to_s }.map { |part| Redhead::HeaderSet.new(part) }
+      
+      one.all? { |a| two.find { |b| a == b } }.should be_false
+      # sanity check with any?
+      one.any? { |a| two.find { |b| a == b } }.should be_false
+      
+      one << two.first # create an overlap
+      
+      one.all? { |a| two.find { |b| a == b } }.should be_false
+      # sanity check with any?
+      one.any? { |a| two.find { |b| a == b } }.should be_true
+    end
+  end
+  
+  describe "#reversible?" do
+    it "returns true if each header in the set is reversible, otherwise false" do
+      @reversible_headers.reversible?.should == @reversible_headers.all? { |header| header.reversible? }
+      @irreversible_headers.reversible?.should == @irreversible_headers.all? { |header| header.reversible? }
+      
+      @reversible_headers.reversible?.should be_true
+      @irreversible_headers.reversible?.should be_false
+      
+      @reversible_headers.to_raw = proc { "" }
+      @reversible_headers.reversible?.should_not be_true # contained headers get caught up in the change
+      
+      # example from the readme:
+      
+      string = "A-Header-Name: a header value\n\nContent."
+      
+      str = Redhead::String.new(string) do |name|
+        name.gsub(/-/, "").upcase.to_sym
+      end
+      
+      str.headers.reversible?.should be_false
+      
+      str = Redhead::String.new(string) do |name|
+        name.split(/-/).map { |e| e.upcase }.join("zzz").to_sym
+      end
+      
+      str.headers.reversible?.should be_false
+      
+      str.headers.to_raw = lambda do |name|
+        name.to_s.split(/zzz/).map { |e| e.capitalize }.join("-")
+      end
+      
+      str.headers.reversible?.should be_true
+    end
+  end
+  
+  describe "#to_raw" do
+    it "defaults to Redhead.to_raw" do
+      # note: Proc#== bug!
+      @header_set.to_raw.should == @default_to_raw
+    end
+  end
+  
+  describe "#to_raw=" do
+    it "sets a new block to be used as to_raw" do
+      # note: Proc#== bug!
+      new_to_raw = proc { "" + "" }
+      @header_set.to_raw = new_to_raw
+      @header_set.to_raw.should_not == @default_to_raw
+      @header_set.to_raw.should == new_to_raw
+    end
+    
+    it "sets to_raw, for each header in the set" do
+      new_to_raw = proc { "" + "" }
+      @header_set.to_raw = new_to_raw
+      @header_set.each { |header| header.to_raw.should == new_to_raw }
+    end
+  end
+  
+  describe "#to_key" do
+    it "defaults to Redhead.to_key" do
+      # note: Proc#== bug!
+      @header_set.to_key.should == @default_to_key
+    end
+  end
+  
+  describe "#to_key=" do
+    it "sets a new block to be used as to_key" do
+      # note: Proc#== bug!
+      new_to_key = proc { "" + "" }
+      @header_set.to_key = new_to_key
+      @header_set.to_key.should_not == @default_to_key
+      @header_set.to_key.should == new_to_key
+    end
+    
+    it "sets to_key, for each header in the set" do
+      new_to_key = proc { "" + "" }
+      @header_set.to_key = new_to_key
+      @header_set.each { |header| header.to_key.should == new_to_key }
+    end
+  end
+end