klammertext/com/kdesc.cpp

#include "argv.h"
#include "command.h"
#include "coverage.h"
#include "error.h"
#include "file.h"
#include "font_store.h"
#include "ktype.h"
#include "katom_rewrite_rules.h"
#include "log.h"
#include "argtype_registry.h"
#include "klammerset_registry.h"
#include "character.h"
#include "show.h"
#include "util.h"

static void font_usage()
{
    std::cout <<
        "Font maintenance commands:\n"
        "  --typeface                       List the available fonts\n"
        "  --typeface list                  The same\n"
        "  --typeface samples <output-dir>  Write a sample page of the available fonts\n"
        "                               to <output-dir>/index.html\n"
        "  --typeface samples <input-dir> <output-dir>\n"
        "                               Write a sample page for the (not yet\n"
        "                               installed) font files under <input-dir>\n"
        "  --typeface install <input-dir>   Install the font files found under\n"
        "                               <input-dir> into the user font directory\n"
        "  --typeface install <input-dir> <output-dir>\n"
        "                               Install into <output-dir> instead\n"
        "  --typeface help                  This description\n"
        "\n"
        "Fonts are searched in the directories of the KLAMMERTEXT_FONTS\n"
        "environment variable (colon-separated; default $HOME/.klammertext/fonts)\n"
        "and then in the default font set.\n";
}

static void coverage_usage()
{
    std::cout <<
        "Coverage commands:\n"
        "  --coverage       Report the targets each klammer covers\n"
        "  --coverage all   Also name the file each klammer is written\n"
        "                   in, and show every \"needs attention\"\n"
        "                   category, including the empty ones\n"
        "  --coverage <target>\n"
        "                   One target's view: the klammers that cover it,\n"
        "                   those that do so with an EMPTY definition (a\n"
        "                   decision: no meaning there), and the undecided\n"
        "                   ones (no definition: nothing decided).  \"all\"\n"
        "                   may be added for the explanations.\n"
        "  --coverage help  This description\n"
        "\n"
        "Coverage is a fact about a klammer: the targets it can render to.  It is\n"
        "DERIVED where the definitions determine it (a general body of klammer\n"
        "calls covers the intersection of what those klammers cover), must be\n"
        "DECLARED where they cannot (an @eval body, whose targets are named in a\n"
        "comma-separated list: @@name.html,tex :: ... @@), and is UNKNOWN where\n"
        "nothing is written -- which never means \"deliberately unavailable\".\n"
        "\n"
        "Without \"all\", an AUTHOR sees what is available and only the problems\n"
        "that exist.  With it, a DESIGNER building a klammer set is reminded of\n"
        "the whole set of categories.\n";
}

static void katom_usage()
{
    std::cout <<
        "Katom commands:\n"
        "  --katoms       List the katom types\n"
        "  --katoms full  The list, with the regex syntax used for a march\n"
        "  --katoms help  This description\n";
}

// The words of a variadic option, with the empty ones dropped.
static strings_t option_words(Argv& args, const std::string& name)
{
    strings_t words {};
    for (const std::string& w : args.as_vector(name)) {
        if (!w.empty()) {
            words.push_back(w);
        }
    }
    return words;
}

static void klammerset_usage()
{
    std::cout <<
        "Klammerset commands:\n"
        "  --klammersets            List the klammersets on the search path\n"
        "  --klammersets <symbols>  Load the klammersets specified by <symbols>\n"
        "  --klammersets help       This description\n"
        "\n"
        "Without an argument, all available klammersets are listed.  With one or more\n"
        "klammerset symbols, those klammersets are loaded for analysis by the -k, -t,\n"
        "--argtypes, --optionsets, and --coverage arguments.\n\n"
        "SEVERAL SETS COMBINE.  The symbols are a list, loaded in the order given, and\n"
        "the klammers of all of them share ONE flat namespace -- membership in a set is\n"
        "provenance, not containment.  Where two sets define the same klammer, the\n"
        "definition modes decide: \":\" is an error if the name is already defined,\n"
        "\":::\" replaces the earlier definition (with a warning), and \"::::\" yields to\n"
        "any later one.  So a set of house overrides is loaded after the set it\n"
        "adjusts, and a set of defaults before it.\n\n"
        "The Standard Klammer Set is loaded by default. If the <symbols> argument is\n"
        "\"none\", no klammerset is loaded.\n\n"
        "A klammerset symbol x names the declaration file x/x.k, searched for in:\n"
        "1) the current directory (for ktext, the input document's directory); 2) the\n"
        "KLAMMERTEXT_KLAMMERSETS directories (colon-separated; the default is\n"
        "$HOME/.klammertext/klammersets); and 3) $KLAMMERTEXT_HOME.  The first hit\n"
        "wins, so a document-local klammerset shadows an installed one, which\n"
        "shadows a distributed one.\n";
}

