remind-rb 6.2.10.1

data/ext/remind/shim.c

@@ -0,0 +1,379 @@
+/***************************************************************/
+/*                                                             */
+/*  SHIM.C                                                     */
+/*                                                             */
+/*  The one piece of C in remind-rb.                           */
+/*                                                             */
+/*  Remind's C interface is not hostile to a binding, but two  */
+/*  parts of it cannot be reached from Fiddle alone:           */
+/*                                                             */
+/*  1. Struct layout. Trigger has thirty-odd fields, and       */
+/*     reading them from Ruby would mean hard-coding byte      */
+/*     offsets that the next release, the next compiler or the */
+/*     next platform is free to move. The accessors below are  */
+/*     compiled against the same headers as the rest of the    */
+/*     library, so the offsets are the compiler's problem      */
+/*     rather than the binding's.                              */
+/*                                                             */
+/*  2. The sequence in DoRem. Parsing a REM line means         */
+/*     CreateParser, ParseRem, ComputeTrigger, ParseToken,     */
+/*     FindToken and DoSubst in that order, with cleanup on    */
+/*     every early exit. Driving that from Ruby would mean     */
+/*     six FFI calls per line and a Parser struct allocated by */
+/*     size; here it is one call that either works or does     */
+/*     not.                                                    */
+/*                                                             */
+/*  Everything else -- dates, the moon, the Hebrew calendar,   */
+/*  expression evaluation -- is called directly from Ruby, and */
+/*  deliberately not wrapped here.                             */
+/*                                                             */
+/*  This file is part of remind-rb, and is distributed under   */
+/*  the same terms as Remind itself.                           */
+/*  SPDX-License-Identifier: GPL-2.0-only                      */
+/*                                                             */
+/***************************************************************/
+
+#include "config.h"
+
+#include <stddef.h>
+#include <string.h>
+
+#include "types.h"
+#include "protos.h"
+#include "globals.h"
+#include "err.h"
+
+/* How big the caller has to make the blocks it hands back in. */
+size_t remrb_sizeof_trigger(void)  { return sizeof(Trigger); }
+size_t remrb_sizeof_timetrig(void) { return sizeof(TimeTrig); }
+
+/* The sentinels Remind uses for "the reminder did not say". */
+int remrb_no_day(void)      { return NO_DAY; }
+int remrb_no_month(void)    { return NO_MON; }
+int remrb_no_year(void)     { return NO_YR; }
+int remrb_no_weekday(void)  { return NO_WD; }
+int remrb_no_until(void)    { return NO_UNTIL; }
+int remrb_no_time(void)     { return NO_TIME; }
+
+/* The marker DoSubst leaves around the part of a message that %" marked as
+   the calendar entry's title. */
+int remrb_quote_marker(void) { return QUOTE_MARKER; }
+
+/* The two ways DoSubst renders a message. */
+int remrb_normal_mode(void) { return NORMAL_MODE; }
+int remrb_cal_mode(void)    { return CAL_MODE; }
+
+/* The body types, so Ruby can tell a MSG from a RUN without repeating the
+   numbers. */
+int remrb_msg_type(void)      { return MSG_TYPE; }
+int remrb_msf_type(void)      { return MSF_TYPE; }
+int remrb_run_type(void)      { return RUN_TYPE; }
+int remrb_cal_type(void)      { return CAL_TYPE; }
+int remrb_sat_type(void)      { return SAT_TYPE; }
+int remrb_passthru_type(void) { return PASSTHRU_TYPE; }
+
+/* Trigger accessors.  One line each, and each one is the compiler's opinion
+   of where the field is rather than the binding's. */
+#define TRIGGER_READER(field) \
+    int remrb_trigger_##field(Trigger const *t) { return t->field; }
+
+TRIGGER_READER(wd)              /* bit set: 1 << 0 is Monday, as Remind counts */
+TRIGGER_READER(d)               /* day of month, or NO_DAY */
+TRIGGER_READER(m)               /* month, 0-based, or NO_MON */
+TRIGGER_READER(y)               /* year, or NO_YR */
+TRIGGER_READER(back)            /* the count on a --n / -n delta */
+TRIGGER_READER(delta)           /* advance warning, in days */
+TRIGGER_READER(rep)             /* *n repeat interval, in days */
+TRIGGER_READER(localomit)       /* bit set of weekdays this reminder OMITs */
+TRIGGER_READER(skip)            /* SKIP / BEFORE / AFTER */
+TRIGGER_READER(until)           /* UNTIL / THROUGH date, or NO_UNTIL */
+TRIGGER_READER(typ)             /* MSG_TYPE, RUN_TYPE, ... */
+TRIGGER_READER(once)            /* ONCE */
+TRIGGER_READER(scanfrom)        /* SCANFROM / FROM date */
+TRIGGER_READER(from)
+TRIGGER_READER(priority)        /* PRIORITY */
+TRIGGER_READER(duration_days)
+TRIGGER_READER(eventduration)   /* DURATION, in minutes */
+TRIGGER_READER(eventstart)      /* start as a Remind datetime */
+TRIGGER_READER(is_todo)
+TRIGGER_READER(addomit)
+TRIGGER_READER(need_wkday)
+
+char const *remrb_trigger_tags(Trigger *t)
+{
+    return DBufValue(&t->tags);
+}
+
+char const *remrb_trigger_timezone(Trigger const *t)
+{
+    return t->tz;
+}
+
+/* TimeTrig accessors. */
+int remrb_timetrig_time(TimeTrig const *tt)     { return tt->ttime; }
+int remrb_timetrig_delta(TimeTrig const *tt)    { return tt->delta; }
+int remrb_timetrig_repeat(TimeTrig const *tt)   { return tt->rep; }
+int remrb_timetrig_duration(TimeTrig const *tt) { return tt->duration; }
+
+/* The tokens main.c dispatches to something other than DoRem.  Everything
+   else -- a number, a month name, a word Remind does not know -- opens a
+   reminder, which is Remind's `default:` case.  T_RemType is on the reminder
+   side: a line that opens with a bare MSG is a reminder with an empty
+   trigger.  T_Omit is not: OMIT can carry a reminder, but the command itself
+   is a calendar-wide exclusion rather than an event. */
+static int
+is_command(enum TokTypes type)
+{
+    switch (type) {
+    case T_Banner:  case T_Clr:        case T_Comment:  case T_Debug:
+    case T_Dumpvars:case T_Else:       case T_Empty:    case T_EndIf:
+    case T_ErrMsg:  case T_Exit:       case T_Expr:     case T_Flush:
+    case T_Frename: case T_Fset:       case T_Funset:   case T_If:
+    case T_IfTrig:  case T_Include:    case T_IncludeCmd:
+    case T_IncludeR:case T_IncludeSys: case T_Omit:     case T_Pop:
+    case T_PopFuncs:case T_PopVars:    case T_Preserve: case T_Push:
+    case T_PushFuncs: case T_PushVars: case T_Return:   case T_Set:
+    case T_Translate: case T_UnSet:
+        return 1;
+    default:
+        return 0;
+    }
+}
+
+/* The expanded message from the last successful parse.  One buffer, reused:
+   the caller copies the string into Ruby before the next call, and the Ruby
+   side serialises calls anyway because Remind's state is process-wide. */
+static DynamicBuffer body;
+static int body_ready = 0;
+
+static void
+reset_body(void)
+{
+    if (!body_ready) {
+        DBufInit(&body);
+        body_ready = 1;
+    } else {
+        DBufFree(&body);
+    }
+}
+
+/***************************************************************/
+/*                                                             */
+/*  remrb_parse_reminder                                       */
+/*                                                             */
+/*  Parse one REM line the way DoRem does, minus the parts a   */
+/*  calendar has no use for: no queueing, no SATISFY, no purge */
+/*  mode, no output.                                           */
+/*                                                             */
+/*  Fills in the caller's Trigger and TimeTrig, writes the     */
+/*  first date the reminder triggers on to *dse, and points    */
+/*  *msg at the message with its %-substitutions expanded for  */
+/*  that date.  Answers OK, or the error code Remind raised;   */
+/*  the caller frees the Trigger either way.                   */
+/*                                                             */
+/***************************************************************/
+int
+remrb_parse_reminder(char const *line, Trigger *trig, TimeTrig *tim,
+                     int *dse, char const **msg, int mode)
+{
+    Parser p;
+    DynamicBuffer token_buf;
+    Token tok;
+    int r;
+
+    reset_body();
+    DBufInit(&token_buf);
+    *dse = -1;
+    *msg = NULL;
+
+    CreateParser(line, &p);
+
+    /* Mirror how main.c decides what a line is. It reads the first token and
+       dispatches on it: T_Rem is a reminder, T_RemType (a bare MSG or CAL) is
+       a reminder, an unrecognised word is a reminder by default -- and
+       anything else is one of Remind's other commands, which is not an event
+       and must not be parsed as though it were.
+
+       ParseRem starts at the date specification, after the keyword, which is
+       why REM is consumed and everything else is pushed back. */
+    r = ParseToken(&p, &token_buf);
+    if (r != OK) {
+        DestroyParser(&p);
+        return r;
+    }
+    FindToken(DBufValue(&token_buf), &tok);
+
+    if (tok.type != T_Rem) {
+        if (is_command(tok.type)) {
+            DBufFree(&token_buf);
+            DestroyParser(&p);
+            return E_PARSE_ERR;
+        }
+        r = PushToken(DBufValue(&token_buf), &p);
+        if (r != OK) {
+            DBufFree(&token_buf);
+            DestroyParser(&p);
+            return r;
+        }
+    }
+    DBufFree(&token_buf);
+
+    r = ParseRem(&p, trig, tim);
+    if (r != OK) {
+        DestroyParser(&p);
+        return r;
+    }
+
+    /* SATISFY is a control construct, not a calendar entry, and the rest of
+       DoRem's handling of it is about the reminder queue. */
+    if (trig->typ == SAT_TYPE) {
+        DestroyParser(&p);
+        return E_PARSE_ERR;
+    }
+
+    *dse = ComputeTrigger(get_scanfrom(trig), trig, tim, &r, 1);
+    if (r != OK) {
+        DestroyParser(&p);
+        return r;
+    }
+    *dse = AdjustTriggerForTimeZone(trig, *dse, tim, 0);
+
+    /* ParseRem has already read the keyword that opens the body -- MSG, MSF,
+       RUN, CAL, SPECIAL -- and left trig->typ set to it, which is why DoRem
+       goes straight from here to rendering. A line with no body at all leaves
+       it at NO_TYPE. */
+    if (trig->typ == NO_TYPE) {
+        DestroyParser(&p);
+        return E_EOLN;
+    }
+
+    /* NORMAL_MODE renders the message the way `remind` prints it; CAL_MODE
+       renders it the way a calendar entry wants it, which is where a %"..%"
+       title is honoured. The caller picks, because a calendar entry needs
+       both: one for the summary and one for the description. */
+    r = DoSubst(&p, &body, trig, tim, *dse, mode);
+    DestroyParser(&p);
+
+    if (r != OK) {
+        return r;
+    }
+
+    *msg = DBufValue(&body);
+    return OK;
+}
+
+/***************************************************************/
+/*                                                             */
+/*  remrb_next_trigger                                         */
+/*                                                             */
+/*  The next date this reminder triggers on, at or after       */
+/*  `from`.  This is the same call DoRem makes to find the     */
+/*  first one, run again from further along, which is how      */
+/*  Remind itself walks a reminder across a date range.        */
+/*                                                             */
+/*  It exists because a calendar has to decide whether an      */
+/*  RRULE says what the reminder says, and the only authority  */
+/*  on that is the reminder: generate a rule, expand it, and   */
+/*  compare it against these dates.  save_in_globals is 0 --   */
+/*  walking a reminder must not move Remind's idea of the last */
+/*  trigger.                                                   */
+/*                                                             */
+/*  Answers -1 and sets *err when the reminder has no further  */
+/*  trigger date, which is how a run-out or expired reminder   */
+/*  ends a walk.                                               */
+/*                                                             */
+/***************************************************************/
+int
+remrb_next_trigger(Trigger *trig, TimeTrig *tim, int from, int *err)
+{
+    int dse;
+
+    *err = OK;
+    dse = ComputeTrigger(from, trig, tim, err, 0);
+    if (*err != OK) {
+        return -1;
+    }
+    return dse;
+}
+
+/***************************************************************/
+/*                                                             */
+/*  remrb_open_file / remrb_read_line                          */
+/*                                                             */
+/*  Remind's own file reader.  A reminder file is not a list of */
+/*  lines: a backslash continues one, INCLUDE pulls another     */
+/*  file into the middle of it, and both are handled here       */
+/*  rather than in the caller.  ReadLine leaves the logical     */
+/*  line in the CurLine global and pops back out of an included */
+/*  file when it ends.                                         */
+/*                                                             */
+/*  remrb_read_line answers OK, or E_EOF when there is nothing  */
+/*  left in any open file.                                     */
+/*                                                             */
+/***************************************************************/
+int
+remrb_open_file(char const *path)
+{
+    return IncludeFile(path);
+}
+
+/* INCLUDE is a command, not part of the reader: ReadLine pops back out of an
+   included file when it ends, but something has to push one on in the first
+   place, and in `remind` that something is DoCommand.  This is that, for the
+   three forms that name a file.
+
+   INCLUDECMD is deliberately not among them.  It runs a shell command and
+   reads its output as reminders, and a program that converts somebody else's
+   reminder file should not execute what is in it. */
+static int
+follow_include(char const *line)
+{
+    Parser p;
+    DynamicBuffer buf;
+    Token tok;
+    int handled = 0;
+
+    CreateParser(line, &p);
+    DBufInit(&buf);
+
+    if (ParseToken(&p, &buf) == OK) {
+        FindToken(DBufValue(&buf), &tok);
+        if (tok.type == T_Include ||
+            tok.type == T_IncludeR ||
+            tok.type == T_IncludeSys) {
+            (void) DoInclude(&p, tok.type);
+            handled = 1;
+        }
+    }
+
+    DBufFree(&buf);
+    DestroyParser(&p);
+    return handled;
+}
+
+int
+remrb_read_line(char const **text)
+{
+    int r;
+
+    while (1) {
+        r = ReadLine();
+        if (r != OK) {
+            *text = NULL;
+            return r;
+        }
+        if (!follow_include(CurLine)) {
+            *text = CurLine;
+            return r;
+        }
+    }
+}
+
+int remrb_eof(void) { return E_EOF; }
+
+/* ParseRem allocates: the tag buffer, the time zone, the INFO headers. */
+void
+remrb_free_trigger(Trigger *t)
+{
+    FreeTrig(t);
+}

