remind-rb 6.2.10.1

data/lib/remind/session.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require "date"
+require "fiddle"
+
+require_relative "library"
+require_relative "native"
+require_relative "runtime"
+require_relative "value"
+
+module Remind
+  # Remind evaluated something and objected. The message is Remind's own, out
+  # of `GetErr`.
+  class EvaluationError < Error
+    attr_reader :code, :subject
+
+    def initialize(code, message, subject)
+      @code = code
+      @subject = subject
+
+      super("#{message} in #{subject.inspect}")
+    end
+  end
+
+  # A live Remind interpreter.
+  #
+  # Remind is a program, not a library, and it shows in the shape of the C:
+  # today's date is a global, the current time is a global, and everything is
+  # computed against whatever those say. That has two consequences.
+  #
+  # The first is a gift: "now" is settable, so a calculation against a fixed
+  # date is reproducible rather than a reading off the clock. Converting a
+  # reminder file to a calendar depends on it -- `REM Mon` means a different
+  # first date tomorrow than it does today.
+  #
+  # The second is that the state is per-process, not per-object. Two Sessions
+  # are two views of the same globals, so the lock is on the class and calls
+  # into the library are serialised whether they came from one Session or
+  # several.
+  class Session
+    LOCK = Mutex.new
+
+    NO_TIME = -1
+
+    SECONDS_PER_MINUTE = 60
+
+    attr_reader :native
+
+    def initialize(native: Native.new, diagnostics: false)
+      @native = native
+
+      Runtime.boot(native, diagnostics: diagnostics)
+    end
+
+    # Evaluates a Remind expression: an Integer for a number, a String for a
+    # string, a Date for a date, a Time for a datetime, minutes since midnight
+    # for a time.
+    #
+    #   session.evaluate("moonphase(today())")   # => 46
+    #   session.evaluate("version()")            # => "06.02.10"
+    def evaluate(expression)
+      LOCK.synchronize do
+        evaluate_unlocked(expression)
+      end
+    end
+
+    # The date every relative calculation is relative to.
+    def today
+      date(native.read_global("DSEToday"))
+    end
+
+    # Pins it, the way `remind --date=` does.
+    def today=(date)
+      LOCK.synchronize do
+        pin_date(date)
+      end
+    end
+
+    # Pins the date and the time of day together, for reminders that depend on
+    # the clock as well as the calendar.
+    def now=(time)
+      LOCK.synchronize do
+        pin_date(time.to_date)
+        pin_time((time.hour * 60) + time.min)
+      end
+    end
+
+    def unpin_time
+      LOCK.synchronize do
+        pin_time(nil)
+      end
+    end
+
+    # Remind's day count for a date, and back again.
+    def dse(date)
+      native.dse(date.year, date.month - 1, date.day)
+    end
+
+    def date(dse)
+      Value.to_date(dse, native)
+    end
+
+    # Whether Remind prints its own diagnostics -- the offending line with a
+    # caret under it -- as well as this raising.
+    def diagnostics=(wanted)
+      LOCK.synchronize do
+        Runtime.point_errors(native, wanted)
+      end
+    end
+
+    # The Remind release the library was built from, out of the library's own
+    # `version()` rather than out of this gem's idea of it.
+    def version
+      evaluate("version()")
+    end
+
+    def error_message(code)
+      native.error_message(code).to_s
+    end
+
+    private
+
+      def evaluate_unlocked(expression)
+        terminated = "#{expression}\0"
+        cursor = pointer_to(terminated)
+        result = Value.allocate
+
+        code = native.evaluate(cursor, result, nil)
+
+        if code.zero?
+          Value.read(result, native)
+        else
+          raise EvaluationError.new(code, error_message(code), expression)
+        end
+      end
+
+      # EvalExpr takes a `char **`: it advances the caller's pointer past what
+      # it consumed, so it is given a slot holding the address of the text
+      # rather than the text itself.
+      def pointer_to(text)
+        buffer = Fiddle::Pointer[text]
+        slot = Fiddle::Pointer.malloc(Fiddle::SIZEOF_VOIDP, Fiddle::RUBY_FREE)
+        slot[0, Fiddle::SIZEOF_VOIDP] = [buffer.to_i].pack("J")
+
+        # The slot keeps an address, which the garbage collector cannot see,
+        # so the string it points into has to outlive the call.
+        @evaluating = text
+
+        slot
+      end
+
+      # RealToday is deliberately left alone: it is what the system clock said
+      # when the library came up, and Remind uses it to tell today from a date
+      # it was told to pretend about.
+      def pin_date(date)
+        counted = dse(date)
+
+        native.write_global("DSEToday", counted)
+        native.write_global("LocalDSEToday", counted)
+        native.write_global("CurYear", date.year)
+      end
+
+      def pin_time(minutes)
+        if minutes.nil?
+          native.write_global("SysTime", NO_TIME)
+          native.write_global("LocalSysTime", NO_TIME)
+        else
+          native.write_global("SysTime", minutes * SECONDS_PER_MINUTE)
+          native.write_global("LocalSysTime", minutes * SECONDS_PER_MINUTE)
+        end
+      end
+  end
+end
+
+__END__
+
+describe "Remind::Session" do
+  session = Remind::Session.new
+
+  before do
+    session.today = Date.new(2027, 1, 15)
+  end
+
+  describe "evaluate" do
+    it "answers an integer" do
+      session.evaluate("1 + 2").should == 3
+    end
+
+    it "answers a string" do
+      session.evaluate('"a" + "b"').should == "ab"
+    end
+
+    it "answers a date" do
+      session.evaluate("today()").should == Date.new(2027, 1, 15)
+    end
+
+    it "answers a time as minutes since midnight" do
+      session.evaluate("12:30").should == 750
+    end
+
+    it "runs Remind's own functions" do
+      session.evaluate("wkdaynum(today())").should == 5
+      session.evaluate("trigger(date(2027, 1, 15))").should == "15 January 2027"
+    end
+
+    it "reads the version out of the library it loaded" do
+      session.version.should == Remind::REMIND_VERSION
+    end
+
+    it "raises with Remind's own message when the expression is wrong" do
+      error = lambda { session.evaluate("1 +") }.should.raise Remind::EvaluationError
+
+      error.message.should.include "1 +"
+      error.code.should.not == 0
+    end
+  end
+
+  describe "pinning the clock" do
+    it "makes today whatever it is told" do
+      session.today = Date.new(2030, 6, 1)
+
+      session.today.should == Date.new(2030, 6, 1)
+      session.evaluate("today()").should == Date.new(2030, 6, 1)
+    end
+
+    it "makes a date calculation reproducible" do
+      session.evaluate("today() + 30").should == Date.new(2027, 2, 14)
+    end
+
+    it "pins the time of day as well" do
+      session.now = Time.local(2027, 1, 15, 9, 30)
+
+      session.evaluate("now()").should == 570
+    ensure
+      session.unpin_time
+    end
+  end
+
+  describe "dates" do
+    it "converts to Remind's day count and back" do
+      session.dse(Date.new(1990, 1, 1)).should == 0
+      session.date(0).should == Date.new(1990, 1, 1)
+      session.dse(Date.new(2027, 1, 15)).should == 13528
+    end
+  end
+end