static void klammerset_command(Machine& machine, const strings_t& words)
{
    if (words.empty()) {
        std::cout << boldblack << "Klammersets\n" << black
                  << describe_klammerset_search(fs::current_path().string());
    } else if (words[0] == "help") {
        klammerset_usage();
    } else {
        // "none" is not filtered out here: load_klammersets() is the single
        // place that decides what the word means, including that it may not be
        // combined with other symbols.  Deciding it twice is how kdesc came to
        // accept "--klammersets none sks" and silently load neither.
        load_klammersets(machine, words);
    }
}

// The target for the Klammertext kdesc renders for its own output: the
// ansi target (plain text with type styles as escape sequences) when
// stdout is a terminal, the txt target otherwise.  The COMMAND decides,
// because only it knows the stream -- the same per-stream rule Color
// follows for the listings, NO_COLOR included -- and the targets stay
// formats a writer names with -t.
static std::string text_target()
{
    return color_enabled(std::cout) ? "ansi" : "txt";
}

// The Machine for a description kdesc renders from the ref/ klammerset.
static Machine ref_machine()
{
    Machine M;
    M.read(M.m_state.value("KLAMMERTEXT_HOME") + "/ref/ref.k");
    return M;
}

void show_fonts()
{
    Machine M = ref_machine();
    M.read_string("@klammertext_fonts@");
    std::cout << "\n" << M.apply(text_target()) << "\n\n";
}

static void font_command(const strings_t& words)
{
    std::string verb = words.empty() ? "list" : words[0];
    size_t n = words.size() - (words.empty() ? 0 : 1);
    if (verb == "list" && n == 0) {
        show_fonts();
    } else if (verb == "samples" && n == 1) {
        std::cout << "Font samples written to "
                  << write_font_samples(words[1]) << "\n";
    } else if (verb == "samples" && n == 2) {
        std::cout << "Font samples written to "
                  << write_font_samples(words[2], words[1]) << "\n";
    } else if (verb == "install" && (n == 1 || n == 2)) {
        std::cout << "Installing fonts from " << words[1] << ":\n"
                  << install_fonts(words[1], n == 2 ? words[2] : "");
    } else if (verb == "help") {
        font_usage();
    } else {
        std::cout << "Unrecognized typeface command: --typeface " << join(words, " ")
                  << "\n\n";
        font_usage();
    }
}

void show_special_characters()
{
    Machine M = ref_machine();
    M.read_string("@b Writing characters with diacritics and non-English characters @\n\n");
    M.read_string("@diacritics_examples@");
    M.read_string("@extended_latin_examples@");
    M.read_string("@pinyin_examples@");
    std::cout << "\n" << M.apply(text_target()) << "\n";
}

void show_unicode_examples()
{
    Machine M = ref_machine();
    M.read_string("@unicode_examples@");
    std::cout << "\n" << M.apply(text_target()) << "\n\n";
}

void show_argtype_definitions()
{
    Machine M = ref_machine();
    M.read_string("@argtype_definitions@");
    std::cout << "\n" << M.apply(text_target()) << "\n\n";
}    

// The katom table is wider than the text: four columns, the last of them a
// sentence.  The width is the klammer's argument rather than a state
// variable set here, so the paragraphs above the table keep the text width.
void describe_katoms(bool show_regex)
{
    Machine M = ref_machine();
    M.read_string(std::string("@katom_descriptions :txt_width ") +
                  (show_regex ? "160 :regex" : "120") + " @");
    std::cout << "\n" << M.apply(text_target()) << "\n\n";
}