data/lib/remind/builder.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+require_relative "library"
+
+module Remind
+  # Builds Remind's sources, plus this gem's shim, into a shared library.
+  #
+  # Remind's own Makefile links two programs and no library, so this is the
+  # one step that has to be invented rather than reused. It is deliberately
+  # thin: `./configure` still decides the compiler, the flags, the feature
+  # macros and the libraries to link, and this class reads those decisions
+  # back out of the generated `src/Makefile` rather than making its own. What
+  # it adds is `-fPIC -shared`, one output file, and `ext/shim.c`.
+  #
+  # The output goes where `Remind::Library` looks -- lib/remind/ -- because
+  # that is where a precompiled gem carries it, and a checkout that puts it
+  # somewhere else is a checkout that tests a different arrangement than the
+  # one users get.
+  #
+  # `rem2ps.c` is left out: the PostScript formatter is a second program with
+  # a second `main`, and nothing in it is worth binding. `main.c` stays in --
+  # a `main` symbol in a shared library is harmless, and leaving it out would
+  # strand every symbol defined beside it.
+  class Builder
+    EXCLUDED_SOURCES = ["rem2ps.c"].freeze
+
+    SHARED_FLAGS = ["-fPIC", "-shared"].freeze
+
+    # Remind resolves `INCLUDE` against this at runtime; pointing it at the
+    # vendored tree means a reminder can include the holiday files that ship
+    # with the release the bindings bind.
+    SYSDIR_TEMPLATE = "-DSYSDIR=%s"
+
+    # Extra arguments for `./configure`.
+    #
+    # There is one job that needs them: building a library to put inside a
+    # precompiled gem. Remind's configure links readline when it finds it, and
+    # a gem whose library needs a readline the installing machine may not have
+    # is a gem that fails to load there. CI therefore builds with
+    #
+    #   REMIND_RB_CONFIGURE_ARGS="ac_cv_lib_readline_readline=no
+    #                             ac_cv_header_readline_readline_h=no"
+    #
+    # which tells configure's own cache the probe already failed. Nothing in
+    # the bindings uses readline -- it is there for `remind`'s interactive
+    # prompt, and there is no prompt in a library.
+    CONFIGURE_ARGS = "REMIND_RB_CONFIGURE_ARGS"
+
+    attr_reader :source_root, :output, :io
+
+    def initialize(source_root: Library.source_root, output: Library.default_path, io: $stderr)
+      @source_root = source_root
+      @output = output
+      @io = io
+    end
+
+    # Answers the path it built.
+    def call
+      configure
+      generate_translatables
+      compile
+
+      output
+    end
+
+    private
+
+      def source_directory
+        File.join(source_root, "src")
+      end
+
+      def makefile
+        File.join(source_directory, "Makefile")
+      end
+
+      # `configure` writes src/Makefile, src/config.h and src/version.h. It is
+      # slow and idempotent, so it runs once and not again unless its output
+      # has gone.
+      def configure
+        if File.exist?(makefile)
+          io.puts("configure: already done")
+        else
+          run(configure_command, chdir: source_root, what: "configure")
+        end
+      end
+
+      def configure_command
+        ["./configure", ENV.fetch(CONFIGURE_ARGS, nil)].compact.join(" ")
+      end
+
+      # xlat.c is generated by a Makefile rule that greps every `tr()` string
+      # out of the sources. Nothing else defines `translatables`, so a library
+      # built without it fails to load rather than failing to build.
+      def generate_translatables
+        run("make xlat.c", chdir: source_directory, what: "make xlat.c")
+      end
+
+      def compile
+        FileUtils.mkdir_p(File.dirname(output))
+        run(compile_command, chdir: source_directory, what: "compile")
+      end
+
+      def compile_command
+        [
+          compiler,
+          *compile_flags,
+          *SHARED_FLAGS,
+          format(SYSDIR_TEMPLATE, File.join(source_root, "include")),
+          "-o",
+          output,
+          *sources,
+          *link_libraries,
+        ].join(" ")
+      end
+
+      # The shim is compiled from where it lives rather than copied in beside
+      # the Remind sources, so a build leaves nothing behind in the vendored
+      # tree.
+      def sources
+        remind_sources + [Library.shim]
+      end
+
+      def remind_sources
+        Dir.children(source_directory)
+           .select { |name| name.end_with?(".c") }
+           .reject { |name| EXCLUDED_SOURCES.include?(name) }
+           .sort
+      end
+
+      # --- what configure decided ------------------------------------------
+
+      def makefile_text
+        File.read(makefile)
+      end
+
+      # The recipe under the `.c.o` suffix rule: the exact command configure
+      # chose for compiling one source file.
+      def compile_recipe
+        recipe(/^\.c\.o:\n\t(.*)$/)
+      end
+
+      # The recipe that links the program, which is where the libraries are.
+      def link_recipe
+        recipe(/^remind: [^\n]*\n\t(.*)$/)
+      end
+
+      def recipe(pattern)
+        match = makefile_text.match(pattern)
+
+        if match
+          match[1].split
+        else
+          raise BuildError, "#{makefile} has no recipe matching #{pattern.inspect}"
+        end
+      end
+
+      def compiler
+        compile_recipe.first
+      end
+
+      # Everything the compile recipe passes except the parts that are about
+      # compiling one file into one object: `-c`, the source, and the make
+      # variables, which have no values outside make.
+      def compile_flags
+        compile_recipe.drop(1).reject { |flag| skip_flag?(flag) }
+      end
+
+      def skip_flag?(flag)
+        flag == "-c" || flag.include?("$") || flag.start_with?("-DSYSDIR")
+      end
+
+      def link_libraries
+        link_recipe.select { |flag| flag.start_with?("-l") }
+      end
+
+      def run(command, chdir:, what:)
+        io.puts("#{what}: #{command}")
+
+        if system(command, chdir: chdir)
+          command
+        else
+          raise BuildError, "#{what} failed in #{chdir}: #{command}"
+        end
+      end
+  end
+end
+
+__END__
+
+require "stringio"
+
+describe "Remind::Builder" do
+  # The build itself is what `rake library` does, and what every other spec
+  # here depends on having run. What is worth pinning is that the build takes
+  # its decisions from configure's output rather than inventing them.
+  builder = proc { Remind::Builder.new(io: StringIO.new) }
+
+  it "builds from the vendored sources" do
+    builder.().send(:source_directory).should == Remind::Library.source_directory
+  end
+
+  it "leaves the PostScript formatter out, and keeps main.c in" do
+    Remind::Builder::EXCLUDED_SOURCES.should.include "rem2ps.c"
+    Remind::Builder::EXCLUDED_SOURCES.should.not.include "main.c"
+  end
+
+  it "compiles the shim alongside them" do
+    builder.().send(:sources).last.should == Remind::Library.shim
+  end
+
+  it "takes the compiler from the generated Makefile" do
+    builder.().send(:compiler).should.not.be.empty
+  end
+
+  it "drops the flags that only make sense one file at a time" do
+    flags = builder.().send(:compile_flags)
+
+    flags.should.not.include "-c"
+    flags.any? { |flag| flag.include?("$") }.should.be.false
+  end
+
+  it "keeps the feature macros configure defined" do
+    builder.().send(:compile_flags).should.include "-DHAVE_CONFIG_H"
+  end
+
+  it "links what the program links" do
+    builder.().send(:link_libraries).all? { |flag| flag.start_with?("-l") }.should.be.true
+  end
+
+  it "passes on the configure arguments packaging needs" do
+    ENV[Remind::Builder::CONFIGURE_ARGS] = "ac_cv_lib_readline_readline=no"
+
+    builder.().send(:configure_command).should == "./configure ac_cv_lib_readline_readline=no"
+  ensure
+    ENV.delete(Remind::Builder::CONFIGURE_ARGS)
+  end
+
+  it "configures with nothing extra by default" do
+    builder.().send(:configure_command).should == "./configure"
+  end
+
+  it "builds one shared library out of all of it" do
+    command = builder.().send(:compile_command)
+
+    command.should.include "-fPIC"
+    command.should.include "-shared"
+    command.should.include "expr.c"
+    command.should.not.include "rem2ps.c"
+  end
+end