From 9b398112066ed862d745de97f9603d3b4cec3055 Mon Sep 17 00:00:00 2001 From: brent saner Date: Wed, 10 Jul 2024 00:40:12 -0400 Subject: [PATCH] v1.0.1 FIX: * Cleaned up some documentation --- README.adoc | 2 +- README.html | 6 +++--- consts.go | 15 ++++++++++----- funcs_request.go | 12 ++++++------ funcs_requestrecord.go | 2 +- funcs_requestrecordgroup.go | 4 ++-- funcs_response.go | 10 +++++----- funcs_responserecordgroup.go | 4 ++-- 8 files changed, 30 insertions(+), 25 deletions(-) diff --git a/README.adoc b/README.adoc index da5392d..78912ab 100644 --- a/README.adoc +++ b/README.adoc @@ -52,7 +52,7 @@ The following are a wishlist or things planned that may come in later versions. * More clear errors ** Currently during e.g. `UnmarshalBinary` calls, just an `io.EOF` will be returned if the buffer is exhausted early. This may be able to be a little more context-helpful by using the `Err*` errors. * Confirmation of read/write sizes in buffers -** We know the sizes they *should* be, there's no reason to not confirm it. +** The sizes they *should* be are known, there's no reason to not confirm it. * Goroutines ** This of course won't work for serializing and keeping *order* of children (e.g. RG => Record); that'd still need to be ordered, but it will allow for parallel parsing *of* those children. Should benchmark, though; it may not be worth it. * `context.Context` support for `Read*` and `Write*` funcs diff --git a/README.html b/README.html index 29a0542..2de4e18 100644 --- a/README.html +++ b/README.html @@ -555,7 +555,7 @@ pre.rouge .gs {
Brent Saner

-Last rendered 2024-07-10 00:18:53 -0400 +Last rendered 2024-07-10 00:40:13 -0400
Table of Contents
@@ -630,7 +630,7 @@ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
  • -

    We know the sizes they should be, there’s no reason to not confirm it.

    +

    The sizes they should be are known, there’s no reason to not confirm it.

@@ -662,7 +662,7 @@ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
diff --git a/consts.go b/consts.go index 262ed15..cced0e8 100644 --- a/consts.go +++ b/consts.go @@ -12,11 +12,14 @@ var ( ) const ( + // IndentDefault is the [IndentChars] to use if not specified. IndentDefault string = "\t" + // SeperatorDefault is the [SeperatorChars] to use if not specified. SeparatorDefault string = " " - maxByteLine int = 12 // split if a value is more than this number of bytes.. + maxByteLine int = 12 // (Split a hex string in a Model if a value is more than this number of bytes.) ) +// Default indent levels. const ( indentR uint = iota indentRG @@ -26,18 +29,18 @@ const ( const indentOrigRec uint = 2 const ( - // ProtoVersion specifies the protocol version for the specification of a Message. + // ProtoVersion specifies the protocol version for the specification of a [Message]. ProtoVersion uint32 = 1 ) const ( // PackedNumSize is the size (length of bytes) of a packed unsigned integer. - PackedNumSize int = 4 // They're all uint32's. + PackedNumSize int = 4 // (They're all uint32's.) // CksumPackedSize is the size (length of bytes) of the checksum algorithm used. - CksumPackedSize int = 4 // CRC32 is a big-endian uint32, but if we use a different algo we need to change this. + CksumPackedSize int = 4 // CRC32 is represented by a big-endian uint32, but if a different algo is used, this will need to be changed. ) -// See https://square-r00t.net/ascii.html for further details. +// See https://square-r00t.net/ascii.html for further details on ASCII symbols. const ( AsciiNUL uint8 = iota // 0x00 AsciiSOH // 0x01 @@ -73,6 +76,7 @@ const ( AsciiUS // 0x1f ) +// Response Status indicator bytes. const ( RespStatusByteOK uint8 = AsciiACK RespStatusByteErr = AsciiNAK @@ -95,5 +99,6 @@ var ( ) const ( + // WriteChunkSize is the default size of chunking to use (in bytes) when using chunked Write* functions (i.e. non-segmented). WriteChunkSize int = 1024 ) diff --git a/funcs_request.go b/funcs_request.go index 0693916..b955b41 100644 --- a/funcs_request.go +++ b/funcs_request.go @@ -34,7 +34,7 @@ func (r *Request) MarshalBinary() (data []byte, err error) { msgSize += i.Size() } - // The message "body" - we do this first so we can checksum (if not nil). + // The message "body" - this is done first so the body can be checksummed (if not nil). if _, err = msgBuf.Write(hdrBODYSTART); err != nil { return } @@ -307,14 +307,14 @@ func (r *Request) UnmarshalBinary(data []byte) (err error) { } r.Checksum = new(uint32) *r.Checksum = byteOrder.Uint32(b) - // Since we've only read the checksum, we now also have to read in the MSGSTART... + // Since only the checksum has been read, now read the MSGSTART... b = make([]byte, len(hdrMSGSTART)) if _, err = buf.Read(b); err != nil { return } - // But we don't need to do anything with it. + // But don't need to do anything with it. } else { - // We've already read MSGSTART as part of the checksum check. + // MSGSTART has already been read as part of the checksum check. r.Checksum = nil } @@ -362,7 +362,7 @@ func (r *Request) UnmarshalBinary(data []byte) (err error) { } } - // Now that we've validated the checksum (if provided), we trim the msgBuf to only RGs. + // Now that the checksum (if provided) has validated, trim the msgBuf to only RGs. // Skip over the BODYSTART, record group count, and record group size. if _, err = msgBuf.Read(make([]byte, len(hdrBODYSTART)+(PackedNumSize*2))); err != nil { return @@ -375,7 +375,7 @@ func (r *Request) UnmarshalBinary(data []byte) (err error) { for idx := 0; idx < rgCnt; idx++ { rgBuf = new(bytes.Buffer) - // The RG unmarshaler handles the record count, but we need to read it to discard it in msgBuf. + // The RG unmarshaler handles the record count, but it needs to be put in msgBuf to do that. if _, err = io.CopyN(rgBuf, msgBuf, int64(PackedNumSize)); err != nil { return } diff --git a/funcs_requestrecord.go b/funcs_requestrecord.go index 551c968..7fa1555 100644 --- a/funcs_requestrecord.go +++ b/funcs_requestrecord.go @@ -186,7 +186,7 @@ func (r *RequestRecord) UnmarshalBinary(data []byte) (err error) { } size = UnpackInt(b) - // And now we handle the FVPs themselves. + // And now handle the FVPs themselves. b = make([]byte, size) if _, err = buf.Read(b); err != nil { return diff --git a/funcs_requestrecordgroup.go b/funcs_requestrecordgroup.go index 4105e9b..361eaa4 100644 --- a/funcs_requestrecordgroup.go +++ b/funcs_requestrecordgroup.go @@ -199,8 +199,8 @@ func (r *RequestRecordGroup) UnmarshalBinary(data []byte) (err error) { for idx := 0; idx < cnt; idx++ { recBuf = new(bytes.Buffer) - // We skip over the KVP count; that's handled in the record Unmarshaler. - // We *do*, however, need to save it to the recBuf. + // Skip over the KVP count; that's handled in the record Unmarshaler. + // It does, however, need to be written to recBuf. if _, err = io.CopyN(recBuf, buf, int64(PackedNumSize)); err != nil { return } diff --git a/funcs_response.go b/funcs_response.go index 4e7f806..d284fb9 100644 --- a/funcs_response.go +++ b/funcs_response.go @@ -90,7 +90,7 @@ func (r *Response) MarshalBinary() (data []byte, err error) { msgSize += i.Size() } - // The message "body" - we do this first so we can checksum . + // The message "body" - this is done first so it can be checksummed. if _, err = msgBuf.Write(hdrBODYSTART); err != nil { return } @@ -120,7 +120,7 @@ func (r *Response) MarshalBinary() (data []byte, err error) { hasErr = true } - // Now we write the response as a whole. + // Now write the response as a whole. // Status if r.Status == RespStatusByteOK && hasErr { @@ -130,7 +130,7 @@ func (r *Response) MarshalBinary() (data []byte, err error) { return } - // Checksum -- ALWAYS present for responses! + // Checksum; ALWAYS present for responses! if _, _, err = r.GenChecksum(); err != nil { return } @@ -426,7 +426,7 @@ func (r *Response) UnmarshalBinary(data []byte) (err error) { return } - // Now that we've validated the checksum, we trim the msgBuf to only RGs. + // Now that the checksum has validated, trim the msgBuf to only RGs. // Skip over the BODYSTART, record group count, and record group size. if _, err = msgBuf.Read(make([]byte, len(hdrBODYSTART)+(PackedNumSize*2))); err != nil { return @@ -439,7 +439,7 @@ func (r *Response) UnmarshalBinary(data []byte) (err error) { for idx := 0; idx < rgCnt; idx++ { rgBuf = new(bytes.Buffer) - // The RG unmarshaler handles the record count, but we need to read it into msgBuf. + // The RG unmarshaler handles the record count, but it needs to be in msgBuf to do that. if _, err = io.CopyN(rgBuf, msgBuf, int64(PackedNumSize)); err != nil { return } diff --git a/funcs_responserecordgroup.go b/funcs_responserecordgroup.go index 2e0a03f..60d8701 100644 --- a/funcs_responserecordgroup.go +++ b/funcs_responserecordgroup.go @@ -189,8 +189,8 @@ func (r *ResponseRecordGroup) UnmarshalBinary(data []byte) (err error) { for idx := 0; idx < cnt; idx++ { recBuf = new(bytes.Buffer) - // We skip over the KVP count; that's handled in the record Unmarshaler. - // We *do*, however, need to save it to the recBuf. + // Skip over the KVP count; that's handled in the record Unmarshaler. + // It does need to be written to recBuf, though. if _, err = io.CopyN(recBuf, buf, int64(PackedNumSize)); err != nil { return }