flex_date 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d8c5b1d1dd3cb06b8f3fc0c101dc59f00c5c809c
+  data.tar.gz: 6286c685d1e746ecd0c5259bd94ec3e657a7437d
+SHA512:
+  metadata.gz: 1fcf79ccd39d5da8ffb6afc8bda0f1f6342d05f09e2f3e81cac52c275920a33ca93d09365f712e842601d6056d60b40ac2a0df18b7deecc8ec09aab31d48411b
+  data.tar.gz: 01bc8e5ae933677cb05ba694d61dbd175ae18016e22c2fa15da36d14447b36bd6083d3724fce061567823f16df8cdc0d5d10d6c84caba072b1f7467b81716d96

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 [name of plugin creator]
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,95 @@
+= FlexDate
+
+Flexible dates for Ruby.
+
+<b>FlexDate is currently compatible with Rails 2.x and Rails 3.</b>
+
+
+== The Problem
+
+You are collecting dates of historic events but you don't always have <i>exact</i> dates. For example, you might know that an event occurred in March of 1862 but you don't know the exact day. You could store this as a Ruby Date object that looks like '1862-03-01' but, really, you don't want to specify a day at all. You want to <b>explicitly not store</b> the day part of the date.
+
+
+== The Solution
+
+FlexDate addresses this problem by extending Ruby's included Date class. At the moment the following methods are provided to create partial dates:
+
+  FlexDate.new(year = nil, month = nil, date = nil)
+  year=(int)
+  month=(int)
+  day=(int)
+
+Where a full date (year, month, and day) is specified, a FlexDate behaves exactly like a normal Ruby Date. When a partial date is specified, only the following methods will work:
+
+  year
+  month
+  day
+  to_s
+  strftime
+
+Comparison operators also (== and <=>) work and I hope to have date arithmetic operators (+ and -) up and running soon.
+
+
+== Installation
+
+To install FlexDate, use the standard Rails plugin installation script:
+
+  script/plugin install git://github.com/alexreisner/flex_date.git 
+
+
+== Integration with Rails/ActiveRecord
+
+The MultipartDate module facilitates integration of FlexDate with ActiveRecord models. It requires that you store each date in three separate columns, each with a _y, _m, or _d suffix. So, if you have a Person model that stores birthdays, the columns required would be (all integers):
+
+  birthday_y
+  birthday_m
+  birthday_d
+
+Then, simply put this in your Person model (you can list multiple attributes if needed):
+
+  multipart_date :birthday
+
+and you'll be able to do things like this:
+
+  # Initialize a new Person object (don't know year they were born).
+  p = Person.new(:birthday_m => 8, :birthday_d => 23)
+  
+  # See if their birthday is set.
+  p.birthday?   
+    => true
+
+  # Get their birthday as a FlexDate object.
+  b = p.birthday
+    => #<FlexDate:0xb78b542c ...>
+  
+  # Display their birthday nicely.
+  p.birthday.to_s(:long)
+    => "August 23"
+  
+  # Add the year when you find out.
+  p.birthday_y = 1964
+  p.birthday.to_s(:long)
+    => "August 23, 1964"
+   
+
+I've also written another Rails plugin called Informant which provides a full-featured FormBuilder class, and includes a <tt>multipart_date_select</tt> field type which is a good compliment to MultipartDate in your Rails application. Install Informant from my Git repository:
+
+  script/plugin install git://github.com/alexreisner/informant.git 
+
+
+== Code Discussion
+
+You might expect FlexDate to be a subclass of Date, but this is not the case. That implementation would be far more complicated because the instance methods of Date require certain instance variables to be set, and to meet certain requirements for validity. Massaging the Date class to accept an invalid date seems like the wrong approach for the modest goals of FlexDate, which is simply to allow storing of partial dates, and duplicate the behavior of the Date class <b>when a date is complete</b>.
+
+So instead, FlexDate is a very simple class that inherits from nothing, provides some (hopefully) useful methods for partial dates, and uses <tt>method_missing</tt> to fall back to Date when a FlexDate object is complete (specifies year, month, and day).
+
+Any comments or suggestions regarding this design are welcome.
+
+
+== To-do List
+
+* <tt>MultipartDate::multipart_date</tt> should also generate a setter method. 
+* Make date arithmetic work (Date minus FlexDate works, but neither FlexDate minus Date or FlexDate minus FlexDate works). 
+
+
+Copyright (c) 2008 Alex Reisner (alex@alexreisner.com), released under the MIT license.

data/Rakefile

