From 5d4302973283b7ce4fabefc28b9cfc9d1a133325 Mon Sep 17 00:00:00 2001 From: Anton Shvetz Date: Fri, 22 Dec 2023 20:20:23 +0300 Subject: [PATCH] Update API documentation --- .../module-info.java | 5 ++++ .../coneforest.psylla.tools/module-info.java | 1 + .../coneforest/psylla/NamespacePool.java | 1 + .../coneforest/psylla/OperatorType.java | 1 - .../coneforest/psylla/Psylla.java | 7 ++---- .../coneforest/psylla/Version.java | 4 ++-- .../coneforest/psylla/core/PsyArray.java | 23 +++++++++++++++---- .../coneforest/psylla/core/PsyBitwise.java | 4 ++++ .../coneforest/psylla/core/PsyContext.java | 5 ++++ .../psylla/core/PsyFormalArray.java | 14 +++++++++++ .../java/coneforest.psylla/module-info.java | 1 + .../coneforest/psylla/Parser.jj | 15 ++++++++++++ 12 files changed, 69 insertions(+), 12 deletions(-) diff --git a/src/examples/java/coneforest.psylla.examples/module-info.java b/src/examples/java/coneforest.psylla.examples/module-info.java index 09f5aa799..5229faacf 100644 --- a/src/examples/java/coneforest.psylla.examples/module-info.java +++ b/src/examples/java/coneforest.psylla.examples/module-info.java @@ -1,3 +1,8 @@ +/** +* The Psylla example code. +* +* @author Anton Shvetz ‹shvetz.anton@gmail.com› +*/ module coneforest.psylla.examples { exports coneforest.psylla.examples; diff --git a/src/main/java/coneforest.psylla.tools/module-info.java b/src/main/java/coneforest.psylla.tools/module-info.java index 619177e8a..7679bf628 100644 --- a/src/main/java/coneforest.psylla.tools/module-info.java +++ b/src/main/java/coneforest.psylla.tools/module-info.java @@ -2,6 +2,7 @@ * The Psylla language tools. * * @author Anton Shvetz ‹shvetz.anton@gmail.com› +* @provides java.util.spi.ToolProvider */ module coneforest.psylla.tools { diff --git a/src/main/java/coneforest.psylla/coneforest/psylla/NamespacePool.java b/src/main/java/coneforest.psylla/coneforest/psylla/NamespacePool.java index ee50446f8..646ebc58d 100644 --- a/src/main/java/coneforest.psylla/coneforest/psylla/NamespacePool.java +++ b/src/main/java/coneforest.psylla/coneforest/psylla/NamespacePool.java @@ -12,6 +12,7 @@ public class NamespacePool * Allocates (if absent) and returns the {@code namespace} object with the given prefix. * * @param prefix the prefix. + * @return the {@code namespace} object. */ public PsyNamespace get(final String prefix) { diff --git a/src/main/java/coneforest.psylla/coneforest/psylla/OperatorType.java b/src/main/java/coneforest.psylla/coneforest/psylla/OperatorType.java index 8923bfb11..8736b7680 100644 --- a/src/main/java/coneforest.psylla/coneforest/psylla/OperatorType.java +++ b/src/main/java/coneforest.psylla/coneforest/psylla/OperatorType.java @@ -6,7 +6,6 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; -//@Target({/*ElementType.TYPE, */ElementType.TYPE_USE}) @Documented @Target(ElementType.FIELD) @Retention(RetentionPolicy.RUNTIME) diff --git a/src/main/java/coneforest.psylla/coneforest/psylla/Psylla.java b/src/main/java/coneforest.psylla/coneforest/psylla/Psylla.java index 36f74a51d..a6f19d9c9 100644 --- a/src/main/java/coneforest.psylla/coneforest/psylla/Psylla.java +++ b/src/main/java/coneforest.psylla/coneforest/psylla/Psylla.java @@ -227,19 +227,16 @@ private static void showVersion() private static void showConfig(final List patterns) { - final Set propertyNames=Config.stringPropertyNames(); - + final var propertyNames=Config.stringPropertyNames(); for(final String pattern: patterns) - { propertyNames.stream() .sorted() .filter(name->Globs.matches(pattern, name)) .forEach(name->System.out.println(name+"=\'"+Config.getProperty(name)+"\'")); - } System.exit(0); } - private static class PsyllaConfig + public static class PsyllaConfig { private void setScriptReader(final Reader scriptReader) { diff --git a/src/main/java/coneforest.psylla/coneforest/psylla/Version.java b/src/main/java/coneforest.psylla/coneforest/psylla/Version.java index 4fe1a6d7d..23f65abfe 100644 --- a/src/main/java/coneforest.psylla/coneforest/psylla/Version.java +++ b/src/main/java/coneforest.psylla/coneforest/psylla/Version.java @@ -1,9 +1,9 @@ package coneforest.psylla; /** -* A class holding versioning information. +* Versioning information. */ -public class Version +public interface Version { /** * Returns the version string. diff --git a/src/main/java/coneforest.psylla/coneforest/psylla/core/PsyArray.java b/src/main/java/coneforest.psylla/coneforest/psylla/core/PsyArray.java index d46f5ba15..33818b9ab 100644 --- a/src/main/java/coneforest.psylla/coneforest/psylla/core/PsyArray.java +++ b/src/main/java/coneforest.psylla/coneforest/psylla/core/PsyArray.java @@ -48,12 +48,12 @@ public PsyArray psyClone() } @Override - public PsyObject get(final int indexValue) + public PsyObject get(final int index) throws PsyRangeCheckException { try { - return array.get(indexValue<0? indexValue+length(): indexValue); + return array.get(index<0? index+length(): index); } catch(final IndexOutOfBoundsException ex) { @@ -187,14 +187,29 @@ public void psySetLength(final PsyInteger oLength) } } + /** + * Sorts this list according to the order induced by the specified comparator. The sort is + * stable: this method must not reorder equal elements. + * + * @param oComparator the {@code proc} comparator used to compare array elements. + * @param oContext the execution context. + */ public void psySort(final PsyProc oComparator, final PsyContext oContext) { - Collections.sort(array, oComparator.asComparator(oContext)); + array.sort(oComparator.asComparator(oContext)); } + /** + * Searches this array for the specified value using the binary search algorithm. The array + * must be sorted into ascending order according to the specified comparator. TODO + * + * @param o the value to be searched for. + * @param oComparator the comparator by which the array is ordered. + * @param oContext the execution context. + * @return TODO + */ public PsyInteger psyBinarySearch(final PsyObject o, final PsyProc oComparator, final PsyContext oContext) { - final var opstack=oContext.operandStack(); return PsyInteger.of(Collections.binarySearch(array, o, oComparator.asComparator(oContext))); } diff --git a/src/main/java/coneforest.psylla/coneforest/psylla/core/PsyBitwise.java b/src/main/java/coneforest.psylla/coneforest/psylla/core/PsyBitwise.java index d94025388..909a8e82f 100644 --- a/src/main/java/coneforest.psylla/coneforest/psylla/core/PsyBitwise.java +++ b/src/main/java/coneforest.psylla/coneforest/psylla/core/PsyBitwise.java @@ -21,6 +21,7 @@ public interface PsyBitwise * @param oBit the index of bit to clear. * @return a {@code bitwise} whose value is equivalent to this value with * the designated bit cleared. + * @throws PsyRangeCheckException if the index is out of range. */ public PsyBitwise psyClearBit(final PsyInteger oBit) throws PsyRangeCheckException; @@ -32,6 +33,7 @@ public PsyBitwise psyClearBit(final PsyInteger oBit) * @param oBit the index of bit to flip. * @return a {@code bitwise} whose value is equivalent to this value with * the designated bit flipped. + * @throws PsyRangeCheckException if the index is out of range. */ public PsyBitwise psyFlipBit(final PsyInteger oBit) throws PsyRangeCheckException; @@ -43,6 +45,7 @@ public PsyBitwise psyFlipBit(final PsyInteger oBit) * @param oBit the index of bit to set. * @return a {@code bitwise} whose value is equivalent to this value with * the designated bit set. + * @throws PsyRangeCheckException if the index is out of range. */ public PsyBitwise psySetBit(final PsyInteger oBit) throws PsyRangeCheckException; @@ -52,6 +55,7 @@ public PsyBitwise psySetBit(final PsyInteger oBit) * * @param oBit the index of bit to test. * @return a {@code boolean} indicating if the designated bit set. + * @throws PsyRangeCheckException if the index is out of range. */ public PsyBoolean psyTestBit(final PsyInteger oBit) throws PsyRangeCheckException; diff --git a/src/main/java/coneforest.psylla/coneforest/psylla/core/PsyContext.java b/src/main/java/coneforest.psylla/coneforest/psylla/core/PsyContext.java index 9f47a8da3..8336ff055 100644 --- a/src/main/java/coneforest.psylla/coneforest/psylla/core/PsyContext.java +++ b/src/main/java/coneforest.psylla/coneforest/psylla/core/PsyContext.java @@ -90,6 +90,11 @@ public void fork() */ public NamespacePool namespacePool(); + /** + * Returns the size of the execution stack. + * + * @return the size of the execution stack. + */ public int execLevel(); /** diff --git a/src/main/java/coneforest.psylla/coneforest/psylla/core/PsyFormalArray.java b/src/main/java/coneforest.psylla/coneforest/psylla/core/PsyFormalArray.java index 1749a8222..98ae4b7ab 100644 --- a/src/main/java/coneforest.psylla/coneforest/psylla/core/PsyFormalArray.java +++ b/src/main/java/coneforest.psylla/coneforest/psylla/core/PsyFormalArray.java @@ -42,10 +42,18 @@ default public PsyFormalArray psyReverse() @Override default public PsyBoolean psyKnown(final PsyInteger oIndex) { + // TODO: index<0 long index=oIndex.longValue(); return PsyBoolean.of(index>=0 && index