tempora 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0a945f2d08e09bed694a289ec99717a591e348d780329fc3d3b9e6d1c57354a8
+  data.tar.gz: a37eed5acf4ff7a0d4c423733b069e7afa195bf859742253c8474c47c3446d6f
+SHA512:
+  metadata.gz: 5e9b967909906cd6f2511c19e455904d53d4797692f635c04a14a4b1a5fe20cd42badafe74e9fb5f0ed1f8722f85836b5424b0b71c7acf67614209fdc6c8e902
+  data.tar.gz: 35ef820b1e2133b6cb2af1b8d5ed80b86fd66f2fb6ef6112fd9fc44239e40c9a948bcd00208fd09776bec0b3884e8c9b98f76fea717bf0fe5a7a0a27555f8ab1

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Max Power
+
+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,176 @@
+# Tempora
+
+Tempora is a lightweight Ruby library for handling months, weeks, quarters, and years with intuitive date-based calculations and range support.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add tempora
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install tempora
+```
+
+## Usage
+
+### Initialization
+
+```
+year     = Year.new(2025)
+month    = Month.new(2025, 12)
+week     = Week.new(2025, 52)
+quarter  = Quarter.new(2025, 4)
+```
+
+Initialization with a Date or Time
+```
+year     = Year.from Time.now
+month    = Month.from Date.today
+week     = Week.from Date.new(2025,1,1)
+quarter  = Quarter.from Date.today
+```
+
+Convenient `.now` method (aliased as `.current`)
+```
+year     = Year.now
+month    = Month.now
+week     = Week.now
+quarter  = Quarter.now
+```
+
+### Navigation
+
+Previous/Next
+```
+month    = Month.now
+next     = month.next  # alias: month.succ
+prev     = month.prev  # alias: month.pred
+```
+
+Use it in ranges
+```
+range = Month.new(2025, 1)..Month.new(2025, 6)
+range.count            # => 6
+range.to_a.map(&:to_s) # => ["January 2025", "February 2025", "March 2025", "April 2025", "May 2025", "June 2025"]
+```
+
+Start date / End date
+```
+month = Month.now
+month.start_date # alias: month.begin
+month.end_date   # alias: month.end
+
+Month.now.weeks.map(&:start_date)
+```
+
+###
+
+
+## 1. Generating Monthly Reports
+
+Useful for finance, sales, employee attendance, or analytics dashboards
+Example: Fetch revenue per day for a given month
+
+```
+month = Month.new(2025, 2)
+sales = { "2025-02-01" => 1000, "2025-02-02" => 2000, "2025-02-10" => 500 } # Sample sales data
+
+month.days.each do |day|
+  puts "#{day}: $#{sales[day.to_s] || 0}"
+end
+```
+
+📌 Output:
+```
+2025-02-01: $1000  
+2025-02-02: $2000  
+2025-02-03: $0  
+...
+2025-02-10: $500  
+```
+
+## 2. Calendar & Scheduling Systems
+
+Generate a calendar for scheduling shifts, meetings, or events
+
+```
+month = Month.from(Date.today)
+puts "📅 Calendar for #{month}"
+month.weeks.each { |week| puts week.to_s }
+```
+
+📌 Output:
+```
+📅 Calendar for February 2025
+Week 5, 2025
+Week 6, 2025
+Week 7, 2025
+Week 8, 2025
+Week 9, 2025
+...
+```
+
+➡️ Could be used in a Rails view to generate a full calendar!
+
+## 3. Recurring Events & Subscriptions
+
+Automate billing cycles, gym memberships, or SaaS renewals
+
+```
+def next_billing_cycle(start_date)
+  Month.from(start_date).next.start_date
+end
+
+puts next_billing_cycle(Date.today) # => 2025-03-01
+```
+
+➡️ Use this for subscription renewals, invoice due dates, etc.
+
+## 4. Employee Shift Management
+
+Organize employees' shifts week-by-week in a month
+
+```
+month = Month.new(2025, 2)
+shifts = {
+  "2025-02-05" => "John",
+  "2025-02-10" => "Anna"
+}
+
+month.each_day do |day|
+  puts "#{day}: #{shifts[day.to_s] || 'No Shift'}"
+end
+```
+
+➡️ Helps in HR systems for workforce planning.
+
+
+## 5. Generating Reports for a Quarter
+
+Use the Quarter class to analyze quarterly data
+
+```
+q = Quarter.new(2025, 1)
+q.months.each { |m| puts m.to_s }
+q.weeks.each { |w| puts w.to_s }
+```
+
+➡️ Use this for quarterly earnings, tax calculations, and budget planning.
+
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/max-power/tempora.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+
+
+

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+task default: :test

data/lib/initialization.rb

@@ -0,0 +1,19 @@
+require 'date'
+
+module Initialization
+  def now
+    from Time.now
+  end
+  
+  alias_method :current, :now
+  
+  def from(date)
+    new *initialization_parameter(date.to_date)
+  end
+  
+  private
+  
+  def initialization_parameter(date)
+    [date.year]
+  end
+end

data/lib/month.rb

@@ -0,0 +1,54 @@
+require_relative 'timeperiod'
+require_relative 'initialization'
+require_relative 'week'
+
+class Month
+  include TimePeriod
+  extend Initialization
+
+  def initialize(year, month)
+    @year   = Integer(year)
+    @number = Integer(month).clamp(1, 12)
+    
+    @start_date = Date.new(@year, @number,  1)
+    @end_date   = Date.new(@year, @number, -1)
+  end
+  
+  def id(seperator="-")
+    "#{@year}#{seperator}#{@number.to_s.rjust(2, '0')}"
+  end
+
+  def to_s
+    "#{month_name} #{@year}"
+  end
+
+  def month_name
+    Date::MONTHNAMES[@number]
+  end
+  
+  def month_abbr
+    Date::ABBR_MONTHNAMES[@number]
+  end
+  
+  def next
+    self.class.from(@start_date.next_month) # @start_date >> 1
+  end
+  
+  def prev
+    self.class.from(@start_date.prev_month) # @start_date << 1
+  end
+  
+  def weeks
+    Week.from(start_date)..Week.from(end_date)
+  end
+  
+  alias_method :month, :number
+  alias_method :succ, :next
+  alias_method :pred, :prev
+
+  private
+  
+  def self.initialization_parameter(date)
+    [date.year, date.month]
+  end
+end

data/lib/quarter.rb

@@ -0,0 +1,52 @@
+require_relative 'timeperiod'
+require_relative 'initialization'
+require_relative 'month'
+require_relative 'week'
+
+class Quarter
+  include TimePeriod
+  extend Initialization
+
+  def initialize(year, quarter)
+    @year   = Integer(year)
+    @number = Integer(quarter).clamp(1,4)
+
+    start_month = (quarter - 1) * 3 + 1
+    @start_date = Date.new(year, start_month, 1)
+    @end_date   = @start_date.next_month(3).prev_day
+  end
+  
+  def id(seperator="-")
+    "#{@year}#{seperator}Q#{@number}"
+  end
+
+  def to_s
+    "Q#{@number} #{@year}"
+  end
+  
+  def next
+    self.class.from(@start_date >> 3)
+  end
+
+  def prev
+    self.class.from(@start_date << 3)
+  end
+  
+  alias_method :succ, :next
+  alias_method :pred, :prev
+    
+  def months
+    Month.from(@start_date)..Month.from(@start_date.next_month(2))
+  end
+  
+  def weeks
+    Week.from(@start_date)..Week.from(@end_date)
+  end
+  
+  private
+  
+  def self.initialization_parameter(date)
+    quarter = ((date.month - 1) / 3) + 1
+    [date.year, quarter]
+  end
+end

data/lib/tempora/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Tempora
+  VERSION = "0.1.0"
+end

data/lib/tempora.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "tempora/version"
+require_relative "timeperiod"
+require_relative "initialization"
+require_relative "year"
+require_relative "month"
+require_relative "week"
+require_relative "quarter"
+
+
+module Tempora
+  class Error < StandardError; end
+  # Your code goes here...
+end

data/lib/timeperiod.rb

@@ -0,0 +1,49 @@
+require 'date'
+
+module TimePeriod
+  include Comparable
+  
+  attr_reader :start_date, :end_date, :year, :number
+
+  def range
+    @start_date..@end_date
+  end
+
+  def duration
+    (@end_date - @start_date).to_i + 1
+  end
+  
+  def days
+    range.to_a
+  end
+
+  def each_day(&block)
+    range.each(&block)
+  end
+
+  def contains?(date)
+    range.cover?(date)
+  end
+
+  def overlaps?(other)
+    range.overlaps?(other.range)
+  end
+
+  def intersection(other)
+    return nil unless overlaps?(other)
+
+    new_start = [@start_date, other.start_date].max
+    new_end = [@end_date, other.end_date].min
+
+    self.class.new(new_start, new_end)
+  end
+  
+  def <=>(other)
+    @start_date <=> other.start_date
+  end
+  
+  alias_method :begin, :start_date
+  alias_method :end, :end_date
+  alias_method :length, :duration
+end
+

data/lib/week.rb

@@ -0,0 +1,40 @@
+require_relative 'timeperiod'
+require_relative 'initialization'
+
+class Week
+  include TimePeriod
+  extend Initialization
+    
+  def initialize(year, week)
+    @year   = Integer(year)
+    @number = Integer(week).clamp(1,52)
+    
+    @start_date = Date.commercial(@year, @number, 1)
+    @end_date   = start_date + 6
+  end
+  
+  def id(seperator="-")
+    "#{@year}#{seperator}W#{format('%02d', @number)}"
+  end
+  
+  def to_s
+    "Week #{@number}, #{@year}"
+  end
+  
+  def next
+    self.class.from(@start_date + 7)
+  end
+
+  def prev
+    self.class.from(@start_date - 7)
+  end
+  
+  alias_method :succ, :next
+  alias_method :pred, :prev
+  
+  private
+  
+  def self.initialization_parameter(date)
+    [date.cwyear, date.cweek]
+  end
+end

data/lib/year.rb

@@ -0,0 +1,43 @@
+require_relative 'timeperiod'
+require_relative 'initialization'
+require_relative 'month'
+require_relative 'week'
+
+class Year
+  include TimePeriod
+  extend Initialization
+  
+  def initialize(year)
+    @year = Integer(year)
+    
+    @start_date = Date.new(@year, 1, 1)
+    @end_date   = Date.new(@year, 12, 31)
+  end
+  
+  def id
+    @year
+  end
+
+  def to_s
+    @year.to_s
+  end
+  
+  def next
+    self.class.new(@year + 1)
+  end
+  
+  def prev
+    self.class.new(@year - 1)
+  end
+  
+  def months
+    Month.new(@year, 1)..Month.new(@year, 12)
+  end
+  
+  def weeks
+    Week.new(@year, 1)..Week.new(@year, 52)
+  end
+
+  alias_method :succ, :next
+  alias_method :pred, :prev
+end

data/sig/tempus.rbs

@@ -0,0 +1,4 @@
+module Tempora
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: tempora
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Max Power
+bindir: exe
+cert_chain: []
+date: 2025-02-15 00:00:00.000000000 Z
+dependencies: []
+description: Tempora is a lightweight Ruby library for handling months, weeks, quarters,
+  and years with intuitive date-based calculations and range support.
+email:
+- kevin.melchert@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/initialization.rb
+- lib/month.rb
+- lib/quarter.rb
+- lib/tempora.rb
+- lib/tempora/version.rb
+- lib/timeperiod.rb
+- lib/week.rb
+- lib/year.rb
+- sig/tempus.rbs
+homepage: https://github.com/max-power/tempora
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/max-power/tempora
+  source_code_uri: https://github.com/max-power/tempora
+  changelog_uri: https://github.com/max-power/tempora/README.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Tempora is a lightweight Ruby library for handling months, weeks, quarters,
+  and years.
+test_files: []