@@ -0,0 +1,84 @@
+require 'rake'
+require "rubygems"
+require 'rake/testtask'
+require 'rdoc/task'
+require "rubygems/package_task"
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+require "rake/testtask"
+desc 'Test the flex_date plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+end
+task :default => ["test"]
+
+# This builds the actual gem. For details of what all these options
+# mean, and other ones you can add, check the documentation here:
+#
+#   http://rubygems.org/read/chapter/20
+#
+spec = Gem::Specification.new do |s|
+
+  # Change these as appropriate
+  s.name              = "flex_date"
+  s.version           = "0.1.0"
+  s.summary           = "Flexible dates for Ruby"
+  s.author            = "Sean Gregory"
+  s.email             = "seangregory@gmail.com"
+  s.homepage          = "https://github.com/skinnyjames/flex_date"
+
+  s.has_rdoc          = true
+  s.extra_rdoc_files  = %w(README.rdoc)
+  s.rdoc_options      = %w(--main README.rdoc)
+
+  # Add any extra files to include in the gem
+  s.files             = %w(README.rdoc Rakefile MIT-LICENSE) + Dir.glob("{test,lib}/**/*")
+  s.require_paths     = ["lib"]
+
+  # If you want to depend on other gems, add them here, along with any
+  # relevant versions
+  # s.add_dependency("some_other_gem", "~> 0.1.0")
+
+  # If your tests use any gems, include them here
+  # s.add_development_dependency("mocha") # for example
+end
+
+# This task actually builds the gem. We also regenerate a static
+# .gemspec file, which is useful if something (i.e. GitHub) will
+# be automatically building a gem for this project. If you're not
+# using GitHub, edit as appropriate.
+#
+# To publish your gem online, install the 'gemcutter' gem; Read more 
+# about that here: http://gemcutter.org/pages/gem_docs
+Gem::PackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+desc "Build the gemspec file #{spec.name}.gemspec"
+task :gemspec do
+  file = File.dirname(__FILE__) + "/#{spec.name}.gemspec"
+  File.open(file, "w") {|f| f << spec.to_ruby }
+end
+
+# If you don't want to generate the .gemspec file, just remove this line. Reasons
+# why you might want to generate a gemspec:
+#  - using bundler with a git source
+#  - building the gem without rake (i.e. gem build blah.gemspec)
+#  - maybe others?
+task :package => :gemspec
+
+# Generate documentation
+RDoc::Task.new do |rd|
+  rd.main = "README.rdoc"
+  rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
+  rd.rdoc_dir = "rdoc"
+end
+
+desc 'Clear out RDoc and generated packages'
+task :clean => [:clobber_rdoc, :clobber_package] do
+  rm "#{spec.name}.gemspec"
+end

data/lib/flex_date.rb

