Calixir

About

Calixir is a port of the Lisp calendar software calendrica-4.0.cl of the 4th edition of the book

Calendrical Calculations - The Ultimate Edition
by Edward M. Reingold and Nachum Dershowitz
Cambridge University Press, 2018

to Elixir. In the software, this book is referenced as DR4. Everybody interested in Calixir probably should get a copy of this book in order to understand the background of the calendars covered by this software.

The package contains all the functions that are required to calculate the sample dates and the holidays. A few functions that are used for illustration or alternative methods of calculation have not been implemented.

Calixir has no relationship to the software Calendrical, which is a partial port of calendrica-3.0.cl, the software of the previous edition of the Dershowitz-Reingold book, to Elixir.

The ported functions are tested against the data provided in the book. All the functions of the Elixir port produce exactly the same data.

The data and the tests are included in this package.

Installation

The package is available in Hex and can be installed by adding calixir to your list of dependencies in mix.exs:

def deps do
  [
    {:calixir, "~> 0.1.0"}
  ]
end

Documentation

Documentation has been generated with ExDoc and published on HexDocs. The docs can be found at https://hexdocs.pm/calixir.

About the 'Design' of this Software

This software has no design.

The original Lisp package calendrica-4.0.cl has no notion of modules that are a common means of design and separation of concerns in Elixir (and many other programming languages, for that matter). Instead, it uses a single large namespace. The functions and macros in this namespace are differentiated by prefixes that denote the various calendars (i.e. gregorian_epoch, julian_epoch, etc.).

During the preparation of this package I tried various approaches: I tried to factor out the different calendars into separate modules and even into separate packages (apps). These attempts resulted in one or another form of 'dependency hell', because functions of several calendars are dependent on each other. Finally, I decided to strictly follow the book (DR4) in the arrangement of functions and macros and to create one mononlithic module that mirrors most functions of the Lisp version. (In case you are interested: The same approach was taken by the Python port of this software: PyCalCal.)

The naming of the Elixir functions follows closely the naming of the Lisp functions (except for using _ instead of - in the function names).

All the functions and tests of this package are heaviliy cross-refrenced by the page and equation numbers in DR4, so that you can easily go to the source.

If you want to 'modularize' this package, I recommend to take this package for a base and to create thin wrappers for the calendars or aspects of your interest. I took this approach for the companion package called Calendars, that factors out the various monotonous (i.e. Gregorian) and cyclical (i.e. Day_of_week, Olympiad) calendars contained in Calixir.

Notes on Copyright and License

CALENDRICA 4.0 -- Common Lisp is written and copyrighted by E. M. Reingold and N. Dershowitz as described in file COPYRIGHT_DERSHOWITZ_REINGOLD. This copyright is part of the Common Lisp source file.

This library is made public under the following conditions:

• The code can be used for personal use.
• The code can be used for demonstrations purposes.
• Non-profit reuse with attribution is fine.
• Commercial use of the algorithms should be licensed and are not allowed from this library.

The permissions above are granted as long as attribution is given to the authors of the original algorithms, Nachum Dershowitz and Edward M. Reingold.

The Calixir source code is licensed under the Apache License, Version 2.0, the same license that is used by Elixir. You may obtain a copy of this License at Apache License, Version 2.0.

Resources

The resources (source code and sample data) for this book are available as downloads from the publisher's website: Cambridge University Press.

The Lisp source file is included in this package (in the assets directory) to make it easier to compare the Lisp and Elixir algorithms. The sample data files are included in this package (also in the assets directory), because they are needed for the tests.

Prof. Reingold maintains a website, CALENDARISTS.COM, where you can get information about previous editions of the book and other calendar-related publications.

Changelog

• 0.1.7 fixed function last_day_of_gregorian_month