|
|
@ -1,10 +1,13 @@
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
|
|
|
* Comment types and parsing
|
|
|
|
|
|
|
|
* facilities
|
|
|
|
|
|
|
|
*
|
|
|
|
|
|
|
|
* Authors: Tristan Brice Velloza Kildaire (deavmi)
|
|
|
|
|
|
|
|
*/
|
|
|
|
module tlang.compiler.symbols.comments;
|
|
|
|
module tlang.compiler.symbols.comments;
|
|
|
|
|
|
|
|
|
|
|
|
// TODO: Add comment parsing
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
import std.string : startsWith, split, strip, stripLeft, stripRight;
|
|
|
|
import std.string : startsWith, split, strip, stripLeft, stripRight;
|
|
|
|
import std.array : join;
|
|
|
|
import std.array : join;
|
|
|
|
|
|
|
|
|
|
|
|
import tlang.misc.logging;
|
|
|
|
import tlang.misc.logging;
|
|
|
|
import std.string : format;
|
|
|
|
import std.string : format;
|
|
|
|
import tlang.compiler.lexer.core.tokens : Token;
|
|
|
|
import tlang.compiler.lexer.core.tokens : Token;
|
|
|
@ -185,22 +188,48 @@ public struct DocStr
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
|
|
|
* Parts of a comment
|
|
|
|
|
|
|
|
*/
|
|
|
|
private struct CommentParts
|
|
|
|
private struct CommentParts
|
|
|
|
{
|
|
|
|
{
|
|
|
|
string bdy;
|
|
|
|
string bdy;
|
|
|
|
DocStr[] strs;
|
|
|
|
DocStr[] strs;
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
|
|
|
* Parses comments of various forms
|
|
|
|
|
|
|
|
*/
|
|
|
|
private class CommentParser
|
|
|
|
private class CommentParser
|
|
|
|
{
|
|
|
|
{
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
|
|
|
* Comment text
|
|
|
|
|
|
|
|
*/
|
|
|
|
private string source;
|
|
|
|
private string source;
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
|
|
|
* Constructs a new `CommentParser`
|
|
|
|
|
|
|
|
* which can extract the comments
|
|
|
|
|
|
|
|
* from the given comment text
|
|
|
|
|
|
|
|
*
|
|
|
|
|
|
|
|
* Params:
|
|
|
|
|
|
|
|
* source = the comment itself
|
|
|
|
|
|
|
|
*/
|
|
|
|
this(string source)
|
|
|
|
this(string source)
|
|
|
|
{
|
|
|
|
{
|
|
|
|
this.source = source;
|
|
|
|
this.source = source;
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
private string commentPart;
|
|
|
|
/**
|
|
|
|
|
|
|
|
* Begins the parsing of the provided
|
|
|
|
|
|
|
|
* comment source text.
|
|
|
|
|
|
|
|
*
|
|
|
|
|
|
|
|
* This assumes a well-formatted
|
|
|
|
|
|
|
|
* comment is passed to us. i.e. one
|
|
|
|
|
|
|
|
* extracted form the lexer.
|
|
|
|
|
|
|
|
*
|
|
|
|
|
|
|
|
* Returns: the `CommentParts`
|
|
|
|
|
|
|
|
*/
|
|
|
|
private CommentParts extract()
|
|
|
|
private CommentParts extract()
|
|
|
|
{
|
|
|
|
{
|
|
|
|
CommentParts parts;
|
|
|
|
CommentParts parts;
|
|
|
@ -277,6 +306,17 @@ private class CommentParser
|
|
|
|
return parts;
|
|
|
|
return parts;
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
|
|
|
* Attempts to extract the doc params
|
|
|
|
|
|
|
|
* from a given line, returning if it
|
|
|
|
|
|
|
|
* was a success or not
|
|
|
|
|
|
|
|
*
|
|
|
|
|
|
|
|
* Params:
|
|
|
|
|
|
|
|
* line = the line to parse
|
|
|
|
|
|
|
|
* ds = the result (if any)
|
|
|
|
|
|
|
|
* Returns: `true` if extraction succeeded,
|
|
|
|
|
|
|
|
* otherwise `false`
|
|
|
|
|
|
|
|
*/
|
|
|
|
private bool extractDocLine(string line, ref DocStr ds)
|
|
|
|
private bool extractDocLine(string line, ref DocStr ds)
|
|
|
|
{
|
|
|
|
{
|
|
|
|
string buildUp;
|
|
|
|
string buildUp;
|
|
|
@ -460,11 +500,19 @@ private class CommentParser
|
|
|
|
return false;
|
|
|
|
return false;
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
// TODO: Use niknaks filter
|
|
|
|
/**
|
|
|
|
|
|
|
|
* Strips out all lines with doc-strings
|
|
|
|
|
|
|
|
* (params) in them
|
|
|
|
|
|
|
|
*
|
|
|
|
|
|
|
|
* Params:
|
|
|
|
|
|
|
|
* input = the input lines
|
|
|
|
|
|
|
|
* Returns: the output lines
|
|
|
|
|
|
|
|
*/
|
|
|
|
private string[] onlyParams(string[] input)
|
|
|
|
private string[] onlyParams(string[] input)
|
|
|
|
{
|
|
|
|
{
|
|
|
|
string[] withDoc;
|
|
|
|
string[] withDoc;
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
// TODO: Use niknaks filter
|
|
|
|
foreach(string i; input)
|
|
|
|
foreach(string i; input)
|
|
|
|
{
|
|
|
|
{
|
|
|
|
if(stripLeft(i).startsWith("@"))
|
|
|
|
if(stripLeft(i).startsWith("@"))
|
|
|
@ -476,11 +524,19 @@ private class CommentParser
|
|
|
|
return withDoc;
|
|
|
|
return withDoc;
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
// TODO: Use niknaks filter
|
|
|
|
/**
|
|
|
|
|
|
|
|
* Strips out any line which is a doc line
|
|
|
|
|
|
|
|
* (non-parameter line)
|
|
|
|
|
|
|
|
*
|
|
|
|
|
|
|
|
* Params:
|
|
|
|
|
|
|
|
* input = the input lines
|
|
|
|
|
|
|
|
* Returns: the output lines
|
|
|
|
|
|
|
|
*/
|
|
|
|
private string[] stripOutDocLines(string[] input)
|
|
|
|
private string[] stripOutDocLines(string[] input)
|
|
|
|
{
|
|
|
|
{
|
|
|
|
string[] withoutDoc;
|
|
|
|
string[] withoutDoc;
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
// TODO: Use niknaks filter
|
|
|
|
foreach(string i; input)
|
|
|
|
foreach(string i; input)
|
|
|
|
{
|
|
|
|
{
|
|
|
|
DEBUG(format("'%s'", i));
|
|
|
|
DEBUG(format("'%s'", i));
|
|
|
@ -502,7 +558,6 @@ private class CommentParser
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
version(unittest)
|
|
|
|
version(unittest)
|
|
|
|
{
|
|
|
|
{
|
|
|
|
import std.stdio;
|
|
|
|
import std.stdio;
|
|
|
@ -521,7 +576,6 @@ unittest
|
|
|
|
|
|
|
|
|
|
|
|
writeln(format("Comment: '%s'", comment));
|
|
|
|
writeln(format("Comment: '%s'", comment));
|
|
|
|
|
|
|
|
|
|
|
|
// *cast(int*)0 = 1;
|
|
|
|
|
|
|
|
assert("Hello there" == comment.bdy);
|
|
|
|
assert("Hello there" == comment.bdy);
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
@ -532,36 +586,85 @@ unittest
|
|
|
|
*/
|
|
|
|
*/
|
|
|
|
public final class Comment
|
|
|
|
public final class Comment
|
|
|
|
{
|
|
|
|
{
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
|
|
|
* The comment's component
|
|
|
|
|
|
|
|
* parts
|
|
|
|
|
|
|
|
*/
|
|
|
|
private CommentParts content;
|
|
|
|
private CommentParts content;
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
|
|
|
* Constructs a new comment out
|
|
|
|
|
|
|
|
* of its parsed component parts
|
|
|
|
|
|
|
|
*
|
|
|
|
|
|
|
|
* Params:
|
|
|
|
|
|
|
|
* content = the parts
|
|
|
|
|
|
|
|
*/
|
|
|
|
private this(CommentParts content)
|
|
|
|
private this(CommentParts content)
|
|
|
|
{
|
|
|
|
{
|
|
|
|
this.content = content;
|
|
|
|
this.content = content;
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
|
|
|
* Generates a comment from the
|
|
|
|
|
|
|
|
* provided token
|
|
|
|
|
|
|
|
*
|
|
|
|
|
|
|
|
* Params:
|
|
|
|
|
|
|
|
* commentToken = token containing
|
|
|
|
|
|
|
|
* the comment
|
|
|
|
|
|
|
|
* Returns: a `Comment`
|
|
|
|
|
|
|
|
*/
|
|
|
|
public static Comment fromToken(Token commentToken)
|
|
|
|
public static Comment fromToken(Token commentToken)
|
|
|
|
{
|
|
|
|
{
|
|
|
|
return fromText(commentToken.getToken());
|
|
|
|
return fromText(commentToken.getToken());
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
|
|
|
* Generates a comment from the
|
|
|
|
|
|
|
|
* provided comment text
|
|
|
|
|
|
|
|
*
|
|
|
|
|
|
|
|
* Params:
|
|
|
|
|
|
|
|
* text = the text containing
|
|
|
|
|
|
|
|
* the comment
|
|
|
|
|
|
|
|
* Returns: a `Comment`
|
|
|
|
|
|
|
|
*/
|
|
|
|
private static Comment fromText(string text)
|
|
|
|
private static Comment fromText(string text)
|
|
|
|
{
|
|
|
|
{
|
|
|
|
// TODO: Inline this behavior here
|
|
|
|
|
|
|
|
CommentParser parser = new CommentParser(text);
|
|
|
|
CommentParser parser = new CommentParser(text);
|
|
|
|
|
|
|
|
|
|
|
|
return new Comment(parser.extract());
|
|
|
|
return new Comment(parser.extract());
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
|
|
|
* Extracts the comment's contents.
|
|
|
|
|
|
|
|
*
|
|
|
|
|
|
|
|
* This excludes param/doc-strings
|
|
|
|
|
|
|
|
*
|
|
|
|
|
|
|
|
* Returns: the contents
|
|
|
|
|
|
|
|
*/
|
|
|
|
public string getContent()
|
|
|
|
public string getContent()
|
|
|
|
{
|
|
|
|
{
|
|
|
|
return this.content.bdy;
|
|
|
|
return this.content.bdy;
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
|
|
|
* Extract all the doc-strings present
|
|
|
|
|
|
|
|
* within the comment
|
|
|
|
|
|
|
|
*
|
|
|
|
|
|
|
|
* Returns: an array of them
|
|
|
|
|
|
|
|
*/
|
|
|
|
public DocStr[] getDocStrings()
|
|
|
|
public DocStr[] getDocStrings()
|
|
|
|
{
|
|
|
|
{
|
|
|
|
return this.content.strs;
|
|
|
|
return this.content.strs;
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
|
|
|
* Extracts all of the param-docs
|
|
|
|
|
|
|
|
* and places them into a key-value
|
|
|
|
|
|
|
|
* mapping whereby the key is
|
|
|
|
|
|
|
|
* the parameter's name and the
|
|
|
|
|
|
|
|
* value the doc itself
|
|
|
|
|
|
|
|
*
|
|
|
|
|
|
|
|
* Returns: a map
|
|
|
|
|
|
|
|
*/
|
|
|
|
public ParamDoc[string] getAllParamDocs()
|
|
|
|
public ParamDoc[string] getAllParamDocs()
|
|
|
|
{
|
|
|
|
{
|
|
|
|
// TODO: Use niknaks
|
|
|
|
// TODO: Use niknaks
|
|
|
@ -578,6 +681,15 @@ public final class Comment
|
|
|
|
return d;
|
|
|
|
return d;
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
|
|
|
* Extracts the return doc-string
|
|
|
|
|
|
|
|
* from this comment
|
|
|
|
|
|
|
|
*
|
|
|
|
|
|
|
|
* Params:
|
|
|
|
|
|
|
|
* retDoc = the found `ReturnDoc`
|
|
|
|
|
|
|
|
* Returns: `true` if found, otheriwse
|
|
|
|
|
|
|
|
* `false`
|
|
|
|
|
|
|
|
*/
|
|
|
|
public bool getReturnDoc(ref ReturnsDoc retDoc)
|
|
|
|
public bool getReturnDoc(ref ReturnsDoc retDoc)
|
|
|
|
{
|
|
|
|
{
|
|
|
|
// TODO: Use niknaks flter
|
|
|
|
// TODO: Use niknaks flter
|
|
|
|