diff --git a/README.md b/README.md index 97b6706..9b6c78c 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,7 @@ In a nutshell, _algorithms_ are congruent to _patterns_. The _logic_ is in the _ ## Basic Concepts Ginr operates in a symbolic domain involving a finite set of symbols and algebraic semiring operators that recombine symbols to express syntactic patterns. Support for Unicode symbols and binary data is built in, and Unicode in ginr source patterns is rendered as UTF-8 byte sequences in compiled automata. UTF-8 text is transduced without decoding and extracted bytes are decoded only in target effectors. Ribose transducer patterns may introduce additional atomic symbols as tokens representing out-of-band (>255) control signals. -Input patterns are expressed in `{byte,signal}*` semirings, and may involve UTF-8 and binary bytes from an external source as well as control signals interjected by target effectors. Ribose transducer patterns are expressed in `(input,effector,parameter)*` semirings, mapping input patterns onto parameterized effectors expressed by domain-specific target classes. They identify syntactic features of interest in the input and apply target effectors to extract and assimilate features into the target domain. +Input patterns are expressed in `{byte,signal}*` semirings, and may involve UTF-8 and binary bytes from an external source as well as control signals interjected by target effectors. Ribose transducer patterns are expressed in `(input,effector,parameter)*` semirings, mapping input patterns onto parametric effectors expressed by domain-specific target classes. They identify syntactic features of interest in the input and apply target effectors to extract and assimilate features into the target domain. A ribose model is associated with a target class and is a container for related collections of transducers, target effectors, static effector parameters, control signals and field registers for accumulating extracted bytes. The `ITransductor` implementation that governs ribose transductions provides a base set of effectors to - extract and compose data in selected fields *(`select, paste, copy, cut, clear`)*, @@ -85,7 +85,7 @@ A ribose model is associated with a target class and is a container for related All ribose models implicitly inherit the transductor effectors, along with an extensible set of control signals `{nul,nil,eol,eos}` and an anonymous field that is preselected for every transduction and reselected when `select` is invoked with no parameter. New signals and fields referenced in transducer patterns implicitly extend the base signal and field collections. Additional effectors may be defined in specialized `ITarget` implementation classes. -The ribose transductor implements `ITarget` and its effectors are sufficient for most ribose models that transduce input to standard output via the `out[...]` effector. Domain-specific target classes may extend `SimpleTarget` to express additional effectors, typically as inner classes specializing `BaseEffector` or `BaseParameterizedEffector`. All effectors are provided with a reference to the containing target instance and an `IOutput` view for extracting fields as `byte[]`, integer, floating point or Unicode `char[]` values, typically for inclusion in immutable value objects that are incorporated into the target model. +The ribose transductor implements `ITarget` and its effectors are sufficient for most ribose models that transduce input to standard output via the `out[...]` effector. Domain-specific target classes may extend `SimpleTarget` to express additional effectors, typically as inner classes specializing `BaseEffector` or `BaseParametricEffector`. All effectors are provided with a reference to the containing target instance and an `IOutput` view for extracting fields as `byte[]`, integer, floating point or Unicode `char[]` values, typically for inclusion in immutable value objects that are incorporated into the target model. Targets need not be monolithic. In fact, every ribose transduction involves a composite target comprised of the transductor and at least one other target class (e.g., `SimpleTarget`). In a composite target one target class is selected as the representative target, which instantiates and gathers effectors from subordinate targets to merge with its own effectors into a single collection to merge with the transductor effectors. Composite targets allow separable concerns within complex semantic domains to be encapsulated in discrete interoperable and reusable targets. For example, a validation model containing a collection of transducers that syntactically recognize domain artifacts would be bound to a target expressing effectors to support semantic validation. The validation model and target, supplied by the service vendor, can then be combined with specialized models in receiving domains to obtain a composite model including validation and reception models and effectors. With some ginr magic receptor patterns can be joined with corresponding validator patterns to obtain receptors that validate in stepwise synchrony with reception and assimilation into the receiving domain. ### Use Cases diff --git a/overview.html b/overview.html index 458bee0..7603539 100644 --- a/overview.html +++ b/overview.html @@ -13,7 +13,7 @@

