time_scales 0.1.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NTIzNjFmNzRjODFmZmE3Y2FmNTc2YTcyZWY1NzQzZGQwZjNkNDAwZA==
+  data.tar.gz: !binary |-
+    ZTFhYTU0NmFiOGNjMDYwMWNiZDhmY2Y0M2VjN2QyZGU2NGRhMzgxYw==
+SHA512:
+  metadata.gz: !binary |-
+    Yzc5NzE0YWQzNTNjNDc0MTQyYTAwZTRmOWM1ZDk2ZmE3ZDQzOGE4ODJmNjMx
+    ZTY3ODNhNzRhNjZhMjFmMzBjZjRmYTJjOGUyMWRlOWIyM2M5MzY0MWNlNzkw
+    NGE4ZjcwZWMwYjhiZGFiZWFhNmM5ZmU4ZWJhMzc5NTAwYmEzYzA=
+  data.tar.gz: !binary |-
+    ZjRkOTFiODQ0NmYwZjJjOTY2Mjc0Y2U5OWY4NDlkNjc3NTEzMTE2NjEyMzdh
+    NDY4NGYyMGQwZmZiMTU0YTMzM2IzOTMwNjg5NDNiNDRmMmEzZGZlNGMyYTQx
+    OGNiODBmNzc4YzRmOWY5MWE5NzY0MWRiN2I3NTQ0MmNiMzc0ZTI=

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 1.9.3

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant](http:contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)

data/Gemfile

@@ -0,0 +1,12 @@
+source 'https://rubygems.org'
+
+# These development dependencies are temporarily
+# loaded from here in Gemfile because they have
+# to come from github, and I can't figure out how
+# to do that in the gemspec file.
+%w[rspec rspec-core rspec-expectations rspec-mocks rspec-support].each do |lib|
+  gem lib, :git => "git://github.com/rspec/#{lib}.git"
+end
+
+# Specify your gem's dependencies in time_scales.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Steve Jorgensen
+
+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.md

