Merge pull request #6 from Tapeline/master

2.0-RC-2

QuailRuntimeEnvironment/src/main/java/me/tapeline/quailj/debugging/DebugServer.java

@@ -26,9 +26,13 @@ public class DebugServer {
     private static Thread serverThread;
     private static volatile Runtime currentRuntime;
     private static volatile Memory currentScope;
-    private static volatile Queue<String> codeToBeExecuted = new ArrayDeque<>();
+
+    /** Whether there was a socket exception and whether debugger can continue its work */
     public static boolean malfunction = false;
 
+    /** Queue of code send via debugger for evaluation */
+    private static volatile Queue<String> codeToBeExecuted = new ArrayDeque<>();
+
     public static HashMap<File, Set<Integer>> breakpoints = new HashMap<>();
 
     public static void initialize(short port) throws IOException {
@@ -42,6 +46,10 @@ public static void awaitConnection() throws IOException {
         out = new BufferedWriter(new OutputStreamWriter(clientSocket.getOutputStream()), 1000000);
     }
 
+    /**
+     * Accepts initial messages from debug client as described in documentation.
+     * These include, but may not be limited to breakpoint information
+     */
     public static void acceptInitial() throws IOException {
         String message = "";
         do {
@@ -61,6 +69,10 @@ public static void startServer() {
         serverThread.start();
     }
 
+    /**
+     * States that program execution ended.
+     * Writes corresponding message to client
+     */
     public static void markProgramEnd() {
         if (malfunction) return;
         try {
@@ -158,6 +170,9 @@ private static void sendMemContents() throws IOException {
         out.flush();
     }
 
+    /**
+     * Called when program steps onto a breakpoint
+     */
     public static void enterBreakpoint(Runtime runtime, Memory scope, int line) throws IOException {
         out.write("bp\n");
         out.write(runtime.getScriptFile() + ";" + line +"\n");

QuailRuntimeEnvironment/src/main/java/me/tapeline/quailj/debugging/DebugServer_legacy.java

@@ -13,6 +13,7 @@
 import java.net.Socket;
 import java.util.*;
 
+@Deprecated
 public class DebugServer_legacy {
 
     private static Socket clientSocket;

QuailRuntimeEnvironment/src/main/java/me/tapeline/quailj/docgen/DocumentationContext.java

@@ -2,6 +2,10 @@
 
 import org.jetbrains.annotations.Nullable;
 
+/**
+ * Specifies path to documenting elements
+ * Created when entering a class or a function
+ */
 public class DocumentationContext {
 
     public final @Nullable DocumentationContext parent;

QuailRuntimeEnvironment/src/main/java/me/tapeline/quailj/docgen/DocumentationGenerator.java

@@ -200,6 +200,9 @@ public String generateDocumentationForNode(Node node, DocumentationContext ctx)
         return "";
     }
 
+    /**
+     * Converts internal representation of arguments back to human-readable format
+     */
     private String argsToString(List<LiteralFunction.Argument> arguments) {
         StringBuilder sb = new StringBuilder("(");
         for (int i = 0; i < arguments.size(); i++) {

QuailRuntimeEnvironment/src/main/java/me/tapeline/quailj/launcher/LaunchCommandParser.java

@@ -25,6 +25,7 @@ public LaunchCommandParser(String[] consoleArgs) throws LauncherException {
         this.userFlags = new HashMap<>();
     }
 
+
     public static boolean toBoolean(String strValue) {
         return strValue.equalsIgnoreCase("true") ||
                 strValue.equalsIgnoreCase("1") ||

QuailRuntimeEnvironment/src/main/java/me/tapeline/quailj/launcher/QuailLauncher.java

@@ -24,7 +24,7 @@
 import java.util.List;
 
 public class QuailLauncher {
-
+// TODO: refactor
     public static final int QUAIL_MAJOR_VERSION = 2;
     public static final int QUAIL_MINOR_VERSION = 0;
     public static final int QUAIL_PATCH_VERSION = 0;

QuailRuntimeEnvironment/src/main/java/me/tapeline/quailj/parsing/Parser.java

@@ -4,6 +4,7 @@
 import me.tapeline.quailj.lexing.TokenType;
 import me.tapeline.quailj.parsing.annotation.Annotation;
 import me.tapeline.quailj.parsing.annotation.Decoration;
+import me.tapeline.quailj.parsing.annotation.std.DecoratorAnnotation;
 import me.tapeline.quailj.parsing.annotation.std.DeprecatedAnnotation;
 import me.tapeline.quailj.parsing.nodes.Node;
 import me.tapeline.quailj.parsing.nodes.comments.*;
@@ -62,6 +63,7 @@ public Parser(String code, List<Token> tokens) {
 
     public static void registerDefaultAnnotations() {
         registerAnnotation(new DeprecatedAnnotation());
+        registerAnnotation(new DecoratorAnnotation());
     }
 
     public static void registerAnnotation(Annotation annotation) {
@@ -289,6 +291,11 @@ private Token toNextSignificant() {
         return current;
     }
 
+    /**
+     * Gets index of next significant token, but does not
+     * modify the current state of parser
+     * @return next significant token index
+     * */
     private int nextSignificantIndex() {
         if (reachedEnd()) return -1;
         int increment = 0;
@@ -303,11 +310,17 @@ private int nextSignificantIndex() {
         return increment;
     }
 
+    /***
+     * @return whether next significant token will be of provided type
+     */
     private boolean forseeToken(TokenType type) {
         int signIndex = nextSignificantIndex();
         return getNext(signIndex) != null && getNext(signIndex).getType() == type;
     }
 
+    /***
+     * @return whether next significant token sequence will resemble provided type pattern
+     */
     private boolean forseePattern(TokenType... pattern) {
         int signIndex = nextSignificantIndex();
         for (int i = 0; i < pattern.length; i++)
@@ -316,10 +329,20 @@ private boolean forseePattern(TokenType... pattern) {
         return true;
     }
 
+    /**
+     * Requires next token to be of provided type
+     * @return next token of provided type
+     * @throws ParserException if next token's type != provided type
+     */
     private Token require(TokenType type) throws ParserException {
         return require(type, null);
     }
 
+    /**
+     * Requires next token to be of provided type
+     * @return next token of provided type
+     * @throws ParserException if next token's type != provided type
+     */
     private Token require(TokenType type, String message) throws ParserException {
         if (reachedEnd())
             error(message == null? "Expected " + type.toString() + " but file ended" : message);
@@ -336,6 +359,9 @@ private Token getPrevious() {
         return tokens.get(pos - 1);
     }
 
+    /**
+     * Transforms short operation to its binary operator. E.g. += to +
+     */
     private Token transformShortOp(Token shortOp) {
         if (shortOp.getType() == SHORT_POWER)
             return new Token(shortOp.getMod(), POWER, shortOp.getLexeme(),
@@ -361,6 +387,9 @@ private Token transformShortOp(Token shortOp) {
         return shortOp;
     }
 
+    /**
+     * Parses a block of code until meets one of provided tokens
+     */
     private BlockNode parseBlockUntil(Token beginning, TokenType... until) throws ParserException {
         BlockNode block = new BlockNode(beginning, new ArrayList<>());
         match(LCPAR);
@@ -370,6 +399,10 @@ private BlockNode parseBlockUntil(Token beginning, TokenType... until) throws Pa
         }
     }
 
+    /**
+     * Rolls the caret through all tabulations (to next non-tab token) and counts them
+     * @return tab count
+     */
     private int consumeTabs() {
         int tabCount = 0;
         //for (; matchExactly(TAB) != null; tabCount++);
@@ -392,6 +425,9 @@ private int consumeTabs() {
         return tabCount;
     }
 
+    /**
+     * Parses a block of code written in Python-style
+     */
     private BlockNode parsePythonBlock() throws ParserException {
         Token blockToken = getPrevious();
         matchExactly(EOL);
@@ -408,6 +444,7 @@ private BlockNode parsePythonBlock() throws ParserException {
         }
     }
 
+    @Deprecated // TODO Remove??
     private Node newNode(Class<? extends Node> node, Object... args) {
         Constructor<?> foundConstructor = null;
         for (Constructor<?> constructor : node.getConstructors()) {
@@ -441,6 +478,12 @@ private Node newNode(Class<? extends Node> node, Object... args) {
         }
     }
 
+    /**
+     * Transforms given node with provided decorations in reverse order
+     * E.g.: @Decorator(...) function f() ... will be transformed into
+     * f = Decorator(function f() ..., ...)
+     * @return node with all decorations applied
+     */
     private Node applyDecorations(List<Decoration> decorations, Node target) {
         if (decorations.isEmpty()) return target;
         decorations = new ArrayList<>(decorations);
@@ -476,6 +519,11 @@ private Node applyDecorations(List<Decoration> decorations, Node target) {
         return target;
     }
 
+    /**
+     * Wraps node with decorations (puts it as an argument into the decorator function).
+     * E.g.: @Decorator(...) function f() ... will be transformed into
+     * Decorator(function f() ..., ...)
+     */
     private Node wrapWithDecoration(Node target, Decoration decoration) {
         String name = null;
         if (target instanceof LiteralClass)
@@ -510,6 +558,9 @@ private Node wrapWithDecoration(Node target, Decoration decoration) {
         }
     }
 
+    /**
+     * @return copy of current list of pending decorations
+     */
     private List<Decoration> freezeDecorations() {
         return pendingDecorations.subList(0, pendingDecorations.size());
     }
@@ -665,6 +716,9 @@ private static Annotation findAnnotation(String name) {
         return null;
     }
 
+    /**
+     * Matches all decorations and stores them as pending decorations to be applied later
+     */
     private void parseDecorations() throws ParserException {
         while (match(ANNOTATION) != null) {
             Token annotationToken = getPrevious();
@@ -745,6 +799,9 @@ private Node parseEffect() throws ParserException {
         return null;
     }
 
+    /**
+     * Parses all function constructions including overrides, constructors and gets/sets
+     */
     private Node parseFunction() throws ParserException {
         List<Decoration> decorations = null;
         if (forseePattern(MOD_STATIC, TYPE_METHOD) ||
@@ -954,6 +1011,11 @@ private Node parseUnary(ParsingPolicy policy) throws ParserException {
         return parseCall(policy);
     }
 
+    /**
+     * Parses call expressions, dot accessors (object.field),
+     * indexes and subscripts. All these syntax objects are
+     * equal by priority
+     */
     private Node parseCall(ParsingPolicy policy) throws ParserException {
         Node left = parsePrimary(policy);
         while (true) {
@@ -1198,6 +1260,10 @@ else if (match(KWARG_CONSUMER) != null)
         return null;
     }
 
+    /**
+     * Converts raw node sequence that is assumed to be arguments to
+     * proper argument sequence
+     */
     private List<LiteralFunction.Argument> convertDefinedArguments(List<Node> argumentNodes)
             throws ParserException {
         List<LiteralFunction.Argument> arguments = new ArrayList<>();
@@ -1292,6 +1358,9 @@ else if (matchMultiple(TYPE_LIST, TYPE_OBJECT, TYPE_FUNC) != null) {
         return currentModifier;
     }
 
+    /**
+     * @return default value for type (0 for number, false for boolean, etc)
+     */
     public static Node getDefaultNodeFor(int[] modifiers) {
         if (modifiers.length != 1) return new LiteralNull(Token.UNDEFINED);
         if (IntFlags.check(modifiers[0], ModifierConstants.BOOL))

QuailRuntimeEnvironment/src/main/java/me/tapeline/quailj/parsing/annotation/std/DecoratorAnnotation.java

@@ -0,0 +1,18 @@
+package me.tapeline.quailj.parsing.annotation.std;
+
+import me.tapeline.quailj.parsing.annotation.Annotation;
+import me.tapeline.quailj.parsing.nodes.Node;
+
+public class DecoratorAnnotation implements Annotation {
+
+    @Override
+    public String name() {
+        return "Decorator";
+    }
+
+    @Override
+    public Node apply(Node target, Object... args) {
+        return target;
+    }
+
+}