data/lib/remind/source.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "fiddle"
+
+require_relative "native"
+require_relative "reminder"
+require_relative "session"
+
+module Remind
+  # A file of reminders, read by Remind.
+  #
+  # Named Source rather than File because it lives inside `Remind`, where a
+  # class called File would shadow the one in the standard library for every
+  # other file in the gem.
+  #
+  # A reminder file is not a list of lines. A backslash joins two of them into
+  # one; `INCLUDE` splices another file into the middle; `INCLUDEsys` reaches
+  # into the system directory for the holiday files that ship with Remind. Any
+  # reader that treats the file as text gets all three wrong, so this one does
+  # not read text: `IncludeFile` opens the file and `ReadLine` hands back one
+  # logical line at a time, out of whichever file is currently on Remind's
+  # stack, exactly as `remind` itself sees them.
+  #
+  # What comes out is the lines Remind can turn into events. Everything else
+  # -- SET, IF, OMIT, comments, RUN reminders -- is skipped, because it is a
+  # command rather than an appointment.
+  class Source
+    # Remind reads standard input under this name, the same as the program.
+    STDIN = "-"
+
+    attr_reader :path, :session
+
+    def initialize(path, session: Session.new)
+      @path = path
+      @session = session
+    end
+
+    # Every reminder in the file, in the order the file gives them. Lazy: a
+    # file can INCLUDE another, and a caller that only wants the first few
+    # should not pay for the rest.
+    def reminders
+      Enumerator.new do |found|
+        lines.each do |line|
+          reminder = Reminder.parse(line, session: session)
+
+          if reminder
+            found << reminder
+          end
+        end
+      end
+    end
+
+    # The logical lines, continuations joined and includes spliced.
+    def lines
+      Enumerator.new do |line|
+        open
+
+        while (text = read)
+          line << text
+        end
+      end
+    end
+
+    private
+
+      def native
+        session.native
+      end
+
+      def open
+        code = native.open_file(Fiddle::Pointer["#{path}\0"])
+
+        if code.nonzero?
+          raise EvaluationError.new(code, session.error_message(code), path)
+        end
+      end
+
+      # nil at the end of the last file, which is how the enumerator stops.
+      def read
+        slot = Fiddle::Pointer.malloc(Fiddle::SIZEOF_VOIDP, Fiddle::RUBY_FREE)
+        code = native.read_line(slot)
+
+        if code.zero?
+          text_at(slot)
+        end
+      end
+
+      def text_at(slot)
+        address = slot[0, Fiddle::SIZEOF_VOIDP].unpack1("J")
+
+        if address.zero?
+          ""
+        else
+          Fiddle::Pointer.new(address).to_s.force_encoding(Encoding::UTF_8)
+        end
+      end
+  end
+end
+
+__END__
+
+require "tempfile"
+
+describe "Remind::Source" do
+  session = Remind::Session.new
+  session.today = Date.new(2026, 8, 19)
+
+  written = proc do |text|
+    file = Tempfile.new(["reminders", ".rem"])
+    file.write(text)
+    file.close
+    Remind::Source.new(file.path, session: session)
+  end
+
+  it "reads the reminders in a file" do
+    file = written.(<<~REM)
+      # A comment
+      REM 15 Jan MSG dentist
+      REM Mon MSG gym
+    REM
+
+    file.reminders.map(&:summary).should == ["dentist", "gym"]
+  end
+
+  it "joins a continued line, the way Remind does" do
+    file = written.(<<~REM)
+      REM 15 Jan \\
+      MSG dentist
+    REM
+
+    file.reminders.map(&:summary).should == ["dentist"]
+  end
+
+  it "skips the commands that are not reminders" do
+    file = written.(<<~REM)
+      SET a 1
+      OMIT 25 Dec
+      IF a > 0
+      REM 1 Jan MSG new year
+      ENDIF
+    REM
+
+    file.reminders.map(&:summary).should == ["new year"]
+  end
+
+  it "splices in an included file" do
+    included = Tempfile.new(["included", ".rem"])
+    included.write("REM 4 Jul MSG fireworks\n")
+    included.close
+
+    file = written.("REM 1 Jan MSG new year\nINCLUDE #{included.path}\n")
+
+    file.reminders.map(&:summary).should == ["new year", "fireworks"]
+  end
+
+  it "raises when the file is not there" do
+    lambda { Remind::Source.new("/nonexistent.rem", session: session).lines.to_a }
+      .should.raise Remind::EvaluationError
+  end
+end

