api.nom

By Bruce Hill | November 5, 2020
This is a simple tool I threw together that automatically generates the Nomsu API here.
#!/usr/bin/env nomsu -v7.0.0
###
    A command line tool to generate HTML documentation for Nomsu code.
    
use "commandline"
use "filesystem"

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

(HTML escaped $text) means
    (
        ($text, with "&" -> "&amp;", with "<" -> "&lt;", with ">" -> "&gt;"), 
            with "\"" -> "&quot;"
    ), with "'" -> "&#39;"

### This is specifically for the Nomsu bitbucket repo:
(URL for $filename $linenum) means:
    $url = "https://bitbucket.org/spilt/nomsu/src/master/\$filename"
    if $linenum:
        $basename = ($filename, match "[^/]+$")
        $url = "\($url)?fileviewer=file-view-default#\($basename)-\$linenum"
    return $url

command line program with $args:
    $def_stubs = {
        ."1 means", ."1 all mean", ."1 parses as", ."1 all parse as", ."1 compiles to"
        ."1 all compile to"
    }
    $skip_stubs = {."\\", .test}
    (defs in $tree) means:
        if (($tree.type == "Action") and $def_stubs.($tree, get stub)): return [$tree]
        if (($tree.type == "Action") and $skip_stubs.($tree, get stub)): return []
        if {.Action, .Block, .FileChunks}.($tree.type):
            return [: for $subtree in $tree: for $def in (defs in $subtree): add $def]
        return []
    
    say ("
        <style>
        .collapsed { display: none; padding: 4px; }
        .collapsed:target { display: table; }
        </style>
        <h1>Nomsu v\($(NOMSU VERSION), joined with ".") API</h1>
    ")
    
    for $filename in $args.extras:
        $file = (read file $filename)
        unless $file:
            fail "File does not exist: \$filename"
        $code = (NomsuCode from ($Source $filename 1 #$file) $file)
        try:
            $tree = ($code parsed)
        ..if it fails with $msg:
            say
                red ("
                    \$filename failed to parse:
                    \$msg
                ")
            $tree = (nil)
        
        unless $tree:
            do next $filename
        
        $showed_header = (no)
        (display $def from $body) means:
            if ($def.type != "Action"): return
            if (($def, get stub) == ""): return
            $file = ($def, get source file)
            [$line, $linenum, $linepos] = ($file, line info at $def.source.start)
            $filename = $def.source.filename
            unless $showed_header:
                say ("
                    
                    <h2><a href='\(URL for $filename)'>\($filename)</a></h2>
                    <ul>
                ")
                
                external:
                    $showed_header = (yes)
            
            say ("
                <li>
                  <a href='#\($def, get stub, as lua id)' class='action-name'>\(HTML escaped ($def as nomsu, text))</a>
                  <div class='collapsed' id='\($def, get stub, as lua id)'>
                    <a href='\(URL for $filename $linenum)' rel='noreferrer' target='_blank'>View source in Bitbucket repo</a>
                    <pre><code>\(HTML escaped ($body as nomsu, text))</code></pre>
                  </div>
                </li>
            ")
        
        for $def in (defs in $tree):
            if ($def.1.type == "List"):
                for $d in $def.1:
                    display $d from $def
            ..else:
                display $def.1 from $def
        
        if $showed_header:
            say "</ul>"