---
layout: default
title: KissBinary AI Skill
library: kiss-binary
skill_version: 0.1.0
release_version: 0.1.0
maven: io.github.arthurhoch:kiss-binary:0.1.0
java: "17+"
format: markdown
---

# 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 <code>-SNAPSHOT</code>, consumer documentation should still use <code>0.1.0</code> 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

~~~xml
<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 <code>io.github.arthurhoch.kissbinary</code>.
- 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

~~~java
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

~~~java
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

~~~java
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 <code>javap -public</code>. It includes public constructors, constants, enum methods, record accessors, inherited Object overrides when public, and public nested classes.

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

~~~text
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:

~~~bash
mvn -B clean verify
mvn -B javadoc:javadoc
~~~

## Release Skill Maintenance

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