Write documentation for like 900 things. :(

Moderocky · Jan 1, 2022 · f6e3fdf · f6e3fdf
1 parent 1b17201
commit f6e3fdf
Show file tree

Hide file tree

Showing 139 changed files with 1,935 additions and 333 deletions.
diff --git a/pom.xml b/pom.xml
@@ -6,7 +6,7 @@
 
     <groupId>org.byteskript</groupId>
     <artifactId>byteskript</artifactId>
-    <version>1.0.7</version>
+    <version>1.0.8</version>
     <name>ByteSkript</name>
 
     <properties>

diff --git a/src/main/java/org/byteskript/skript/api/Document.java b/src/main/java/org/byteskript/skript/api/Document.java
@@ -0,0 +1,13 @@
+/*
+ * Copyright (c) 2022 ByteSkript org (Moderocky)
+ * View the full licence information and permissions:
+ * https://github.com/Moderocky/ByteSkript/blob/master/LICENSE
+ */
+
+package org.byteskript.skript.api;
+
+/**
+ * A miniature record for holding documentation for a syntax element.
+ */
+public record Document(String name, String type, String[] patterns, String description, String[] examples) {
+}
diff --git a/src/main/java/org/byteskript/skript/api/Event.java b/src/main/java/org/byteskript/skript/api/Event.java
@@ -11,6 +11,7 @@
 public abstract class Event {
 
     public final void run(final Skript skript) {
+        skript.runEvent(this);
     }
 
     public boolean isAsync() {

diff --git a/src/main/java/org/byteskript/skript/api/Library.java b/src/main/java/org/byteskript/skript/api/Library.java
@@ -11,7 +11,9 @@
 import mx.kenzie.foundation.language.PostCompileClass;
 import org.byteskript.skript.compiler.Context;
 
+import java.util.ArrayList;
 import java.util.Collection;
+import java.util.List;
 
 public interface Library {
 
@@ -32,4 +34,12 @@ public interface Library {
      */
     Collection<PostCompileClass> getRuntime();
 
+    default Document[] generateDocumentation() {
+        final List<Document> documents = new ArrayList<>();
+        for (final SyntaxElement syntax : this.getSyntax()) {
+            documents.add(syntax.createDocument());
+        }
+        return documents.toArray(new Document[0]);
+    }
+
 }
diff --git a/src/main/java/org/byteskript/skript/api/SyntaxElement.java b/src/main/java/org/byteskript/skript/api/SyntaxElement.java
@@ -8,6 +8,7 @@
 
 import mx.kenzie.foundation.*;
 import mx.kenzie.foundation.compiler.State;
+import org.byteskript.skript.api.note.Documentation;
 import org.byteskript.skript.api.note.ForceBridge;
 import org.byteskript.skript.api.note.ForceExtract;
 import org.byteskript.skript.api.note.ForceInline;
@@ -43,14 +44,22 @@ default Type getReturnType() {
         return CommonTypes.VOID;
     }
 
-    String name();
+    default String name() {
+        final Documentation documentation = this.getClass().getAnnotation(Documentation.class);
+        if (documentation == null) return getPattern().name();
+        return documentation.name();
+    }
 
     default String description() {
-        return null;
+        final Documentation documentation = this.getClass().getAnnotation(Documentation.class);
+        if (documentation == null) return "None.";
+        return documentation.description();
     }
 
     default String[] examples() {
-        return null;
+        final Documentation documentation = this.getClass().getAnnotation(Documentation.class);
+        if (documentation == null) return new String[0];
+        return documentation.examples();
     }
 
     boolean hasHandler(HandlerType type);
@@ -63,6 +72,16 @@ default CompileState getSubState() {
         return CompileState.STATEMENT;
     }
 
+    default void prepareExpectedTypes(Context context, Method target) {
+        if (target == null) return;
+        final ElementTree[] inputs = context.getCompileCurrent().nested();
+        if (inputs.length == 0) return;
+        final Type[] types = Type.of(target.getParameterTypes());
+        for (int i = 0; i < Math.min(types.length, inputs.length); i++) {
+            inputs[i].wanted = types[i];
+        }
+    }
+
     default boolean allowAsInputFor(Type type) {
         if (CommonTypes.REFERENT.equals(type) && hasHandler(StandardHandlers.SET)) return true;
         return type.equals(CommonTypes.OBJECT) || type.equals(getReturnType());
@@ -168,4 +187,8 @@ default String assemble(int line, String... inputs) throws ScriptReassemblyError
         throw new ScriptReassemblyError(line, "Not supported yet.");
     }
 
+    default Document createDocument() {
+        return new Document(name(), getType().name(), getPatterns(), description(), examples());
+    }
+
 }
diff --git a/src/main/java/org/byteskript/skript/api/note/Documentation.java b/src/main/java/org/byteskript/skript/api/note/Documentation.java
@@ -0,0 +1,21 @@
+/*
+ * Copyright (c) 2022 ByteSkript org (Moderocky)
+ * View the full licence information and permissions:
+ * https://github.com/Moderocky/ByteSkript/blob/master/LICENSE
+ */
+
+package org.byteskript.skript.api.note;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Documentation {
+
+    String name() default "";
+
+    String description() default "";
+
+    String[] examples() default {};
+
+}
diff --git a/src/main/java/org/byteskript/skript/api/syntax/ComplexExpression.java b/src/main/java/org/byteskript/skript/api/syntax/ComplexExpression.java
@@ -12,13 +12,24 @@
 import org.byteskript.skript.api.SyntaxElement;
 import org.byteskript.skript.compiler.CompileState;
 import org.byteskript.skript.compiler.Context;
+import org.byteskript.skript.compiler.Pattern;
+
+import java.lang.reflect.Method;
 
 public abstract class ComplexExpression extends Element implements SyntaxElement {
 
     public ComplexExpression(final Library provider, final LanguageElement type, final String... patterns) {
         super(provider, type, patterns);
     }
 
+    @Override
+    public void preCompile(Context context, Pattern.Match match) throws Throwable {
+        super.preCompile(context, match);
+        final Method target = handlers.get(context.getHandlerMode());
+        if (target == null) return;
+        this.prepareExpectedTypes(context, target);
+    }
+
     @Override
     public boolean allowedIn(State state, Context context) {
         return state == CompileState.STATEMENT && context.hasCurrentUnit();

diff --git a/src/main/java/org/byteskript/skript/api/syntax/Effect.java b/src/main/java/org/byteskript/skript/api/syntax/Effect.java
@@ -33,6 +33,9 @@ public CompileState getSubState() {
 
     @Override
     public void preCompile(Context context, Pattern.Match match) throws Throwable {
+        final Method target = handlers.get(StandardHandlers.RUN);
+        if (target == null) return;
+        this.prepareExpectedTypes(context, target);
     }
 
     @Override

diff --git a/src/main/java/org/byteskript/skript/api/syntax/Element.java b/src/main/java/org/byteskript/skript/api/syntax/Element.java
@@ -47,11 +47,6 @@ public LanguageElement getType() {
         return type;
     }
 
-    @Override
-    public String name() {
-        return pattern.name();
-    }
-
     @Override
     public boolean hasHandler(HandlerType type) {
         return handlers.containsKey(type) && handlers.get(type) != null;

diff --git a/src/main/java/org/byteskript/skript/api/syntax/EventValueExpression.java b/src/main/java/org/byteskript/skript/api/syntax/EventValueExpression.java
@@ -7,6 +7,8 @@
 package org.byteskript.skript.api.syntax;
 
 import mx.kenzie.foundation.MethodBuilder;
+import mx.kenzie.foundation.Type;
+import mx.kenzie.foundation.WriteInstruction;
 import mx.kenzie.foundation.compiler.State;
 import org.byteskript.skript.api.Library;
 import org.byteskript.skript.api.SyntaxElement;
@@ -35,6 +37,8 @@ public void compile(Context context, Pattern.Match match) throws Throwable {
         assert target.getReturnType() != void.class;
         this.writeCall(method, target, context);
         context.setState(CompileState.STATEMENT);
+        final Type type = context.getCompileCurrent().wanted;
+        if (type != null) method.writeCode(WriteInstruction.cast(type));
     }
 
     @Override

diff --git a/src/main/java/org/byteskript/skript/api/syntax/Literal.java b/src/main/java/org/byteskript/skript/api/syntax/Literal.java
@@ -7,6 +7,7 @@
 package org.byteskript.skript.api.syntax;
 
 import mx.kenzie.foundation.MethodBuilder;
+import mx.kenzie.foundation.WriteInstruction;
 import mx.kenzie.foundation.compiler.State;
 import org.byteskript.skript.api.LanguageElement;
 import org.byteskript.skript.api.Library;
@@ -32,6 +33,8 @@ public void compile(Context context, Pattern.Match match) throws Throwable {
         assert target != null;
         assert target.getReturnType() != void.class;
         this.writeCall(method, target, context);
+        final mx.kenzie.foundation.Type type = context.getCompileCurrent().wanted;
+        if (type != null) method.writeCode(WriteInstruction.cast(type));
     }
 
     public abstract Type parse(String input);

diff --git a/src/main/java/org/byteskript/skript/api/syntax/RelationalExpression.java b/src/main/java/org/byteskript/skript/api/syntax/RelationalExpression.java
@@ -7,6 +7,8 @@
 package org.byteskript.skript.api.syntax;
 
 import mx.kenzie.foundation.MethodBuilder;
+import mx.kenzie.foundation.Type;
+import mx.kenzie.foundation.WriteInstruction;
 import mx.kenzie.foundation.compiler.State;
 import org.byteskript.skript.api.LanguageElement;
 import org.byteskript.skript.api.Library;
@@ -26,11 +28,13 @@ public RelationalExpression(final Library provider, final LanguageElement type,
     @Override
     public void compile(Context context, Pattern.Match match) throws Throwable {
         final MethodBuilder method = context.getMethod();
-        assert method != null;
         final Method target = handlers.get(context.getHandlerMode());
-        assert target != null : "" + context.getHandlerMode();
+        assert target != null : "Missing target for: " + context.getHandlerMode();
         this.writeCall(method, target, context);
         context.setState(CompileState.STATEMENT);
+        if (!context.getHandlerMode().expectReturn()) return;
+        final Type type = context.getCompileCurrent().wanted;
+        if (type != null) method.writeCode(WriteInstruction.cast(type));
     }
 
     @Override

diff --git a/src/main/java/org/byteskript/skript/api/syntax/SimpleExpression.java b/src/main/java/org/byteskript/skript/api/syntax/SimpleExpression.java
@@ -8,6 +8,7 @@
 
 import mx.kenzie.foundation.MethodBuilder;
 import mx.kenzie.foundation.Type;
+import mx.kenzie.foundation.WriteInstruction;
 import mx.kenzie.foundation.compiler.State;
 import org.byteskript.skript.api.LanguageElement;
 import org.byteskript.skript.api.Library;
@@ -26,15 +27,24 @@ public SimpleExpression(final Library provider, final LanguageElement type, fina
         super(provider, type, patterns);
     }
 
+    @Override
+    public void preCompile(Context context, Pattern.Match match) throws Throwable {
+        super.preCompile(context, match);
+        final Method target = handlers.get(context.getHandlerMode());
+        if (target == null) return;
+        this.prepareExpectedTypes(context, target);
+    }
+
     @Override
     public void compile(Context context, Pattern.Match match) throws Throwable {
         final MethodBuilder method = context.getMethod();
         assert method != null;
         final Method target = handlers.get(StandardHandlers.GET);
         assert target != null;
-        assert target.getReturnType() != void.class;
         this.writeCall(method, target, context);
         context.setState(CompileState.STATEMENT);
+        final Type type = context.getCompileCurrent().wanted;
+        if (type != null) method.writeCode(WriteInstruction.cast(type));
     }
 
     @Override

diff --git a/src/main/java/org/byteskript/skript/compiler/ElementTree.java b/src/main/java/org/byteskript/skript/compiler/ElementTree.java
@@ -6,6 +6,7 @@
 
 package org.byteskript.skript.compiler;
 
+import mx.kenzie.foundation.Type;
 import org.byteskript.skript.api.HandlerType;
 import org.byteskript.skript.api.SyntaxElement;
 import org.byteskript.skript.api.syntax.Section;
@@ -21,6 +22,7 @@ public final class ElementTree {
     public boolean compile = true;
     public boolean treasure = false;
     public boolean takeAtomic = false;
+    public Type wanted = null;
     public HandlerType type = StandardHandlers.GET;
 
     public ElementTree(SyntaxElement current, Pattern.Match match, ElementTree... nested) {

diff --git a/src/main/java/org/byteskript/skript/compiler/SkriptLangSpec.java b/src/main/java/org/byteskript/skript/compiler/SkriptLangSpec.java
@@ -49,7 +49,6 @@
 import org.byteskript.skript.lang.syntax.list.IndexOfList;
 import org.byteskript.skript.lang.syntax.list.ListCreator;
 import org.byteskript.skript.lang.syntax.literal.*;
-import org.byteskript.skript.lang.syntax.map.ClearMap;
 import org.byteskript.skript.lang.syntax.map.KeyInMap;
 import org.byteskript.skript.lang.syntax.map.MapCreator;
 import org.byteskript.skript.lang.syntax.maths.*;
@@ -170,8 +169,7 @@ private SkriptLangSpec() {
             new BreakIfEffect(),
             new BreakEffect(),
             new TryEffect(),
-            new ClearList(),
-            new ClearMap()
+            new ClearList()
         );
         registerSyntax(CompileState.STATEMENT,
             new NoneLiteral(),

diff --git a/src/main/java/org/byteskript/skript/compiler/structure/Function.java b/src/main/java/org/byteskript/skript/compiler/structure/Function.java
@@ -31,7 +31,6 @@ public WriteInstruction invoke(String source) {
         final org.objectweb.asm.Type[] types = convert(parameters);
         final org.objectweb.asm.Type blob = org.objectweb.asm.Type.getType(void.class);
         return WriteInstruction.invokeDynamic(CommonTypes.OBJECT, name, arguments, Bootstrapper.getBootstrapFunction(), source, owner, org.objectweb.asm.Type.getMethodDescriptor(blob, types));
-//        return WriteInstruction.invokeStatic(provider, CommonTypes.OBJECT, name, types);
     }
 
     private org.objectweb.asm.Type convert(Type type) {

diff --git a/src/main/java/org/byteskript/skript/compiler/structure/PropertyAccessGenerator.java b/src/main/java/org/byteskript/skript/compiler/structure/PropertyAccessGenerator.java
@@ -93,15 +93,13 @@ public void compile(Context context) {
                 visitor.visitLdcInsn(name);
                 visitor.visitMethodInsn(184, "skript", "get_java_field", "(Ljava/lang/Object;Ljava/lang/Object;)Ljava/lang/Object;", false);
                 visitor.visitInsn(176); // areturn
-                return;
             });
             else if (this.type == StandardHandlers.SET) method.writeCode((writer, visitor) -> {
                 visitor.visitVarInsn(25, 0); // load holder
                 visitor.visitLdcInsn(name);
                 visitor.visitVarInsn(25, 1); // load value
-                visitor.visitMethodInsn(184, "skript", "set_java_field", "(Ljava/lang/Object;Ljava/lang/Object;Ljava/lang/Object;)Ljava/lang/Void;", false);
+                visitor.visitMethodInsn(184, "skript", "set_java_field", "(Ljava/lang/Object;Ljava/lang/Object;Ljava/lang/Object;)V", false);
                 visitor.visitInsn(177); // return top
-                return;
             });
         }
         if (this.type.expectReturn()) { // return null if requires result

diff --git a/src/main/java/org/byteskript/skript/lang/syntax/comparison/Contains.java b/src/main/java/org/byteskript/skript/lang/syntax/comparison/Contains.java
@@ -9,13 +9,27 @@
 import mx.kenzie.foundation.MethodBuilder;
 import mx.kenzie.foundation.Type;
 import mx.kenzie.foundation.WriteInstruction;
+import org.byteskript.skript.api.note.Documentation;
 import org.byteskript.skript.api.syntax.RelationalExpression;
 import org.byteskript.skript.compiler.*;
 import org.byteskript.skript.lang.element.StandardElements;
 import org.byteskript.skript.runtime.internal.OperatorHandler;
 
 import java.lang.reflect.Method;
 
+@Documentation(
+    name = "Contains",
+    description = """
+        Check whether the first object contains the second.
+        Applies to strings, lists and other collection types.""",
+    examples = {
+        "assert \"hello\" contains \"h\"",
+        """
+            if {list} contains 3:
+                print "hello"
+                """
+    }
+)
 public class Contains extends RelationalExpression {
 
     public Contains() {
@@ -46,21 +60,4 @@ public Type getReturnType() {
         return CommonTypes.BOOLEAN;
     }
 
-    @Override
-    public String description() {
-        return """
-            Check whether the first object contains the second.
-            Applies to strings, lists and other collection types.""";
-    }
-
-    @Override
-    public String[] examples() {
-        return new String[]{
-            "assert \"hello\" contains \"h\"",
-            """
-                if {list} contains 3:
-                    print "hello"
-                    """
-        };
-    }
 }