Skip to content

Commit f6e3fdf

Browse files
ModerockyModerocky
committed
Write documentation for like 900 things. :(
1 parent 1b17201 commit f6e3fdf

File tree

139 files changed

+1935
-333
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

139 files changed

+1935
-333
lines changed

‎pom.xml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66

77
<groupId>org.byteskript</groupId>
88
<artifactId>byteskript</artifactId>
9-
<version>1.0.7</version>
9+
<version>1.0.8</version>
1010
<name>ByteSkript</name>
1111

1212
<properties>

‎src/main/java/org/byteskript/skript/api/Document.java

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
/*
2+
* Copyright (c) 2022 ByteSkript org (Moderocky)
3+
* View the full licence information and permissions:
4+
* https://github.com/Moderocky/ByteSkript/blob/master/LICENSE
5+
*/
6+
7+
package org.byteskript.skript.api;
8+
9+
/**
10+
* A miniature record for holding documentation for a syntax element.
11+
*/
12+
public record Document(String name, String type, String[] patterns, String description, String[] examples) {
13+
}

‎src/main/java/org/byteskript/skript/api/Event.java

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
public abstract class Event {
1212

1313
public final void run(final Skript skript) {
14+
skript.runEvent(this);
1415
}
1516

1617
public boolean isAsync() {

‎src/main/java/org/byteskript/skript/api/Library.java

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,9 @@
1111
import mx.kenzie.foundation.language.PostCompileClass;
1212
import org.byteskript.skript.compiler.Context;
1313

14+
import java.util.ArrayList;
1415
import java.util.Collection;
16+
import java.util.List;
1517

1618
public interface Library {
1719

@@ -32,4 +34,12 @@ public interface Library {
3234
*/
3335
Collection<PostCompileClass> getRuntime();
3436

37+
default Document[] generateDocumentation() {
38+
final List<Document> documents = new ArrayList<>();
39+
for (final SyntaxElement syntax : this.getSyntax()) {
40+
documents.add(syntax.createDocument());
41+
}
42+
return documents.toArray(new Document[0]);
43+
}
44+
3545
}

‎src/main/java/org/byteskript/skript/api/SyntaxElement.java

Lines changed: 26 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88

99
import mx.kenzie.foundation.*;
1010
import mx.kenzie.foundation.compiler.State;
11+
import org.byteskript.skript.api.note.Documentation;
1112
import org.byteskript.skript.api.note.ForceBridge;
1213
import org.byteskript.skript.api.note.ForceExtract;
1314
import org.byteskript.skript.api.note.ForceInline;
@@ -43,14 +44,22 @@ default Type getReturnType() {
4344
return CommonTypes.VOID;
4445
}
4546

46-
String name();
47+
default String name() {
48+
final Documentation documentation = this.getClass().getAnnotation(Documentation.class);
49+
if (documentation == null) return getPattern().name();
50+
return documentation.name();
51+
}
4752

4853
default String description() {
49-
return null;
54+
final Documentation documentation = this.getClass().getAnnotation(Documentation.class);
55+
if (documentation == null) return "None.";
56+
return documentation.description();
5057
}
5158

5259
default String[] examples() {
53-
return null;
60+
final Documentation documentation = this.getClass().getAnnotation(Documentation.class);
61+
if (documentation == null) return new String[0];
62+
return documentation.examples();
5463
}
5564

5665
boolean hasHandler(HandlerType type);
@@ -63,6 +72,16 @@ default CompileState getSubState() {
6372
return CompileState.STATEMENT;
6473
}
6574

75+
default void prepareExpectedTypes(Context context, Method target) {
76+
if (target == null) return;
77+
final ElementTree[] inputs = context.getCompileCurrent().nested();
78+
if (inputs.length == 0) return;
79+
final Type[] types = Type.of(target.getParameterTypes());
80+
for (int i = 0; i < Math.min(types.length, inputs.length); i++) {
81+
inputs[i].wanted = types[i];
82+
}
83+
}
84+
6685
default boolean allowAsInputFor(Type type) {
6786
if (CommonTypes.REFERENT.equals(type) && hasHandler(StandardHandlers.SET)) return true;
6887
return type.equals(CommonTypes.OBJECT) || type.equals(getReturnType());
@@ -168,4 +187,8 @@ default String assemble(int line, String... inputs) throws ScriptReassemblyError
168187
throw new ScriptReassemblyError(line, "Not supported yet.");
169188
}
170189

190+
default Document createDocument() {
191+
return new Document(name(), getType().name(), getPatterns(), description(), examples());
192+
}
193+
171194
}

‎src/main/java/org/byteskript/skript/api/note/Documentation.java

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
/*
2+
* Copyright (c) 2022 ByteSkript org (Moderocky)
3+
* View the full licence information and permissions:
4+
* https://github.com/Moderocky/ByteSkript/blob/master/LICENSE
5+
*/
6+
7+
package org.byteskript.skript.api.note;
8+
9+
import java.lang.annotation.Retention;
10+
import java.lang.annotation.RetentionPolicy;
11+
12+
@Retention(RetentionPolicy.RUNTIME)
13+
public @interface Documentation {
14+
15+
String name() default "";
16+
17+
String description() default "";
18+
19+
String[] examples() default {};
20+
21+
}

‎src/main/java/org/byteskript/skript/api/syntax/ComplexExpression.java

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,13 +12,24 @@
1212
import org.byteskript.skript.api.SyntaxElement;
1313
import org.byteskript.skript.compiler.CompileState;
1414
import org.byteskript.skript.compiler.Context;
15+
import org.byteskript.skript.compiler.Pattern;
16+
17+
import java.lang.reflect.Method;
1518

1619
public abstract class ComplexExpression extends Element implements SyntaxElement {
1720

1821
public ComplexExpression(final Library provider, final LanguageElement type, final String... patterns) {
1922
super(provider, type, patterns);
2023
}
2124

25+
@Override
26+
public void preCompile(Context context, Pattern.Match match) throws Throwable {
27+
super.preCompile(context, match);
28+
final Method target = handlers.get(context.getHandlerMode());
29+
if (target == null) return;
30+
this.prepareExpectedTypes(context, target);
31+
}
32+
2233
@Override
2334
public boolean allowedIn(State state, Context context) {
2435
return state == CompileState.STATEMENT && context.hasCurrentUnit();

‎src/main/java/org/byteskript/skript/api/syntax/Effect.java

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,9 @@ public CompileState getSubState() {
3333

3434
@Override
3535
public void preCompile(Context context, Pattern.Match match) throws Throwable {
36+
final Method target = handlers.get(StandardHandlers.RUN);
37+
if (target == null) return;
38+
this.prepareExpectedTypes(context, target);
3639
}
3740

3841
@Override

‎src/main/java/org/byteskript/skript/api/syntax/Element.java

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -47,11 +47,6 @@ public LanguageElement getType() {
4747
return type;
4848
}
4949

50-
@Override
51-
public String name() {
52-
return pattern.name();
53-
}
54-
5550
@Override
5651
public boolean hasHandler(HandlerType type) {
5752
return handlers.containsKey(type) && handlers.get(type) != null;

‎src/main/java/org/byteskript/skript/api/syntax/EventValueExpression.java

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@
77
package org.byteskript.skript.api.syntax;
88

99
import mx.kenzie.foundation.MethodBuilder;
10+
import mx.kenzie.foundation.Type;
11+
import mx.kenzie.foundation.WriteInstruction;
1012
import mx.kenzie.foundation.compiler.State;
1113
import org.byteskript.skript.api.Library;
1214
import org.byteskript.skript.api.SyntaxElement;
@@ -35,6 +37,8 @@ public void compile(Context context, Pattern.Match match) throws Throwable {
3537
assert target.getReturnType() != void.class;
3638
this.writeCall(method, target, context);
3739
context.setState(CompileState.STATEMENT);
40+
final Type type = context.getCompileCurrent().wanted;
41+
if (type != null) method.writeCode(WriteInstruction.cast(type));
3842
}
3943

4044
@Override

‎src/main/java/org/byteskript/skript/api/syntax/Literal.java

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
package org.byteskript.skript.api.syntax;
88

99
import mx.kenzie.foundation.MethodBuilder;
10+
import mx.kenzie.foundation.WriteInstruction;
1011
import mx.kenzie.foundation.compiler.State;
1112
import org.byteskript.skript.api.LanguageElement;
1213
import org.byteskript.skript.api.Library;
@@ -32,6 +33,8 @@ public void compile(Context context, Pattern.Match match) throws Throwable {
3233
assert target != null;
3334
assert target.getReturnType() != void.class;
3435
this.writeCall(method, target, context);
36+
final mx.kenzie.foundation.Type type = context.getCompileCurrent().wanted;
37+
if (type != null) method.writeCode(WriteInstruction.cast(type));
3538
}
3639

3740
public abstract Type parse(String input);

‎src/main/java/org/byteskript/skript/api/syntax/RelationalExpression.java

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@
77
package org.byteskript.skript.api.syntax;
88

99
import mx.kenzie.foundation.MethodBuilder;
10+
import mx.kenzie.foundation.Type;
11+
import mx.kenzie.foundation.WriteInstruction;
1012
import mx.kenzie.foundation.compiler.State;
1113
import org.byteskript.skript.api.LanguageElement;
1214
import org.byteskript.skript.api.Library;
@@ -26,11 +28,13 @@ public RelationalExpression(final Library provider, final LanguageElement type,
2628
@Override
2729
public void compile(Context context, Pattern.Match match) throws Throwable {
2830
final MethodBuilder method = context.getMethod();
29-
assert method != null;
3031
final Method target = handlers.get(context.getHandlerMode());
31-
assert target != null : "" + context.getHandlerMode();
32+
assert target != null : "Missing target for: " + context.getHandlerMode();
3233
this.writeCall(method, target, context);
3334
context.setState(CompileState.STATEMENT);
35+
if (!context.getHandlerMode().expectReturn()) return;
36+
final Type type = context.getCompileCurrent().wanted;
37+
if (type != null) method.writeCode(WriteInstruction.cast(type));
3438
}
3539

3640
@Override

‎src/main/java/org/byteskript/skript/api/syntax/SimpleExpression.java

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88

99
import mx.kenzie.foundation.MethodBuilder;
1010
import mx.kenzie.foundation.Type;
11+
import mx.kenzie.foundation.WriteInstruction;
1112
import mx.kenzie.foundation.compiler.State;
1213
import org.byteskript.skript.api.LanguageElement;
1314
import org.byteskript.skript.api.Library;
@@ -26,15 +27,24 @@ public SimpleExpression(final Library provider, final LanguageElement type, fina
2627
super(provider, type, patterns);
2728
}
2829

30+
@Override
31+
public void preCompile(Context context, Pattern.Match match) throws Throwable {
32+
super.preCompile(context, match);
33+
final Method target = handlers.get(context.getHandlerMode());
34+
if (target == null) return;
35+
this.prepareExpectedTypes(context, target);
36+
}
37+
2938
@Override
3039
public void compile(Context context, Pattern.Match match) throws Throwable {
3140
final MethodBuilder method = context.getMethod();
3241
assert method != null;
3342
final Method target = handlers.get(StandardHandlers.GET);
3443
assert target != null;
35-
assert target.getReturnType() != void.class;
3644
this.writeCall(method, target, context);
3745
context.setState(CompileState.STATEMENT);
46+
final Type type = context.getCompileCurrent().wanted;
47+
if (type != null) method.writeCode(WriteInstruction.cast(type));
3848
}
3949

4050
@Override

‎src/main/java/org/byteskript/skript/compiler/ElementTree.java

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66

77
package org.byteskript.skript.compiler;
88

9+
import mx.kenzie.foundation.Type;
910
import org.byteskript.skript.api.HandlerType;
1011
import org.byteskript.skript.api.SyntaxElement;
1112
import org.byteskript.skript.api.syntax.Section;
@@ -21,6 +22,7 @@ public final class ElementTree {
2122
public boolean compile = true;
2223
public boolean treasure = false;
2324
public boolean takeAtomic = false;
25+
public Type wanted = null;
2426
public HandlerType type = StandardHandlers.GET;
2527

2628
public ElementTree(SyntaxElement current, Pattern.Match match, ElementTree... nested) {

‎src/main/java/org/byteskript/skript/compiler/SkriptLangSpec.java

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,6 @@
4949
import org.byteskript.skript.lang.syntax.list.IndexOfList;
5050
import org.byteskript.skript.lang.syntax.list.ListCreator;
5151
import org.byteskript.skript.lang.syntax.literal.*;
52-
import org.byteskript.skript.lang.syntax.map.ClearMap;
5352
import org.byteskript.skript.lang.syntax.map.KeyInMap;
5453
import org.byteskript.skript.lang.syntax.map.MapCreator;
5554
import org.byteskript.skript.lang.syntax.maths.*;
@@ -170,8 +169,7 @@ private SkriptLangSpec() {
170169
new BreakIfEffect(),
171170
new BreakEffect(),
172171
new TryEffect(),
173-
new ClearList(),
174-
new ClearMap()
172+
new ClearList()
175173
);
176174
registerSyntax(CompileState.STATEMENT,
177175
new NoneLiteral(),

‎src/main/java/org/byteskript/skript/compiler/structure/Function.java

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,6 @@ public WriteInstruction invoke(String source) {
3131
final org.objectweb.asm.Type[] types = convert(parameters);
3232
final org.objectweb.asm.Type blob = org.objectweb.asm.Type.getType(void.class);
3333
return WriteInstruction.invokeDynamic(CommonTypes.OBJECT, name, arguments, Bootstrapper.getBootstrapFunction(), source, owner, org.objectweb.asm.Type.getMethodDescriptor(blob, types));
34-
// return WriteInstruction.invokeStatic(provider, CommonTypes.OBJECT, name, types);
3534
}
3635

3736
private org.objectweb.asm.Type convert(Type type) {

‎src/main/java/org/byteskript/skript/compiler/structure/PropertyAccessGenerator.java

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -93,15 +93,13 @@ public void compile(Context context) {
9393
visitor.visitLdcInsn(name);
9494
visitor.visitMethodInsn(184, "skript", "get_java_field", "(Ljava/lang/Object;Ljava/lang/Object;)Ljava/lang/Object;", false);
9595
visitor.visitInsn(176); // areturn
96-
return;
9796
});
9897
else if (this.type == StandardHandlers.SET) method.writeCode((writer, visitor) -> {
9998
visitor.visitVarInsn(25, 0); // load holder
10099
visitor.visitLdcInsn(name);
101100
visitor.visitVarInsn(25, 1); // load value
102-
visitor.visitMethodInsn(184, "skript", "set_java_field", "(Ljava/lang/Object;Ljava/lang/Object;Ljava/lang/Object;)Ljava/lang/Void;", false);
101+
visitor.visitMethodInsn(184, "skript", "set_java_field", "(Ljava/lang/Object;Ljava/lang/Object;Ljava/lang/Object;)V", false);
103102
visitor.visitInsn(177); // return top
104-
return;
105103
});
106104
}
107105
if (this.type.expectReturn()) { // return null if requires result

‎src/main/java/org/byteskript/skript/lang/syntax/comparison/Contains.java

Lines changed: 14 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -9,13 +9,27 @@
99
import mx.kenzie.foundation.MethodBuilder;
1010
import mx.kenzie.foundation.Type;
1111
import mx.kenzie.foundation.WriteInstruction;
12+
import org.byteskript.skript.api.note.Documentation;
1213
import org.byteskript.skript.api.syntax.RelationalExpression;
1314
import org.byteskript.skript.compiler.*;
1415
import org.byteskript.skript.lang.element.StandardElements;
1516
import org.byteskript.skript.runtime.internal.OperatorHandler;
1617

1718
import java.lang.reflect.Method;
1819

20+
@Documentation(
21+
name = "Contains",
22+
description = """
23+
Check whether the first object contains the second.
24+
Applies to strings, lists and other collection types.""",
25+
examples = {
26+
"assert \"hello\" contains \"h\"",
27+
"""
28+
if {list} contains 3:
29+
print "hello"
30+
"""
31+
}
32+
)
1933
public class Contains extends RelationalExpression {
2034

2135
public Contains() {
@@ -46,21 +60,4 @@ public Type getReturnType() {
4660
return CommonTypes.BOOLEAN;
4761
}
4862

49-
@Override
50-
public String description() {
51-
return """
52-
Check whether the first object contains the second.
53-
Applies to strings, lists and other collection types.""";
54-
}
55-
56-
@Override
57-
public String[] examples() {
58-
return new String[]{
59-
"assert \"hello\" contains \"h\"",
60-
"""
61-
if {list} contains 3:
62-
print "hello"
63-
"""
64-
};
65-
}
6663
}

0 commit comments

Comments
 (0)