chronos 0.1.0

data/CHANGELOG.rdoc

@@ -0,0 +1,27 @@
+= 0.0.4
+=== 7th July, 2007
+
+* Improved C code (thanks to chris2)
+* Added default value for alpha in ::floats methods
+* Fixed a typo in mixer.rb
+
+= 0.0.3
+=== 7th July, 2007
+
+* Added documentation to .rb files
+* Moved +/- for most classes to Color::Common
+* Improved Rakefile
+* Basic implementation of Color::Named
+* Added as_floats argument to #to_hash methods
+* Added ::floats to most color classes
+
+= 0.0.2
+=== 6th July, 2007
+
+* Fixed Color::Common#with
+* Corrected the Rakefile
+
+= 0.0.1
+=== 6th July, 2007
+
+* Initial release of the color classes implemented in C and Ruby.

data/HISTORY.rdoc

@@ -0,0 +1,4 @@
+== 1.0.0 / 2008-03-03
+
+* 1 major enhancement
+  * Birthday!

data/LICENSE.txt

@@ -0,0 +1,52 @@
+The Chronos library is copyrighted free software by Stefan Rusterholz.
+You can redistribute it and/or modify it under the terms o the conditions
+below (also known as the 'Ruby License'):
+
+  1. You may make and give away verbatim copies of the source form of the
+     software without restriction, provided that you duplicate all of the
+     original copyright notices and associated disclaimers.
+
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+
+       a) place your modifications in the Public Domain or otherwise
+          make them Freely Available, such as by posting said
+	  modifications to Usenet or an equivalent medium, or by allowing
+	  the author to include your modifications in the software.
+
+       b) use the modified software only within your corporation or
+          organization.
+
+       c) rename any non-standard executables so the names do not conflict
+	  with standard executables, which must also be provided.
+
+       d) make other distribution arrangements with the author.
+
+  3. You may distribute the software in object code or executable
+     form, provided that you do at least ONE of the following:
+
+       a) distribute the executables and library files of the software,
+	  together with instructions (in the manual page or equivalent)
+	  on where to get the original distribution.
+
+       b) accompany the distribution with the machine-readable source of
+	  the software.
+
+       c) give non-standard executables non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the author.
+
+  4. You may modify and include the part of the software into any other
+     software (possibly commercial).  
+
+  5. The scripts and library files supplied as input to or produced as 
+     output from the software do not automatically fall under the
+     copyright of the software, but belong to whomever generated them, 
+     and may be sold commercially, and may be aggregated with this
+     software.
+
+  6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.

data/MANIFEST.txt

@@ -0,0 +1,51 @@
+CHANGELOG.rdoc
+HISTORY.rdoc
+LICENSE.txt
+MANIFEST.txt
+NOTES.rdoc
+README.rdoc
+Rakefile
+TODO.rdoc
+bench/completebench.rb
+lib/chronos.rb
+lib/chronos/calendar.rb
+lib/chronos/calendar/gregorian.rb
+lib/chronos/data/zones.tab
+lib/chronos/datetime.rb
+lib/chronos/datetime/gregorian.rb
+lib/chronos/duration.rb
+lib/chronos/duration/gregorian.rb
+lib/chronos/durationtotext.rb
+lib/chronos/exceptions.rb
+lib/chronos/gregorian.rb
+lib/chronos/interval.rb
+lib/chronos/interval/gregorian.rb
+lib/chronos/locale/parsers/de_CH.rb
+lib/chronos/locale/parsers/en_US.rb
+lib/chronos/locale/parsers/generic.rb
+lib/chronos/locale/strings/de_DE.yaml
+lib/chronos/locale/strings/en_US.yaml
+lib/chronos/minimalistic.rb
+lib/chronos/numeric/gregorian.rb
+lib/chronos/ruby.rb
+lib/chronos/version.rb
+lib/chronos/zone.rb
+rake/initialize.rb
+rake/lib/assesscode.rb
+rake/lib/bonesplitter.rb
+rake/lib/projectclass.rb
+rake/tasks/copyright.rake
+rake/tasks/gem.rake
+rake/tasks/git.rake
+rake/tasks/loc.rake
+rake/tasks/manifest.rake
+rake/tasks/meta.rake
+rake/tasks/notes.rake
+rake/tasks/post_load.rake
+rake/tasks/rdoc.rake
+rake/tasks/rubyforge.rake
+rake/tasks/spec.rake
+spec/bacon_helper.rb
+spec/lib/chronos/datetime/gregorian_spec.rb
+spec/lib/chronos/datetime_spec.rb
+spec/lib/chronos_spec.rb

