remind-rb 6.2.10.1

data/lib/remind/library.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+require_relative "version"
+
+module Remind
+  # Written out rather than `Class.new(StandardError)`: a test runner that
+  # `load`s a file twice would otherwise replace the class and orphan every
+  # subclass of it.
+  class Error < StandardError
+  end
+
+  # The shared library is not built, and no REMIND_LIBRARY says otherwise.
+  class LibraryMissing < Error
+    def initialize(path)
+      super(<<~MESSAGE)
+        Remind's shared library is not built: #{path}
+
+        Build it with `rake library`, or point REMIND_LIBRARY at one built
+        elsewhere. Building needs a C compiler and make -- the same two things
+        Remind itself needs.
+      MESSAGE
+    end
+  end
+
+  # `configure`, `make` or the compiler said no.
+  class BuildError < Error
+  end
+
+  # Where the shared library is, and where the sources it is built from are.
+  #
+  # Remind ships no shared library -- its Makefile builds two programs -- so
+  # there is nothing installed to find. `Builder` compiles one out of the
+  # vendored sources into `tmp/`, and this is the module that agrees with it
+  # about where that is.
+  module Library
+    # An escape hatch for a library built elsewhere: a distribution package, a
+    # Nix store path, a scratch build.
+    ENV_VAR = "REMIND_LIBRARY"
+
+    # `.so` on Linux, `.bundle` on macOS -- whatever this Ruby loads.
+    EXTENSION = RbConfig::CONFIG.fetch("DLEXT")
+
+    module_function
+
+    # The gem's own directory: two levels up from lib/remind/.
+    def root
+      File.expand_path("../..", __dir__)
+    end
+
+    # The vendored Remind release, named for its version so that the bindings
+    # cannot be vague about which one they bind.
+    def source_root
+      File.join(root, "remind-v#{REMIND_VERSION}")
+    end
+
+    def source_directory
+      File.join(source_root, "src")
+    end
+
+    # The one C file this gem owns. See ext/remind/shim.c for what it is for.
+    def shim
+      File.join(
+        root,
+        "ext",
+        "remind",
+        "shim.c",
+      )
+    end
+
+    # The compiled library: what `rake compile` writes, and what a precompiled
+    # gem carries. One place, so that a checkout and an installed gem look the
+    # same to everything above this.
+    def default_path
+      File.join(
+        root,
+        "lib",
+        "remind",
+        "libremind.#{EXTENSION}",
+      )
+    end
+
+    # A library named in the environment is the answer, whether or not it is
+    # there: someone who names one has a particular library in mind, and
+    # quietly using a different one would be worse than saying it is missing.
+    def path
+      candidate = ENV.fetch(ENV_VAR, default_path)
+
+      if File.exist?(candidate)
+        candidate
+      else
+        raise LibraryMissing, candidate
+      end
+    end
+
+    def built?
+      File.exist?(ENV.fetch(ENV_VAR, default_path))
+    end
+  end
+end
+
+__END__
+
+describe "Remind::Library" do
+  it "puts the library where a precompiled gem carries it" do
+    Remind::Library.default_path.should.end_with "/lib/remind/libremind.#{RbConfig::CONFIG["DLEXT"]}"
+  end
+
+  it "vendors the sources in a directory named for the Remind release" do
+    Remind::Library.source_root.should.end_with "remind-v#{Remind::REMIND_VERSION}"
+  end
+
+  it "finds the sources and the shim it claims to build from" do
+    File.directory?(Remind::Library.source_directory).should.be.true
+    File.exist?(File.join(Remind::Library.source_root, "configure")).should.be.true
+    File.exist?(Remind::Library.shim).should.be.true
+  end
+
+  it "prefers a library named in the environment" do
+    ENV[Remind::Library::ENV_VAR] = __FILE__
+
+    Remind::Library.path.should == __FILE__
+  ensure
+    ENV.delete(Remind::Library::ENV_VAR)
+  end
+
+  it "loads the compiled library when nothing overrides it" do
+    Remind::Library.path.should == Remind::Library.default_path
+    Remind::Library.should.be.built
+  end
+
+  it "explains itself when there is no library to load" do
+    ENV[Remind::Library::ENV_VAR] = "/nonexistent/libremind.so"
+
+    error = lambda { Remind::Library.path }.should.raise Remind::LibraryMissing
+    error.message.should.include "rake library"
+  ensure
+    ENV.delete(Remind::Library::ENV_VAR)
+  end
+end

