Skip to content

Commit

Permalink
Renamed "EndianBinaryReader" to "SchemaBinaryReader", "EndianBinaryWr…
Browse files Browse the repository at this point in the history
…iter" to "SchemaBinaryWriter", and "TextReader" to "SchemaTextReader" for consistency.
  • Loading branch information
MeltyPlayer committed Oct 20, 2023
1 parent a513626 commit 92f11cc
Show file tree
Hide file tree
Showing 88 changed files with 1,017 additions and 1,072 deletions.
11 changes: 5 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,16 +47,15 @@ Any readonly primitives will treated as assertions, which is useful for validati

For complicated schema classes, such as ones that use decompression logic or pointers, you'll need to implement the read/write logic manually.

Specifically, you'll need to implement both a `Read(IEndianBinaryReader er)` and `Write(ISubEndianBinaryWriter ew)` method.
The `EndianBinaryReader` and `EndianBinaryWriter` classes provide many helpful methods for reading/writing a number of different primitive formats, including basic ones such as `byte`/`int`/`float`, but also more complex/unique ones such as `Half` (two-byte float) and `un16` (unsigned normalized 16-bit float).
Specifically, you'll need to implement both a `Read(IBinaryReader br)` and `Write(ISubBinaryWriter bw)` method.
The `SchemaBinaryReader` and `SchemaBinaryWriter` classes provide many helpful methods for reading/writing a number of different primitive formats, including basic ones such as `byte`/`int`/`float`, but also more complex/unique ones such as `Half` (two-byte float) and `un16` (unsigned normalized 16-bit float).

Similar to the automatic process, you can nest schema classes and manually read/write them by calling their `Read()`/`Write()` methods.
This can allow you to automatically generate subsections, so only the most complex logic needs to be manually written.

### How to use a binary schema class

To convert a given schema class to or from binary, simply instantiate an `EndianBinaryReader` or `EndianBinaryWriter` and pass it into the corresponding `Read()` or `Write()` methods in the schema class.
You must use the `EndianBinaryReader`/`EndianBinaryWriter` defined within this project, as this adds more functionality.
To convert a given schema class to or from binary, simply instantiate an `SchemaBinaryReader` or `SchemaBinaryWriter` and pass it into the corresponding `Read()` or `Write()` methods in the schema class.

### Supported Attributes

Expand All @@ -66,7 +65,7 @@ The following attributes are currently supported in this library **when automati

#### Align

