KissBinary AI Skill v0.1.0

This Markdown file is a versioned AI skill for using KissBinary in other Java projects. It is intentionally self-contained so an AI assistant can load this one document, add the Maven dependency, write consumer code, and avoid inventing APIs.

Use this skill for release 0.1.0. If the repository source is on a later -SNAPSHOT, consumer documentation should still use 0.1.0 unless the user explicitly asks for a snapshot build.

Library Summary

Tiny zero-dependency Java 17+ binary IO helper for explicit primitive reads and writes, primitive arrays, endian-aware formats, magic bytes, version checks, and memory-mapped reads.

Maven Dependency

<dependency>
  <groupId>io.github.arthurhoch</groupId>
  <artifactId>kiss-binary</artifactId>
  <version>0.1.0</version>
</dependency>

AI Usage Rules

Target Java 17 or newer.
Prefer the public package rooted at io.github.arthurhoch.kissbinary.
Do not invent convenience APIs. Use only the public members listed in this file or in generated Javadocs for the same release.
Keep examples small and explicit, matching the KISS philosophy.
Do not add extra frameworks unless the consuming project already uses them.
Keep older skill files in place when a new release is documented.

Quick Example

BinaryWriter writer = BinaryWriter.create(Endianness.BIG_ENDIAN);
writer.writeMagic("KISS");
writer.writeVersion(1);
writer.writeInt(42);

BinaryReader reader = BinaryReader.from(writer.toByteArray(), Endianness.BIG_ENDIAN);
reader.expectMagic("KISS");
reader.expectVersion(1);
int value = reader.readInt();

How To Use The Library

BinaryWriter.create() creates an in-memory big-endian writer. BinaryWriter.create(Endianness) makes byte order explicit.
BinaryReader.from(byte[]) and BinaryReader.from(ByteBuffer) read sequentially from existing bytes. ByteBuffer input is read through the supplied/current byte order contract.
MappedBinaryReader.from(Path) maps a file for random-access reads by absolute offset. Always close it, preferably with try-with-resources.
Use writeMagic, expectMagic, writeVersion, readVersion, and expectVersion to make binary format boundaries explicit.
Instances are not documented as thread-safe. Keep one reader/writer per stream of work unless external synchronization is provided.

Behavioral Contract For v0.1.0

Endianness.BIG_ENDIAN is the default and matches Java/network byte order. Endianness.LITTLE_ENDIAN supports existing little-endian formats.
Primitive reads and writes are fixed-width: byte 1, boolean 1, char/short 2, int/float 4, long/double 8 bytes.
Boolean writes use 0 for false and 1 for true. Boolean reads expect that convention.
Array methods read/write raw contiguous primitive values; they do not include a length prefix. Callers must store and validate lengths explicitly.
toByteArray() returns a copy. writeTo(OutputStream) writes current contents and does not close the stream.
BinaryException represents invalid usage or IO failures. BinaryFormatException represents format mismatches and carries an offset when available.

Practical Examples

Length-prefixed payload

byte[] payload = "hello".getBytes(StandardCharsets.UTF_8);
BinaryWriter writer = BinaryWriter.create();
writer.writeInt(payload.length);
writer.writeBytes(payload);

BinaryReader reader = BinaryReader.from(writer.toByteArray());
byte[] copy = reader.readBytes(reader.readInt());

Mapped random access

try (MappedBinaryReader reader = MappedBinaryReader.from(Path.of("data.bin"), Endianness.LITTLE_ENDIAN)) {
    int count = reader.readInt(0);
    long firstOffset = reader.readLong(4);
}

Public API Specification

The following index is generated from compiled public classes with javap -public. It includes public constructors, constants, enum methods, record accessors, inherited Object overrides when public, and public nested classes.

When an internal package appears here, treat it as implementation detail unless the project documentation explicitly says otherwise. Consumer code should prefer the public surface described above.

public class io.github.arthurhoch.kissbinary.BinaryException extends java.lang.RuntimeException {
  public io.github.arthurhoch.kissbinary.BinaryException(java.lang.String);
  public io.github.arthurhoch.kissbinary.BinaryException(java.lang.String, java.lang.Throwable);
}

public class io.github.arthurhoch.kissbinary.BinaryFormatException extends io.github.arthurhoch.kissbinary.BinaryException {
  public io.github.arthurhoch.kissbinary.BinaryFormatException(java.lang.String);
  public io.github.arthurhoch.kissbinary.BinaryFormatException(long, java.lang.String);
  public io.github.arthurhoch.kissbinary.BinaryFormatException(long, java.lang.String, java.lang.Throwable);
  public long offset();
}

