icalPal 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a530f29b36a30e180b8bf2a82c3107a2bfa40a12fc62e1fd5431696c9fc860a0
+  data.tar.gz: 95caaf61238e643ef328dd5dfafaa00b4a14c50e4565ca5498ddf660e24245f3
+SHA512:
+  metadata.gz: 8624c9eeea269874b876205cb556cff492bcd39d9196a428a1f95a3995ca997545ded47749841c8e113a6c4862405d85f053e99f9fc03ddaa877a3b543189eb2
+  data.tar.gz: 8870801cc536557e2cb8c4eb1e6a7831ae0c73ced12ff41be3a4a0e19ea482a934b514b9eee6228e09d2b82e2bdc7b51db7c7e1707c3fd600a6bc81bb5054bdd

data/README.md

@@ -0,0 +1,184 @@
+# icalPal
+
+## Description
+
+icalPal is a command-line tool to query a macOS Calendar database for
+accounts, calendars, and events.  It can be run on any system with
+[Ruby](https://www.ruby-lang.org/) and access to a Calendar database
+file.
+
+## Installation
+
+<code>gem install icalPal</code>
+
+
+## Usage
+
+ical: Usage: ical [options] [-c] COMMAND
+
+COMMAND must be one of the following:
+
+    events                  Print events
+    calendars               Print calendars
+    accounts                Print accounts
+
+    eventsToday             Print events occurring today
+    eventsToday+NUM         Print events occurring between today and NUM days into the future
+    eventsNow               Print events occurring at present time
+
+Global options:
+
+    -c, --cmd=COMMAND       Command to run
+        --db=DB             Use DB file instead of Calendar
+        --cf=FILE           Set config file path (default: $HOME/.icalPal)
+    -o, --output=FORMAT     Print as FORMAT (default: default)
+                            [ansi, csv, default, hash, html, json, md, rdoc, toc, yaml]
+
+Including/excluding calendars:
+
+        --is=ACCOUNTS       List of accounts to include
+        --es=ACCOUNTS       List of accounts to exclude
+
+        --it=TYPES          List of calendar types to include
+        --et=TYPES          List of calendar types to exclude
+                            [Local, Exchange, CalDAV, MobileMe, Subscribed, Birthdays]
+
+        --ic=CALENDARS      List of calendars to include
+        --ec=CALENDARS      List of calendars to exclude
+
+Choosing dates:
+
+        --from=DATE         List events starting on or after DATE
+        --to=DATE           List events starting on or before DATE
+                            DATE can be yesterday, today, tomorrow, +N, -N, or anything accepted by DateTime.parse()
+                            See https://ruby-doc.org/stdlib-2.6.1/libdoc/date/rdoc/DateTime.html#method-c-parse
+
+    -n                      Include only events from now on
+        --days=N            Show N days of events, including start date
+        --sed               Show empty dates with --sd
+        --ia                Include only all-day events
+        --ea                Exclude all-day events
+
+Choose properties to include in the output:
+
+        --iep=PROPERTIES    List of properties to include
+        --eep=PROPERTIES    List of properties to exclude
+        --aep=PROPERTIES    List of properties to include in addition to the default list
+
+        --uid               Show event UIDs
+        --eed               Exclude end datetimes
+
+        --nc                No calendar names
+        --npn               No property names
+        --nrd               No relative dates
+
+    Properties are listed in the order specified
+
+    Use 'all' for PROPERTIES to include all available properties (except any listed in --eep)
+    Use 'list' for PROPERTIES to list all available properties and exit
+
+Formatting the output:
+
+        --li=N              Show at most N items (default: 0 for no limit)
+
+        --sc                Separate by calendar
+        --sd                Separate by date
+        --sep=PROPERTY      Separate by PROPERTY
+
+        --sort=PROPERTY     Sort by PROPERTY
+    -r, --reverse           Sort in reverse
+
+        --ps=SEPARATORS     List of property separators
+        --ss=SEPARATOR      Set section separator
+
+        --df=FORMAT         Set date format
+        --tf=FORMAT         Set time format
+                            See https://ruby-doc.org/stdlib-2.6.1/libdoc/date/rdoc/DateTime.html#method-i-strftime for details
+
+    -b, --ab=STRING         Use STRING for bullets
+        --nnr=SEPARATOR     Set replacement for newlines within notes
+
+    -f                      Format output using standard ANSI colors
+        --color             Format output using a larger color palette
+
+Help:
+
+    -h, --help              Show this message
+    -V, -v, --version       Show version and exit (1.0)
+    -d, --debug=LEVEL       Set the logging level (default: warn)
+                            [debug, info, warn, error, fatal]
+
+Environment variables:
+
+    ICALPAL                 Additional arguments
+    ICALPAL_CONFIG          Additional arguments from a file
+                            (default: $HOME/.icalPal)
+
+
+## History
+
+If you've found this page it's likely you've heard of [icalBuddy](https://github.com/ali-rantakari/icalBuddy):
+
+> Command-line utility for printing events and tasks from the OS X calendar database.
+
+I have used icalBuddy for many years.  It's great for scripting,
+automation, and as a desktop widget for apps like
+[GeekTool](https://www.tynsoe.org/geektool/) and
+[Übersicht](https://tracesof.net/uebersicht/).
+
+As with many applications, I started to run into some limitations in
+icalBuddy.  The biggest being that active development ended over 8
+years ago.  It's only thanks to the efforts of [Jim
+Lawton](https://github.com/jimlawton) that it even compiles anymore.
+
+Instead of trying to understand and extend the existing code, I chose
+to start anew using my language of choice.
+
+- Output in CSV, JSON, HTML, Markdown, and [more](#label-Output+formats)
+- Enhanced color option[#label-Usage]
+- Show and filter by Account
+- Show and filter by Calendar type
+- Select a different Calendar database
+- Multi-platform
+- Much less code (1200 lines vs. 7000)
+
+I won't pretend to understand **why** you would want this on Linux or
+Windows.  But since icalPal is written in Ruby and gets its data
+directly from the Calendar database file instead of an API, you *can*.
+
+## Output formats
+
+icalPal supports several output formats.  The +default+ format tries
+to mimic icalBuddy as much as possible.
+
+CSV, Hash, JSON, and YAML print all fields for all items in their
+respective formats.  From that you can analyze the results any way you like.
+
+All other formats, ANSI, HTML, Markdown, RDoc, and TOC, use Ruby's
+[RDoc::Markup](https://ruby-doc.org/stdlib-2.6.10/libdoc/rdoc/rdoc/RDoc/Markup.html)
+framework to build and render the items.
+
+Each item to be printed is a new
+[RDoc::Markup::Document](https://ruby-doc.org/stdlib-2.6.10/libdoc/rdoc/rdoc/RDoc/Markup/Document.html).
+
+When using one of the <em>separate by</em> options, a section header is added first.  The section contains:
+
+* [RDoc::Markup::BlankLine](https://ruby-doc.org/stdlib-2.6.10/libdoc/rdoc/rdoc/RDoc/Markup/BlankLine.html)
+  (unless this is the first section)
+* RDoc::Markup::Heading (level 1)
+* [RDoc::Markup::Rule](https://ruby-doc.org/stdlib-2.6.10/libdoc/rdoc/rdoc/RDoc/Markup/Rule.html)
+
+The rest of the document is a series of
+[RDoc::Markup::List](https://ruby-doc.org/stdlib-2.6.10/libdoc/rdoc/rdoc/RDoc/Markup/List.html)
+objects, one for each of the item's properties:
+
+* [RDoc::Markup::List](https://ruby-doc.org/stdlib-2.6.10/libdoc/rdoc/rdoc/RDoc/Markup/List.html)
+* RDoc::Markup::Heading (level 2)
+* [RDoc::Markup::BlankLine](https://ruby-doc.org/stdlib-2.6.10/libdoc/rdoc/rdoc/RDoc/Markup/BlankLine.html)
+* [RDoc::Markup::ListItem](https://ruby-doc.org/stdlib-2.6.10/libdoc/rdoc/rdoc/RDoc/Markup/ListItem.html)
+* [RDoc::Markup::Paragraph](https://ruby-doc.org/stdlib-2.6.10/libdoc/rdoc/rdoc/RDoc/Markup/Paragraph.html)
+
+The document will also include a number of
+[RDoc::Markup::Verbatim](https://ruby-doc.org/stdlib-2.6.10/libdoc/rdoc/rdoc/RDoc/Markup/Verbatim.html)
+items.  The are not included in the output, but are used to pass
+information about the item and property to the default formatter.

data/bin/icalPal

@@ -0,0 +1,204 @@
+#!/usr/bin/env ruby
+# *-*- mode: enh-ruby -*-*
+
+require 'logger'
+
+require 'csv'
+require 'json'
+require 'rdoc'
+require 'sqlite3'
+require 'yaml'
+
+require_relative '../lib/icalPal'
+require_relative '../lib/options'
+
+
+##################################################
+# Load options
+
+# All kids love log!
+$log = Logger.new(STDERR, { datetime_format: '%H:%M:%S.%L', level: $defaults[:common][:debug] })
+$log.formatter = proc do |s, t, p, m| # Severity, time, progname, msg
+  ($log.level.positive?)? "#{s}: #{m}\n" :
+    "[%-5s] %s [%s] - %s\n" %
+    [ s, t.strftime($log.datetime_format), caller(4, 1)[0].split('/')[-1], m ]
+end
+
+$opts = ICalPal::Options.new.parse_options
+
+$rows = []                      # Rows from the database
+$items = []                     # Items to be printed
+
+
+##################################################
+# All kids love log!
+
+$log.info("Options: #{$opts}")
+
+
+##################################################
+# Add an item to the list
+#
+# @param item[Object]
+def add(item)
+  $log.debug("Adding #{item['UUID']} (#{item['title']})") if item['UUID']
+  item['sday'] = ICalPal::RDT.new(*item['sdate'].to_a[0..2]) if item['sdate']
+  $items.push(item)
+end
+
+
+##################################################
+# Load the data
+
+# What are we getting?
+klass = ICalPal::($opts[:cmd])
+q = klass::QUERY
+
+$log.debug(q.gsub(/\n/, ' '))
+
+# Get it
+stmt = $db.prepare(q)
+abort(stmt.columns.sort.join(' ')) if $opts[:props].any? 'list'
+$opts[:props] = stmt.columns - $opts[:eep] if $opts[:props].any? 'all'
+
+# Iterate the SQLite3::ResultSet once
+stmt.execute.each_with_index { |i, j| $rows[j] = i }
+stmt.close
+
+$log.info("Loaded #{$rows.count} rows from #{$db.filename}")
+$db.close
+
+
+##################################################
+# Process the data
+
+# Add rows
+$rows.each do |row|
+  # --es/--is
+  next if $opts[:es].any? row['account']
+  next unless $opts[:is].empty? or $opts[:is].any? row['account']
+
+  # --ec/--ic
+  next if $opts[:ec].any? row['calendar']
+  next unless $opts[:ic].empty? or $opts[:ic].any? row['calendar']
+
+  item = klass.new(row)
+
+  # --et/--it
+  next if $opts[:et].any? item['type']
+  next unless $opts[:it].empty? or $opts[:it].any? item['type']
+
+  unless ICalPal::Event === item
+    # Always add non-event items
+    add(item)
+  else
+    # Check for all-day and cancelled events
+    next if $opts[:ea] && item['all_day'].positive?
+    next if $opts[:ia] && !item['all_day'].positive?
+    next if item['status'] == :canceled
+
+    (item['has_recurrences'].positive?)?
+      item.recurring.each { |i| add(i) } :
+      item.non_recurring.each { |i| add(i) }
+  end
+end
+
+# Add placeholders for empty days
+if $opts[:sed] && $opts[:sd] && klass == ICalPal::Event
+  days = $items.collect { |i| i['sday'] }.uniq.sort
+
+  $opts[:days].times do |n|
+    day = $opts[:from] + n
+    $items.push(klass.new(day)) unless days.any? { |i| i == day }
+  end
+end
+
+# Sort the rows
+begin
+  $items.sort_by! { |i| [ i[$opts[:sep]], i[$opts[:sort]], i['sdate'] ] }
+  $items.reverse! if $opts[:reverse]
+rescue ArgumentError => e
+  $log.warn("Sorting failed, results may be unexpected\n")
+end
+
+# Configure formatting
+mu = case $opts[:output]
+     when 'ansi' then RDoc::Markup::ToAnsi.new
+     when 'csv' then proc { |f| f.respond_to?(:gsub)? f.gsub(/\n/, '\n') : f }
+     when 'default' then RDoc::Markup::ToICalPal.new($opts)
+     when 'html' then
+       rdoc = RDoc::Options.new
+       rdoc.pipe = true
+       rdoc.output_decoration = false
+       RDoc::Markup::ToHtml.new(rdoc)
+     when 'md' then RDoc::Markup::ToMarkdown.new
+     when 'rdoc' then RDoc::Markup::ToRdoc.new
+     when 'toc' then RDoc::Markup::ToTableOfContents.new
+     end
+
+
+##################################################
+# Print the data
+
+section = nil if $opts[:sep]
+
+$items.each_with_index do |i, j|
+  # --li
+  break if $opts[:li].positive? && j >= $opts[:li]
+
+  case $opts[:output]
+  when 'csv' then
+    values = i.values.map { |v| v.to_s }
+    puts CSV.generate(write_converters: mu) { |k| k << i.keys } unless j.positive?
+    puts CSV.generate(write_converters: mu) { |k| k << values }
+  when 'hash' then p i.self
+  when 'json' then puts i.self.to_json
+  when 'yaml' then puts i.self.to_yaml
+  else
+    doc = RDoc::Markup::Document.new
+
+    # Sections
+    if $opts[:sep] && section != i[$opts[:sep]]
+      $log.debug("Section: #{i[$opts[:sep]]}")
+
+      v = RDoc::Markup::Verbatim.new
+      v.format = { item: i, prop: $opts[:sep] }
+      doc << v
+
+      doc << RDoc::Markup::BlankLine.new if j.positive?
+      doc << RDoc::Markup::Heading.new(1, i[$opts[:sep]].to_s)
+      doc << RDoc::Markup::Rule.new(0)
+
+      section = i[$opts[:sep]]
+    end
+
+    # Item
+    props = RDoc::Markup::List.new(:BULLET)
+
+    # Properties
+    $opts[:props].each_with_index do |prop, k|
+      next unless i[prop]
+      next if Array === i[prop] && !i[prop][0]
+
+      $log.debug("#{prop}: #{i[prop]}")
+
+      v = RDoc::Markup::Verbatim.new
+      v.format = { item: i, prop: prop }
+      props << v
+
+      unless k.positive?
+        # First property, value only
+        props << RDoc::Markup::Heading.new(2, i[prop].to_s)
+      else
+        props << RDoc::Markup::BlankLine.new unless (i['placeholder'] || $opts[:ps])
+        props << RDoc::Markup::ListItem.new(prop, RDoc::Markup::Paragraph.new(i[prop]))
+      end
+    end
+
+    # Print it
+    unless props.empty?
+      doc << props
+      puts doc.accept(mu)
+    end
+  end
+end

data/icalPal.gemspec

@@ -0,0 +1,21 @@
+Gem::Specification.new do |s|
+  s.name	= "icalPal"
+  s.version	= "1.0.0"
+  s.summary	= "Command-line tool to query the macOS Calendar"
+  s.description	= <<-EOF
+Inspired by icalBuddy and maintains close compatability.  Includes
+many additional features for querying, filtering, and formatting.
+EOF
+
+  s.authors	= "Andy Rosen"
+  s.email	= "ajr@corp.mlfs.org"
+  s.homepage	= "https://github.com/ajrosen/#{s.name}"
+  s.licenses	= [ "GPL-3.0+" ]
+
+  s.files	= Dir[ "#{s.name}.gemspec", "bin/*", "lib/*.rb" ]
+  s.executables	= [ "#{s.name}" ]
+  s.extra_rdoc_files = [ "README.md" ]
+
+  s.bindir = 'bin'
+  s.required_ruby_version = '>= 2.6.0'
+end

data/lib/EventKit.rb

@@ -0,0 +1,44 @@
+# Constants from EventKit[https://developer.apple.com/documentation/eventkit/]
+class EventKit
+  EKEntityType = [
+    'event',
+    'reminder',
+  ]
+
+  EKEventAvailability = {
+    notSupported: -1,
+    busy: 0,
+    free: 1,
+    tentative: 2,
+    unavailable: 3,
+  }
+
+  EKEventStatus = {
+    none: 0,
+    confirmed: 1,
+    tentative: 2,
+    canceled: 3,
+  }
+
+  EKRecurrenceFrequency = [
+    'daily',
+    'weekly',
+    'monthly',
+    'yearly',
+  ]
+
+  # EKSourceType (with color)
+  EKSourceType = [
+    { name: 'Local',      color: '#FFFFFF' }, # White
+    { name: 'Exchange',   color: '#00FFFF' }, # Cyan
+    { name: 'CalDAV',     color: '#00FF00' }, # Green
+    { name: 'MobileMe',   color: '#FFFF00' }, # Yellow
+    { name: 'Subscribed', color: '#FF0000' }, # Red
+    { name: 'Birthdays',  color: '#FF00FF' }, # Magenta
+  ]
+
+  EKSpan = [
+    'this',
+    'future',
+  ]
+end

data/lib/ToICalPal.rb

@@ -0,0 +1,177 @@
+##################################################
+# Render an RDoc::Markup::Document, closely mimicking
+# icalBuddy[https://github.com/ali-rantakari/icalBuddy]
+
+class RDoc::Markup::ToICalPal < RDoc::Markup::Formatter
+  # Standard
+  # ANSI[https://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-T.416-199303-I!!PDF-E&type=items]
+  # colors
+  ANSI = {
+    'black': 30,        '#000000': '38;5;0',
+    'red': 31,          '#ff0000': '38;5;1',
+    'green': 32,        '#00ff00': '38;5;2',
+    'yellow': 33,       '#ffff00': '38;5;3',
+    'blue': 34,         '#0000ff': '38;5;4',
+    'magenta': 35,      '#ff00ff': '38;5;5',
+    'cyan': 36,         '#00ffff': '38;5;6',
+    'white': 37,        '#ffffff': '38;5;255',
+    'default': 39,       'custom': nil,
+  }
+
+  # Increased intensity
+  BOLD = '%c[1m' % 27.chr
+
+  # Default rendition
+  NORM = '%c[0m' % 27.chr
+
+  # Properties for which we don't include labels
+  NO_LABEL = [ 'title', 'datetime' ]
+
+  # Properties that are always colorized
+  COLOR_LABEL = [ 'title', 'calendar' ]
+
+  # Default color for labels
+  LABEL_COLOR = [ 'cyan', '#00ffff' ]
+
+  # Color for datetime value
+  DATE_COLOR = [ 'yellow', '#ffff00' ]
+
+  # @param opts [Hash] Used for conditional formatting
+  # @option opts [String] :bullet Bullet
+  # @option opts [Boolean] :nc No calendar names
+  # @option opts [Boolean] :npn No property names
+  # @option opts [Integer] :palette (nil) 8 for \-f, 24 for \--color
+  # @option opts [Array<String>] :ps List of property separators
+  # @option opts [String] :ss Section separator
+  def initialize(opts)
+    @opts = opts
+  end
+
+  # Start a new document
+  def start_accepting
+    @res = []
+    @ps = 0
+  end
+
+  # Close the document
+  def end_accepting
+    @res.join
+  end
+
+  # Add a bullet for the first property of an item
+  #
+  # @param arg [Array] Ignored
+  def accept_list_start(arg)
+    begin
+      return if @item['placeholder']
+    rescue
+    end
+
+    @res << "#{@opts[:bullet]} "
+  end
+
+  # Add a property name
+  #
+  # @param arg [RDoc::Markup::ListItem]
+  # @option arg [String] .label Contains the property name
+  def accept_list_item_start(arg)
+    @res << @opts[:ps][@ps] || '    ' unless @item['placeholder']
+    @res << colorize(*LABEL_COLOR, arg.label) << ": " unless @opts[:npn] || NO_LABEL.any?(arg.label)
+
+    @ps += 1 unless @ps == @opts[:ps].count - 1
+  end
+
+  # Add a blank line
+  #
+  # @param arg [Array] Ignored
+  def accept_blank_line(*arg)
+    @res << "\n"
+  end
+
+  # Add either a section header or the first property of an item
+  #
+  # @param h [RDoc::Markup::Heading]
+  # @option h [Integer] :level 1 for a section header
+  # @option h [Integer] :level 2 for a property name
+  # @option h [String] :text The header's text
+  def accept_heading(h)
+    h.text = colorize(@item['symbolic_color_name'], @item['color'], h.text) if (h.level == 2) || COLOR_LABEL.any?(@prop)
+    @res << h.text
+
+    case h.level
+    when 1 then
+      @res << ":"
+    when 2 then
+      if @prop == 'title' && @item['calendar']
+        @res << bold(" (#{@item['calendar']})") unless @opts[:nc] || @item['title'] == @item['calendar']
+      end
+    end
+  end
+
+  # Add the property value
+  #
+  # @param p [RDoc::Markup::Paragraph]
+  # @option p [Array<String>] :parts The property's text
+  def accept_paragraph(p)
+    t = p.parts.join('; ').gsub(/\n/, "\n    ")
+    t = colorize(*DATE_COLOR, t) if @prop == 'datetime'
+    @res << t
+  end
+
+  # Add a section separator
+  #
+  # @param weight Ignored
+  def accept_rule(weight)
+    @res << @opts[:ss]
+    accept_blank_line
+  end
+
+  # Don't add anything to the document, just save the item and
+  # property name for later
+  #
+  # @param h [RDoc::Markup::Verbatim]
+  # @option h [String] :parts Ignored
+  # @option h [{item, prop => ICalPal::Event, String}] :format
+  def accept_verbatim(h)
+    @item = h.format[:item]
+    @prop = h.format[:prop]
+  end
+
+  # @param str [String]
+  # @return [String] str with increased intensity[#BOLD]
+  def bold(str)
+    return str unless @opts[:palette]
+    BOLD + str + NORM
+  end
+
+  # @param c8 [String] Color used for \-f
+  # @param c24 [String] Color used for \--color
+  # @return [String] str in color, depending on opts[#]
+  def colorize(c8, c24, str)
+    return str unless c8 && c24 && @opts[:palette]
+
+    case @opts[:palette]
+    when 8 then                 # Default colour table
+      c = ANSI[c8.downcase.to_sym]
+      c ||= ANSI[c24[0..6].downcase.to_sym]
+      c ||= ANSI[:white]
+
+    when 24 then                # Direct colour in RGB space
+      rgb = c24[1..].split(/(\h\h)(\h\h)(\h\h)/)
+      rgb.map! { |i| i.to_i(16) }
+      c = [ 38, 2, rgb[1..] ].join(';')
+    end
+
+    sprintf('%c[%sm%s%c[%sm', 27.chr, c, str, 27.chr, ANSI[:default])
+  end
+
+  # @!visibility private
+
+  # @param a [Array] Ignored
+  def accept_list_end(a)
+  end
+
+  # @param a [Array] Ignored
+  def accept_list_item_end(a)
+  end
+end

data/lib/calendar.rb

@@ -0,0 +1,24 @@
+module ICalPal
+  # Class representing items from the <tt>Calendar</tt> table
+  class Calendar
+    include ICalPal
+
+    QUERY = <<~SQL
+SELECT DISTINCT
+
+Store.name AS account,
+Calendar.title AS calendar,
+*
+
+FROM #{self.name.split('::').last}
+
+JOIN Store ON store_id = Store.rowid
+
+WHERE Store.disabled IS NOT 1
+AND Store.display_order IS NOT -1
+AND (Calendar.display_order IS NOT -1 OR external_rep IS NOT NULL)
+AND Calendar.flags IS NOT 519
+SQL
+
+  end
+end