path: root/src/sisudoc/ocda/meta/doc_matters.d

/+
- Name: SisuDoc Spine, Doc Reform [a part of]
  - Description: documents, structuring, processing, publishing, search
    - static content generator

  - Author: Ralph Amissah
    [ralph.amissah@gmail.com]

  - Copyright: (C) 2015 (continuously updated, current 2026) Ralph Amissah, All Rights Reserved.

  - License: AGPL 3 or later:

    Spine (SiSU), a framework for document structuring, publishing and
    search

    Copyright (C) Ralph Amissah

    This program is free software: you can redistribute it and/or modify it
    under the terms of the GNU AFERO General Public License as published by the
    Free Software Foundation, either version 3 of the License, or (at your
    option) any later version.

    This program is distributed in the hope that it will be useful, but WITHOUT
    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
    FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
    more details.

    You should have received a copy of the GNU General Public License along with
    this program. If not, see [https://www.gnu.org/licenses/].

    If you have Internet connection, the latest version of the AGPL should be
    available at these locations:
    [https://www.fsf.org/licensing/licenses/agpl.html]
    [https://www.gnu.org/licenses/agpl.html]

  - Spine (by Doc Reform, related to SiSU) uses standard:
    - docReform markup syntax
      - standard SiSU markup syntax with modified headers and minor modifications
    - docReform object numbering
      - standard SiSU object citation numbering & system

  - Homepages:
    [https://www.sisudoc.org]
    [https://www.doc-reform.org]

  - Git
    [https://git.sisudoc.org/]

+/
module sisudoc.ocda.meta.doc_matters;
@safe:
/+ ↓ doc_matters: the one description of what an output writer is given

     spineAbstraction() builds this from the markup it has just parsed. A
     document loaded from a .ssp or a .ocda.db has to arrive at the same
     value from what the artefact carries, so the construction lives here
     rather than inside the parser, and both paths fill the same arguments:

       program_info           the run
       opt_action             the run
       manifest               where the document is, and what it is called
       conf_make_meta         the document's header, plus the site config
       doc_has                the counts, lists and indexes (ST_DocHas)
       doc_digest             the source digests
       insert_file_list       the files the markup inserted, for --pod2

     Nothing downstream learns which path filled them, which is the point:
     an output writer that has to know where the document came from is a
     writer that has had something leak into it from upstream.
+/
template spineDocMatters() {
  import std.conv : to;
  import std.datetime;
  import std.stdio;
  import sisudoc.ocda.meta.conf_make_meta_structs;
  import sisudoc.ocda.io_in.paths_source;
  auto docMattersMake(P,O,M,H,D)(
    P             program_info,
    O             _opt_action,
    M             _manifest,
    ConfComposite _make_and_meta_struct,
    H             _doc_has_struct,
    D             doc_digests,
    string[]      _insert_file_list,
  ) {
    struct ST_DocumentMatters {
      auto generator_program() {
        struct Prog_ {
          string project_name() {
            return "spine";
          }
          string name() {
            return program_info.name;
          }
          string ver() {
            return program_info.ver;
          }
          @trusted string name_and_version() {
            return program_info.name_and_version;
          }
          @trusted string name_version_and_compiler() {
            return program_info.name_version_and_compiler;
          }
          string url_home() {
            return "https://sisudoc.org";
          }
          string url_git() {
            return "https://git.sisudoc.org/projects/";
          }
          auto compiler() {
            return program_info.compiler;
          }
          auto time_output_generated() {
            return program_info.time_output_generated;
          }
        }
        return Prog_();
      }
      /+ ↓ when the document is from, as a UTC instant, for the output formats
           that must carry a timestamp: epub3 requires exactly one
           dcterms:modified on the package, and an odt carries
           meta:creation-date and dc:date.
           .
           Taken from the document rather than from the clock, so that those
           artefacts are a function of their source. Stamped from the clock,
           two runs over unchanged markup produced different bytes, and no
           comparison of that output could tell a real change from the
           seconds between two builds.
           .
           Read in order: SOURCE_DATE_EPOCH where the environment sets it,
           which is the reproducible-builds convention and lets a build pin
           every artefact of one run; then the document's own date.modified;
           then date.published. The clock is the last resort, for a document
           that says nothing about when it is from.
           .
           A document date is loose markup: "1991", "2006-03" and
           "2021-12-00" all occur in the sample set, and a month or day of 00
           is not a date. A missing or zero part becomes 01, and a day out of
           range for its month falls back to the first, so what is written is
           always a valid CCYY-MM-DDThh:mm:ssZ.
      +/
      string modified_utc() {
        import std.datetime : Date, SysTime, unixTimeToStdTime;
        import std.format   : format;
        import std.process  : environment;
        import std.regex    : ctRegex, matchFirst;
        /+ ↓ a build may pin every artefact of the run +/
        string _sde = environment.get("SOURCE_DATE_EPOCH", "");
        if (_sde.length > 0) {
          try {
            auto _t = SysTime(unixTimeToStdTime(_sde.to!long), UTC());
            return format("%04d-%02d-%02dT%02d:%02d:%02dZ",
              _t.year, _t.month.to!int, _t.day, _t.hour, _t.minute, _t.second);
          } catch (Exception) {
          }
        }
        /+ ↓ what the document itself says +/
        auto _rgx_date
          = ctRegex!(`^\s*(?P<y>\d{4})(?:[-/](?P<m>\d{1,2}))?(?:[-/](?P<d>\d{1,2}))?`);
        foreach (_said; [
          conf_make_meta.meta.date_modified,
          conf_make_meta.meta.date_published,
        ]) {
          if (_said.length == 0) {
            continue;
          }
          if (auto _m = _said.matchFirst(_rgx_date)) {
            int _y  = _m["y"].to!int;
            int _mo = (_m["m"].length > 0) ? _m["m"].to!int : 1;
            int _d  = (_m["d"].length > 0) ? _m["d"].to!int : 1;
            if (_mo < 1 || _mo > 12) {
              _mo = 1;
            }
            if (_d < 1) {
              _d = 1;
            }
            try {
              cast(void) Date(_y, _mo, _d);
            } catch (Exception) {
              _d = 1;
            }
            return format("%04d-%02d-%02dT00:00:00Z", _y, _mo, _d);
          }
        }
        /+ ↓ the document says nothing: the run's own time +/
        auto _now = Clock.currTime(UTC());
        return format("%04d-%02d-%02dT%02d:%02d:%02dZ",
          _now.year, _now.month.to!int, _now.day,
          _now.hour, _now.minute, _now.second);
      }
      // auto generated_time() { // UNUSED
      //   auto _st = Clock.currTime(UTC());
      //   auto _time = _st.year.to!string
      //     ~ "-" ~ _st.month.to!int.to!string // prefer as month number
      //     ~ "-" ~ _st.day.to!string
      //     ~ " [" ~ _st.isoWeek.to!string ~ "/" ~ _st.dayOfWeek.to!int.to!string ~ "]"
      //     ~ " " ~ _st.hour.to!string
      //     ~ ":" ~ _st.minute.to!string
      //     ~ ":" ~ _st.second.to!string;
      //   return _time;
      // }
      ConfComposite conf_make_meta() {
        return _make_and_meta_struct;
      }
      auto doc_digest() {
        return doc_digests;
      }
      auto has() {
        return _doc_has_struct;
      }
      auto env() {
        struct Env_ {
          auto pwd() {
            return _manifest.env.pwd;
          }
          auto home() {
            return _manifest.env.home;
          }
        }
        return Env_();
      }
      auto opt() {
        struct Opt_ {
          auto action() {
            /+ getopt options, commandline instructions, raw
             - processing instructions --epub --html etc.
             - command line config instructions --output
            +/
            return _opt_action;
          }
        }
        return Opt_();
      }
      auto src() {
        return _manifest.src;
      }
      auto src_path_info() {
        return spinePathsSRC!()(_manifest.env.pwd, _manifest.src.file_with_absolute_path); // would like (to have and use) relative path
      }
      auto pod() {
        return _manifest.pod;
      }
      auto sqlite() {
        struct SQLite_ {
          string filename() {
            string _fn = "";
            string _pth = "";
            if (_opt_action.sqliteDB_filename.length > 0) {
              _fn = _opt_action.sqliteDB_filename;
            } else if (_make_and_meta_struct.conf.w_srv_db_sqlite_filename.length > 0) {
              _fn = _make_and_meta_struct.conf.w_srv_db_sqlite_filename;
            }
            return _fn;
          }
          string path() {
            string _pth = "";
            if (_opt_action.sqliteDB_path.length > 0) {
              _pth = _opt_action.sqliteDB_path;
            } else if (_make_and_meta_struct.conf.w_srv_db_sqlite_path.length > 0) {
              _pth = _make_and_meta_struct.conf.w_srv_db_sqlite_path;
            }
            return _pth;
          }
          string cgi_filename() {
            string _fn = "";
            if (_opt_action.cgi_sqlite_search_filename.length > 0) {
              _fn = _opt_action.cgi_sqlite_search_filename;
            } else if (_make_and_meta_struct.conf.w_srv_cgi_search_script.length > 0) {
              _fn = _make_and_meta_struct.conf.w_srv_cgi_search_script;
            }
            return _fn;
          }
          string cgi_filename_d() {
            string _fn = "";
            if (_opt_action.cgi_sqlite_search_filename_d.length > 0) {
              _fn = _opt_action.cgi_sqlite_search_filename_d;
            } else if (_make_and_meta_struct.conf.w_srv_cgi_search_script_raw_fn_d.length > 0) {
              _fn = _make_and_meta_struct.conf.w_srv_cgi_search_script_raw_fn_d;
            }
            return _fn;
          }
        }
        return SQLite_();
      }
      auto output_path() {
        return _make_and_meta_struct.conf.output_path;
      }
      auto srcs() {
        struct SRC_ {
          auto file_insert_list() {
            return _insert_file_list;
          }
          auto image_list() {
            return _doc_has_struct.imagelist;
          }
        }
        return SRC_();
      }
    }
    return ST_DocumentMatters();
  }
}