@@ -0,0 +1,120 @@
+require 'date'
+class FlexDate
+  include Comparable
+  
+  def <=>(other)
+    spaceship = 0 # start assuming equal
+    %w(year month day).each do |p|
+      a = eval("self.#{p}") || 0
+      b = eval("other.#{p}") || 0
+      break if (spaceship = a <=> b) != 0
+    end
+    spaceship
+  end
+  
+  def ==(other)
+    [year,month,day] == [other.year, other.month, other.day]
+  end
+  
+  attr_accessor :year, :month, :day
+  
+  ##
+  # Initialize the FlexDate with whichever are available: year, month, and day.
+  #
+  def initialize(year = nil, month = nil, day = nil)
+    @year, @month, @day = year, month, day
+  end
+  
+  ##
+  # Define some preset date formats.
+  #
+  DATE_FORMATS = {
+    :short      => "%b %e",
+    :medium     => "%e %b %Y",
+    :long       => "%B %e, %Y",
+    :db         => "%Y-%m-%d",
+    :number     => "%Y%m%d",
+    :rfc822     => "%e %b %Y"
+  }
+
+  ##
+  # String representation of a date. Pass a <tt>strftime</tt>-format string
+  # or a symbol which is a key in the DATE_FORMATS hash.
+  #
+  def to_s(format = :medium)
+    format = DATE_FORMATS[format] if format.is_a?(Symbol)
+    s = strftime(format)
+    
+    # Do some rough cleanup (this isn't very "programmatic").
+    replacements = [
+      [/^[ ,]+/, ''], # leading whitespace and commas
+      [/[ ,]+$/, ''], # trailing whitespace and commas
+      [/ +, +/, ' '], # commas and whitespace in middle
+    ]
+    s.strip!
+    replacements.each do |r|
+      s.gsub!(r[0], r[1])
+    end
+    s
+  end
+  
+  ##
+  # Does this FlexDate specify a year, month, and day?
+  #
+  def complete?
+    not (@year and @month and @day).nil?
+  end
+  
+  ##
+  # Same as Date#strftime but gracefully removes missing parts.
+  #
+  def strftime(format = '%F')
+    # If we have a complete date, just let Date handle it.
+    return real_date.strftime(format) if complete?
+    
+    # If we have a partial date, define token dependencies.
+    dependencies = {
+      :year  => %w(C c D F G g u V v w x Y y),
+      :month => %w(B b c D F h m u V v w x),
+      :day   => %w(A a c D d e F j u V v w x),
+      :time  => %w(H I k L M N P p Q R r S s T X Z)
+    }
+
+    # Remove tokens that refer to missing parts.
+    format = format.gsub(/%([-_0^#]+)?(\d+)?[EO]?(:{1,3}z|.)/m) do |m|
+      s, w, c = $1, $2, $3
+      ok = true
+      dependencies.each do |attr,tokens|
+        missing = instance_variable_get("@#{attr}").nil?
+        ok = false if (tokens.include?(c) and missing)
+      end
+      ok ? m : ''
+    end
+    phony_date.strftime(format)
+  end
+  
+  ##
+  # Pass unimplemented methods along to a regular Date object if possible.
+  #
+  def method_missing(name, *args)
+    real_date.send(name, *args) if complete?
+  end
+  
+  
+  private # -------------------------------------------------------------------
+  
+  ##
+  # Get a Date object based on the current values of @year, @month, and @day.
+  # Returns nil unless all three are known.
+  #
+  def real_date
+    Date.new(@year, @month, @day) if complete?
+  end
+  
+  ##
+  # Get a Date object with "1" set for any unknown parts.
+  #
+  def phony_date
+    Date.new((@year || 1), (@month || 1), (@day || 1))
+  end
+end

data/test/flex_date_test.rb

@@ -0,0 +1,62 @@
+require 'test/unit'
+$:.unshift File.join(File.dirname(__FILE__), '../lib')
+require 'flex_date'
+
+class FlexDateTest < Test::Unit::TestCase
+
+  def test_creation
+    assert FlexDate.new(1953, 11, 2).is_a?(FlexDate)
+    assert FlexDate.new(1953, 11).is_a?(FlexDate)
+    assert FlexDate.new(1953).is_a?(FlexDate)
+    assert FlexDate.new(nil, 11).is_a?(FlexDate)
+    assert FlexDate.new(nil, 11, 2).is_a?(FlexDate)
+    assert FlexDate.new(nil, nil, 2).is_a?(FlexDate)
+    assert FlexDate.new.is_a?(FlexDate)
+  end
+  
+  def test_accessors
+    f = FlexDate.new
+
+    assert !f.complete?
+    assert f.year.nil?
+    f.year = 1794
+    assert_equal 1794, f.year
+    
+    assert !f.complete?
+    assert f.month.nil?
+    f.month = 9
+    assert_equal 9, f.month
+
+    assert !f.complete?
+    assert f.day.nil?
+    f.day = 4
+    assert_equal 4, f.day
+
+    assert f.complete?
+  end
+  
+  def test_formatting
+    f = FlexDate.new
+    assert_equal "", f.strftime("%Y")
+    f.year = 2087
+    assert_equal "2087", f.strftime("%Y")
+    assert_equal "2087-", f.strftime("%Y-%m")
+    assert_equal "2087", f.to_s("%Y")
+    assert_equal "2087", f.to_s(:long)
+    f.month = 8
+    assert_equal "Aug 2087", f.to_s("%b %e, %Y")
+  end
+  
+  def test_comparison_and_equality
+    a = FlexDate.new(2008,6,4)
+    b = FlexDate.new(2004,9,30)
+    assert_equal 0, a <=> a
+    assert a == a
+    assert a != b
+    assert_equal 1, a <=> b
+    c = FlexDate.new(2004)
+    d = FlexDate.new(1980,8,3)
+    e = FlexDate.new(1945,6)
+    assert_equal [e,d,c,b,a], [b,e,a,d,c].sort
+  end
+end

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification
+name: flex_date
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sean Gregory
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-06-18 00:00:00.000000000 Z
+dependencies: []
+description: 
+email: seangregory@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.rdoc
+files:
+- MIT-LICENSE
+- README.rdoc
+- Rakefile
+- lib/flex_date.rb
+- test/flex_date_test.rb
+homepage: https://github.com/skinnyjames/flex_date
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options:
+- "--main"
+- README.rdoc
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.2
+signing_key: 
+specification_version: 4
+summary: Flexible dates for Ruby
+test_files: []