From b9990cbbad663a1b38d9b0d24a73af9ebf0de160 Mon Sep 17 00:00:00 2001 From: dzikoysk Date: Fri, 1 Nov 2019 18:11:16 +0100 Subject: [PATCH] GH-392 Make executable special type of statement, document and simplify classes related to the runtime --- .../panda_lang/framework/design/Failure.java | 12 +++++- .../architecture/dynamic/ControlledScope.java | 11 +++++ .../architecture/dynamic/Controller.java | 10 ++++- .../architecture/dynamic/Executable.java | 6 ++- .../design/architecture/dynamic/Frame.java | 10 ++++- .../prototype/ReferenceFetchException.java | 4 -- .../design/runtime/MemoryContainer.java | 11 +++-- .../framework/design/runtime/Process.java | 5 ++- .../design/runtime/ProcessStack.java | 41 +++++++++++++++++++ .../framework/design/runtime/Result.java | 16 ++++++++ .../framework/design/runtime/Status.java | 15 +++++++ .../dynamic/AbstractExecutableStatement.java | 3 +- .../architecture/dynamic/AbstractFrame.java | 6 +-- .../language/runtime/PandaProcess.java | 2 +- .../language/runtime/PandaProcessStack.java | 6 +-- ...stants.java => PandaRuntimeConstants.java} | 8 +++- .../runtime/PandaRuntimeException.java | 7 ---- .../architecture/PandaApplication.java | 11 ++--- .../parser/scope/branching/Break.java | 2 +- .../parser/scope/branching/Continue.java | 2 +- .../parser/scope/branching/Return.java | 2 +- .../parser/scope/branching/Throw.java | 2 +- .../org/panda_lang/panda/shell/repl/Repl.java | 6 +-- .../panda/shell/repl/ReplFrame.java | 4 +- 24 files changed, 154 insertions(+), 48 deletions(-) rename panda-framework/src/main/java/org/panda_lang/framework/language/runtime/{PandaProcessStackConstants.java => PandaRuntimeConstants.java} (84%) diff --git a/panda-framework/src/main/java/org/panda_lang/framework/design/Failure.java b/panda-framework/src/main/java/org/panda_lang/framework/design/Failure.java index 6611cf8dd..1e84bc427 100644 --- a/panda-framework/src/main/java/org/panda_lang/framework/design/Failure.java +++ b/panda-framework/src/main/java/org/panda_lang/framework/design/Failure.java @@ -16,8 +16,18 @@ package org.panda_lang.framework.design; +import org.jetbrains.annotations.Nullable; + +/** + * Represents errors occurred in the framework + */ public interface Failure { - String getNote(); + /** + * Get additional information about the failure + * + * @return the note + */ + @Nullable String getNote(); } diff --git a/panda-framework/src/main/java/org/panda_lang/framework/design/architecture/dynamic/ControlledScope.java b/panda-framework/src/main/java/org/panda_lang/framework/design/architecture/dynamic/ControlledScope.java index 998559852..751d429e3 100644 --- a/panda-framework/src/main/java/org/panda_lang/framework/design/architecture/dynamic/ControlledScope.java +++ b/panda-framework/src/main/java/org/panda_lang/framework/design/architecture/dynamic/ControlledScope.java @@ -21,8 +21,19 @@ import org.panda_lang.framework.design.runtime.ProcessStack; import org.panda_lang.framework.design.runtime.Result; +/** + * Scope that takes over control on the returned by process stack {@link org.panda_lang.framework.design.runtime.Result} + */ public interface ControlledScope extends Scope { + /** + * Custom call called by the process + * + * @param stack the current stack + * @param instance the current instance + * @return result of invocation + * @throws Exception if something happen + */ @Nullable Result controlledCall(ProcessStack stack, Object instance) throws Exception; } diff --git a/panda-framework/src/main/java/org/panda_lang/framework/design/architecture/dynamic/Controller.java b/panda-framework/src/main/java/org/panda_lang/framework/design/architecture/dynamic/Controller.java index 6e533fb33..db66aa755 100644 --- a/panda-framework/src/main/java/org/panda_lang/framework/design/architecture/dynamic/Controller.java +++ b/panda-framework/src/main/java/org/panda_lang/framework/design/architecture/dynamic/Controller.java @@ -16,8 +16,16 @@ package org.panda_lang.framework.design.architecture.dynamic; +/** + * Specific type of statement that contains status code considered by the process of execution + */ public interface Controller extends Executable { - byte getStatus(); + /** + * Get represented status code + * + * @return the status code + */ + byte getStatusCode(); } diff --git a/panda-framework/src/main/java/org/panda_lang/framework/design/architecture/dynamic/Executable.java b/panda-framework/src/main/java/org/panda_lang/framework/design/architecture/dynamic/Executable.java index 2c1c78286..1d6eeed6a 100644 --- a/panda-framework/src/main/java/org/panda_lang/framework/design/architecture/dynamic/Executable.java +++ b/panda-framework/src/main/java/org/panda_lang/framework/design/architecture/dynamic/Executable.java @@ -17,9 +17,13 @@ package org.panda_lang.framework.design.architecture.dynamic; import org.jetbrains.annotations.Nullable; +import org.panda_lang.framework.design.architecture.statement.Statement; import org.panda_lang.framework.design.runtime.ProcessStack; -public interface Executable { +/** + * Executable type of statement + */ +public interface Executable extends Statement { /** * Execute the statement diff --git a/panda-framework/src/main/java/org/panda_lang/framework/design/architecture/dynamic/Frame.java b/panda-framework/src/main/java/org/panda_lang/framework/design/architecture/dynamic/Frame.java index 9a4795c11..bafa83d9f 100644 --- a/panda-framework/src/main/java/org/panda_lang/framework/design/architecture/dynamic/Frame.java +++ b/panda-framework/src/main/java/org/panda_lang/framework/design/architecture/dynamic/Frame.java @@ -19,11 +19,17 @@ import org.panda_lang.framework.design.architecture.statement.FramedScope; import org.panda_lang.framework.design.runtime.MemoryContainer; +/** + * Specific type of memory container, associated with the {@link org.panda_lang.framework.design.architecture.statement.FramedScope}. + * + */ public interface Frame extends MemoryContainer { /** - * @return the proper scope + * Get associated scope with the frame + * + * @return the frame scope */ - FramedScope getScope(); + FramedScope getFramedScope(); } diff --git a/panda-framework/src/main/java/org/panda_lang/framework/design/architecture/prototype/ReferenceFetchException.java b/panda-framework/src/main/java/org/panda_lang/framework/design/architecture/prototype/ReferenceFetchException.java index 5114472d2..191adeb64 100644 --- a/panda-framework/src/main/java/org/panda_lang/framework/design/architecture/prototype/ReferenceFetchException.java +++ b/panda-framework/src/main/java/org/panda_lang/framework/design/architecture/prototype/ReferenceFetchException.java @@ -28,8 +28,4 @@ public ReferenceFetchException(String message) { super(message); } - public ReferenceFetchException(Throwable cause) { - super(cause); - } - } diff --git a/panda-framework/src/main/java/org/panda_lang/framework/design/runtime/MemoryContainer.java b/panda-framework/src/main/java/org/panda_lang/framework/design/runtime/MemoryContainer.java index 2f4075768..ba883e866 100644 --- a/panda-framework/src/main/java/org/panda_lang/framework/design/runtime/MemoryContainer.java +++ b/panda-framework/src/main/java/org/panda_lang/framework/design/runtime/MemoryContainer.java @@ -18,6 +18,9 @@ import org.jetbrains.annotations.Nullable; +/** + * Represents segment of memory + */ public interface MemoryContainer { /** @@ -29,14 +32,16 @@ public interface MemoryContainer { @Nullable T set(int pointer, @Nullable T value); /** + * Get value at the given position + * * @param pointer index of variable in current scope - * @return value + * @return the value at the given position */ @Nullable T get(int pointer); /** - * @return array length + * @return the size of memory */ - int getAmountOfVariables(); + int getMemorySize(); } diff --git a/panda-framework/src/main/java/org/panda_lang/framework/design/runtime/Process.java b/panda-framework/src/main/java/org/panda_lang/framework/design/runtime/Process.java index cf262749d..538d416e6 100644 --- a/panda-framework/src/main/java/org/panda_lang/framework/design/runtime/Process.java +++ b/panda-framework/src/main/java/org/panda_lang/framework/design/runtime/Process.java @@ -16,10 +16,13 @@ package org.panda_lang.framework.design.runtime; +/** + * Instance of application + */ public interface Process { /** - * Execute the process + * Launch the process * * @return a result of the execution process */ diff --git a/panda-framework/src/main/java/org/panda_lang/framework/design/runtime/ProcessStack.java b/panda-framework/src/main/java/org/panda_lang/framework/design/runtime/ProcessStack.java index 34ab4dbaf..6f7c08b29 100644 --- a/panda-framework/src/main/java/org/panda_lang/framework/design/runtime/ProcessStack.java +++ b/panda-framework/src/main/java/org/panda_lang/framework/design/runtime/ProcessStack.java @@ -22,16 +22,57 @@ import org.panda_lang.framework.design.architecture.statement.Statement; import org.panda_lang.utilities.commons.function.ThrowingSupplier; +/** + * Stack stores information about the active subroutines of a process + */ public interface ProcessStack { + /** + * Call frame within the given instance + * + * @param instance the instance under which the frame has to be performed + * @param frame the frame to call + * @return result of invocation + * @throws Exception if something happen + */ @Nullable Result call(Object instance, Frame frame) throws Exception; + /** + * Call frame within the given instance and return custom result + * + * @param instance the instance within the frame has to be performed + * @param frame the frame to call + * @param resultSupplier the supplier of result + * @return result of invocation + * @throws Exception if something happen + */ @Nullable Result call(Object instance, Frame frame, ThrowingSupplier, Exception> resultSupplier) throws Exception; + /** + * Call scope within the given instance + * + * @param instance the instance within the frame has to performed + * @param scope the scope to call + * @return result of invocation + * @throws Exception if something happen + */ @Nullable Result call(Object instance, Scope scope) throws Exception; + /** + * Call statement within the given instance + * + * @param instance the instance within the statement + * @param statement the statement to call + * @return result of invocation + * @throws Exception if something happen + */ @Nullable Result call(Object instance, Statement statement) throws Exception; + /** + * Get statements on stack + * + * @return the array of statements on stack + */ Statement[] getLivingFramesOnStack(); /** diff --git a/panda-framework/src/main/java/org/panda_lang/framework/design/runtime/Result.java b/panda-framework/src/main/java/org/panda_lang/framework/design/runtime/Result.java index 0a4155ee9..71fda7f51 100644 --- a/panda-framework/src/main/java/org/panda_lang/framework/design/runtime/Result.java +++ b/panda-framework/src/main/java/org/panda_lang/framework/design/runtime/Result.java @@ -18,6 +18,11 @@ import org.jetbrains.annotations.Nullable; +/** + * Result of invocation with status code + * + * @param generic type of result + */ public class Result { private final byte status; @@ -28,10 +33,21 @@ public Result(byte status, T result) { this.result = result; } + /** + * Get result value + * + * @return the value + */ public @Nullable T getResult() { return result; } + /** + * Get status code + * + * @return the status code + * @see org.panda_lang.framework.design.runtime.Status + */ public byte getStatus() { return status; } diff --git a/panda-framework/src/main/java/org/panda_lang/framework/design/runtime/Status.java b/panda-framework/src/main/java/org/panda_lang/framework/design/runtime/Status.java index fa286fa1b..2e490351c 100644 --- a/panda-framework/src/main/java/org/panda_lang/framework/design/runtime/Status.java +++ b/panda-framework/src/main/java/org/panda_lang/framework/design/runtime/Status.java @@ -16,14 +16,29 @@ package org.panda_lang.framework.design.runtime; +/** + * Default status codes + */ public final class Status { + /** + * Represents thrown value + */ public static final byte THROW = 0x00; + /** + * Represents returned value + */ public static final byte RETURN = 0x01; + /** + * Represents break of scope on stack + */ public static final byte BREAK = 0x02; + /** + * Represents omission of the rest of current scope on stack + */ public static final byte CONTINUE = 0x03; } diff --git a/panda-framework/src/main/java/org/panda_lang/framework/language/architecture/dynamic/AbstractExecutableStatement.java b/panda-framework/src/main/java/org/panda_lang/framework/language/architecture/dynamic/AbstractExecutableStatement.java index a6887f9bc..0eaf18ff9 100644 --- a/panda-framework/src/main/java/org/panda_lang/framework/language/architecture/dynamic/AbstractExecutableStatement.java +++ b/panda-framework/src/main/java/org/panda_lang/framework/language/architecture/dynamic/AbstractExecutableStatement.java @@ -17,11 +17,10 @@ package org.panda_lang.framework.language.architecture.dynamic; import org.panda_lang.framework.design.architecture.dynamic.Executable; -import org.panda_lang.framework.design.architecture.statement.Statement; import org.panda_lang.framework.design.interpreter.source.SourceLocation; import org.panda_lang.framework.language.architecture.statement.AbstractStatement; -public abstract class AbstractExecutableStatement extends AbstractStatement implements Executable, Statement { +public abstract class AbstractExecutableStatement extends AbstractStatement implements Executable { protected AbstractExecutableStatement(SourceLocation location) { super(location); diff --git a/panda-framework/src/main/java/org/panda_lang/framework/language/architecture/dynamic/AbstractFrame.java b/panda-framework/src/main/java/org/panda_lang/framework/language/architecture/dynamic/AbstractFrame.java index cfe6d686a..50d2bbf8d 100644 --- a/panda-framework/src/main/java/org/panda_lang/framework/language/architecture/dynamic/AbstractFrame.java +++ b/panda-framework/src/main/java/org/panda_lang/framework/language/architecture/dynamic/AbstractFrame.java @@ -37,7 +37,7 @@ protected AbstractFrame(T frame) { private void checkIndex(int index) { if (index < 0 || index >= localMemory.length) { - throw new PandaRuntimeException("Invalid variable index: " + index + "; Amount of localMemory: " + getAmountOfVariables()); + throw new PandaRuntimeException("Invalid variable index: " + index + "; Amount of localMemory: " + getMemorySize()); } } @@ -56,12 +56,12 @@ public synchronized R set(int pointer, @Nullable R value) { } @Override - public int getAmountOfVariables() { + public int getMemorySize() { return localMemory.length; } @Override - public T getScope() { + public T getFramedScope() { return frame; } diff --git a/panda-framework/src/main/java/org/panda_lang/framework/language/runtime/PandaProcess.java b/panda-framework/src/main/java/org/panda_lang/framework/language/runtime/PandaProcess.java index 36e29a18c..074070e1b 100644 --- a/panda-framework/src/main/java/org/panda_lang/framework/language/runtime/PandaProcess.java +++ b/panda-framework/src/main/java/org/panda_lang/framework/language/runtime/PandaProcess.java @@ -39,7 +39,7 @@ public PandaProcess(Application application, FramedScope mainScope, String... pa @Override @SuppressWarnings("unchecked") public @Nullable Object execute() { - ProcessStack stack = new PandaProcessStack(this, PandaProcessStackConstants.DEFAULT_STACK_SIZE); + ProcessStack stack = new PandaProcessStack(this, PandaRuntimeConstants.DEFAULT_STACK_SIZE); try { Frame instance = mainScope.revive(null, null); diff --git a/panda-framework/src/main/java/org/panda_lang/framework/language/runtime/PandaProcessStack.java b/panda-framework/src/main/java/org/panda_lang/framework/language/runtime/PandaProcessStack.java index 400d82559..58e5de5e1 100644 --- a/panda-framework/src/main/java/org/panda_lang/framework/language/runtime/PandaProcessStack.java +++ b/panda-framework/src/main/java/org/panda_lang/framework/language/runtime/PandaProcessStack.java @@ -31,8 +31,6 @@ import org.panda_lang.utilities.commons.collection.IStack; import org.panda_lang.utilities.commons.function.ThrowingSupplier; -import java.util.function.Supplier; - public class PandaProcessStack implements ProcessStack { private final Process process; @@ -46,7 +44,7 @@ public PandaProcessStack(Process process, int stackCapacity) { @Override public @Nullable Result call(Object instance, Frame frame) throws Exception { - return call(instance, frame, () -> call(frame, frame.getScope())); + return call(instance, frame, () -> call(frame, frame.getFramedScope())); } @Override @@ -85,7 +83,7 @@ public PandaProcessStack(Process process, int stackCapacity) { if (statement instanceof Executable) { if (statement instanceof Controller) { Controller controller = (Controller) statement; - return new Result<>(controller.getStatus(), controller.execute(this, instance)); + return new Result<>(controller.getStatusCode(), controller.execute(this, instance)); } ((Executable) statement).execute(this, instance); diff --git a/panda-framework/src/main/java/org/panda_lang/framework/language/runtime/PandaProcessStackConstants.java b/panda-framework/src/main/java/org/panda_lang/framework/language/runtime/PandaRuntimeConstants.java similarity index 84% rename from panda-framework/src/main/java/org/panda_lang/framework/language/runtime/PandaProcessStackConstants.java rename to panda-framework/src/main/java/org/panda_lang/framework/language/runtime/PandaRuntimeConstants.java index a67f29a92..7f3e44a81 100644 --- a/panda-framework/src/main/java/org/panda_lang/framework/language/runtime/PandaProcessStackConstants.java +++ b/panda-framework/src/main/java/org/panda_lang/framework/language/runtime/PandaRuntimeConstants.java @@ -16,8 +16,14 @@ package org.panda_lang.framework.language.runtime; -public final class PandaProcessStackConstants { +/** + * Constants related to the runtime + */ +public final class PandaRuntimeConstants { + /** + * Default size of stack + */ public static final int DEFAULT_STACK_SIZE = 1024; } diff --git a/panda-framework/src/main/java/org/panda_lang/framework/language/runtime/PandaRuntimeException.java b/panda-framework/src/main/java/org/panda_lang/framework/language/runtime/PandaRuntimeException.java index 8d767db83..d3a0174e8 100644 --- a/panda-framework/src/main/java/org/panda_lang/framework/language/runtime/PandaRuntimeException.java +++ b/panda-framework/src/main/java/org/panda_lang/framework/language/runtime/PandaRuntimeException.java @@ -20,9 +20,6 @@ public class PandaRuntimeException extends PandaFrameworkException { - public PandaRuntimeException() { - } - public PandaRuntimeException(String message) { super(message); } @@ -31,8 +28,4 @@ public PandaRuntimeException(String message, Throwable cause) { super(message, cause); } - public PandaRuntimeException(Throwable cause) { - super(cause); - } - } diff --git a/panda/src/main/java/org/panda_lang/panda/language/architecture/PandaApplication.java b/panda/src/main/java/org/panda_lang/panda/language/architecture/PandaApplication.java index 50ad738f7..efbc53e74 100644 --- a/panda/src/main/java/org/panda_lang/panda/language/architecture/PandaApplication.java +++ b/panda/src/main/java/org/panda_lang/panda/language/architecture/PandaApplication.java @@ -33,7 +33,6 @@ public class PandaApplication implements Application { private final Environment environment; private final List