From e3cf4a72565c47086756debcc45b085cdff89388 Mon Sep 17 00:00:00 2001 From: jrte Date: Sun, 17 Sep 2023 12:07:48 -0300 Subject: [PATCH] Javadoc edits to fix errors and warnings + drop BaseParameterizedEffector.getParameters + relocate BaseParameterizedEffector.showParameterType* Signed-off-by: jrte --- .../jrte/engine/Transductor.java | 2 +- .../ribose/IParameterizedEffector.java | 48 +++++++------- .../base/BaseParameterizedEffector.java | 62 ++++++++++--------- 3 files changed, 61 insertions(+), 51 deletions(-) diff --git a/src/com/characterforming/jrte/engine/Transductor.java b/src/com/characterforming/jrte/engine/Transductor.java index 2a7dbdb..a5454e4 100644 --- a/src/com/characterforming/jrte/engine/Transductor.java +++ b/src/com/characterforming/jrte/engine/Transductor.java @@ -846,7 +846,7 @@ public Integer[] allocateParameters(int parameterCount) { return new Integer[parameterCount]; } - @Override + @Override public Integer compileParameter(final IToken[] parameterList) throws TargetBindingException { if (parameterList.length != 1) { throw new TargetBindingException("The signal effector accepts at most one parameter"); diff --git a/src/com/characterforming/ribose/IParameterizedEffector.java b/src/com/characterforming/ribose/IParameterizedEffector.java index f280f7c..1d60949 100644 --- a/src/com/characterforming/ribose/IParameterizedEffector.java +++ b/src/com/characterforming/ribose/IParameterizedEffector.java @@ -27,19 +27,23 @@ /** * Interface for parameterized effectors extends {@link IEffector} with a monadic - * {@link #invoke(int)} method. In ribose transducer patterns parameters are - * represented as lists of one or more backquoted tokens, eg {@code out[`~field` `,`]}. - * In ginr automata and ribose transducers ginr tokens are represented as arrays - * of raw bytes which may contain text, which ginr encodes as UTF-8 bytes, binary - * data encoded using hexadecimal {@code \xHH} representation for unprintable - * bytes, or field (`~field`), transducer (`@transducer`) or signal (`!signal`) - * references. + * {@link #invoke(int p)} method that produces an effect using a P instance + * selected from an array of immutable parameter objects. Each parameterized effector + * is thus an indexed collection of {@link IEffector}. The array is populated with + * P instances compiled from lists of tokens bound to parameterized effector + * references in the ribose model. In ribose transducer patterns parameters are + * represented as lists of one or more backquoted tokens, eg {@code + * out[`~field` `,`]}. In ginr compiled FSTs and in ribose transducers these + * tokens are represented as arrays of raw bytes which may contain UTF-8 encoded + * text, binary data encoded using hexadecimal {@code \xHH} representation for + * unprintable bytes, or field (`~field`), transducer (`@transducer`) or + * signal (`!signal`) references. *

* Proxy parameterized effectors compile parameters from arrays of {@link * IToken} when a model is compiled and when it is loaded for runtime use. Each * token array is compiled to an immutable instance of the effector's parameter * type P, which must be constructible from {@code IToken[]}. The model - * will call {@link #allocateParameters(int)} to obtain an array P[] of + * will call {@link #allocateParameters(int)} to obtain an array P[] of * parameter instances and {@link #compileParameter(IToken[])} for each parameter * to populate the array. When parameter compilation is complete the proxy effector * is passivated with a call to {@link #passivate()} and its raw tokens and compiled @@ -47,9 +51,7 @@ * and {@link #invoke(int)} methods are never called for proxy effectors. Proxy * effectors receive calls to {@link #showParameterTokens(int)} and {@link * #showParameterType()} from the model decompiler; these methods are implemented - * in {@link BaseParameterizedEFfector} but may be overriden by subclasses. - *

- * + * in {@link BaseParameterizedEffector} but may be overriden by subclasses. *

* For example: * 
@@ -69,15 +71,16 @@
  *     return RTX_NONE;
  *   }
  * }
- * Live parameterized effectors populate an array P[] of precompiled - * parameters from their proxies via {@link #setParameters(Object)} when the model is - * loaded into the runtime. Live effectors are not otherwise involved in parameter - * compilation or decompilation and are never passivated. They reference their - * parameters by array index in their {@link #invoke(int)} methods, which return an - * {@code IEffector RTX} code as for {@link IEffector#invoke()}. Effectors normally - * return {@code IEffector.RTX_NONE}, indicating no special condition, but may also - * encode a {@link Signal} in the returned RTX code. See the javadoc comments for - * {@link IEffector} for more information regarding effector {@code RTX} codes. + * Live parameterized effectors receive a reference to the parameters + * P[] precompiled by the respective proxy effector via {@link + * BaseParameterizedEffector#setParameters(IParameterizedEffector)} when the + * model is loaded into the runtime. Live effectors are not otherwise involved + * in parameter compilation or decompilation and are never passivated. They + * select their parameters by array index in their {@link #invoke(int p)} + * methods, which normally return {@link IEffector#RTX_NONE} to indicate + * no special condition. They may also return a {@link Signal} encoded by + * {@link IEffector#rtxSignal(int)}. See the javadoc comments for {@link + * IEffector} for more information regarding effector {@code RTX} codes. *

* All {@code IParameterizedEffector} implementations must be subclasses of * {@link BaseParameterizedEffector}, which implements the parameter compilation @@ -90,10 +93,11 @@ * @author Kim Briggs * @param the effector target type * @param

the effector parameter type, constructible from byte[][] (eg new P(byte[][])) + * @see BaseParameterizedEffector */ public interface IParameterizedEffector extends IEffector { /** - * Parameterized effector invocation receives the index of the {@code P} + * Parameterized effector invocation receives the index of the P * instance to apply for the invocation. * * @param parameterIndex the index of the parameter object to be applied @@ -103,7 +107,7 @@ public interface IParameterizedEffector extends IEffector< int invoke(int parameterIndex) throws EffectorException; /** - * Allocate an array (P[]) to hold precompiled parameter objects + * Allocate an array (P[]) to hold precompiled parameter objects * * @param parameterCount the size of parameter array to allocate * @return the allocated array diff --git a/src/com/characterforming/ribose/base/BaseParameterizedEffector.java b/src/com/characterforming/ribose/base/BaseParameterizedEffector.java index deab076..3c56d88 100644 --- a/src/com/characterforming/ribose/base/BaseParameterizedEffector.java +++ b/src/com/characterforming/ribose/base/BaseParameterizedEffector.java @@ -20,8 +20,6 @@ package com.characterforming.ribose.base; -import java.lang.reflect.ParameterizedType; -import java.lang.reflect.Type; import java.util.List; import com.characterforming.ribose.IParameterizedEffector; @@ -30,17 +28,24 @@ /** * Base {@link IParameterizedEffector} implementation class extends {@link BaseEffector} - * to support specialized effectors. All {@code IParameterizedEffector} implementation classes - * must extend {@code BaseParameterizedEffector}. Subclasses must implement - * {@link IParameterizedEffector#invoke()}, {@link IParameterizedEffector#invoke(int)}, - * {@link IParameterizedEffector#allocateParameters(int)}, {@link IParameterizedEffector#compileParameter(IToken[])} - * and {@link IParameterizedEffector#showParameterType()} methods and may override - * {@link IParameterizedEffector#showParameterTokens(int)} if required. + * to support specialized effectors. All {@link IParameterizedEffector} implementations + * must extend {@link BaseParameterizedEffector} and must implement: + *

    + *
  • {@link IParameterizedEffector#invoke()}
    • + *
  • {@link IParameterizedEffector#invoke(int)}
    • + *
  • {@link IParameterizedEffector#allocateParameters(int)}
    • + *
  • {@link IParameterizedEffector#compileParameter(IToken[])}
    • + *
+ * Default {@link showParameterType()} and {@link showParameterTokens(int)} methods are + * implemented here but subclasses may override these if desired. Otherwise, + * public methods not exposed in the {@link IParameterizedEffector} interface are for + * internal use only. These methods implement the parameter compilation and binding + * protocols for all parameterized effector implementations. * * @param the effector target type * @param

the effector parameter type, constructible from IToken[] (eg new P(IToken[])) * @author Kim Briggs - * @see com.characterforming.ribose.IParameterizedEffector + * @see IParameterizedEffector */ public abstract class BaseParameterizedEffector extends BaseEffector implements IParameterizedEffector { @@ -67,15 +72,32 @@ protected BaseParameterizedEffector(final T target, final String name) { @Override // @see com.characterforming.ribose.base.IParameterizedEffector#compileParameter(IToken[]) public abstract P compileParameter(IToken[] parameterTokens) throws TargetBindingException; - public final P[] getParameters() { - return this.parameters; + @Override + public String showParameterType() { + return this.parameters != null && this.parameters.length > 0 + ? this.parameters[0].getClass().getSimpleName() + : "void"; } + @Override + public String showParameterTokens(int parameterIndex) { + StringBuilder sb = new StringBuilder(256); + for (IToken token : this.tokens[parameterIndex]) { + sb.append(sb.length() == 0 ? "`" : " `").append(token.toString()).append("`"); + } + return sb.toString(); + } + + /** + * Get the parameters array from proxy effector + * + * @param proxyEffector the proxy effector + */ @SuppressWarnings("unchecked") public final void setParameters(IParameterizedEffector proxyEffector) { assert proxyEffector instanceof BaseParameterizedEffector; if (proxyEffector instanceof BaseParameterizedEffector proxy) { - this.parameters = (P[])proxy.getParameters(); + this.parameters = (P[])proxy.parameters; } } @@ -127,20 +149,4 @@ public final boolean compileParameters(IToken[][] parameterTokens, List protected final P getParameter(int parameterIndex) { return this.parameters[parameterIndex]; } - - @Override - public String showParameterType() { - return this.parameters != null && this.parameters.length > 0 - ? this.parameters[0].getClass().getSimpleName() - : "void"; - } - - @Override - public String showParameterTokens(int parameterIndex) { - StringBuilder sb = new StringBuilder(256); - for (IToken token : this.tokens[parameterIndex]) { - sb.append(sb.length() == 0 ? "`" : " `").append(token.toString()).append("`"); - } - return sb.toString(); - } }