klammertext/ref/reflect.cpp

#include "machine.h"
#include "character.h"
#include "error.h"
#include "show.h"

// extern "C" is needed for dlsym name lookup. Returning std::string from
// C-linkage functions is technically non-standard but works correctly on
// Linux (Itanium ABI) where C and C++ calling conventions are identical.
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wreturn-type-c-linkage"
#endif

extern "C"
std::string diacritics_examples([[maybe_unused]] Machine& machine)
{
    if (diacritics.size() != diacritic_symbols_order.size()) {
        throw Internal_error("Mismatch between diacritics order list and their definitions");
    }
    //std::cout << machine;

    std::stringstream kt {};
    kt << "@table :caption Diacritics (with typical base characters) :cell_hpos c c l |\n"
       << "@i-Displayed | @i-Written | @i-Name ||\n";

    for (char symbol : diacritic_symbols_order) {
        std::string sym { symbol };
        auto [code, name] = diacritics[sym];
        std::string letter = diacritic_example_letter[sym];
        std::string written = "^" + letter + sym;
        if (sym == "~") {
            written = "^" + letter + "^~";
        }
        std::string display = "^" + letter + sym;
        kt << display << " | @t ^" << written << " @ | " << name << " ||\n";
    }
    kt << "table@";
    return kt.str();
}

extern "C"
std::string extended_latin_examples([[maybe_unused]] Machine& machine)
{
    std::stringstream kt {};
    kt << "@table :caption Extended Latin characters and ligatures :cell_hpos c c l |\n"
       << "@i-Displayed | @i-Written | @i-Name ||\n";
    for (const std::string& symbol : extended_latin_symbols) {
        auto [code, name] = extended_latin[symbol];
        std::string coded = "^" + symbol + "^";
        std::string file_literal = "^^ #- " + symbol + " #- ^^";
        kt << coded << " | @t " << file_literal << " @ | " << name << " ||\n";
    }
    kt << "table@";
    return kt.str();
}


extern "C"
std::string pinyin_examples([[maybe_unused]] Machine& machine)
{
    std::stringstream kt {};
    kt << "@table :caption Mandarin pinyin tones (using vowel ``a'') :cell_hpos c c l |\n"
       << "   @i-Displayed | @i-Written | @i-Name ||\n";

    for (auto [symbol, codename] : pinyin_tones) {
        auto [code, name] = codename;
        std::string literal = "^a" + symbol;
        kt << literal << " | @t ^" << literal << " @ | " << name << " ||\n";
    }
    kt << "table@";
    return kt.str();
}

extern "C"
std::string unicode_examples([[maybe_unused]] Machine& machine)
{
    std::stringstream kt {};
    kt << "\n@b Including Unicode in Klammertext files @\n\n"
       << "To specify a wide variety of different letter forms, the Unicode Standard "
       << "defines a large set of \"code points\" organized by groups.  To include a "
       << "Unicode character in Klammertext, you surround its hexadecimal number with "
       << "the \"^^\" character. For example, the Cyrillic captial letter \"I\" is \"И\", "
       << "included in Klammertext as ^^0418^^.\n\n"
       << "To search for Unicode characters by their description, see: @nl@\n"
       << "@link https://www.fileformat.info/info/unicode/char/search.htm @\n\n";

    kt << "@table :caption Examples of Chinese characters :cell_hpos c |\n"
       << " Character | Unicode | Pinyin ||\n";

    for (auto chr : dao) {
        std::string code = "^" + chr[1] + "^";
        kt << process_unicode_codepoint(code) << " | "
           << "^" << code << "^" << " | "
           << chr[0] << " ||\n";
    }
    kt << "table@\n\n";


    kt << "@table :caption Examples of Egyptian hieroglyphs :cell_hpos c c c l |\n"
       << "Hieroglyph | Unicode | Sound | Gardiner ||\n";

    // The body font carries no hieroglyphs, so the glyph names the
    // typeface it needs (shipped in fnt/); @document declares and localizes
    // it.  Under txt @typeface passes the text through unchanged.
    for (auto glyph : ptolemy) {
        kt << "@typeface noto-sans-egyptian-hieroglyphs :scale 1.5 | "
           << process_unicode_codepoint("^" + glyph[2] + "^") << " @ | "
                  << "^^" + glyph[2] + "^^ | "
                  << glyph[1] << " | "
                  << glyph[0] << " ||\n";
    }
    kt << "table@\n\n"
       << "\nIn @link https://en.wikipedia.org/wiki/List_of_Egyptian_hieroglyphs @, "
       << "the Unicode codepoint in the second column of the \"List of hieroglyphs\" "
       << "table is the number in the ^^...^^ code used by Klammertext.\n\n";

    return kt.str();
}