Specifies how a field or property's offset (relative to the start of the stream) should be aligned when reading/writing. If misaligned, the `EndianBinaryReader`/`EndianBinaryWriter` will automatically insert the remaining bytes of padding. For example, `[Align(4)]` would force a field/property's starting offset to be a multiple of 4 (0, 4, 8, 12, 16, etc.).
Specifies how a field or property's offset (relative to the start of the stream) should be aligned when reading/writing. If misaligned, the `SchemaBinaryReader`/`SchemaBinaryWriter` will automatically insert the remaining bytes of padding. For example, `[Align(4)]` would force a field/property's starting offset to be a multiple of 4 (0, 4, 8, 12, 16, etc.).
```cs
[Align(4)]
public int alignedField;
Expand All @@ -77,7 +76,7 @@ public int AlignedProperty { get; set; }

#### Endianness

Forces a type, field, or property to be read/written with a given [endianness](https://en.wikipedia.org/wiki/Endianness) (big-endian or little-endian). Tracked via a stack within the `EndianBinaryReader`/`EndianBinaryWriter`. If unspecified, will use whatever endianness was last specified in the stack (or the system endianness by default).
Forces a type, field, or property to be read/written with a given [endianness](https://en.wikipedia.org/wiki/Endianness) (big-endian or little-endian). Tracked via a stack within the `SchemaBinaryReader`/`SchemaBinaryWriter`. If unspecified, will use whatever endianness was last specified in the stack (or the system endianness by default).
```cs
[BinarySchema]
[Endianness(Endianness.BigEndian)]
Expand Down
12 changes: 6 additions & 6 deletions Schema Build Tests/attributes/sequence/ClassSequenceTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -52,11 +52,11 @@ public void TestWriteAndReadArrayObject() {

var endianness = Endianness.BigEndian;

var ew = new EndianBinaryWriter(endianness);
var ew = new SchemaBinaryWriter(endianness);
expectedSw.Write(ew);
ew.CompleteAndCopyToDelayed(ms).Wait();

var er = new EndianBinaryReader(ms, endianness);
var er = new SchemaBinaryReader(ms, endianness);
er.Position = 0;
var actualSws = er.ReadNew<StructArraySequenceWrapper>();
Assert.AreEqual(expectedSw, actualSws);
Expand All @@ -77,11 +77,11 @@ public void TestWriteAndReadArrayValues() {

var endianness = Endianness.BigEndian;

var ew = new EndianBinaryWriter(endianness);
var ew = new SchemaBinaryWriter(endianness);
expectedSw.Write(ew);
ew.CompleteAndCopyToDelayed(ms).Wait();

var er = new EndianBinaryReader(ms, endianness);
var er = new SchemaBinaryReader(ms, endianness);
er.Position = 1;
var actualSws = er.ReadNewArray<SchemaClass>(expectedSw.Values.Length);
Assert.True(expectedSw.Values.SequenceEqual(actualSws));
Expand Down Expand Up @@ -118,12 +118,12 @@ public void TestWriteAndReadListObject() {

var endianness = Endianness.BigEndian;

var ew = new EndianBinaryWriter(endianness);
var ew = new SchemaBinaryWriter(endianness);
expectedSw.Write(ew);
ew.CompleteAndCopyToDelayed(ms).Wait();

ms.Position = 0;
var er = new EndianBinaryReader(ms, endianness);
var er = new SchemaBinaryReader(ms, endianness);
var actualSw = er.ReadNew<StructListSequenceWrapper>();
Assert.AreEqual(expectedSw, actualSw);
}
Expand Down
8 changes: 4 additions & 4 deletions Schema Build Tests/attributes/sequence/ISequenceTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -39,14 +39,14 @@ public void TestWriteAndRead1() {
var ms = new MemoryStream();

var endianness = Endianness.BigEndian;
var ew = new EndianBinaryWriter(endianness);
var ew = new SchemaBinaryWriter(endianness);

expectedSw.Write(ew);
ew.CompleteAndCopyToDelayed(ms).Wait();
Assert.AreEqual(4 + 9 * 4, ms.Position);

ms.Position = 0;
var er = new EndianBinaryReader(ms, endianness);
var er = new SchemaBinaryReader(ms, endianness);
var actualSw = er.ReadNew<MutableSequenceWrapper1>();

Assert.AreEqual(expectedSw, actualSw);
Expand Down Expand Up @@ -82,14 +82,14 @@ public void TestWriteAndRead2() {
var ms = new MemoryStream();

var endianness = Endianness.BigEndian;
var ew = new EndianBinaryWriter(endianness);
var ew = new SchemaBinaryWriter(endianness);

expectedSw.Write(ew);
ew.CompleteAndCopyToDelayed(ms).Wait();
Assert.AreEqual(4 + 9 * 4, ms.Position);

ms.Position = 0;
var er = new EndianBinaryReader(ms, endianness);
var er = new SchemaBinaryReader(ms, endianness);
var actualSw = er.ReadNew<MutableSequenceWrapper2>();

Assert.AreEqual(expectedSw, actualSw);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -34,12 +34,12 @@ public void TestWriteAndReadBytes() {

var endianness = Endianness.BigEndian;

var ew = new EndianBinaryWriter(endianness);
var ew = new SchemaBinaryWriter(endianness);
expectedSw.Write(ew);
ew.CompleteAndCopyToDelayed(ms).Wait();

ms.Position = 0;
var er = new EndianBinaryReader(ms, endianness);
var er = new SchemaBinaryReader(ms, endianness);
var actualSw = er.ReadNew<ByteSequenceWrapper>();
Assert.AreEqual(expectedSw, actualSw);
}
Expand All @@ -52,7 +52,7 @@ public void TestWriteAndReadBytesInSubstream() {
};

var ms = new MemoryStream(bytes);
var er = new EndianBinaryReader(ms);
var er = new SchemaBinaryReader(ms);

ByteSequenceWrapper actualSw = default;
er.SubreadAt(3,
Expand All @@ -77,7 +77,7 @@ public void TestWriteAndReadBytesInLocalSubstream() {
};

var ms = new MemoryStream(bytes);
var er = new EndianBinaryReader(ms);
var er = new SchemaBinaryReader(ms);

er.Position = 1;
er.PushLocalSpace();
Expand Down Expand Up @@ -124,12 +124,12 @@ public void TestWriteAndReadInts() {

var endianness = Endianness.BigEndian;

var ew = new EndianBinaryWriter(endianness);
var ew = new SchemaBinaryWriter(endianness);
expectedSw.Write(ew);
ew.CompleteAndCopyToDelayed(ms).Wait();

ms.Position = 0;
var er = new EndianBinaryReader(ms, endianness);
var er = new SchemaBinaryReader(ms, endianness);
var actualSw = er.ReadNew<IntSequenceWrapper>();
Assert.AreEqual(expectedSw, actualSw);
}
Expand Down Expand Up @@ -185,12 +185,12 @@ public void TestWriteAndReadClasses() {

var endianness = Endianness.BigEndian;

var ew = new EndianBinaryWriter(endianness);
var ew = new SchemaBinaryWriter(endianness);
expectedSw.Write(ew);
ew.CompleteAndCopyToDelayed(ms).Wait();

ms.Position = 0;
var er = new EndianBinaryReader(ms, endianness);
var er = new SchemaBinaryReader(ms, endianness);
var actualSw = er.ReadNew<FloatClassSequenceWrapper>();
Assert.AreEqual(expectedSw, actualSw);
}
Expand Down Expand Up @@ -244,7 +244,7 @@ public void TestWriteAndReadClassesInLocalSubstream() {
};

var ms = new MemoryStream(bytes);
var er = new EndianBinaryReader(ms);
var er = new SchemaBinaryReader(ms);

er.Position = 1;
er.PushLocalSpace();
Expand Down
16 changes: 8 additions & 8 deletions Schema Build Tests/attributes/sequence/SequenceTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -32,12 +32,12 @@ public void TestWriteAndRead() {

var endianness = Endianness.BigEndian;

var ew = new EndianBinaryWriter(endianness);
var ew = new SchemaBinaryWriter(endianness);
expectedSw.Write(ew);
ew.CompleteAndCopyToDelayed(ms).Wait();

ms.Position = 0;
var er = new EndianBinaryReader(ms, endianness);
var er = new SchemaBinaryReader(ms, endianness);
var actualSw = er.ReadNew<SequenceWrapper>();
Assert.AreEqual(expectedSw, actualSw);
}
Expand Down Expand Up @@ -68,12 +68,12 @@ public void TestWriteAndReadWithUint32Length() {

var endianness = Endianness.BigEndian;

var ew = new EndianBinaryWriter(endianness);
var ew = new SchemaBinaryWriter(endianness);
expectedSw.Write(ew);
ew.CompleteAndCopyToDelayed(ms).Wait();

ms.Position = 0;
var er = new EndianBinaryReader(ms, endianness);
var er = new SchemaBinaryReader(ms, endianness);
var actualSw = er.ReadNew<Uint32LengthSequenceWrapper>();
Assert.AreEqual(expectedSw, actualSw);
}
Expand Down Expand Up @@ -107,12 +107,12 @@ public void TestWriteAndReadWithUint16Length() {

var endianness = Endianness.BigEndian;

var ew = new EndianBinaryWriter(endianness);
var ew = new SchemaBinaryWriter(endianness);
expectedSw.Write(ew);
ew.CompleteAndCopyToDelayed(ms).Wait();

ms.Position = 0;
var er = new EndianBinaryReader(ms, endianness);
var er = new SchemaBinaryReader(ms, endianness);
var actualSw = er.ReadNew<Uint16LengthSequenceWrapper>();
Assert.AreEqual(expectedSw, actualSw);
}
Expand Down Expand Up @@ -146,12 +146,12 @@ public void TestWriteAndReadWithUint64Length() {

var endianness = Endianness.BigEndian;

var ew = new EndianBinaryWriter(endianness);
var ew = new SchemaBinaryWriter(endianness);
expectedSw.Write(ew);
ew.CompleteAndCopyToDelayed(ms).Wait();

ms.Position = 0;
var er = new EndianBinaryReader(ms, endianness);
var er = new SchemaBinaryReader(ms, endianness);
var actualSw = er.ReadNew<Uint64LengthSequenceWrapper>();
Assert.AreEqual(expectedSw, actualSw);
}
Expand Down
12 changes: 6 additions & 6 deletions Schema Build Tests/attributes/sequence/StructSequenceTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -51,11 +51,11 @@ public void TestWriteAndReadArrayObject() {

var endianness = Endianness.BigEndian;

var ew = new EndianBinaryWriter(endianness);
var ew = new SchemaBinaryWriter(endianness);
expectedSw.Write(ew);
ew.CompleteAndCopyToDelayed(ms).Wait();

var er = new EndianBinaryReader(ms, endianness);
var er = new SchemaBinaryReader(ms, endianness);
er.Position = 0;
var actualSws = er.ReadNew<StructArraySequenceWrapper>();
Assert.AreEqual(expectedSw, actualSws);
Expand All @@ -75,11 +75,11 @@ public void TestWriteAndReadArrayValues() {

var endianness = Endianness.BigEndian;

var ew = new EndianBinaryWriter(endianness);
var ew = new SchemaBinaryWriter(endianness);
expectedSw.Write(ew);
ew.CompleteAndCopyToDelayed(ms).Wait();

var er = new EndianBinaryReader(ms, endianness);
var er = new SchemaBinaryReader(ms, endianness);
er.Position = 1;
var actualSws = er.ReadNewArray<SchemaStruct>(expectedSw.Values.Length);
Assert.True(expectedSw.Values.SequenceEqual(actualSws));
Expand Down Expand Up @@ -112,12 +112,12 @@ public void TestWriteAndReadListObject() {

var endianness = Endianness.BigEndian;

var ew = new EndianBinaryWriter(endianness);
var ew = new SchemaBinaryWriter(endianness);
expectedSw.Write(ew);
ew.CompleteAndCopyToDelayed(ms).Wait();

ms.Position = 0;
var er = new EndianBinaryReader(ms, endianness);
var er = new SchemaBinaryReader(ms, endianness);
var actualSw = er.ReadNew<StructListSequenceWrapper>();
Assert.AreEqual(expectedSw, actualSw);
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -40,13 +40,13 @@ public void TestWriteAndRead() {
var ms = new MemoryStream();

var endianness = Endianness.BigEndian;
var ew = new EndianBinaryWriter(endianness);
var ew = new SchemaBinaryWriter(endianness);

expectedSw.Write(ew);
ew.CompleteAndCopyToDelayed(ms).Wait();

ms.Position = 0;
var er = new EndianBinaryReader(ms, endianness);
var er = new SchemaBinaryReader(ms, endianness);
var actualSw = er.ReadNew<StringWrapper>();

Assert.AreEqual(expectedSw, actualSw);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -44,13 +44,13 @@ public void TestWriteAndReadMultiple() {
var ms = new MemoryStream();

var endianness = Endianness.BigEndian;
var ew = new EndianBinaryWriter(endianness);
var ew = new SchemaBinaryWriter(endianness);

expectedSw.Write(ew);
ew.CompleteAndCopyToDelayed(ms).Wait();

ms.Position = 0;
var er = new EndianBinaryReader(ms, endianness);
var er = new SchemaBinaryReader(ms, endianness);
var actualSw = er.ReadNew<MultipleStringWrapper>();

Assert.AreEqual(expectedSw, actualSw);
Expand Down
10 changes: 4 additions & 6 deletions Schema Build Tests/build/PointerToTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -30,13 +30,11 @@ public async Task TestPointerToThroughParent() {
var parent = new ParentImpl();
parent.Field = 12;

var ew = new EndianBinaryWriter();
parent.Write(ew);
var bw = new SchemaBinaryWriter();
parent.Write(bw);

var bytes = await BinarySchemaAssert.GetEndianBinaryWriterBytes(ew);
BinarySchemaAssert.AssertSequence(
bytes,
new byte[] { 1, 12, 0, 0, 0 });
var bytes = await BinarySchemaAssert.GetEndianBinaryWriterBytes(bw);
CollectionAssert.AreEqual(new byte[] { 1, 12, 0, 0, 0 }, bytes);
}
}
}
10 changes: 4 additions & 6 deletions Schema Build Tests/build/SizeOfMemberInBytesTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -30,13 +30,11 @@ public async Task TestSizeOfThroughParent() {
var parent = new ParentImpl();
parent.Field = 12;

var ew = new EndianBinaryWriter();
parent.Write(ew);
var bw = new SchemaBinaryWriter();
parent.Write(bw);

var bytes = await BinarySchemaAssert.GetEndianBinaryWriterBytes(ew);
BinarySchemaAssert.AssertSequence(
bytes,
new byte[] {4, 12, 0, 0, 0});
var bytes = await BinarySchemaAssert.GetEndianBinaryWriterBytes(bw);
CollectionAssert.AreEqual(new byte[] { 4, 12, 0, 0, 0 }, bytes);
}
}
}
4 changes: 2 additions & 2 deletions Schema Build Tests/build/StructBuildTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -45,13 +45,13 @@ public void TestWriteAndRead() {
var ms = new MemoryStream();

var endianness = Endianness.BigEndian;
var ew = new EndianBinaryWriter(endianness);
var ew = new SchemaBinaryWriter(endianness);

expectedSw.Write(ew);
ew.CompleteAndCopyToDelayed(ms).Wait();

ms.Position = 0;
var er = new EndianBinaryReader(ms, endianness);
var er = new SchemaBinaryReader(ms, endianness);
var actualSw = er.ReadNew<StructWrapper>();

Assert.AreEqual(expectedSw, actualSw);
Expand Down
6 changes: 3 additions & 3 deletions Schema Build Tests/build/Types.cs
Original file line number Diff line number Diff line change
Expand Up @@ -76,8 +76,8 @@ public interface IMagicSection<T> {

public class MagicSectionStub<T> : IMagicSection<T>, IBinaryConvertible {
public T Data { get; set; }
public void Write(ISubEndianBinaryWriter ew) { }
public void Read(IEndianBinaryReader er) { }
public void Write(ISubBinaryWriter ew) { }
public void Read(IBinaryReader br) { }
}

[BinarySchema]
Expand All @@ -94,6 +94,6 @@ public partial class SwitchMagicStringUInt32SizedSection<T> : IMagicSection<T>
[Ignore]
public T Data => this.impl_.Data;

public void Read(IEndianBinaryReader er) { }
public void Read(IBinaryReader br) { }
}
}
Loading

0 comments on commit 92f11cc

Please sign in to comment.