void show_katom_rewrite_patterns()
{
    Machine M = ref_machine();
    M.read_string("@katom_rewrite_patterns@");
    std::cout << "\n" << M.apply(text_target()) << "\n\n";
}

int main(int argc, char* argv[])
{
    try {
        set_verbose_level(argc, argv);

        Argv args {};
        // Declaration order is display order in the usage text, so these are
        // ordered by how likely a user is to want them.  A single letter is a
        // flag one reaches for often; a multi-letter name is a more specialised
        // topic.  -v stays last: it says how much to show about the command's
        // PROCESSING, never what its RESULT contains -- which is why the katom
        // regexes and the coverage file column are words of their own options
        // rather than verbosity levels.
        args.var("k", "Show klammers.  With <text>, only those whose name or description contains <text>.", "text");
        args.flag("c", "Show the codes for accented vowels and other special characters");
        args.flag("u", "Describe including Unicode characters in KLammertext");
        args.flag("t", "Show the targets for Klammertext output");
        args.opt("i", "Input filename to analyze containing klammer and other definitions", "filename", "", "'text'");
        args.var("klammersets", "List the available klammersets, or load one or more for analysis.  Enter \"--klammersets help\" for details.", "symbols");
        args.var("typeface", "List installed typefaces.  Enter \"--typeface help\" for typeface maintenance commands.");
        args.flag("argtypes", "Show the klammer argument types");
        args.var("katoms", "Show the katom types.  Enter \"--katoms help\" for details.");
        args.flag("rewrite", "Show the katom rewrite patterns");
        args.flag("optionsets", "Show the option sets declared by the input");
        args.var("coverage", "Show the targets each klammer covers.  Enter \"--coverage help\" for details.");
        args.opt("v",  "'verbosity'", "n", "0", "'verbosity'");

        if (show_usage(argc, argv)) {
            // A bare command is a REQUEST for information, not a failure:
            // usage goes to stdout (it is the result being asked for) and the
            // exit status is 0, so "kdesc && echo ok" reports what happened.
            args.usage(file_basename(argv[0]));
            exit(0);
        }
        auto p = [&](const std::string& name) { return args.get(name) == "true"; };

        args.parse(argc, argv);
        verbose_level = stoi(args.get("v"));
        if (verbose_level > 0) {
            args.describe();
        }


        if (p("u")) {
            show_unicode_examples();
        }


        if (p("argtypes")) {
            show_argtype_definitions();
        }

        if (args.given("katoms")) {
            strings_t words = option_words(args, "katoms");
            std::string verb = words.empty() ? "" : words[0];
            if (verb == "help") {
                katom_usage();
                return 0;
            }
            if (!verb.empty() && verb != "full") {
                std::cout << "Unrecognized katom command: --katoms " << join(words, " ") << "\n\n";
                katom_usage();
                return 1;
            }
            describe_katoms(verb == "full");
        }

        if (p("rewrite")) {
            show_katom_rewrite_patterns();
        }

        // The --typeface subcommands operate on the Klammertext font store
        // (infrastructure) and load no klammer set.
        if (args.given("typeface")) {
            font_command(option_words(args, "typeface"));
            return 0;
        }

        Machine M;
        // Same rule as kdiag: a command that specifies no target evaluates
        // under the GENERAL target (Andy, 2026-08-15).  kdesc has no target
        // argument either -- it describes what a klammer set provides for ALL
        // targets -- and a designer's ".k" holding a top-level @eval hit the
        // identical "Variable "K_target" not defined".
        M.m_state.set("K_target", Target_registry::general_name);

        strings_t input_filenames = resolve_filename_list(args.get("i"));
        if (verbose_level > 0 && !input_filenames.empty()) {
            std::cout << "input_filenames: " << input_filenames << "\n";
        }

        if (!input_filenames.empty()) {
            M.m_state.set(
                "K_input_dir", absolute_pathname(file_directory(input_filenames[0])));
        } else {
            M.m_state.set("K_input_dir", fs::current_path().generic_string());
        }

        // --klammersets both lists and loads: with no words it enumerates the
        // search path, with symbols it loads them for the analyses below.
        if (args.given("klammersets")) {
            klammerset_command(M, option_words(args, "klammersets"));
        } else {  // By default, SKS is loaded for analysis
            M.read(fs::path(M.m_state.value("KLAMMERTEXT_HOME") + "/sks/sks.k"));
        }

        // Snapshot BEFORE the input is read.  The distinction is not "declared
        // by a klammerset" but "loaded as context": an input file may itself
        // declare @@@klammerset -- that is how a designer writes one -- and
        // its klammers are still the ones being asked about.
        strings_t context_files = M.m_klammersets.loaded_files();

        for (auto fname : input_filenames) {
            if (verbose_level > 0) {
                std::cout << "Read " << fname << "\n";
            }
            M.read(fs::path(absolute_pathname(fname)));
        }

        // --coverage is validated here, before a klammer set is read, so a
        // mistyped word or "help" is answered at once.  The report itself
        // needs the loaded registry, so it runs at the end.
        // The words are "help", "all", and at most one target name, which
        // can only be checked once the klammersets are loaded (below).
        bool coverage_all = false;
        std::string coverage_target {};
        if (args.given("coverage")) {
            strings_t words = option_words(args, "coverage");
            for (const std::string& word : words) {
                if (word == "help") {
                    coverage_usage();
                    return 0;
                } else if (word == "all") {
                    coverage_all = true;
                } else if (coverage_target.empty()) {
                    coverage_target = word;
                } else {
                    std::cout << "Unrecognized coverage command: --coverage "
                              << join(words, " ") << "\n\n";
                    coverage_usage();
                    return 1;
                }
            }
        }

        strings_t own_klammers_only {};
        if (!input_filenames.empty()) {
            own_klammers_only = context_files;
        }


        if (p("c")) {
            show_special_characters();
            std::cout << "\n";
        }

        if (p("t")) {
            std::cout << boldblack << "Targets\n" << black
                      << M.m_targets.describe(2, true, own_klammers_only);
        }

        // "-k <text>" searches names AND descriptions, case-insensitively,
        // with whitespace collapsed on both sides.  An empty listing for a
        // search that was actually made is reported: silence would read as a
        // broken command.  It is not an error -- finding nothing is a result.
        // With an input file, the klammersets are loaded so the input can be
        // ANALYSED against them, but they are not what the user is asking
        // about: a designer wants the klammers this file defines, and a reader
        // of an unfamiliar document wants the custom klammers it carries.  So
        // the listing is restricted to klammers with a definition outside the
        // klammerset files.  Without -i there is nothing else to show, so the
        // klammerset itself is the answer and no filter applies.
        if (args.given("k")) {
            std::string search = join(option_words(args, "k"), " ");
            std::string listing = M.m_klammers.describe(2, search, own_klammers_only);
            if (listing.empty() && !search.empty()) {
                std::cout << "No klammer names or descriptions contained "
                          << q_(collapse_whitespace(search)) << ".\n";
            } else {
                std::cout << boldblack << "Klammers\n" << black << listing;
            }
        }

        if (p("optionsets")) {
            std::cout << boldblack << "Option sets\n" << black
                      << M.m_option_sets.describe(2, own_klammers_only);
        }

        // Analysis only: klammer_coverage() reads the registry and modifies
        // nothing, so what a document renders to is unaffected by asking.
        if (args.given("coverage")) {
            if (!coverage_target.empty()) {
                if (!is_in(coverage_target, M.m_targets.user_defined())) {
                    std::cout << "No target \"" << coverage_target << "\" is defined.  Enter \"kdesc -t\" to see the\n"
                              << "targets the loaded klammersets define, or \"--coverage help\".\n";
                    return 1;
                }
                report_target_coverage(klammer_coverage(M, own_klammers_only), coverage_target, coverage_all, std::cout);
            } else {
                report_coverage(M, klammer_coverage(M, own_klammers_only), coverage_all, std::cout);
            }
        }
    }
    catch (Error& e) {
        // Nonzero, as ktext does: a command that prints an error and exits 0
        // reports success, and a script cannot tell the difference.
        e.print_message();
        return 1;
    }
    return 0;
}