data/lib/remind/value.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "date"
+require "fiddle"
+
+module Remind
+  # Remind's `Value` -- a type tag and a union of `char *` and `int` -- read
+  # back into Ruby.
+  #
+  #   typedef struct {
+  #       char type;
+  #       union { char *str; int val; } v;
+  #   } Value;
+  #
+  # This one struct is read directly rather than through the shim: it is two
+  # fields, the union sits at the pointer's alignment on every platform
+  # Fiddle runs on, and an expression's result is the only place it appears.
+  #
+  # Every type but one maps onto something already in the standard library.
+  # The exception is TIME, which Remind stores as minutes since midnight with
+  # no date attached; it stays an Integer, because inventing a date for it
+  # would be inventing information.
+  module Value
+    ERR = 0x0
+
+    INT = 0x1
+
+    TIME = 0x2
+
+    DATE = 0x4
+
+    DATETIME = TIME | DATE
+
+    STR = 0x8
+
+    MINUTES_PER_DAY = 1440
+
+    MINUTES_PER_HOUR = 60
+
+    UNION_OFFSET = Fiddle::SIZEOF_VOIDP
+
+    SIZE = Fiddle::SIZEOF_VOIDP * 2
+
+    module_function
+
+    def allocate
+      Fiddle::Pointer.malloc(SIZE, Fiddle::RUBY_FREE)
+    end
+
+    def type(pointer)
+      pointer[0, 1].unpack1("c")
+    end
+
+    # `native` is what turns a day count back into a date: Remind's own
+    # FromDSE, so the epoch is Remind's rather than one repeated here.
+    def read(pointer, native)
+      case type(pointer)
+      when INT      then integer(pointer)
+      when STR      then string(pointer)
+      when DATE     then to_date(integer(pointer), native)
+      when TIME     then integer(pointer)
+      when DATETIME then to_time(integer(pointer), native)
+      end
+    end
+
+    def integer(pointer)
+      pointer[UNION_OFFSET, Fiddle::SIZEOF_INT].unpack1("i!")
+    end
+
+    # The string was malloc'd by Remind and is ours to free once copied.
+    def string(pointer)
+      address = pointer[UNION_OFFSET, Fiddle::SIZEOF_VOIDP].unpack1("J")
+
+      if address.zero?
+        ""
+      else
+        copied(address)
+      end
+    end
+
+    def copied(address)
+      Fiddle::Pointer.new(address).to_s.force_encoding(Encoding::UTF_8).tap do
+        Fiddle.free(address)
+      end
+    end
+
+    def to_date(dse, native)
+      year = Fiddle::Pointer.malloc(Fiddle::SIZEOF_INT, Fiddle::RUBY_FREE)
+      month = Fiddle::Pointer.malloc(Fiddle::SIZEOF_INT, Fiddle::RUBY_FREE)
+      day = Fiddle::Pointer.malloc(Fiddle::SIZEOF_INT, Fiddle::RUBY_FREE)
+
+      native.from_dse(
+        dse,
+        year,
+        month,
+        day,
+      )
+
+      # Remind numbers months from zero, everywhere. That stops here.
+      Date.new(
+        unpack(year),
+        unpack(month) + 1,
+        unpack(day),
+      )
+    end
+
+    # A datetime is one number: the day count times the minutes in a day, plus
+    # the minutes into that day. It is wall-clock time in the local zone,
+    # which is what Time.local means.
+    def to_time(packed, native)
+      day = to_date(packed / MINUTES_PER_DAY, native)
+      minutes = packed % MINUTES_PER_DAY
+
+      Time.local(
+        day.year,
+        day.month,
+        day.day,
+        minutes / MINUTES_PER_HOUR,
+        minutes % MINUTES_PER_HOUR,
+      )
+    end
+
+    def unpack(pointer)
+      pointer[0, Fiddle::SIZEOF_INT].unpack1("i!")
+    end
+  end
+end
+
+__END__
+
+require_relative "native"
+
+describe "Remind::Value" do
+  native = Remind::Native.new
+
+  # Building a Value by hand is the only way to read one without evaluating an
+  # expression, and it pins the layout this file assumes.
+  build = proc do |type, number|
+    Remind::Value.allocate.tap do |pointer|
+      pointer[0, 1] = [type].pack("c")
+      pointer[Remind::Value::UNION_OFFSET, Fiddle::SIZEOF_INT] = [number].pack("i!")
+    end
+  end
+
+  read = proc { |type, number| Remind::Value.read(build.(type, number), native) }
+
+  it "reads an integer" do
+    read.(Remind::Value::INT, 42).should == 42
+    read.(Remind::Value::INT, -17).should == -17
+  end
+
+  it "reads a date through Remind's own epoch" do
+    read.(Remind::Value::DATE, 0).should == Date.new(1990, 1, 1)
+    read.(Remind::Value::DATE, 13528).should == Date.new(2027, 1, 15)
+  end
+
+  it "reads a time as minutes since midnight" do
+    read.(Remind::Value::TIME, 570).should == 570
+  end
+
+  it "reads a datetime as local wall-clock time" do
+    packed = (13528 * Remind::Value::MINUTES_PER_DAY) + 570
+
+    read.(Remind::Value::DATETIME, packed).should == Time.local(2027, 1, 15, 9, 30)
+  end
+
+  it "reads an error value as nothing at all" do
+    read.(Remind::Value::ERR, 0).should.be.nil
+  end
+end

data/lib/remind/version.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Remind
+  # <Remind release>.<our release>. The first three segments say which version
+  # of Remind this gem vendors and binds; the fourth is ours, bumped for
+  # changes on the Ruby side against that same release. Managed by
+  # bin/increment-version -- edit that, not this.
+  VERSION = "6.2.10.1"
+
+  # The vendored source directory is named for the release, in Remind's own
+  # zero-padded spelling.
+  REMIND_VERSION = "06.02.10"
+end