data/NOTES.rdoc

@@ -0,0 +1,85 @@
+= NOTES
+
+== Daylight Savings Time (DST)
+* Math operations will keep the DST sticky, even if the resulting datetime would have a different
+  result for dst?.
+  Example:
+    cest_0230  = Datetime.civil(2008,10,26,2,30).in("CEST") # => 2008-10-26T02:30:00+02:00
+    cest_0330  = cest_0230+1.hour                           # => 2008-10-26T03:30:00+02:00
+    cet_0230   = Datetime.civil(2008,10,26,2,30).in("CET")  # => 2008-10-26T02:30:00+01:00
+    cet_0330   = Datetime.civil(2008,10,26,3,30).in("CET")  # => 2008-10-26T03:30:00+01:00
+    normalized = cest_0330.normalized_dst                   # => 2008-10-26T02:30:00+01:00
+    cest_0230.dst?                # => true
+    cest_0330.dst?                # => false
+    cet_0230.dst?                 # => false
+    cet_0330.dst?                 # => false
+    normalized.dst?               # => false
+    cest_0330.timezone.name       # => "CEST"; adding a duration will keep the timezone
+    (cest_0330 - cest_0330).hours # => 0
+    (cest_0330 - cest_0230).hours # => 1
+    (cet_0330 - cest_0330).hours  # => 1
+    (cet_0330 - cest_0230).hours  # => 2
+    normalized == cest_0330       # => true (== only checks day_number and ps_number)
+    normalized.eql?(cest_0330)    # => false (eql? additionally checks timezone and language)
+* Deviating from the above, DST does not influence math:
+    result = somedatetime + Duration.new(:hours => 2)
+    result.hour == somedatetime.hour+2
+  Is guaranteed to be true, no matter whether you cross a DST border there.
+  If we respected DST, it could be +1, +2 or +3, depending on whether we cross the DST
+  border in one or the other direction or not at all.
+* DST being active can be checked by Datetime#dst?, which returns true/false if a DST rule
+  is applicable and nil if no DST rule is applicable. No rule being applicable is the case
+  for dates in the future (since the DST rules might change) and for timezones which simply
+  don't have DST.
+* Getting the datetime in the timezone with the correct DST applied is done via #normalized_dst
+  E.g. if you got a result from an addition, subtraction, parsing that gives you a datetime
+  with timezone CEST (which implies DST is true) but at a date where DST is off, you can
+  use #normalized_dst and the resulting Datetime will be in CET (which implies DST is false)
+
+== Leap seconds
+* Leap seconds do not influence math
+    result = somedatetime + Duration.new(:seconds => 60)
+    result.minute = somedatetime.minute+1
+   Is guaranteed to be true. If we respected leap seconds for calculations, this would
+   not be guaranteed since a minute could have 61 seconds (when you cross the leap second).
+* Parsing a datetime which has the leapsecond set will be treated as the normal 60 value for
+  second (which means 'infinitesimally shortly before the change to the next minute')
+
+== Leap years
+* Leap years DO influence math
+    result = somedatetime + Duration.new(:days => 365)
+    result.year = somedatetime.year + 1
+  Is NOT guaranteed to be true.
+
+== Infinitesimally shortly before change of the bigger unit
+* You can express a time infinitesimally shortly before the same time with one unit switching
+  (e.g. hour switching from 1 to 2) by specifying the next smaller unit to max+1.
+  Example:
+    a = Datetime.today.at(12,59,59.9999999)
+    b = Datetime.today.at(12,60)
+    c = Datetime.today.at(13,00)
+    a < b # => true
+    b < c # => true
+
+== Subtracting a datetime from a datetime
+* Subtracting a datetime from another will result in an Interval
+* Intervals have the guaranteed property of Interval#start <= Interval#end
+* Converting a gregorian Interval to a Duration will create a gregorian Duration, using both, months
+  and picoseconds (the alternative choice would have been to use picoseconds only).
+* The direction is preserved, so if datetime_a < datetime_b and you do
+    datetime_a - datetime_b
+  Then the resulting Interval's start will be datetime_a, its end will be datetime_b. All units will
+  be positive. But the moment you convert it to a Duration, the units will be negative.
+
+== The problem with +/- and datetimes/durations
+* Adding and subtracting durations to and from datetimes depends on the operands.
+  This means that adding a duration to a datetime and subtracting the same duration from the
+  result can result in a new datetime that is not equal to the original datetime:
+    (a_datetime + a_duration) - a_duration == a_datetime # is NOT guaranteed to be true
+  An example where this happens:
+    a = Datetime.civil(2007,1,31) # => 2007-01-31
+    b = a + 1.month               # => 2007-02-28
+    c = b - 1.month               # => 2007-01-28
+    a == c                        # => false
+  Nota bene: datetime + (duration - duration) == datetime # IS guaranteed, since
+  duration - duration will result in a zero duration.

