/**
 * Copyright: © 2014 Economic Modeling Specialists, Intl.
 * Authors: Brian Schott
 * License: $(LINK2 http://www.boost.org/LICENSE_1_0.txt Boost License 1.0)
 *
 * Forked and modified in 2021 for hgen by Eugene 'Vindex' Stulin.
 * The 'hgen' project: https://gitlab.com/vindexbit/hgen
 * Author: Eugene 'Vindex' Stulin <tech.vindex@gmail.com>
 * License: $(LINK2 http://www.boost.org/LICENSE_1_0.txt Boost License 1.0)
 */

module ddoc.sections;

import std.algorithm.searching : canFind, endsWith, find;
import std.array : appender;
import std.range : dropBack, enumerate, retro;
import std.string : strip;

import ddoc.lexer;
import ddoc.macros;
import std.typecons;


/*******************************************************************************
 * Standard section names.
 */
immutable string[] STANDARD_SECTIONS = [
    "Authors", "Bugs", "Copyright", "Date",
    "Deprecated", "Examples", "History", "License", "Returns", "See_Also",
    "Standards", "Throws", "Version"
];


/*******************************************************************************
 * Data structure containing the comment section name,
 * comment section contents and pair mapping for 'Params', 'Macros', 'Escapes'.
 */
struct Section {
    /// The section name.
    string name;

    /// The section content.
    string content;

    /***************************************************************************
     * Mapping used by the Params, Macros, and Escapes section types.
     *
     * $(UL
     * $(LI "Params": key = parameter name, value = parameter description)
     * $(LI "Macros": key = macro name, value = macro implementation)
     * $(LI "Escapes": key = character to escape, value = replacement string)
     * )
     */
    KeyValuePair[] mapping;

    /***************************************************************************
     * Returns: true if $(B name) is one of $(B STANDARD_SECTIONS).
     */
    bool isStandard() const @property {
        return STANDARD_SECTIONS.canFind(name);
    }

    ///
    unittest {
        Section s;
        s.name = "Authors";
        assert(s.isStandard);
        s.name = "Butterflies";
        assert(!s.isStandard);
    }
}


/*******************************************************************************
 * Parses a Macros or Params section, filling in the mapping fields of the
 * returned section.
 */
Section parseMacrosOrParams(string name,
                            ref Lexer lexer,
                            ref string[string] macros) {
    Section s;
    s.name = name;
    while (!lexer.empty && lexer.front.type != Type.header) {
        if (!parseKeyValuePair(lexer, s.mapping)) {
            break;
        }
        if (name == "Macros") {
            foreach (kv; s.mapping) {
                macros[kv[0]] = kv[1];
            }
        }
    }
    return s;
}


/*******************************************************************************
 * Split a text into sections.
 *
 * Takes a text, which is generally a full comment (usually you'll also call
 * $(D unDecorateComment) before). It splits it in an array of $(D Section)
 * and returns it.
 * Whatever the content of $(D text) is, this function will always return an
 * array of at least 2 items. Those 2 sections are the "Summary" and
 * "Description" sections (which may be empty).
 *
 * Params:
 * text = A DDOC-formatted comment.
 *
 * Returns:
 * An array of $(D Section) with at least 2 elements.
 */
Section[] splitSections(string text) {
    // Note: The specs says those sections are unnamed. So some people could
    // name one of it's section 'Summary' or 'Description', and it would be
    // legal (but arguably wrong).
    auto lex = Lexer(text);
    auto app = appender!(Section[]);
    bool hasSummary;
    // Used to strip trailing newlines / whitespace.
    lex.stripWhitespace();
    size_t sliceStart = lex.offset - lex.front.text.length;
    if (lex.front.type == Type.inlined) {
        sliceStart -= 2; // opening and closing '`' characters
    }
    size_t sliceEnd = sliceStart;
    string name;
    app ~= Section();
    app ~= Section();

    void finishSection() {
        auto text = lex.text[sliceStart .. sliceEnd];
        // remove the last line from the current section except for the last section
        // (the last section doesn't have a following section)
        auto endDashes = text.endsWith("---");
        if (text.canFind("\n") && sliceEnd != lex.text.length && !endDashes) {
            text = text.dropBack(
                text.retro.enumerate.find!(e => e.value == '\n').front.index
            );
        }

        if (!hasSummary) {
            hasSummary = true;
            app.data[0].content = text;
        } else if (name is null) {
            //immutable bool hadContent = app.data[1].content.length > 0;
            app.data[1].content ~= text;
        } else {
            appendSection(name, text, app);
        }
        sliceStart = sliceEnd = lex.offset;
    }

    while (!lex.empty) switch (lex.front.type) {
        case Type.header:
            finishSection();
            name = lex.front.text;
            lex.popFront();
            lex.stripWhitespace();
            break;
        case Type.newline:
            lex.popFront();
            if (name is null && !lex.empty && lex.front.type == Type.newline)
                finishSection();
            break;
        case Type.embedded:
            finishSection();
            name = "Examples";
            appendSection("Examples", "---\n" ~ lex.front.text ~ "\n---", app);
            lex.popFront();
            sliceStart = sliceEnd = lex.offset;
            break;
        default:
            lex.popFront();
            sliceEnd = lex.offset;
            break;
    }
    finishSection();
    foreach (ref section; app.data) {
        section.content = section.content.strip();
    }
    return app.data;
}