Ginr automata for ribose are 3-tape finite state transducers (FSTs) compiled from 3-dimensional regular patterns that express the source syntax on the input tape and -unambiguously map it onto parameterized effectors, expressed by a target, that extract and +unambiguously map it onto parametric effectors, expressed by a target, that extract and assimilate input data into the target domain. Ginr encodes Unicode literal characters and tokens, eg 'Σ', 'Π', `ΣΠ`, as multibyte UTF-8 sequences and the encoded form is used throughout ribose. This is largely transparent to end users, but care must be taken when @@ -131,16 +131,16 @@ reference to the target instance and an {@code IOutput} instance that supports conversion of transducer fields to Java primitive values or {@code byte[]} or {@code char[]} arrays. There are three types of effectors: simple effector, -parameterized effector and receptor effector. Simple effectors extend {@code +parametric effector and receptor effector. Simple effectors extend {@code IEffector}, which expresses a niladic {@code invoke()} method -that is called when the effector fires in running transduction. Parameterized -effectors extend {@code IParameterizedEffector extends +that is called when the effector fires in running transduction. Parametric +effectors extend {@code IParametricEffector extends IEffector>} and contain an array {@code P[]} of parametric objects compiled -from lists effector tokens. Parameterized effectors inherit {@code IEffector.invoke()} +from lists effector tokens. Parametric effectors inherit {@code IEffector.invoke()} and add a monadic {@code invoke(int)} method, where the {@code int} argument selects -a specific {@code P} instance to use. Receptor effectors are specialized parameterized +a specific {@code P} instance to use. Receptor effectors are specialized parametric effectors that extend {@code BaseReceptorEffector extends -BaseParameterizedEffector}. Receptor effectors express public fields +BaseParametricEffector}. Receptor effectors express public fields that receive data decoded from transducer fields.

The transductor is itself a target expressing a suite of core effectors that are diff --git a/src/com/characterforming/jrte/engine/BaseFieldEffector.java b/src/com/characterforming/jrte/engine/BaseFieldEffector.java index 02d97e5..01da3a8 100644 --- a/src/com/characterforming/jrte/engine/BaseFieldEffector.java +++ b/src/com/characterforming/jrte/engine/BaseFieldEffector.java @@ -23,17 +23,17 @@ import java.nio.charset.CharacterCodingException; import com.characterforming.ribose.IToken; -import com.characterforming.ribose.base.BaseParameterizedEffector; +import com.characterforming.ribose.base.BaseParametricEffector; import com.characterforming.ribose.base.TargetBindingException; /** - * Base class for parameterized field effectors, which are invoked with + * Base class for parametric field effectors, which are invoked with * field name parameters. The setParamater(int, charset, byte[][]), invoke(), and * invoke(int) methods must be implemented by subclasses. * * @author Kim Briggs */ -abstract class BaseFieldEffector extends BaseParameterizedEffector { +abstract class BaseFieldEffector extends BaseParametricEffector { /** * Constructor * @@ -45,12 +45,12 @@ protected BaseFieldEffector(final Transductor transductor, final String name) th super(transductor, name); } - @Override // @see com.characterforming.ribose.IParameterizedEffector#allocateParameters(int) + @Override // @see com.characterforming.ribose.IParametricEffector#allocateParameters(int) public Integer[] allocateParameters(int parameterCount) { return new Integer[parameterCount]; } - @Override // IParameterizedEffector#compileParameter(IToken[]) + @Override // IParametricEffector#compileParameter(IToken[]) public Integer compileParameter(final IToken[] parameterList) throws TargetBindingException { if (parameterList.length != 1) { throw new TargetBindingException(String.format("%1$s.%2$s[]: effector accepts exactly one parameter", diff --git a/src/com/characterforming/jrte/engine/BaseInputOutputEffector.java b/src/com/characterforming/jrte/engine/BaseInputOutputEffector.java index 06588e8..be70a41 100644 --- a/src/com/characterforming/jrte/engine/BaseInputOutputEffector.java +++ b/src/com/characterforming/jrte/engine/BaseInputOutputEffector.java @@ -23,14 +23,14 @@ import java.nio.charset.CharacterCodingException; import com.characterforming.ribose.IToken; -import com.characterforming.ribose.base.BaseParameterizedEffector; +import com.characterforming.ribose.base.BaseParametricEffector; import com.characterforming.ribose.base.EffectorException; import com.characterforming.ribose.base.TargetBindingException; /** * @author Kim Briggs */ -abstract class BaseInputOutputEffector extends BaseParameterizedEffector { +abstract class BaseInputOutputEffector extends BaseParametricEffector { /** * Constructor * @@ -42,17 +42,17 @@ protected BaseInputOutputEffector(Transductor transductor, String name) throws C super(transductor, name); } - @Override // @see com.characterforming.ribose.IParameterizedEffector#invoke() + @Override // @see com.characterforming.ribose.IParametricEffector#invoke() public int invoke() throws EffectorException { throw new EffectorException(String.format("The %1$s effector requires at least one parameter", super.getName())); } - @Override // @see com.characterforming.ribose.IParameterizedEffector#allocateParameters(int) + @Override // @see com.characterforming.ribose.IParametricEffector#allocateParameters(int) public IToken[][] allocateParameters(int parameterCount) { return new IToken[parameterCount][]; } - @Override // @see com.characterforming.ribose.IParameterizedEffector#compileParameter(IToken[]) + @Override // @see com.characterforming.ribose.IParametricEffector#compileParameter(IToken[]) public IToken[] compileParameter(final IToken[] parameterList) throws TargetBindingException { if (parameterList.length < 1) { throw new TargetBindingException(String.format( diff --git a/src/com/characterforming/jrte/engine/Chain.java b/src/com/characterforming/jrte/engine/Chain.java index 09d3ab8..d8b474a 100644 --- a/src/com/characterforming/jrte/engine/Chain.java +++ b/src/com/characterforming/jrte/engine/Chain.java @@ -46,7 +46,7 @@ boolean isEffector() { && this.effectVector[1] == 0; } - boolean isParameterizedEffector() { + boolean isParametricEffector() { return this.effectVector.length == 3 && this.effectVector[0] < 0 && this.effectVector[2] == 0; diff --git a/src/com/characterforming/jrte/engine/Model.java b/src/com/characterforming/jrte/engine/Model.java index c09d31c..21e09b3 100644 --- a/src/com/characterforming/jrte/engine/Model.java +++ b/src/com/characterforming/jrte/engine/Model.java @@ -40,13 +40,13 @@ import java.util.logging.Logger; import com.characterforming.ribose.IEffector; -import com.characterforming.ribose.IParameterizedEffector; +import com.characterforming.ribose.IParametricEffector; import com.characterforming.ribose.ITarget; import com.characterforming.ribose.IToken; import com.characterforming.ribose.ITransduction; import com.characterforming.ribose.ITransductor; import com.characterforming.ribose.base.BaseEffector; -import com.characterforming.ribose.base.BaseParameterizedEffector; +import com.characterforming.ribose.base.BaseParametricEffector; import com.characterforming.ribose.base.Bytes; import com.characterforming.ribose.base.Codec; import com.characterforming.ribose.base.CompilationException; @@ -256,7 +256,7 @@ protected boolean save(Argument[][] effectorParameters) { for (int effectorOrdinal = 0; effectorOrdinal < this.effectorOrdinalMap.size(); effectorOrdinal++) { Argument[] arguments = effectorParameters[effectorOrdinal]; if (arguments != null && arguments.length > 0) { - assert this.proxyEffectors[effectorOrdinal] instanceof IParameterizedEffector; + assert this.proxyEffectors[effectorOrdinal] instanceof IParametricEffector; this.writeArguments(arguments); } else this.writeInt(-1); @@ -324,7 +324,7 @@ protected Model load() throws ModelException, CharacterCodingException { IToken[][] parameterTokens = new IToken[effectorArguments.length][]; for (int i = 0; i < effectorArguments.length; i++) parameterTokens[i] = Token.getParameterTokens(this, effectorArguments[i]); - if (this.proxyEffectors[effectorOrdinal] instanceof BaseParameterizedEffector effector) + if (this.proxyEffectors[effectorOrdinal] instanceof BaseParametricEffector effector) effector.compileParameters(parameterTokens, errors); if (this.targetMode.isLive()) this.proxyEffectors[effectorOrdinal].passivate(); @@ -387,7 +387,7 @@ public boolean map(PrintStream mapWriter) { for (int effector = 0; effector < effectorIndex.length; effector++) { mapWriter.printf("%1$6d effector %2$s", effector, effectorIndex[effector].asString()); - if (this.proxyEffectors[effector] instanceof BaseParameterizedEffector proxyEffector) { + if (this.proxyEffectors[effector] instanceof BaseParametricEffector proxyEffector) { mapWriter.printf(" [ %1$s ]%n", proxyEffector.showParameterType()); for (int parameter = 0; parameter < proxyEffector.getParameterCount(); parameter++) mapWriter.printf("%1$6d parameter %2$s%n", parameter, proxyEffector.showParameterTokens(parameter)); @@ -435,10 +435,10 @@ protected Argument[][] compileModelParameters(List errors) throws Effect for (int effectorOrdinal = 0; effectorOrdinal < this.proxyEffectors.length; effectorOrdinal++) { HashMap parametersMap = this.effectorParametersMaps.get(effectorOrdinal); this.proxyEffectors[effectorOrdinal].setOutput(this.proxyTransductor); - if (this.proxyEffectors[effectorOrdinal] instanceof BaseParameterizedEffector parameterizedEffector) { + if (this.proxyEffectors[effectorOrdinal] instanceof BaseParametricEffector parametricEffector) { if (parametersMap != null) { assert parametersMap != null: String.format("Effector parameters map is null for %1$s effector", - parameterizedEffector.getName()); + parametricEffector.getName()); Argument[] arguments = new Argument[parametersMap.size()]; IToken[][] tokens = new IToken[arguments.length][]; for (Map.Entry e : parametersMap.entrySet()) { @@ -446,7 +446,7 @@ protected Argument[][] compileModelParameters(List errors) throws Effect tokens[ordinal] = Token.getParameterTokens(this, argument); arguments[ordinal] = argument; } - parameterizedEffector.compileParameters(tokens, errors); + parametricEffector.compileParameters(tokens, errors); effectorArguments[effectorOrdinal] = arguments; } else effectorArguments[effectorOrdinal] = new Argument[0]; diff --git a/src/com/characterforming/jrte/engine/ModelCompiler.java b/src/com/characterforming/jrte/engine/ModelCompiler.java index c4e109a..55b2e5e 100755 --- a/src/com/characterforming/jrte/engine/ModelCompiler.java +++ b/src/com/characterforming/jrte/engine/ModelCompiler.java @@ -505,7 +505,7 @@ void putAutomaton() throws CharacterCodingException { transitionMatrix[inputOrdinal][rteState][1] = 1; else if (chain.isEffector()) transitionMatrix[inputOrdinal][rteState][1] = effectVector[0]; - else if (chain.isParameterizedEffector()) + else if (chain.isParametricEffector()) transitionMatrix[inputOrdinal][rteState][1] = Transducer.action(-1 * effectVector[0], effectVector[1]); else transitionMatrix[inputOrdinal][rteState][1] = -1 * this.effectorVectorMap.computeIfAbsent( diff --git a/src/com/characterforming/jrte/engine/ModelLoader.java b/src/com/characterforming/jrte/engine/ModelLoader.java index 23f66aa..6741d8e 100644 --- a/src/com/characterforming/jrte/engine/ModelLoader.java +++ b/src/com/characterforming/jrte/engine/ModelLoader.java @@ -35,13 +35,13 @@ import java.util.logging.Level; import com.characterforming.ribose.IEffector; -import com.characterforming.ribose.IParameterizedEffector; +import com.characterforming.ribose.IParametricEffector; import com.characterforming.ribose.IModel; import com.characterforming.ribose.ITarget; import com.characterforming.ribose.ITransduction; import com.characterforming.ribose.ITransductor; import com.characterforming.ribose.ITransductor.Metrics; -import com.characterforming.ribose.base.BaseParameterizedEffector; +import com.characterforming.ribose.base.BaseParametricEffector; import com.characterforming.ribose.base.Bytes; import com.characterforming.ribose.base.Codec; import com.characterforming.ribose.base.DomainErrorException; @@ -104,12 +104,12 @@ public ITransductor transductor(ITarget target) } catch (EffectorException e) { throw new ModelException(e); } - if (super.proxyEffectors[i] instanceof IParameterizedEffector proxyEffector) { - if (boundFx[i] instanceof BaseParameterizedEffector boundEffector) + if (super.proxyEffectors[i] instanceof IParametricEffector proxyEffector) { + if (boundFx[i] instanceof BaseParametricEffector boundEffector) boundEffector.setParameters(proxyEffector); else throw new ModelException(String.format( - "Target effector '%s' implementation must extend BaseParameterizedEffector", proxyEffector.getClass().getName())); + "Target effector '%s' implementation must extend BaseParametricEffector", proxyEffector.getClass().getName())); } } trex.setEffectors(boundFx); @@ -267,7 +267,7 @@ public void decompile(final String transducerName) System.out.printf("%1$d %2$d -> %3$d", from, equivalent, to); if (effect >= 0x10000) { int effectorOrdinal = Transducer.effector(effect); - if (super.proxyEffectors[effectorOrdinal] instanceof BaseParameterizedEffector effector) { + if (super.proxyEffectors[effectorOrdinal] instanceof BaseParametricEffector effector) { int parameterOrdinal = Transducer.parameter(effect); System.out.printf(" %s[", effectorNames[effectorOrdinal]); System.out.printf(" %s ]", effector.showParameterTokens(parameterOrdinal)); @@ -282,7 +282,7 @@ public void decompile(final String transducerName) System.out.printf(" %s", effectorNames[effectorVectors[index++]]); else { int effectorOrdinal = -1 * effectorVectors[index++]; - if (super.proxyEffectors[effectorOrdinal] instanceof BaseParameterizedEffector effector) { + if (super.proxyEffectors[effectorOrdinal] instanceof BaseParametricEffector effector) { int parameterOrdinal = Transducer.parameter(effectorVectors[index++]); System.out.printf(" %s[", effectorNames[effectorOrdinal]); System.out.printf(" %s ]", effector.showParameterTokens(parameterOrdinal)); diff --git a/src/com/characterforming/jrte/engine/Transductor.java b/src/com/characterforming/jrte/engine/Transductor.java index c1a98f8..4437f3b 100644 --- a/src/com/characterforming/jrte/engine/Transductor.java +++ b/src/com/characterforming/jrte/engine/Transductor.java @@ -29,14 +29,14 @@ import com.characterforming.ribose.IEffector; import com.characterforming.ribose.IOutput; -import com.characterforming.ribose.IParameterizedEffector; +import com.characterforming.ribose.IParametricEffector; import com.characterforming.ribose.IModel; import com.characterforming.ribose.ITarget; import com.characterforming.ribose.IToken; import com.characterforming.ribose.ITransduction; import com.characterforming.ribose.ITransductor; import com.characterforming.ribose.base.BaseEffector; -import com.characterforming.ribose.base.BaseParameterizedEffector; +import com.characterforming.ribose.base.BaseParametricEffector; import com.characterforming.ribose.base.Bytes; import com.characterforming.ribose.base.Codec; import com.characterforming.ribose.base.DomainErrorException; @@ -47,7 +47,7 @@ /** * Runtime transductor instances are instantiated using {@link IModel#transductor(ITarget)} - * presenting a collection of {@link IEffector} and {@link IParameterizedEffector} + * presenting a collection of {@link IEffector} and {@link IParametricEffector} * instances. Client applications drive transduction using the Transductor.run() method, * which processes the input stack until one of the following conditions is satisfied: *

@@ -594,7 +594,7 @@ else if (action != NIL) // effect action and check for transducer or input stack adjustment int aftereffects = IEffector.RTX_NONE; if (action >= 0x10000) { - if ( this.effectors[Transducer.effector(action)] instanceof IParameterizedEffector e) + if ( this.effectors[Transducer.effector(action)] instanceof IParametricEffector e) aftereffects = e.invoke(Transducer.parameter(action)); else assert false; } else if (action >= 0) @@ -718,7 +718,7 @@ private int effect(int action, int token, int[] effectorVector) E: do { action = effectorVector[index++]; if (action < 0 ) { - if (this.effectors[0 - action] instanceof IParameterizedEffector e) + if (this.effectors[0 - action] instanceof IParametricEffector e) aftereffects |= e.invoke(effectorVector[index++]); else assert false; } else if (action != NUL) { @@ -975,7 +975,7 @@ public int invoke(final int parameterIndex) throws EffectorException { } } - private final class SignalEffector extends BaseParameterizedEffector { + private final class SignalEffector extends BaseParametricEffector { private SignalEffector(final Transductor transductor) throws CharacterCodingException { super(transductor, "signal"); } @@ -990,7 +990,7 @@ public int invoke(final int parameterIndex) throws EffectorException { return IEffector.signal(super.parameters[parameterIndex]); } - @Override // @see com.characterforming.ribose.IParameterizedEffector#allocateParameters(int) + @Override // @see com.characterforming.ribose.IParametricEffector#allocateParameters(int) public Integer[] allocateParameters(int parameterCount) { return new Integer[parameterCount]; } @@ -1089,7 +1089,7 @@ public int invoke(final int parameterIndex) throws EffectorException { } } - private final class CountEffector extends BaseParameterizedEffector { + private final class CountEffector extends BaseParametricEffector { private CountEffector(final Transductor transductor) throws CharacterCodingException { super(transductor, "count"); } @@ -1099,7 +1099,7 @@ public int invoke() throws EffectorException { throw new EffectorException(String.format("Cannot invoke inline effector '%1$s'", super.getName())); } - @Override // @see com.characterforming.ribose.IParameterizedEffector#allocateParameters(int) + @Override // @see com.characterforming.ribose.IParametricEffector#allocateParameters(int) public int[][] allocateParameters(int parameterCount) { return new int[parameterCount][]; } @@ -1139,7 +1139,7 @@ else if (parameterList[0].isLiteral()) { } } - private final class StartEffector extends BaseParameterizedEffector { + private final class StartEffector extends BaseParametricEffector { private StartEffector(final Transductor transductor) throws CharacterCodingException { super(transductor, "start"); } @@ -1149,7 +1149,7 @@ public int invoke() throws EffectorException { throw new EffectorException("The start effector requires a parameter"); } - @Override // @see com.characterforming.ribose.IParameterizedEffector#allocateParameters(int) + @Override // @see com.characterforming.ribose.IParametricEffector#allocateParameters(int) public Integer[] allocateParameters(int parameterCount) { return new Integer[parameterCount]; } @@ -1192,7 +1192,7 @@ public int invoke() throws EffectorException { } } - private final class MsumEffector extends BaseParameterizedEffector { + private final class MsumEffector extends BaseParametricEffector { private MsumEffector(final Transductor transductor) throws CharacterCodingException { super(transductor, "msum"); } @@ -1202,7 +1202,7 @@ public int invoke() throws EffectorException { return IEffector.RTX_NONE; } - @Override // @see com.characterforming.ribose.IParameterizedEffector#allocateParameters(int) + @Override // @see com.characterforming.ribose.IParametricEffector#allocateParameters(int) public long[][] allocateParameters(int parameterCount) { return new long[parameterCount][]; } @@ -1259,7 +1259,7 @@ private void printRange(StringBuilder sb, int startBit, int endBit) { } } - private final class MproductEffector extends BaseParameterizedEffector { + private final class MproductEffector extends BaseParametricEffector { private MproductEffector(final Transductor transductor) throws CharacterCodingException { super(transductor, "mproduct"); } @@ -1282,7 +1282,7 @@ public int invoke(final int parameterIndex) throws EffectorException { return IEffector.RTX_NONE; } - @Override // @see com.characterforming.ribose.IParameterizedEffector#allocateParameters(int) + @Override // @see com.characterforming.ribose.IParametricEffector#allocateParameters(int) public byte[][] allocateParameters(int parameterCount) { return new byte[parameterCount][]; } @@ -1308,7 +1308,7 @@ public String showParameterTokens(int parameterIndex) { } } - private final class MscanEffector extends BaseParameterizedEffector { + private final class MscanEffector extends BaseParametricEffector { private MscanEffector(final Transductor transductor) throws CharacterCodingException { super(transductor, "mscan"); } @@ -1329,7 +1329,7 @@ public int invoke(final int parameterIndex) throws EffectorException { return IEffector.RTX_NONE; } - @Override // @see com.characterforming.ribose.IParameterizedEffector#allocateParameters(int) + @Override // @see com.characterforming.ribose.IParametricEffector#allocateParameters(int) public Integer[] allocateParameters(int parameterCount) { return new Integer[parameterCount]; } diff --git a/src/com/characterforming/ribose/IEffector.java b/src/com/characterforming/ribose/IEffector.java index 6826e41..db6696f 100644 --- a/src/com/characterforming/ribose/IEffector.java +++ b/src/com/characterforming/ribose/IEffector.java @@ -77,7 +77,7 @@ * Ribose and ginr currently support only UTF-8 character encodings. * * @param The effector target type - * @see IParameterizedEffector + * @see IParametricEffector * @see BaseEffector * @author Kim Briggs */ diff --git a/src/com/characterforming/ribose/IOutput.java b/src/com/characterforming/ribose/IOutput.java index f32a7ff..b78983a 100755 --- a/src/com/characterforming/ribose/IOutput.java +++ b/src/com/characterforming/ribose/IOutput.java @@ -39,7 +39,7 @@ * to {@link #getTransducerFieldndex(String, String)}. Effectors should obtain field * ordinals in {@code setOutput()} and retain them for use with the data transfer methods * ({@link #asInteger(int, int)}, etc) in {@link IEffector#invoke()} and {@link - * IParameterizedEffector#invoke(int)} as shown in the example below (this example is + * IParametricEffector#invoke(int)} as shown in the example below (this example is * implemented more succinctly as a receptor effector -- see below). *
  * record Header (int version, int tapes, int transitions, int states, int symbols) {}
diff --git a/src/com/characterforming/ribose/IParameterizedEffector.java b/src/com/characterforming/ribose/IParametricEffector.java
similarity index 82%
rename from src/com/characterforming/ribose/IParameterizedEffector.java
rename to src/com/characterforming/ribose/IParametricEffector.java
index 8eebfa3..a14251d 100644
--- a/src/com/characterforming/ribose/IParameterizedEffector.java
+++ b/src/com/characterforming/ribose/IParametricEffector.java
@@ -20,19 +20,19 @@
 
 package com.characterforming.ribose;
 
-import com.characterforming.ribose.base.BaseParameterizedEffector;
+import com.characterforming.ribose.base.BaseParametricEffector;
 import com.characterforming.ribose.base.EffectorException;
 import com.characterforming.ribose.base.TargetBindingException;
 
 /**
- * Interface for parameterized effectors extends {@link IEffector} with a monadic
+ * Interface for parametric effectors extends {@link IEffector} with a monadic
  * {@link #invoke(int p)} method that selects a P instance from an enumerated
  * set of immutable parameter instances. Implementation classes must extend
- * {@link BaseParameterizedEffector}, which implements the parameter compilation,
- * binding and access protocols and exposes {@code BaseParameterizedEffector.P[]}
+ * {@link BaseParametricEffector}, which implements the parameter compilation,
+ * binding and access protocols and exposes {@code BaseParametricEffector.P[]}
  * as a protected field for direct subclass access to compiled parameters.
  * 

- * Each {@link IParameterizedEffector} implementation is a template for an indexed + * Each {@link IParametricEffector} implementation is a template for an indexed * collection of {@link IEffector}. In ribose models, they are specialized by the * union of parameter lists bound to their effectors in transducer patterns. In * ribose transducer patterns effector parameters are represented as lists of one @@ -43,13 +43,13 @@ * transducer (`@transducer`) or signal (`!signal`) references. Tokens are * presented in the {@link IToken} interface. *

- * Parameterized effectors compile their parameters when a model is created and + * Parametric effectors compile their parameters when a model is created and * again whenever it is loaded for runtime use. Each parameter is compiled from * an array of {@link IToken} ({@code IToken[] -> P}) to an immutable instance of * P. Parameter compilation is performed using proxy target, * transductor and effector instances, which are never involved in live * transductions. A simple parameter compilation protocol is implemented in - * {@link BaseParameterizedEffector}, which all {@code IParameterizedEffector} + * {@link BaseParametricEffector}, which all {@code IParametricEffector} * implementations must extend: *
    *
  1. model calls subclassEffector.allocateParameters(int n) @@ -63,13 +63,13 @@ *
* Proxy effectors may receive calls to {@link #showParameterType()} and {@link * #showParameterTokens(int)} from the model decompiler; these methods are implemented - * in {@link BaseParameterizedEffector} but may be overridden by subclasses. The + * in {@link BaseParametricEffector} but may be overridden by subclasses. The * {@link IEffector#invoke()} and {@link #invoke(int)} methods are never called for * proxy effectors. *

* For example: *
- * private final class DateEffector extends BaseParameterizedEffector<Target, SimpleDateFormat> {
+ * private final class DateEffector extends BaseParametricEffector<Target, SimpleDateFormat> {
  *   public SimpleDateFormat[] allocateParameters(int size) {
  *     super.parameters = new SimpleDateFormat[size];
  *   }
@@ -87,14 +87,14 @@
  * }
* In live contexts the precompiled parameters are retained in the live model * and are available for referential sharing across live transductors bound to the - * model. Live parameterized effectors receive a reference to the precompiled - * parameters {@code P[]} via {@link BaseParameterizedEffector#setParameters(IParameterizedEffector)} + * model. Live parametric effectors receive a reference to the precompiled + * parameters {@code P[]} via {@link BaseParametricEffector#setParameters(IParametricEffector)} * when they become bound to a transductor. Live effectors are never passivated and * may receive a series of {@link #invoke()} and {@link #invoke(int p)} methods, * which return an {@code RTX} code as for {@link IEffector}. *

- * All {@code IParameterizedEffector} implementations must be subclasses of - * {@link BaseParameterizedEffector}. Other than immutability ribose places + * All {@code IParametricEffector} implementations must be subclasses of + * {@link BaseParametricEffector}. Other than immutability ribose places * no constraints on effector implementation. Most effector implementations * are light weight, tightly focused and single threaded. A parallel array * of derivative objects can be allocated and instantiated along with the @@ -104,11 +104,11 @@ * @param the effector target type * @param

the effector parameter type, constructible from byte[][] (eg new P(byte[][])) * @see IEffector - * @see BaseParameterizedEffector + * @see BaseParametricEffector */ -public interface IParameterizedEffector extends IEffector { +public interface IParametricEffector extends IEffector { /** - * Parameterized effector invocation receives the index of the P + * Parametric effector invocation receives the index of the P * instance to apply for the invocation. Normally implementation will return * {@code IEffector.RTX_NONE}, which has no effect. In some cases a signal may * be encoded in the return value using {@code IEffector.signal(sig)}, where @@ -147,14 +147,14 @@ P compileParameter(IToken[] parameterTokens) * (generic parameter type is difficult to obtain by reflection). * * @return a printable string representing the effector's parameter object type. - * This is implemented in {@link BaseParameterizedEffector} but may be overriden + * This is implemented in {@link BaseParametricEffector} but may be overriden * by subclasses. */ String showParameterType(); /** * Render tokens for a parameter object in a printable format, to support - * decompilation. This is implemented in {@link BaseParameterizedEffector} + * decompilation. This is implemented in {@link BaseParametricEffector} * but may be overriden by subclasses. * * @param parameterIndex the parameter index diff --git a/src/com/characterforming/ribose/ITarget.java b/src/com/characterforming/ribose/ITarget.java index 8594234..9f4a255 100644 --- a/src/com/characterforming/ribose/ITarget.java +++ b/src/com/characterforming/ribose/ITarget.java @@ -25,13 +25,13 @@ /** * Interface for transduction target classes, which express {@link IEffector} - * and {@link IParameterizedEffector} instances that are invoked from runtime + * and {@link IParametricEffector} instances that are invoked from runtime * transductions. The runtime {@code Transductor} class, which encapsulates * ribose transductions, implements {@code ITarget} and provides the base ribose * effectors that are accessible to all transducers. These are listed in the * {@link ITransductor} documentation. The {@link SimpleTarget} class exposes * only the {@code Transductor} effectors and is included to support - * simple models that do not require specialized effectors. Specialized + * simple models that do not require specialized effectors. Specialized * {@code ITarget} implementations may supplement these with additional * effectors. *

@@ -39,7 +39,7 @@ * with no arguments. This is used to instantiate proxy instances to enumerate * effectors and precompile effector parameters. A proxy target instantiates * an array of proxy effectors that are used only for parameter precompilation. - * See the {@link IParameterizedEffector} documentation for more information + * See the {@link IParametricEffector} documentation for more information * regarding the effector parameter binding protocol. At runtime, a live target * instance is bound to a transductor and the binding persists for the lifetime * of the transductor. Live runtime targets are instantiated externally and @@ -63,7 +63,7 @@ *

* For example, a validation model containing a collection of transducers that * syntactically recognize domain artifacts would be bound to a target expressing - * effectors to support semantic validation. The validation patterns and target, + * effectors to support semantic validation. The validation patterns and target, * supplied by the service provider, can then be combined with specialized models * in receiving domains to obtain composite models that include provider validation * and consumer reception patterns, targets and effectors. With some ginr magic diff --git a/src/com/characterforming/ribose/IToken.java b/src/com/characterforming/ribose/IToken.java index e49bbc7..dbe7f50 100644 --- a/src/com/characterforming/ribose/IToken.java +++ b/src/com/characterforming/ribose/IToken.java @@ -47,9 +47,9 @@ * non-literal tokens types. *

* Arrays of {@code IToken} objects, corresponding to effector parameters, are conveyed - * to proxy parameterized effectors for parameter precompilation. The proxy effector + * to proxy parametric effectors for parameter precompilation. The proxy effector * constructs from each {@code IToken[]} array an indexed instance of its generic parameter - * type P. See the {@link IParameterizedEffector} documentation for more information + * type P. See the {@link IParametricEffector} documentation for more information * regarding effector parameter compilation. * * @author Kim Briggs diff --git a/src/com/characterforming/ribose/ITransductor.java b/src/com/characterforming/ribose/ITransductor.java index 36244b8..22abcf6 100644 --- a/src/com/characterforming/ribose/ITransductor.java +++ b/src/com/characterforming/ribose/ITransductor.java @@ -109,7 +109,7 @@ *

* The {@code signal[`!signal`]} effector injects a signal for immediate transduction on * the next transition. Effectors may inject a signal by returning from {@link IEffector#invoke()} - * or {@link IParameterizedEffector#invoke(int)} a signal ordinal encoded with + * or {@link IParametricEffector#invoke(int)} a signal ordinal encoded with * {@link IEffector#signal(int)}. This can be used to effect backflow of information * from the target to the transductor; for example, *

(nl, isThatSo[`!true` `!false`]) ((true, yep) | (false, nope))
diff --git a/src/com/characterforming/ribose/base/BaseParameterizedEffector.java b/src/com/characterforming/ribose/base/BaseParametricEffector.java similarity index 75% rename from src/com/characterforming/ribose/base/BaseParameterizedEffector.java rename to src/com/characterforming/ribose/base/BaseParametricEffector.java index a2724f4..a376948 100644 --- a/src/com/characterforming/ribose/base/BaseParameterizedEffector.java +++ b/src/com/characterforming/ribose/base/BaseParametricEffector.java @@ -23,34 +23,34 @@ import java.nio.charset.CharacterCodingException; import java.util.List; -import com.characterforming.ribose.IParameterizedEffector; +import com.characterforming.ribose.IParametricEffector; import com.characterforming.ribose.ITarget; import com.characterforming.ribose.IToken; /** - * Base {@link IParameterizedEffector} implementation class extends {@link BaseEffector} - * to support specialized effectors. All {@link IParameterizedEffector} implementations - * must extend {@link BaseParameterizedEffector} and must implement: + * Base {@link IParametricEffector} implementation class extends {@link BaseEffector} + * to support specialized effectors. All {@link IParametricEffector} implementations + * must extend {@link BaseParametricEffector} and must implement: *
    - *
  • {@link IParameterizedEffector#invoke()}
  • - *
  • {@link IParameterizedEffector#invoke(int)}
  • - *
  • {@link IParameterizedEffector#allocateParameters(int)}
  • - *
  • {@link IParameterizedEffector#compileParameter(IToken[])}
  • + *
  • {@link IParametricEffector#invoke()}
  • + *
  • {@link IParametricEffector#invoke(int)}
  • + *
  • {@link IParametricEffector#allocateParameters(int)}
  • + *
  • {@link IParametricEffector#compileParameter(IToken[])}
  • *
* Subclasses may access indexed compiled parameter objects in their {@link #invoke(int)} * implementations directly as {@code super.parameters[int]}. 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 + * {@link IParametricEffector} interface are for internal use only. These methods + * implement the parameter compilation and binding protocols for all parametric effector * implementations. * * @param the effector target type * @param

the effector parameter type, constructible from IToken[] (eg new P(IToken[])) * @author Kim Briggs - * @see IParameterizedEffector + * @see IParametricEffector */ -public abstract class BaseParameterizedEffector extends BaseEffector implements IParameterizedEffector { +public abstract class BaseParametricEffector extends BaseEffector implements IParametricEffector { /** Raw and compiled effector parameters indexed and selected by parameter ordinal.*/ protected P[] parameters = null; @@ -63,18 +63,18 @@ public abstract class BaseParameterizedEffector extends Ba * @param name the effector name as referenced from ginr transducers * @throws CharacterCodingException if encoder fails */ - protected BaseParameterizedEffector(final T target, final String name) + protected BaseParametricEffector(final T target, final String name) throws CharacterCodingException { super(target, name); } - @Override // @see com.characterforming.ribose.base.IParameterizedEffector#nvoke(int) + @Override // @see com.characterforming.ribose.base.IParametricEffector#nvoke(int) public abstract int invoke(int parameterIndex) throws EffectorException; - @Override // @see com.characterforming.ribose.base.IParameterizedEffector#allocateParameters(int) + @Override // @see com.characterforming.ribose.base.IParametricEffector#allocateParameters(int) public abstract P[] allocateParameters(int parameterCount); - @Override // @see com.characterforming.ribose.base.IParameterizedEffector#compileParameter(IToken[]) + @Override // @see com.characterforming.ribose.base.IParametricEffector#compileParameter(IToken[]) public abstract P compileParameter(IToken[] parameterTokens) throws TargetBindingException; @Override @@ -101,9 +101,9 @@ public String showParameterTokens(int parameterIndex) { * @param proxyEffector the proxy effector holding the compiled parameters */ @SuppressWarnings("unchecked") - public final void setParameters(IParameterizedEffector proxyEffector) { - assert proxyEffector instanceof BaseParameterizedEffector; - if (proxyEffector instanceof BaseParameterizedEffector proxy) { + public final void setParameters(IParametricEffector proxyEffector) { + assert proxyEffector instanceof BaseParametricEffector; + if (proxyEffector instanceof BaseParametricEffector proxy) { this.parameters = (P[])proxy.parameters; } } diff --git a/src/com/characterforming/ribose/base/BaseReceptorEffector.java b/src/com/characterforming/ribose/base/BaseReceptorEffector.java index a58821f..7557131 100644 --- a/src/com/characterforming/ribose/base/BaseReceptorEffector.java +++ b/src/com/characterforming/ribose/base/BaseReceptorEffector.java @@ -38,13 +38,16 @@ * {@link BaseEffector#invoke()} method provides the parameterless {@code invoke()} * method; subclasses may override this with their own {@code invoke()} implementation. *

- * A receptor effector can have only one parameterized form, which lists the transducer + * A receptor effector can have only one parametric form, which lists the transducer * fields to be received. It can be called from any transducer that expresses the same * fields, but the same fields must be supplied in each case. Subclass receiver fields * must be {@code public} and may be of any primitive Java type or a {@code byte[]} or - * {@code char[]} array. Each call to {@link #invoke(int)} overwrites the receiver - * fields in the effector with the converted value from the respective transducer fields, - * or with the default value if a transducer field is empty. + * {@code char[]} array. When the receptor effector is invoked it calls {@link + * BaseReceptorEffector#invoke(int)}, which overwrites the receiver fields in the + * effector with the converted value from the respective transducer fields, or with + * the default value if a transducer field is empty. The effector immediately dispatches + * the receiver field values into the target. The receiver field values are then stale + * and should not be used outside the scope of the effector's {@code #invoke()} method. *

* The subclass effector must call {@link setEffector(BaseReceptorEffector)} from * its constructor after calling the constructor for this base class. @@ -77,7 +80,7 @@ * * @author Kim Briggs */ -public abstract class BaseReceptorEffector extends BaseParameterizedEffector { +public abstract class BaseReceptorEffector extends BaseParametricEffector { private BaseReceptorEffector effector; @@ -103,7 +106,7 @@ protected void setEffector(BaseReceptorEffector effector) { this.effector = effector; } - @Override // @see com.characterforming.ribose.IParameterizedEffector#invoke(int) + @Override // @see com.characterforming.ribose.IParametricEffector#invoke(int) public int invoke(int parameter) throws EffectorException { assert parameter == 0; for (Receiver r : super.parameters[0]) { @@ -156,12 +159,12 @@ public int invoke(int parameter) throws EffectorException { return IEffector.RTX_NONE; } - @Override // @see com.characterforming.ribose.IParameterizedEffector#allocateParameters(int) + @Override // @see com.characterforming.ribose.IParametricEffector#allocateParameters(int) public Receiver[][] allocateParameters(int parameterCount) { return new Receiver[parameterCount][]; } - @Override // IParameterizedEffector#compileParameter(IToken[]) + @Override // IParametricEffector#compileParameter(IToken[]) public Receiver[] compileParameter(final IToken[] parameterList) throws TargetBindingException { if (super.parameters.length != 1) throw new TargetBindingException(String.format( diff --git a/src/com/characterforming/ribose/base/package-info.java b/src/com/characterforming/ribose/base/package-info.java index d8c55cc..23a6180 100644 --- a/src/com/characterforming/ribose/base/package-info.java +++ b/src/com/characterforming/ribose/base/package-info.java @@ -24,7 +24,7 @@ * Ribose operates on byte[] and {@link Signal} inputs. Input may include UTF-8 * encoded text and/or binary data. The {@link Bytes} wrapper class and {@link Base} * utility class are used extensively throughout the ribose compiler and runtime. - * The base classes {@link BaseEffector} and {@link BaseParameterizedEffector} + * The base classes {@link BaseEffector} and {@link BaseParametricEffector} * provide cross-cutting support to all effector subclasses. The {@link SimpleTarget} * provides a target that exposes the built-in {@link ITransductor} effectors and * can be used to construct simple models that do not require specialized effectors. diff --git a/src/com/characterforming/ribose/package-info.java b/src/com/characterforming/ribose/package-info.java index 5dd31a9..308e99d 100755 --- a/src/com/characterforming/ribose/package-info.java +++ b/src/com/characterforming/ribose/package-info.java @@ -20,23 +20,23 @@ * solely on the transductor effectors and express output through the {@code * out[..]} effector. Domain specific {@link ITarget} implementations may extend * the range of the transductor target with specialized {@link IEffector} and - * {@link IParameterizedEffector} implementations. All effectors receive a reference + * {@link IParametricEffector} implementations. All effectors receive a reference * to their respective target and an {@link IOutput} view that provides access * to extracted field output as raw bytes, common Java primitive, or Unicode text. *

- * {@link IEffector} and {@link IParameterizedEffector} classes are typically + * {@link IEffector} and {@link IParametricEffector} classes are typically * implemented as private inner classes of the target class. Every target class * must present a default constructor that instantiates a proxy instance * for effector parameter compilation. Parameters are compiled once when the * model is compiled, to validate the supplied parameters, and once again every * time the model is loaded for runtime use. Parameters are represented as lists of * backquoted Unicode {@code `tokens`} in ribose patterns and presented as arrays - * of UTF-8 {@code bytes} to parameterized effectors to compile. A parameterized + * of UTF-8 {@code bytes} to parametric effectors to compile. A parametric * effector {@code E} compiles from each token array an instance of {@code P}. * The runtime model retains the proxy target and supplies compiled parameters to live * effectors when a live target is bound to a transductor. These bindings (model:proxy * target, model:live target) persisti for the lifetime of the transductor. See - * {@link ITarget}, {@link IEffector} and {@link IParameterizedEffector} for more + * {@link ITarget}, {@link IEffector} and {@link IParametricEffector} for more * information regarding these classes in model compilation and runtime contexts. *

* A ribose model is simple if the model target class defines no specialized