data/README.rdoc

@@ -0,0 +1,125 @@
+= Chronos
+
+
+
+== INDEXING
+Name::             Chronos
+Gem::              chronos
+Summary::          Library to deal with Date, Time, Durations and Intervals.
+Author::           Stefan Rusterholz <stefan.rusterholz+chronos at gmail.com>
+Version::          0.1.1
+Website::          http://chronos.rubyforge.org/
+Git Repository::   http://github.com/apeiros/chronos
+Bugtracker::       http://rubyforge.org/tracker/?atid=25774&group_id=6649&func=browse
+Feature Requests:: http://rubyforge.org/tracker/?atid=25777&group_id=6649&func=browse
+License::          Ruby License (see LICENSE.txt)
+
+
+
+== SUMMARY
+Chronos is a library that lets you easily deal with various kinds of calculations
+with dates, times, durations and intervals.
+
+
+
+== DESCRIPTION
+(none yet)
+
+
+
+== IMPORTANT
+Date, Time and Duration don't satisfy usual algebraic laws. Many operations are a
+matter of definition. It is very likely that your expectation might be broken at
+some points. Read the NOTES.rdoc for ambiguous cases and how they are solved in
+Chronos.
+
+
+
+== INSTALLING
+=== Via RubyGems
+You need for the installation:
+* rubygems >= 1.2.0
+
+You need for some of the rake tasks:
+* bacon
+* flexmock
+* git
+* hpricot
+* rcov
+* rdiscount (or markdown)
+* rdoc
+* rspec
+
+To install, do:
+
+	gem install chronos
+
+Note: you might have to use 'sudo gem install chronos'
+
+=== From Github
+You need for the installation:
+* rubygems >= 1.2.0
+
+You need for some of the rake tasks:
+* bacon
+* flexmock
+* git
+* hpricot
+* rcov
+* rdiscount (or markdown)
+* rdoc
+* rspec
+
+To install, do:
+
+	curl -L -o chronos.tgz http://github.com/apeiros/chronos/tarball/master
+	tar -xfz chronos.tgz
+	cd apeiros-chronos-<big number here>/
+	rake gem:install
+
+Note: you might have to use 'sudo rake gem:install'
+
+
+
+== EXAMPLES
+See in the examples directory for code examples.
+
+
+
+== DESIGN
+=== General
+In general for all structures there are calendary-agnostic classes. Those are directly
+defined within the Chronos module. The calendary specific subclasses are then defined
+as ::Chronos::+Classname+::+Calendarname+. There are shortcuts defined via specific requires.
+E.g. if you require 'chronos/+calendarname+' it will map all
+::Chronos::+Classname+::+Calendarname+ to  ::+Classname+ for convenience.
+
+=== Datetime
+A datetime is a point on the axis of time. This axis has an origin (zero point). For chronos this
+origin is defined to be backdated gregorian datetime 0000-01-01T00:00:00Z. The units to measure
+the distance from this origin is days+picoseconds, where 8.64e16 picoseconds is 1 day.
+The calendar specific classes then can represent that date/time in the units defined for that
+calendar, such as gregorian can represent that distance from origin as
+year-month-day"T"hour:minute:second.fraction±offset.
+Timezone and DST are only representational offsets on top of that distance. That means that
+2008-01-01T12:00Z and 2008-01-01T14:00+02:00 have the same distance, but are represented
+differently due to the different offset. Just as "May" (english) and "Mai" (german) are
+different representations of the same month.
+So Datetime and all its subclasses store date and time without representational offsets, those
+are only respected when accessing calendary-specific values, such as month, day, hour etc.
+
+
+
+== CREDITS
+Yukihiro "Matz" Matsumoto:: For ruby
+Jarrett C.:: Helping with the C implementation
+Various People:: For rubygems, rake, all the support in #ruby-lang, #ruby-pro and the ruby-talk ML
+
+
+
+== LINKS
+Website::           http://chronos.rubyforge.org/
+Git Repository::    http://github.com/apeiros/chronos
+Report a bug::      http://rubyforge.org/tracker/?func=add&group_id=6649&atid=25774
+Request a feature:: http://rubyforge.org/tracker/?func=add&group_id=6649&atid=25777
+ISO 8601::          http://en.wikipedia.org/wiki/ISO_8601