data/lib/remind/native.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+require "fiddle"
+
+require_relative "library"
+
+module Remind
+  # The dlopen'd library: the Remind functions the bindings call, the shim
+  # functions that reach what Fiddle cannot, and the globals Remind keeps its
+  # state in.
+  #
+  # Fiddle rather than a C extension, because there is no extension to write.
+  # Remind's sources build into a shared library as they are, and everything
+  # here is a plain C function over ints and pointers. The one file of C in
+  # this gem, ext/shim.c, exists for struct layout and for the six-call
+  # sequence that parses a REM line -- not because Fiddle needs help calling
+  # anything.
+  #
+  # Functions are looked up on first call and kept: `Fiddle::Handle#[]` is a
+  # dlsym every time.
+  class Native
+    INT = Fiddle::TYPE_INT
+
+    POINTER = Fiddle::TYPE_VOIDP
+
+    SIZE = Fiddle::TYPE_SIZE_T
+
+    VOID = Fiddle::TYPE_VOID
+
+    # name => [C symbol, argument types, return type]
+    FUNCTIONS = {
+      # Dates. Remind counts days from 1990-01-01 and numbers months from
+      # zero; both conversions are called rather than repeated, so the epoch
+      # cannot drift from the library's.
+      dse:                    ["DSE", [INT, INT, INT], INT],
+      from_dse:               ["FromDSE", [INT, POINTER, POINTER, POINTER], VOID],
+
+      # Expressions, and the messages for when they fail.
+      evaluate:               ["EvalExpr", [POINTER, POINTER, POINTER], INT],
+      error_message:          ["GetErr", [INT], POINTER],
+
+      # The startup sequence `Runtime` mirrors. Remind does all of this inside
+      # InitRemind, which also parses argv, opens files and exits on bad
+      # input, and is therefore not something a library can call.
+      init_variables:         ["InitVars", [], VOID],
+      init_user_functions:    ["InitUserFunctions", [], VOID],
+      init_translation_table: ["InitTranslationTable", [], VOID],
+      init_files:             ["InitFiles", [], VOID],
+      init_dedupe_table:      ["InitDedupeTable", [], VOID],
+      init_buffer:            ["DBufInit", [POINTER], VOID],
+      system_date:            ["SystemDate", [POINTER, POINTER, POINTER], INT],
+      system_time:            ["SystemTime", [INT], INT],
+
+      # libc's, through the same handle: Remind writes its diagnostics through
+      # a FILE *, so somewhere to point it is part of the interface.
+      open_stream:            ["fopen", [POINTER, POINTER], POINTER],
+
+      # The shim.
+      sizeof_trigger:         ["remrb_sizeof_trigger", [], SIZE],
+      sizeof_timetrig:        ["remrb_sizeof_timetrig", [], SIZE],
+      parse_reminder:         ["remrb_parse_reminder", [POINTER, POINTER, POINTER, POINTER, POINTER, INT], INT],
+      next_trigger:           ["remrb_next_trigger", [POINTER, POINTER, INT, POINTER], INT],
+      free_trigger:           ["remrb_free_trigger", [POINTER], VOID],
+      open_file:              ["remrb_open_file", [POINTER], INT],
+      read_line:              ["remrb_read_line", [POINTER], INT],
+      trigger_tags:           ["remrb_trigger_tags", [POINTER], POINTER],
+      trigger_timezone:       ["remrb_trigger_timezone", [POINTER], POINTER],
+    }.freeze
+
+    # The Trigger fields a calendar entry is made out of. Each is an accessor
+    # in the shim, compiled against Remind's own headers, so no byte offset is
+    # ever written down on this side.
+    TRIGGER_FIELDS = %i[
+      wd d m y back delta rep localomit skip until typ once scanfrom from
+      priority duration_days eventduration eventstart is_todo addomit need_wkday
+    ].freeze
+
+    TIMETRIG_FIELDS = %i[time delta repeat duration].freeze
+
+    # The values Remind uses for "the reminder did not say", and the constants
+    # it tags a body with. Read from the shim rather than copied, for the same
+    # reason as the field offsets.
+    CONSTANTS = %i[
+      no_day no_month no_year no_weekday no_until no_time quote_marker
+      normal_mode cal_mode eof
+      msg_type msf_type run_type cal_type sat_type passthru_type
+    ].freeze
+
+    # Remind keeps its idea of now in globals rather than passing it around,
+    # so these are as much a part of the interface as the functions.
+    #
+    #   DSEToday       the date every relative calculation is relative to
+    #   LocalDSEToday  the same, before a --date override moves it
+    #   RealToday      what the system clock said at startup
+    #   CurYear        the year an incomplete date is completed with
+    #   SysTime        seconds since midnight, or -1 to read the clock
+    GLOBALS = %w[DSEToday LocalDSEToday RealToday CurYear SysTime LocalSysTime].freeze
+
+    # The dynamic buffers Remind expects to have been initialised, and the
+    # stream it expects to have been pointed somewhere.
+    BUFFERS = %w[Banner LineBuffer ExprBuf].freeze
+
+    ERROR_STREAM = "ErrFp"
+
+    attr_reader :path
+
+    def initialize(path = Library.path)
+      @path = path
+      @handle = Fiddle::Handle.new(path)
+      @functions = {}
+    end
+
+    FUNCTIONS.each do |name, (symbol, arguments, returning)|
+      define_method(name) do |*values|
+        function(symbol, arguments, returning).call(*values)
+      end
+    end
+
+    TRIGGER_FIELDS.each do |field|
+      define_method(:"trigger_#{field}") do |trigger|
+        function("remrb_trigger_#{field}", [POINTER], INT).call(trigger)
+      end
+    end
+
+    TIMETRIG_FIELDS.each do |field|
+      define_method(:"timetrig_#{field}") do |timetrig|
+        function("remrb_timetrig_#{field}", [POINTER], INT).call(timetrig)
+      end
+    end
+
+    CONSTANTS.each do |name|
+      define_method(name) do
+        function("remrb_#{name}", [], INT).call
+      end
+    end
+
+    def read_global(name)
+      global(name)[0, Fiddle::SIZEOF_INT].unpack1("i!")
+    end
+
+    def write_global(name, value)
+      global(name)[0, Fiddle::SIZEOF_INT] = [value].pack("i!")
+    end
+
+    # The address of a global, for the functions that take one: DBufInit wants
+    # the buffer itself, not a copy of it.
+    def address_of(name)
+      Fiddle::Pointer.new(@handle[name])
+    end
+
+    # A pointer-sized global, which is what a FILE * is.
+    def write_pointer(name, address)
+      Fiddle::Pointer.new(@handle[name], Fiddle::SIZEOF_VOIDP)[0, Fiddle::SIZEOF_VOIDP] =
+        [address].pack("J")
+    end
+
+    # `stderr` is a variable in libc, and it holds the FILE * rather than
+    # being one.
+    def standard_error
+      Fiddle::Pointer.new(Fiddle::Handle::DEFAULT["stderr"], Fiddle::SIZEOF_VOIDP)[
+        0,
+        Fiddle::SIZEOF_VOIDP,
+      ].unpack1("J")
+    end
+
+    private
+
+      def function(symbol, arguments, returning)
+        @functions[symbol] ||= Fiddle::Function.new(
+          @handle[symbol],
+          arguments,
+          returning,
+          name: symbol,
+        )
+      end
+
+      def global(name)
+        Fiddle::Pointer.new(@handle[name], Fiddle::SIZEOF_INT)
+      end
+  end
+end
+
+__END__
+
+describe "Remind::Native" do
+  native = Remind::Native.new
+
+  it "loads the library the bindings resolved" do
+    native.path.should == Remind::Library.path
+  end
+
+  describe "Remind's own functions" do
+    it "converts a date to Remind's day count" do
+      # Remind counts from 1990-01-01 and numbers months from zero.
+      native.dse(1990, 0, 1).should == 0
+      native.dse(2027, 0, 15).should == 13528
+    end
+
+    it "keeps a function across calls rather than dlsym-ing again" do
+      first = native.send(:function, "DSE", [Remind::Native::INT] * 3, Remind::Native::INT)
+
+      native.send(:function, "DSE", [Remind::Native::INT] * 3, Remind::Native::INT)
+            .should.be.same_as first
+    end
+  end
+
+  describe "the shim" do
+    it "answers how big the structs a caller has to allocate are" do
+      native.sizeof_trigger.should.be > 0
+      native.sizeof_timetrig.should.be > 0
+    end
+
+    it "answers Remind's sentinels rather than repeating their values" do
+      native.no_day.should == -1
+      native.no_year.should == -1
+      native.no_time.should == 2_147_483_647
+    end
+
+    it "answers the body types" do
+      native.msg_type.should == 1
+      native.run_type.should == 2
+    end
+
+    it "answers the marker DoSubst leaves around a calendar title" do
+      native.quote_marker.should == 1
+    end
+
+    it "has an accessor for every Trigger field the bindings read" do
+      Remind::Native::TRIGGER_FIELDS.each do |field|
+        native.should.respond_to :"trigger_#{field}"
+      end
+    end
+  end
+
+  describe "globals" do
+    it "reads and writes Remind's idea of today" do
+      was = native.read_global("DSEToday")
+
+      native.write_global("DSEToday", 13528)
+      native.read_global("DSEToday").should == 13528
+    ensure
+      native.write_global("DSEToday", was)
+    end
+
+    it "names every global the bindings touch" do
+      Remind::Native::GLOBALS.each do |name|
+        lambda { native.read_global(name) }.should.not.raise Fiddle::DLError
+      end
+    end
+
+    it "finds the buffers Remind expects initialised" do
+      Remind::Native::BUFFERS.each do |name|
+        native.address_of(name).to_i.should.not == 0
+      end
+    end
+  end
+end