public final class io.github.arthurhoch.kissbinary.BinaryReader {
  public static io.github.arthurhoch.kissbinary.BinaryReader from(byte[]);
  public static io.github.arthurhoch.kissbinary.BinaryReader from(byte[], io.github.arthurhoch.kissbinary.Endianness);
  public static io.github.arthurhoch.kissbinary.BinaryReader from(java.nio.ByteBuffer);
  public static io.github.arthurhoch.kissbinary.BinaryReader from(java.nio.ByteBuffer, io.github.arthurhoch.kissbinary.Endianness);
  public byte readByte();
  public boolean readBoolean();
  public char readChar();
  public short readShort();
  public int readInt();
  public long readLong();
  public float readFloat();
  public double readDouble();
  public byte[] readByteArray(int);
  public byte[] readBytes(int);
  public void readFully(byte[]);
  public void readFully(byte[], int, int);
  public long skipBytes(long);
  public void skipFully(long);
  public short[] readShortArray(int);
  public void readShortArray(short[]);
  public void readShortArray(short[], int, int);
  public int[] readIntArray(int);
  public void readIntArray(int[]);
  public void readIntArray(int[], int, int);
  public long[] readLongArray(int);
  public void readLongArray(long[]);
  public void readLongArray(long[], int, int);
  public float[] readFloatArray(int);
  public void readFloatArray(float[]);
  public void readFloatArray(float[], int, int);
  public double[] readDoubleArray(int);
  public void readDoubleArray(double[]);
  public void readDoubleArray(double[], int, int);
  public char[] readCharArray(int);
  public void validateMagic(byte[]);
  public void expectMagic(java.lang.String);
  public int readVersion();
  public void validateVersion(int);
  public void expectVersion(int);
  public int position();
  public int remaining();
  public boolean hasRemaining();
}

public final class io.github.arthurhoch.kissbinary.BinaryWriter {
  public static io.github.arthurhoch.kissbinary.BinaryWriter create();
  public static io.github.arthurhoch.kissbinary.BinaryWriter create(io.github.arthurhoch.kissbinary.Endianness);
  public void writeByte(byte);
  public void writeByte(int);
  public void writeBoolean(boolean);
  public void writeChar(char);
  public void writeShort(short);
  public void writeInt(int);
  public void writeLong(long);
  public void writeFloat(float);
  public void writeDouble(double);
  public void writeByteArray(byte[]);
  public void writeBytes(byte[]);
  public void writeBytes(byte[], int, int);
  public void writeShortArray(short[]);
  public void writeIntArray(int[]);
  public void writeLongArray(long[]);
  public void writeFloatArray(float[]);
  public void writeDoubleArray(double[]);
  public void writeCharArray(char[]);
  public void writeMagic(java.lang.String);
  public void writeVersion(int);
  public void writeTo(java.io.OutputStream);
  public byte[] toByteArray();
  public int size();
  public int position();
}

public final class io.github.arthurhoch.kissbinary.Endianness extends java.lang.Enum<io.github.arthurhoch.kissbinary.Endianness> {
  public static final io.github.arthurhoch.kissbinary.Endianness BIG_ENDIAN;
  public static final io.github.arthurhoch.kissbinary.Endianness LITTLE_ENDIAN;
  public static io.github.arthurhoch.kissbinary.Endianness[] values();
  public static io.github.arthurhoch.kissbinary.Endianness valueOf(java.lang.String);
}

public final class io.github.arthurhoch.kissbinary.MappedBinaryReader implements java.lang.AutoCloseable {
  public static io.github.arthurhoch.kissbinary.MappedBinaryReader from(java.nio.file.Path);
  public static io.github.arthurhoch.kissbinary.MappedBinaryReader from(java.nio.file.Path, io.github.arthurhoch.kissbinary.Endianness);
  public byte readByte(long);
  public boolean readBoolean(long);
  public char readChar(long);
  public short readShort(long);
  public int readInt(long);
  public long readLong(long);
  public float readFloat(long);
  public double readDouble(long);
  public byte[] readByteArray(long, int);
  public void readBytes(long, byte[], int, int);
  public short[] readShortArray(long, int);
  public void readShortArray(long, short[]);
  public void readShortArray(long, short[], int, int);
  public int[] readIntArray(long, int);
  public void readIntArray(long, int[]);
  public void readIntArray(long, int[], int, int);
  public long[] readLongArray(long, int);
  public void readLongArray(long, long[]);
  public void readLongArray(long, long[], int, int);
  public float[] readFloatArray(long, int);
  public void readFloatArray(long, float[]);
  public void readFloatArray(long, float[], int, int);
  public double[] readDoubleArray(long, int);
  public void readDoubleArray(long, double[]);
  public void readDoubleArray(long, double[], int, int);
  public char[] readCharArray(long, int);
  public void validateMagic(long, byte[]);
  public void expectMagic(java.lang.String);
  public void validateVersion(long, int);
  public long size();
  public void close();
}

Local Verification Commands

Run these commands in the KissBinary repository when changing examples, docs, or release skill files:

mvn -B clean verify
mvn -B javadoc:javadoc

Release Skill Maintenance

For a future release such as 0.2.0, create a new file at docs/skills/v0.2.0.md instead of editing or deleting this historical file. Update docs/skills/index.md with a view link and a raw download link for the new version.