data/Rakefile

@@ -0,0 +1,34 @@
+#--
+# Copyright 2007-2008 by Stefan Rusterholz.
+# All rights reserved.
+# See LICENSE.txt for permissions.
+#++
+
+
+
+# Look in the rake/initialize.rb file for the various options that can be
+# configured in this Rakefile. The .rake files in the rake/tasks directory
+# are where the options are used.
+require 'rake/initialize'
+
+# The default task
+task :default => 'spec:run'
+
+
+
+# Project details (defaults are in rake/initialize, some cleanup is done per section in the
+# prerequisite task in each .task file, some other cleanup is done in post_load.rake)
+Project.meta.name             = 'chronos'
+Project.meta.version          = version_proc("Chronos::VERSION")
+Project.meta.website          = 'http://chronos.rubyforge.org/'
+Project.meta.bugtracker       = 'http://'
+Project.meta.feature_requests = 'http://'
+Project.meta.use_git          = true
+
+# TODO: remove chronos_core from this list later
+Project.manifest.exclude     += %w[ext/cchronos/**/* ext/chronos_core/**/*]
+
+Project.rdoc.exclude         += %w[lib/**/*.yaml ext/**/*]
+
+Project.rubyforge.project     = 'chronos'
+Project.rubyforge.path        = 'chronos'

data/TODO.rdoc

@@ -0,0 +1,63 @@
+= BUGS
+* Datetime with timezones having positive offsets picoseconds becomes negative and days & overflow
+  are wrong
+
+= TODO
+== Pre-Release
+* Validate Datetime API
+* Refactor Interval (Gregorian)
+* Test rake tasks and temporarly remove non-working or fix
+* Complete specs
+* Complete minimal docs
+
+== Low priority
+* Verify all rake tasks
+* Fix gem rake task (must validate manifest and version)
+* Rake task to help localization
+* Spec to test completeness of localizations
+* Write extensive parsing suite, there should be 4 kinds of parsers:
+  * Extremely strict format specific parsers, such as Chronos::Datetime::Gregorian::iso8601 which
+    parses only and only iso8601 compliant strings and raises if it fails.
+  * User defined strict parsers which use a Parser::Format (or a string which the parser method
+    converts to a Parser::Format instance) to determine the parsing rules which raise if they fail
+    to match.
+  * Strict automatic parser +Classname+::parse, which tries predetermined formats and
+    raises if it fails to consume the whole string.
+  * Lax automatic parser (no name yet, maybe just a switch to ::parse) which do "as good as
+    possible" matching and conversion and defaultize whatever is missing and never raise.
+* Write extensive #format suite with proper localization
+  * Localize words ('month', 'months', ...)
+  * Localize numerics ('one', 'two', ...)
+  * Localize entities ('January', ..., 'Monday', ...)
+  * Localize format (mm/dd/YYYY, dd.mm.YYYY, ...)
+* Lazy loading of strings/parsers/formatters
+* chronos/replace/time - Allow Chronos::Datetime::Gregorian to act as a Time drop-in
+* chronos/replace/date - Allow Chronos::Datetime::Gregorian to act as a Date drop-in
+* chronos/compat/time - Allow Chronos::Duration::Gregorian to work seamlessly with Time
+* chronos/compat/date - Allow Chronos::Duration::Gregorian to work seamlessly with Date
+* Import Scheduler
+* Handle recurring
+* Natural language parsers
+* Extractors (extract datetimes, intervals and durations from plaintext)
+* Improve formatters
+* Add other calendary systems
+  * Chinese
+  * Jewish
+  * Indian
+  * Julian
+  * Discordian
+* Full documentation, including guides/howtos/caveeats
+
+
+= UNHAPPY
+* DateTime#strftime("%Z") does not indicate if it's in a timezone with active DST or not,
+  so importing a DateTime and importing a Time will give different results.
+* Freeze datetime/duration/interval
+
+== WHAT I WANT
+All changes to the source MUST NOT violate any of the following statements:
+
+* Multiple calendar systems can be used at the same time
+* If a single calendar system is used, (almost) all of the complexity of supporting multiple
+  calendars is hidden
+* Chronos is multilingual