unittest {
    import std.conv : text;
    import std.algorithm.iteration : map;
    import std.algorithm.comparison : equal;

    auto s = `description

Something else

---
// an example
---
Throws: a fit
---
/// another example
---
`;
    const sections = splitSections(s);
    immutable expectedExample = `---
// an example
---
---
/// another example
---`;
    assert(sections.length == 4);
    assert(sections.map!(a => a.name).equal(["", "", "Examples", "Throws"]));
    assert(sections[0].content == "description");
    assert(sections[1].content == "Something else");
    assert(sections[2].content == expectedExample);
    assert(sections[3].content == "a fit");
}

unittest {
    import std.conv : text;

    auto s1 = `Short comment.
Still comment.

Description.
Still desc...

Still

Authors:
Me & he
Bugs:
None
Copyright:
Date:

Deprecated:
Nope,

------
void foo() {}
----

History:
License:
Returns:
See_Also
See_Also:
Standards:

Throws:
Version:


`;
    auto cnt = [
        "Short comment.\nStill comment.",
        "Description.\nStill desc...\nStill",
        "Me & he",
        "None",
        "",
        "",
        "Nope,",
        "---\nvoid foo() {}\n---",
        "",
        "",
        "See_Also",
        "",
        "",
        "",
        ""
    ];
    foreach (idx, sec; splitSections(s1)) {
        if (idx < 2) {
            // Summary & description
            assert(sec.name is null, sec.name);
        } else {
            assert(sec.name == STANDARD_SECTIONS[idx - 2], sec.name);
        }
        assert(
            sec.content == cnt[idx],
            text(sec.name, " (", idx, "): ",
            sec.content)
        );
    }
}


unittest {
    immutable comment = `summary

---
some code!!!
---`;
    const sections = splitSections(comment);
    assert(sections[0].content == "summary");
    assert(sections[1].content == "");
    assert(sections[2].content == "---\nsome code!!!\n---");
}

// Split section content correctly (without next line)
unittest {
    immutable comment = `Params:
    pattern(s) = Regular expression(s) to match
    flags = The _attributes (g, i, m and x accepted)

    Throws: $(D RegexException) if there were any errors during compilation.`;

    const sections = splitSections(comment);
    const exp = "pattern(s) = Regular expression(s) to match\n"
              ~ "    flags = The _attributes (g, i, m and x accepted)";
    assert(sections[2].content == exp);
}


// Handle inlined code properly
unittest {
    immutable comment = "`code` something";
    const sections = splitSections(comment);
    assert(sections[0].content == "`code` something");
}


/*******************************************************************************
 * Append a section to the given output or merge it if a section with
 * the same name already exists.
 *
 * Returns:
 * $(D true) if the section did not already exists,
 * $(D false) if the content was merged with an existing section.
 */
private bool appendSection(O)(string name, string content, ref O output)
in {
    assert(name !is null, "You should not call appendSection with a null name");
}
do {
    for (size_t i = 2; i < output.data.length; ++i) {
        if (output.data[i].name != name) {
            continue;
        }
        if (output.data[i].content.length == 0) {
            output.data[i].content = content;
        } else if (content.length > 0) {
            output.data[i].content ~= "\n" ~ content;
        }
        return false;
    }
    output ~= Section(name, content);
    return true;
}