@@ -0,0 +1,136 @@
+# TimeScales
+
+Date/Time representations with specific scopes, units, and precisions.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby gem 'time_scales' ```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install time_scales
+
+## Usage
+
+The fuctionality of TimeScales is primarily accessed through
+frame types and instances of frame types.
+
+It's probably most useful to start with some examples…
+
+Example A:
+
+    # Build a frame from part values, and get time value & range.
+
+    frame = TimeScales[year: 2015, quarter: 4, month: 1, day: 21]
+    
+    puts frame.begin_time
+    # Output: 2015-10-21 00:00:00 -0700
+    
+    puts frame.to_range
+    # Output: 2015-10-21 00:00:00 -0700...2015-10-22 00:00:00 -0700
+    # Note that the range excludes its end value as indicated by
+    # "...".
+
+Example B:
+
+    # Derive a frame composed of year, day-of-year, and
+    # hour-of-day from a Time value.
+    
+    frame_type = TimeScales[:year, :day, :hour]
+    frame = frame_type & Time.new(2011,6,25 , 13,15)
+    
+    puts(
+      frame.year_of_scheme,
+      frame.day_of_year,
+      frame.hour_of_day,
+    )
+    # == Output ==
+    # 2011
+    # 176
+    # 13
+
+Example C:
+
+    # Determine whether a date falls within a particular month
+    # of a particular quarter of its year.
+
+    frame_type = TimeScales[:quarter, :month]
+    some_time = Time.new(2011,10,31 , 12,00)
+    
+    puts frame_type & some_time == frame_type.new(3, 1)
+    # Output: false
+    
+    puts frame_type & some_time == frame_type.new(4, 1)
+    # Output: true
+
+A frame type consists of a number of parts, each of which has a
+scope unit and a subdivision unit. The frame type has an outer
+scope (the scope of its largest part) and a precision (the
+subdivision of its smallest part).
+
+In order to be a valid set of parts for a frame type, it must be
+possible to form a chain of parts such that the scope unit of a
+smaller part is the same as the subdivision unit of a larger
+part. It is possible to specify a part by its subdivision unit
+if there is any such part that will properly chain to the next
+larger part. When a unit specifies the largest part for a frame
+type, then it refers to the unit's default part (e.g. DayOfMonth
+for Day).
+
+Of the available units, the Scheme unit is special. Scheme refers
+to the date/time scheme of the time values that a frame can be
+built from or converted into. There can never be a unit larger
+than Scheme, and Scheme can only be the outer scope of a frame
+type. Also, only a frame instance with a Scheme-scoped type (a
+specific type) can be converted into a Time value.
+
+The available units are…
+* `TimeScales::Units::Scheme` (`:scheme`)
+* `TimeScales::Units::Year` (`:year`)
+* `TimeScales::Units::Quarter` (`:quarter`)
+* `TimeScales::Units::Month` (`:month`)
+* `TimeScales::Units::Day` (`:day`)
+* `TimeScales::Units::Hour` (`:hour`)
+* `TimeScales::Units::Hour` (`:minute`)
+
+The available frame parts are…
+* `TimeScales::Parts::YearOfScheme` (`:year_of_scheme`, default for `Year`)
+* `TimeScales::Parts::QuarterOfyear` (`:quarter_of_year`, default for `Quarter`)
+* `TimeScales::Parts::MonthOfYear` (`:month_of_year`, default for `Year`)
+* `TimeScales::Parts::MonthOfQuarter` (`:month_of_quarter`)
+* `TimeScales::Parts::DayOfMonth` (`:day_of_month`, default for `Day`)
+* `TimeScales::Parts::DayOfYear` (`:day_of_year`)
+* `TimeScales::Parts::DayOfQuarter` (`:day_of_quarter`)
+* `TimeScales::Parts::HourOfDay` (`:hour_of_day`, default for `Hour`)
+* `TimeScales::Parts::MinuteOfHour` (`:minute_of_hour`, default for `Minute`)
+
+## Future Plans
+
+Hopefully, TimeScales will eventually deal with ISO-8601 weeks as
+well as variations based on different starting day of week.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then,
+run `bin/console` for an interactive prompt that will allow you to
+experiment.
+
+To install this gem onto your local machine, run
+`bundle exec rake install`. To release a new version, update the version
+number in `version.rb`, and then run `bundle exec rake release` to create a
+git tag for the version, push git commits and tags, and push the `.gem`
+file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/time_scales/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

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "time_scales"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/time_scales.rb

@@ -0,0 +1,28 @@
+require 'singleton'
+require "time_scales/version"
+require "time_scales/time_struct"
+require "time_scales/units"
+require "time_scales/parts"
+require "time_scales/frame"
+
+module TimeScales
+  class TimeScalesError < StandardError ; end
+  class NoPartOrUnitForKeyError < TimeScalesError ; end
+
+  def self.[](hash_or_first_part, *args)
+    defines_type =
+      Symbol === hash_or_first_part ||
+      hash_or_first_part.respond_to?(:to_time_scales_part) ||
+      hash_or_first_part.respond_to?(:to_time_scales_unit)
+    if defines_type
+      TimeScales::Frame.type_for( hash_or_first_part, *args )
+    elsif hash_or_first_part.respond_to?( :to_hash ) || hash_or_first_part.respond_to?( :to_h )
+      raise ArgumentError, "Must supply only a hash argument when first argument is a hash" unless args.empty?
+      hash = hash_or_first_part.to_hash if hash_or_first_part.respond_to?( :to_hash )
+      hash = hash_or_first_part.to_h if hash_or_first_part.respond_to?( :to_h )
+      TimeScales::Frame[ hash_or_first_part ]
+    else
+      raise ArgumentError, "Must supply time-part key arguments or a single hash as arguments"
+    end
+  end
+end

data/lib/time_scales/frame.rb

@@ -0,0 +1,50 @@
+require 'time'
+require 'time_scales/frame/part_def'
+require 'time_scales/frame/part_defs'
+require 'time_scales/frame/base'
+require 'time_scales/frame/null_frame'
+require 'time_scales/frame/scheme_relative_frame'
+require 'time_scales/frame/part_components'
+require 'time_scales/frame/precisions'
+require 'time_scales/frame/type_builder'
+
+module TimeScales
+
+  module Frame
+
+    class << self
+      def type_for(*part_keys)
+        return Frame::NullFrame if part_keys.empty?
+
+        part_defs = PartDefs.from_key_value_map( part_keys )
+        type_for_parts( part_defs.parts )
+      end
+
+      def [](frame_parts = {})
+        return Frame::NullFrame.instance if frame_parts.keys.empty?
+
+        part_defs = PartDefs.from_key_value_map( frame_parts )
+        instance_for_part_defs( part_defs )
+      end
+
+      private
+
+      def type_for_parts(parts)
+        return Frame::NullFrame if parts.empty?
+        builder = TypeBuilder.new(parts)
+        builder.call
+      end
+
+      def instance_for_part_defs(defs)
+        type = type_for_parts( defs.parts )
+        type.new( *defs.part_values )
+      end
+    end
+
+    class NullFrame < Frame::Base
+      include Singleton
+    end
+
+  end
+
+end

data/lib/time_scales/frame/base.rb

@@ -0,0 +1,122 @@
+module TimeScales
+  module Frame
+
+    class Base
+
+      class << self
+        def parts
+          @parts ||=
+            _parts.
+            sort_by { |part| -part.scale }.
+            freeze
+        end
+
+        def outer_scope
+          parts.first.scope
+        end
+
+        def precision
+          parts.last.subdivision
+        end
+
+        def &(time)
+          part_values = parts.map { |part|
+            part & time
+          }
+          new( *part_values )
+        end
+
+        private
+
+        def _parts
+          []
+        end
+      end
+
+      def initialize(*args)
+        _initialize args
+      end
+
+      def to_time_scales_frame
+        self
+      end
+
+      def type
+        self.class
+      end
+
+      def parts
+        @parts ||= Hash[
+          self.class.parts.map { |part|
+            [ part.symbol, send(part.symbol) ]
+          }
+        ]
+        @parts.dup
+      end
+
+      def outer_scope
+        self.class.outer_scope
+      end
+
+      def precision
+        self.class.precision
+      end
+
+      # Symmetric, hash-key equality.
+      def eql?(other)
+        self.class == other.class &&
+          self._to_a == other._to_a
+      end
+
+      def ==(other)
+        return true if eql?( other )
+        return false unless other.respond_to?( :to_time_scales_frame )
+        other = other.to_time_scales_frame
+        other.outer_scope == outer_scope &&
+          other.precision == precision &&
+          other.begin_time_struct == begin_time_struct
+      end
+
+      def hash
+        @hash ||= self.class.hash ^ _to_a.hash
+      end
+
+      def to_a
+        _to_a.dup
+      end
+
+      protected
+
+      def _to_a
+        @to_a ||= self.class.parts.map{ |part|
+          send( part.symbol )
+        }.freeze
+      end
+
+      def begin_time_struct
+        @begin_time = begin
+          struct = TimeStruct.new
+          prepare_time_struct struct
+          struct.normalize
+          struct.freeze
+        end
+      end
+
+      private
+
+      def _initialize(args_array)
+        #stub
+      end
+
+      def ensure_fixnum(value)
+        return value if Fixnum === value
+        raise ArgumentError, "Time part value must be of Fixnum type (a numeric integer)"
+      end
+
+      def prepare_time_struct(struct)
+        # stub
+      end
+    end
+
+  end
+end