twiki-parse

#!/usr/bin/env raku

# use Grammar::Tracer;

sub get-twiki-author(Str $author) {
    given $author {
        when /^[ $<first>=(<[A..Z]> <[a..z]>+) $<last>=(<[A..Z]> <[A..Z a..z]>+) ]$/ {
            ~$/<first> ~ ' ' ~ ~$/<last>.tclc
        }

        when /^[ TWiki\w+ | BaseUserMapping_\d+ ]$/ {
            'TWiki Pseudo User'
        }

        default {
            note "Unexpected page author: { $author }";
            $author
        }
    }
}

sub get-name-from-twiki-file(Str $file) {
    $file.IO
        .basename
        .subst(/'.txt' $/)
}

sub get-title-from-twiki-file(Str $file) {
    get-name-from-twiki-file($file)
        .subst(/(<[a..z]>) (<[A..Z]>)/, { "$0 $1" }, :g)
}

sub ensure-trailing-slash-if-not-empty(Str $path is rw) {
    if $path ne '' && $path.substr(*-1) ne '/' {
        $path ~= '/';
    }
}

sub indent(Str $text) {
    my $indent = '    ';
    $indent ~ join("\n" ~ $indent, $text.split("\n"))
}

grammar TWiki::Grammar {
    token TOP {
        :my $*IN-TWIKI-TABLE = False;

        <metainfo>

        \n*

        <paragraph>*
    }

    token metainfo {
        <topic-info>
        <topic-parent>?
    }

    token topic-info {
        ^^ '%META:TOPICINFO{' <metavar>+ % ' ' '}%' \n
    }

    token topic-parent {
        ^^ '%META:TOPICPARENT{' <metavar> '}%' \n
    }

    token metavar {
        $<name>=[\w+] '="' ~ '"' $<value>=[<-["]>*]
    }

    token paragraph {
        (
            # We have to use "|" here because separators and headers start in
            # the same way.
            || [ <separator> | <header> ]
            || <signature>
            || <block-image>
            || <list-items>
            || <table>
            || <attachment>
            || <normal-text>
        )

        [ \n+ || $ ]
    }

    token separator {
        ^^ '-' ** 3..*
    }

    token header {
        ^^ '-' ** 3..4
        [
            || $<level>=['+' ** 1..5] ' '? <text-span>?
            || { die "Incorrect header syntax near position { $/.pos() + 5 }" }
        ]
    }

    token attribute {
        # This definition of value doesn't allow using quotes of the other
        # kind inside the attribute value, which is allowed in theory, but is
        # not needed in practice, and it's much simpler to forbid it.
        $<name>=[\w+] '=' $<quote>=<['"]> ~ $<quote> $<value>=<-['"]>*
    }

    token image-tag {
        '<img ' ~ ' />' [ <attribute>+ % ' ' ]
    }

    token block-image {
        ^^ <.ws> <image-tag> <.ws> $$
    }

    token inline-image {
        <image-tag>
    }

    # In principle, only spaces are allowed. but some of the existing pages
    # use TABs, so we have to accept them too.
    token list-indent(Int $level) {
        <list-space-indent: $level> || <list-tab-indent: $level>
    }

    # Using <...>**$level would require <!before> to ensure that we get
    # exactly the needed number of spaces or TABs, which is slower than using
    # a code block, so use the latter instead.
    token list-space-indent(Int $level) {
        '   '+ <?{ $/.chars div 3 == $level }>
    }

    token list-tab-indent(Int $level) {
        \t+ <?{ $/.chars == $level }>
    }

    token list-items(Int $level = 1) {
        ^^ <list-indent: $level> <!before \s>
        $<item>=<list-item: $level>
        [
            || \n $<item>=<list-items: $level + 1>
            || \n \h* <?before \n>
            || \n <.list-indent: $level> $<item>=<list-item: $level>
        ]*
    }

    token list-item(Int $level) {
        (
            || <list-bullet: $level>
            || <list-numbered: $level>
            || <list-def: $level>
            || { die "Incorrect level $level list syntax near position { $/.pos() + 3 }" }
        )
    }

    # List item text can wrap on the following line if it starts by just a
    # single indent (even for a nested list!), but we shouldn't match the
    # following item here.
    token list-text(Int $level) {
        <text-span> [ \n <.list-indent: 1> <!before <[* 1..9 A a $]> > <text-span>+ ]*
    }

    token list-bullet(Int $level) {
        # There are some (useless) empty list items in the existing pages, so
        # allow them.
        '* ' <list-text: $level>?
    }

    token list-numbered(Int $level) {
        # Period is supposed to be mandatory here but in practice can be (and
        # is) omitted. OTOH we don't support Roman numerals of numbering nor
        # any other Latin letters because this is not used in the existing
        # pages.
        <[1..9 A a]> '.'? ' ' <list-text: $level>
    }

    token list-def(Int $level) {
        '$ ' $<name>=<-[:\n]>+ ': ' $<text>=<.list-text: $level>
    }

    # We have to allow empty and multiline tag contents here.
    #
    # TODO: We ignore wiki markup inside HTML tags currently but it can
    # actually be used there.
    token html-tag(Str $tag) {
        "<$tag" [\h+ <-[>]>+]? '>'
        [
            || [\n <.text-span>?]+
            || <.text-span>?
        ]
        "</$tag>"
    }

    token html-fragment {
        || <html-tag: 'col'>
        || <html-tag: 'div'>
        || <html-tag: 'span'>
        || <html-tag: 'table'>
        || <html-tag: 'tbody'>
        || <html-tag: 'td'>
        || <html-tag: 'th'>
        || <html-tag: 'tr'>
    }

    token table {
        ^^
        [ '%TABLE{' \N+? '}%' \n ]?
        '|'
        { $*IN-TWIKI-TABLE = True }
        [
            || [ <header-row> || <table-row> ] \n
               [ '|' <table-row> ]* % \n
            || { die "Incorrect table syntax near position { $/.pos() + 3 }" }
        ]
        { $*IN-TWIKI-TABLE = False }
    }

    # Redefine the default ws to _not_ include vertical whitespace such as \n.
    token ws {
        \h*
    }

    # This is our own token, unlike <ws>.
    token space {
        \h+
    }

    token header-row {
        [ <.ws> <header-cell>? '|' ]+ <.ws>
    }

    token header-cell {
        '*' $<value>=<-[*|\n]>+ '*' <.ws>
    }

    token table-row {
        <.ws> [ $<cell>=(<text-span>?) '|' ]+ <.ws>
    }

    token text-span {
        (
            || <space>
            || <percent-sign>
            || <attached-image>
            || <variable>
            || <pre-verbatim>
            || <pre>
            || <verbatim>
            || <p>
            || <nop>
            || <br>
            || <strong>
            || <strike>
            || <em>
            || <bold>
            || <bold-italic>
            || <italic>
            || <bold-fixed>
            || <fixed>
            || <html-fragment>
            || <inline-image>
            || <html-link>
            || <literal>
            || <sticky-check>
            || <not-a-link>
            || <ignored-tag>
            || <unknown-tag>
            || <forced-link>
            || <wiki-link>
            || <normal-word>
        )+
    }

    # This is almost like html-tag but is used for TWiki-specific tags too and
    # captures its contents.
    token capture-tag(Str $tag) {
        "<$tag" [\h+ $<attributes>=<-[>]>+]? ">"
        \n*
        $<contents>=.*?
        \n?
        "</$tag>"
    }

    # Handle percent signs at the end of the words separately to detect
    # unknown variables when we encounter them in any other place.
    token percent-sign {
        '%' <?before \s>
    }

    token attached-image {
        '%ATTACHURL%/' (\S+)
    }

    token variable {
        '%' (
            || <toc>
            || <icon>
            || <color-start>
            || <color-end>
            || <ignored-directive>
        ) '%'
    }

    token toc {
        'TOC'
    }

    token icon {
        || 'ICON{' $<name>=[ 'info' || 'note' || 'question' || 'todo' || 'warning' || 'wip' ] '}'
        || $<name>=<[H P X Y]>
        # Those ones don't actually exist, but are used in several places, so
        # handle them too.
        || $<name>='FIXME'
        || $<name>='TODO'
    }

    token color-start {
        || 'RED' || 'YELLOW' || 'ORANGE' || 'PINK' || 'PURPLE' || 'TEAL'
        || 'NAVY' || 'BLUE' || 'AQUA' || 'LIME' || 'GREEN' || 'OLIVE'
        || 'MAROON' || 'BROWN' || 'BLACK' || 'GRAY' || 'SILVER' || 'WHITE'
    }

    token color-end {
        'ENDCOLOR'
    }

    token pre-verbatim {
        '<pre>' <.ws> <capture-tag: 'verbatim'> \s*? '</pre>'
    }

    token pre {
        <capture-tag: 'pre'>
    }

    token verbatim {
        <capture-tag: 'verbatim'>
    }

    token p {
        '<p' [\h+ <-[>]>+]? '>' <text-span> '</p>'
    }

    token nop {
        '<nop>'
    }

    token br {
        '<br />'
    }

    token strong {
        <capture-tag: 'strong'>
    }

    token strike {
        '<strike>' <text-span> '</strike>'
    }

    token em {
        <capture-tag: 'em'>
    }

    token bold {
        <!after \w> '*' $<text>=\N+? '*' <!before \w>
    }

    token bold-italic {
        « '__' $<text>=\N+? '__' »
    }

    token italic {
        # Don't take into account underscores appearing in the middle of the
        # words and do allow them in between those that bracket words.
        « '_' $<text>=\N+? '_' »
    }

    token bold-fixed {
        # Note that '=' should be allowed inside here, it can, and is, used.
        <!after \w> '==' $<text>=[ <-[=]>+ '=' <-[=]>+ ]+ '==' <!before \w>
    }

    token fixed {
        # We have to account for using '=' inside this one, this can happen as
        # long as it's not followed by a space or punctuation (but not any
        # punctuation neither, as we can something like "=path=/root=" too).
        '=' $<text>=\N+? '=' <?before <[\s , . : ; ( )]>>
    }

    token html-link {
        <capture-tag: 'a'>
    }

    token literal {
        <capture-tag: 'literal'>
    }

    # The only occurrences of <sticky> in our pages are these ones, so just
    # hardcode them instead of dealing with it more generally.
    token sticky-check {
        '<sticky>&check;</sticky>'
    }

    # We can't have HTML lists intermingled with normal markup, it could (and
    # would) result in markup being mangled and ignored, e.g. Asciidoc refuses
    # to have headers inside list items. And it seems better to drop the lists
    # than the rest of the markup.
    token ignored-tag {
        || '<li' ' dir="ltr"'? '>'
        || '<ol>'
        || '<ul>'
        || '</li>'
        || '</ol>'
        || '</ul>'
    }

    # We can't allow "<" inside normal words because this would consume any
    # tags following them, so we have to handle all occurrences of "<"
    # separately, even it's not always special.
    token unknown-tag {
        '<' <-[/]> \N*? '>'
    }

    token not-a-link {
        || '!' ( <upper> \w+ )
        || '<noautolink>' ( <-[<\n]>+ ) '</noautolink>'
    }

    token forced-link {
        '[[' $<link>=<-[\]]>+ ']'
        [ '[' $<text>=<-[\]]>+ ']' ]?
        ']'
    }

    token wiki-link {
        [ <upper> <lower>+ <digit>* ] ** 2..*
    }

    # We need to allow "="s not at the start or end of the word (knowing that
    # the other ones will be consumed by <fixed> tried earlier) and "_" and
    # "*" inside the words (those preceded by the word boundaries should have
    # been consumed by <italic>).
    #
    # Also allow "*" at the beginning of the line because there is wrong TWiki
    # markup using it -- this is not rendered correctly by it, but we still
    # have to accept it, if only as plain text.
    token normal-word {
        [
        || <-[<*=\n]> <[\w] + [. _ *]>*
        || <!wb> [ '=' || '*' || '<=' || '>=' || '>' ]
        || <!wb> '<' <!before '/'>
        || <wb> '='
        || <wb> '==' <wb>
        || ^^ '*' <wb>
        ]
        # Finally, forbid "|" inside the table cells.
        <?{ !($*IN-TWIKI-TABLE && ~$/ ~~ /^ '|'/) }>
    }

    token signature-date {
        \d ** 1..2 ' ' \w ** 3..4 ' ' \d ** 4
    }

    token signature-date-ISO {
        \d ** 4 '-' \d ** 2 '-' \d ** 2
    }

    token signature {
        ^^
        [
            '-- Main.' $<author>=[\w+] ' - '
            $<action>=
            [
                || 'Created '
                || 'Last modified '
                || 'Updated '
            ]?
            $<date>=[ <.signature-date> || <.signature-date-ISO> ]
        ]+ % ' '
        # Some signature lines have various junk at the end.
        [
            || ' - ' $<comment>=\N+
            || ' <br/>'
            || \h+
        ]?
    }

    token attachment {
        ^^ '%META:FILEATTACHMENT{'
        [
            || <metavar>+ % ' ' '}%'
            || { die "Incorrect FILEATTACHMENT syntax near position { $/.pos() + 3 }" }
        ]
    }

    token ignored-directive {
        [
            || 'META:' [ FORM || FIELD || PREFERENCE || TOPICMOVED ]
            || 'EDITPREFERENCES'
            || 'INCLUDE'
            || 'SEARCH'
        ] '{'  \N+? '}'
    }

    token normal-text {
        ^^ <text-span>
    }
}

class TWiki::Metainfo {
    has $.file;
    has $.author;
    has Instant $.date;
    has $.parent;

    method gist() {
        my $opt-attrs = '';
        $opt-attrs ~= qq[, parent="$.parent"] if $.parent;

        qq[{ self.^name }(author="$.author", date={$.date.DateTime}$opt-attrs)]
    }

    method to-adoc() {
         qq:to/END/;
        = { get-title-from-twiki-file($.file) }
        :author: $.author
        :revdate: { $.date.DateTime }
        END
    }
}

class TWiki::Verbatim {
    has $.text;

    method gist() {
        "{ self.^name }(\n{ indent($.text) }\n)"
    }

    method to-adoc() {
        # When we're inside a list, we need to make the block part of the
        # list, otherwise we just need to separate it from the preceding text.
        qq:to/END/;
        { $*TWIKI-LIST-LEVEL ?? "\n+" !! '' }
        ....
        $.text
        ....
        END
    }
}

class TWiki::Ignored {
    method gist() {
        self.^name
    }

    method to-adoc() {
        ''
    }
}

class TWiki::LineBreak {
    method gist() {
        self.^name
    }

    method to-adoc() {
        " +\n"
    }
}

class TWiki::Link {
    has Str:D $.link is required;
    has Str $.text;

    method gist() {
        "{ self.^name }[$.link]"
    }

    method to-adoc() {
        "link:{$.link}[{ $.text // '' }]"
    }
}

class TWiki::FormattedText {
    has $.delimiter;
    has $.text;

    method gist() {
        "{ self.^name }({ $.delimiter }{ $.text }{ $.delimiter })"
    }

    method to-adoc() {
        $.delimiter ~ $.text ~ $.delimiter.flip
    }
}

class TWiki::StrikeThrough {
    has $.contents;

    method gist() {
        "{ self.^name }(\n{ indent($.contents.gist) }\n)"
    }

    method to-adoc() {
        # This could be implemented as [.line-through]#...#, but we don't have
        # support for this in the CSS currently, so implement this via HTML
        # pass through for now.
        "+++<strike>+++{ $.contents.to-adoc }+++</strike>+++"
    }
}

class TWiki::PlainText {
    has $.text is rw;

    method new(Str $text) {
        self.bless(:$text)
    }

    method append(Str $text) {
        $.text ~= $text;
    }

    method gist() {
        "{ self.^name }($.text)"
    }

    method to-adoc() {
        $.text
    }
}

class TWiki::Icon {
    has Str $.name;

    method gist() {
        "{ self.^name }($.name)"
    }

    method to-adoc() {
        # We use GitHub-specific icon names as it seems to be the only thing
        # which actually works when rendering.
        "+++:$.name:+++"
    }
}

class TWiki::Image {
    has $.src is required;
    has $.alt;
    has $.width;
    has $.height;

    method gist() {
        "{ self.^name }($.src)"
    }

    method attrs() {
        my $attrs = '';
        if $.alt {
            $attrs = $.alt
        }
        if $.width || $.height {
            $attrs ~= ",$.width,$.height"
        }

        $attrs
    }

    # Some images are actually icons and should be represented as such.
    method is-todo-icon() {
        $.src eq '%ICONURL{todo}%'
    }

    method adoc-todo-icon {
        TWiki::Icon.new(name => 'stop_sign').to-adoc;
    }
}

class TWiki::BlockImage is TWiki::Image {
    method to-adoc() {
        return self.adoc-todo-icon if self.is-todo-icon;

        qq:to/END/;

        image::{ $.src }[{ self.attrs }]
        END
    }
}

class TWiki::InlineImage is TWiki::Image {
    method to-adoc() {
        return self.adoc-todo-icon if self.is-todo-icon;

        "image:{ $.src }[{ self.attrs }]"
    }
}

class TWiki::Signature {
    has Str @.authors;
    has Str @.actions;
    has Str @.dates;
    has Str $.comment;

    method gist() {
        "{ self.^name }({ @.authors.join(', ') })"
    }

    method to-adoc() {
        # We could put this information into the document properties, but it
        # seems better to just show it here in the same format as TWiki does.
        my Str $sig = "---\n";

        for @.authors Z @.actions Z @.dates -> [$author, $action, $date] {
            $sig ~= "\n- $author {$action || 'Edited '}$date"
        }

        $sig ~= " ($.comment)" if $.comment;

        $sig
    }
}

class TWiki::Attachment {
    has Str $.name is required;
    has Str $.url is required;
    has Str $.attachment;
    has Str $.comment;
    has Str $.date;
    has Str $.path;
    has Str $.size;
    has Str $.user;
    has Str $.version;

    method gist() {
        "{ self.^name }($.name)"
    }

    method to-adoc() {
        # There is no support for attachments per se, so just show them in a
        # list.
        chomp qq:to/END/;
        * link:{ $.url }[$.name] $.comment (by $.user at { Instant.from-posix($.date).DateTime })
        END
    }
}

class TWiki::BulletListItem {
    has $.text;

    method gist() {
        "{ self.^name }({ $.text.gist })"
    }

    method to-adoc(Int $level) {
        # As mentioned in the grammar, there are some empty lists, accept them
        # without complaining and, as a lone "*" isn't recognized as a list
        # item, ensure that we always use a non-empty text.
        '*' x $level ~ ' ' ~ ($.text ?? $.text.to-adoc !! '&nbsp;')
    }
}

class TWiki::NumberedListItem {
    has $.text;

    method gist() {
        "{ self.^name }({ $.text.gist })"
    }

    method to-adoc(Int $level) {
        '.' x $level ~ ' ' ~ $.text.to-adoc
    }
}

class TWiki::DefListItem {
    has $.name;
    has $.text;

    method to-adoc(Int $level) {
        note "Definition lists at level $level not supported." if $level != 1;
        "{$.name}:: { $.text.to-adoc }"
    }
}

class TWiki::List {
    has @.items;

    method gist() {
        chomp qq:to/END/;
        { self.^name }(
        { indent(join("\n", @.items».gist)) }
        )
        END
    }

    method to-adoc(Int $level = 0) {
        $*TWIKI-LIST-LEVEL += 1;
        LEAVE $*TWIKI-LIST-LEVEL -= 1;

        @.items».to-adoc($level + 1).join("\n");
    }
}

class TWiki::ColorStart {
    has Str $.name;

    method gist() {
        "{ self.^name }($.name)"
    }

    method to-adoc() {
        # We have to pass the colours through to HTML as there is no direct
        # support for them in Asciidoc.
        qq[+++<span style="color: { $.name.lc };">+++]
    }
}

class TWiki::ColorEnd {
    method gist() {
        self.^name
    }

    method to-adoc() {
        qq[+++</span>+++]
    }
}

class TWiki::HTMLSpan {
    has $.html;

    method gist() {
        "{ self.^name }(\n{ indent($.html) }\n)"
    }

    method to-adoc() {
        "+++$.html+++"
    }
}

class TWiki::HTMLBlock {
    has $.html is rw;

    method gist() {
        "{ self.^name }(\n{ indent($.html) }\n)"
    }

    method to-adoc() {
        qq:to/END/;
        ++++
        $.html
        ++++
        END
    }
}

class TWiki::Separator is TWiki::HTMLBlock {
    submethod TWEAK {
        self.html = '<hr>';
    }

    method gist() {
        self.^name
    }
}

class TWiki::Header {
    has Int $.level;
    has $.text;

    method gist() {
        chomp qq:to/END/;
        { self.^name }($.level,
        { indent($.text.gist) }
        )
        END
    }

    method to-adoc() {
        '=' x ($.level + 1) ~ ' ' ~ $.text.to-adoc ~ "\n"
    }
}

class TWiki::TableRow {
    has @.cells;

    method gist() {
        "{ self.^name }({ join(' | ', @.cells».gist) })"
    }

    method to-adoc() {
        '|' ~ join '|', @.cells».to-adoc
    }
}

class TWiki::Table {
    has Str @.headers;
    has @.rows;

    method gist() {
        chomp qq:to/END/;
        { self.^name }({ "\n" ~
            indent("Headers: " ~ join(' | ', @.headers)) if @.headers
        }
        { indent(join("\n", @.rows».gist)) }
        )
        END
    }

    method to-adoc() {
        my ($num-columns, $headers-attr, $headers-row);
        if @.headers {
            $num-columns = @.headers.elems;
            $headers-attr = '%header,';
            $headers-row = '|' ~ join('|', @.headers) ~ "\n";
        } else {
            $num-columns = @.rows[0].cells.elems;
            $headers-attr = '';
            $headers-row = '';
        }

        qq:to/END/;
        [{ $headers-attr }cols="{ join ',', '1' xx $num-columns }"]
        |===
        { $headers-row }{ join "\n", @.rows».to-adoc }
        |===
        END
    }
}

class TWiki::Text {
    has @.elements;

    method gist() {
        chomp qq:to/END/;
        { self.^name }(
        { indent(@.elements».gist.join("\n")) }
        )
        END
    }

    method to-adoc() {
        @.elements».to-adoc.join
    }
}

# This function performs an optimization of the parse tree and creates Text
# only if necessary, i.e. if there are elements other than just PlainText ones
# in the provided array. Otherwise it coalesces them all into a single
# PlainText and just returns it instead.
sub twiki-text(*@elements-orig) {
    # Coalesce consecutive plain text arguments into a single one.
    my Bool $last-is-plain-text = False;

    my @elements;
    for @elements-orig -> $element {
        my Bool $this-is-plain-text = $element ~~ TWiki::PlainText;

        if $last-is-plain-text && $this-is-plain-text {
            @elements.tail.append: $element.text;
        } else {
            @elements.append: $element;
            $last-is-plain-text = $this-is-plain-text;
        }
    }

    @elements.elems == 1 ?? @elements.tail !! TWiki::Text.new(:@elements)
}

class TWiki::Page {
    has TWiki::Metainfo $.metainfo;
    has Bool $.toc;
    has @.body;

    method gist() {
        "{ self.^name }[{ $.metainfo.gist }{ $.toc ?? ', toc' !! '' }]\n" ~
        indent(@.body».gist.join("\n"))
    }

    method to-adoc() {
        my Int $*TWIKI-LIST-LEVEL = 0;

        my $doc = $.metainfo.to-adoc;
        $doc ~= ":toc:\n" if $.toc;

        $doc ~ "\n" ~ join("\n\n", @.body».to-adoc) ~ "\n"
    }
}

class TWiki::Actions {
    has $.file;
    has Str:D $.wiki-links-root is required;
    has Str:D $.attachments-root is required;
    has Bool:D $.warn-unknown = False;

    has Bool $!toc = False;

    submethod TWEAK {
        ensure-trailing-slash-if-not-empty($!wiki-links-root);
        ensure-trailing-slash-if-not-empty($!attachments-root);
    }

    # Expand %ATTACHURL% and %ATTACHURLPATH% TWiki variables in the path if
    # they exist.
    method !expand-attachment-path(Str $path) {
        $path.subst(
            rx{ ^^ '%' ATTACHURL [ PATH ]? '%' <?before '/'> },
            $.attachments-root ~ get-name-from-twiki-file($.file)
        );
    }

    # Create a full path for an attachment from a relative path.
    method !make-attachment-path(Str $name) {
        note qq{Unexpected attachment name "$name" in $.file} if '/' ∈ $name;

        $.attachments-root ~ get-name-from-twiki-file($.file) ~ '/' ~ $name
    }

    method TOP($/) {
        # Get rid of paragraphs without any corresponding AST node.
        my @paragraphs;
        for $/<paragraph> {
            my $ast = $_.ast;

            # Somehow we end up with lists containing a single element and not
            # just the element itself here.
            if $ast.elems > 1 {
                note "Unexpected AST structure when parsing $.file: { $ast.perl }";
                next
            }

            # We also may have an empty list, but this is fine, just skip it.
            next unless $ast.elems;

            my $value = $ast[0];

            # Some AST nodes don't have any value associated with them, this
            # is fine too, just skip them.
            next unless defined $value;

            @paragraphs.push($value);
        }

        make TWiki::Page.new(
            metainfo => $<metainfo>.ast,
            toc      => $!toc,
            body     => @paragraphs,
        );
    }

    method metainfo($/) {
        my $info = $/<topic-info>.ast;
        my $parent = $/<topic-parent>;
        make TWiki::Metainfo.new(
            file   => $.file,
            author => $info<author>,
            date   => $info<date>,
            parent => $parent ?? ~$parent.ast !! Nil,
        );
    }

    method topic-info($/) {
        my $author;
        my $date;
        for $/<metavar> {
            my $var = $_.ast;
            given $var.key {
                when 'author' { $author = get-twiki-author($var.value) }
                when 'date' { $date = Instant.from-posix: $var.value }
                when 'format' | 'version' | 'reprev' { }
                default { note "In $.file: unknown metavar { $var.key } = { $var.value }" }
            }
        }

        die "Required author metavar not found."
            unless defined($author);
        die "Required date metavar not found."
            unless defined($date);

        make { author => $author, date => $date }
    }

    method topic-parent($/) {
        my $parent = $/<metavar>;
        die "Found $parent<name> instead of the expected name attribute in META:TOPICPARENT."
            unless $parent<name> eq 'name';

        make $parent<value>;
    }

    method metavar($/) {
        make ~$/<name> => ~$/<value>;
    }

    method signature($/) {
        make TWiki::Signature.new(
            authors => $<author>».Str,
            actions => $<action>».Str,
            dates   => $<date>».Str,
            comment => $<comment> ?? ~$<comment> !! ''
        );
    }

    method attachment($/) {
        my %params;
        for $<metavar>».ast -> $kv {
            if $kv.key eq 'name' {
                %params.append: (url => self!make-attachment-path($kv.value))
            }

            %params.append: $kv
        }

        make TWiki::Attachment.new(
            | %params
        );
    }

    method paragraph($/) {
        make $/[0].hash.values».ast;
    }

    method separator($/) {
        make TWiki::Separator.new;
    }

    method attribute($/) {
        make ~$/<name> => ~$/<value>;
    }

    method space($/) {
        make TWiki::PlainText.new(~$/);
    }

    method toc($/) {
        $!toc = True;

        # Although this token is only recognized for its side effect, we still
        # must have something corresponding to it in the AST node.
        make TWiki::Ignored.new();
    }

    method percent-sign($/) {
        make TWiki::PlainText.new(~$/);
    }

    method attached-image($/) {
        my $src = self!make-attachment-path(~$/[0]);
        make TWiki::BlockImage.new(:$src);
    }

    method icon($/) {
        # This is an abstraction violation but we translate TWiki icons names
        # directly to GitHub emojis names for simplicity.
        my $name = do given ~$/<name> {
            when 'info'             { 'writing_hand' }
            when /note || P/        { 'pencil' }
            when 'question'         { 'question' }
            when /:i ^ todo $/      { 'stop_sign' }
            when 'FIXME'            { 'exclamation' }
            when /warning || X/     { 'warning' }
            when 'wip'              { 'construction' }
            when 'H'                { 'speech_balloon' } # better match?
            when 'Y'                { 'heavy_check_mark' }

            default {
                note "Unknown icon name: { $_ }";
                $_
            }
        };

        make TWiki::Icon.new(:$name);
    }

    method color-start($/) {
        # This is not ideal, as normally we should create a parent node and
        # put the text between color start and end nodes under it, but this
        # would complicate the grammar, so for now just use separate nodes.
        make TWiki::ColorStart.new(name => ~$/);
    }

    method color-end($/) {
        make TWiki::ColorEnd.new;
    }

    method variable($/) {
        make $/[0].hash.values[0].ast;
    }

    method pre-verbatim($/) {
        make TWiki::HTMLBlock.new(
            html => ~$<capture-tag><contents>
        );
    }

    method pre($/) {
        # This should probably handle TWiki markup in the contents, but we
        # don't need to do it currently.
        make TWiki::HTMLBlock.new(
            html => ~$<capture-tag><contents>
        );
    }

    method verbatim($/) {
        make TWiki::Verbatim.new(
            text => ~$<capture-tag><contents>
        );
    }

    method p($/) {
        make twiki-text(
            $<text-span>.ast,
            TWiki::LineBreak.new()
        );
    }

    method nop($/) {
        make TWiki::Ignored.new();
    }

    method br($/) {
        make TWiki::LineBreak.new();
    }

    method strong($/) {
        # Most occurrences of <strong> can be mapped to Asciidoc native bold
        # markup, but this tag can also be used with attributes, in which case
        # we need to preserve it as HTML.
        my $attributes = $<capture-tag><attributes>;

        $attributes
            ?? make TWiki::HTMLSpan.new(
                html => ~$/
            )
            !! make TWiki::FormattedText.new(
                delimiter => '*',
                text      => ~$<capture-tag><contents>
            );
    }

    method strike($/) {
        make TWiki::StrikeThrough.new(
            contents => twiki-text($<text-span>.ast)
        );
    }

    method em($/) {
        make TWiki::FormattedText.new(
            delimiter => '_',
            text      => ~$<capture-tag><contents>
        );
    }

    method bold($/) {
        make TWiki::FormattedText.new(
            delimiter => '*',
            text      => ~$<text>
        );
    }

    method bold-italic($/) {
        make TWiki::FormattedText.new(
            delimiter => '*_',
            text      => ~$<text>
        );
    }

    method italic($/) {
        make TWiki::FormattedText.new(
            delimiter => '_',
            text      => ~$<text>
        );
    }

    method bold-fixed($/) {
        make TWiki::FormattedText.new(
            delimiter => '`*',
            text      => ~$<text>
        );
    }

    method fixed($/) {
        make TWiki::FormattedText.new(
            delimiter => '`',
            text      => ~$<text>
        );
    }

    method html-link($/) {
        make TWiki::HTMLSpan.new(
            html => ~$/
        );
    }

    method literal($/) {
        make TWiki::HTMLBlock.new(
            html => ~$<capture-tag><contents>
        );
    }

    method sticky-check($/) {
        make TWiki::Icon.new(
            name => 'heavy_check_mark'
        );
    }

    method ignored-tag($/) {
        make TWiki::Ignored.new();
    }

    method unknown-tag($/) {
        note qq[Unknown tag "$/" in $.file at position { $/.pos() }.] if $.warn-unknown;
        make TWiki::PlainText.new(~$/);
    }

    method not-a-link($/) {
        make TWiki::PlainText.new(~$/[0]);
    }

    method forced-link($/) {
        make TWiki::Link.new(
            link => self!expand-attachment-path(~$<link>),
            text => $<text> ?? ~$<text> !! Str
        );
    }

    method wiki-link($/) {
        if $.wiki-links-root {
            make TWiki::Link.new(
                link => $.wiki-links-root ~ $/,
                text => ~$/
            );
        } else {
            make TWiki::Link.new(
                link => ~$/
            );
        }
    }

    method normal-word($/) {
        make TWiki::PlainText.new(~$/);
    }

    method image-tag($/) {
        my %attributes;
        %attributes.append: $<attribute>.list».ast;

        if 'src' ∈ %attributes {
            %attributes<src> = self!expand-attachment-path(%attributes<src>);
        } else {
            note qq[Image without "src" in $.file at position { $/.pos() }.];
        }

        make %attributes;
    }

    method block-image($/) {
        make TWiki::BlockImage.new(
            | $<image-tag>.ast
        );
    }

    method inline-image($/) {
        make TWiki::InlineImage.new(
            | $<image-tag>.ast
        );
    }

    method list-items($/) {
        make TWiki::List.new(
            items => $<item>».ast
        );
    }

    method list-item($/) {
        # The matches hash here contains just a single element because it's an
        # alternative, so take it.
        make $/[0].hash.values[0].ast;
    }

    method list-text($/) {
        my @elements;
        for $<text-span> -> $span {
            # Ensure there is a space before the continuation line.
            if @elements {
                @elements.push: TWiki::PlainText.new(' ')
            }
            @elements.append: $span.ast;
        }

        make twiki-text(@elements);
    }

    method list-bullet($/) {
        make TWiki::BulletListItem.new(
            text => $<list-text>.ast
        );
    }

    method list-numbered($/) {
        make TWiki::NumberedListItem.new(
            text => $<list-text>.ast
        );
    }

    method list-def($/) {
        make TWiki::DefListItem.new(
            name => ~$<name>,
            text => $<text>.ast,
        );
    }

    method html-fragment($/) {
        make TWiki::HTMLSpan.new(
            html => ~$/
        );
    }

    method header($/) {
        # Header may not have any text, making it rather useless, so skip it.
        my $text = $/<text-span>;
        return unless $text;

        make TWiki::Header.new(
            level => $/<level>.chars,
            text  => twiki-text($text.ast)
        );
    }

    method header-row($/) {
        make $/<header-cell>».ast;
    }

    method header-cell($/) {
        # There are some empty header cells too.
        my $text = $/<value>;
        make $text ?? ~$text !! '';
    }

    method table-row($/) {
        my @cells;
        for $<cell> -> $cell {
            my $cell-contents = $cell<text-span>;

            # We still must have something in the cell even if it's empty.
            @cells.append: twiki-text(
                $cell-contents
                    ?? $cell-contents.ast
                    !! TWiki::PlainText.new('')
            )
        }

        make TWiki::TableRow.new(:@cells);
    }

    method table($/) {
        make TWiki::Table.new(
            headers => defined($/<header-row>) ?? $/<header-row>.ast !! [],
            rows    => $/<table-row>».ast
        );
    }

    method text-span($/) {
        # Text span contains a single multiple match represented by an array
        # whose elements are single-element hashes, so flatten them.
        #
        # The grammar structure probably could (should?) be reorganized to
        # simplify this.
        my @elements;
        for $/[0] -> $single-element {
            my $span = $single-element.hash.values;
            if $span.elems != 1 {
                note "Unexpected span AST structure when parsing $.file: { $span.perl }";
            }

            @elements.push: $span[0].ast;
        }

        make @elements;
    }

    method ignored-directive($/) {
        make TWiki::Ignored.new();
    }

    method normal-text($/) {
        make twiki-text($<text-span>.ast);
    }
}

class TWiki::Result {
    has $.error;
    has $.adoc;
    has $.ast;
}

sub convert-twiki-to-adoc(Str $file, %actions-options) {
    my $input = $file.IO.slurp;
    my $actions = TWiki::Actions.new(:$file, | %actions-options);
    my $ast = try TWiki::Grammar.parse($input, :$actions).ast;
    my ($adoc, $error);
    if !$ast {
        $error = "Failed to parse $file as TWiki page";
    } else {
        $adoc = try $ast.to-adoc;
        if $! {
            $error = "Failed to convert $file to Asciidoc";
        }
    }

    if $! {
        $error ~= ": $!\n{ $!.backtrace }"
    }

    return $file => TWiki::Result.new(:$error, :$adoc, :$ast)
}

sub MAIN(*@twiki-files,
        Str :$out-dir,              #= Directory for the output files.
        Str :$wiki-links-root       #= Prefix to use for WikiLinks.
            = '',
        Str :$attachments-root      #= Prefix to use for the attachments.
            = '/uploads',
        Bool :$warn-unknown,        #= Warn about unknown tags.
        Bool :$debug,               #= Dump AST.
    ) {
    if $out-dir {
        $out-dir.IO.mkdir;
    }

    my %actions-options;
    %actions-options.append({ :$wiki-links-root });
    %actions-options.append({ :$attachments-root });
    %actions-options.append({ :$warn-unknown }) if $warn-unknown;

    my @conversions;
    for @twiki-files -> $twiki-file {
        @conversions.append: start convert-twiki-to-adoc($twiki-file, %actions-options);
    }

    my $rc = 0;
    for await @conversions {
        my ($file, $result) = ($_.key, $_.value);
        if $result.error {
            note $result.error;

            $rc = 1;

            next
        }

        note $result.ast if $debug;

        if $out-dir {
            try {
                $out-dir.IO.add(
                    get-name-from-twiki-file($file) ~ '.adoc'
                ).spurt: $result.adoc
            }
        }
    }

    exit $rc
}