////
 Go WireProto API Documentation © 2024 by Brent Saner is licensed under Creative Commons Attribution-ShareAlike 4.0 International. To view a copy of this license, visit https://creativecommons.org/licenses/by-sa/4.0/
////

= Go WireProto API Documentation
Brent Saner <bts@square-r00t.net>
Last rendered {localdatetime}
:doctype: book
:docinfo: shared
:data-uri:
:imagesdir: images
:sectlinks:
:sectnums:
:sectnumlevels: 7
:toc: preamble
:toc2: left
:idprefix:
:toclevels: 7
:source-highlighter: rouge
:docinfo: shared
:this_protover: 1
:this_protover_hex: 0x00000001

[id="ref"]
== Reference
In addition to the documentation found in this document and https://wireproto.io/[the specification^], library usage documentation can be found at https://pkg.go.dev/r00t2.io/wireproto[the Golang module documentation page^]:

++++
<a href="https://go.pkg.dev/r00t2.io/wireproto">
    <img src="https://pkg.go.dev/badge/r00t2.io/wireproto.svg"
         alt="Go Reference"/>
</a>
++++

[id="lic"]
== License
This library is licensed for use, inclusion, and distribution under the https://opensource.org/license/bsd-3-clause["3-Clause BSD" license^].

.Full License
[%collapsible]
====
[source,plain]
----
include::LICENSE[]
----
====

[id="todo"]
== TODO
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
** 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
** This is a relatively low priority as the passed `net.Conn` will likely return an error if its own context is canceled. This can be handled in the caller downstream.
* Better/more strict interfaces
* Maps for generic should have `any`, not `interface{}` values
* FVP should have its own method to a map[string][]byte return value
* "Getters and Setters" (ew, I know, but compromises are made with flexibility)
** `.Append*()` methods to append any type to any parent type. e.g. `<Response>.AppendFVP(<FieldValuePair>)` would append an FVP to the most recent ResponseRecord to the most recent ResponseRecordGroup (or create if they don't exist), `<Response>.AppendRecord(...)` for appending a record to most recent record group etc.
** `.Get()`/`.Set()` on a Response/Request to get/set a slice of values (`<FieldValue>`) from filter criteria as struct (e.g. field name, how many, first X, last X, etc.)
** `.GetPath*()` and `.SetPath*()` to use *[`RG_N`[`R_N`[`FVP_N`]]]* indexing (e.g. `0, 0, 0` for RecordGroup 0/Record 0/FVP 0, `1, 3, 5` for RecordGroup 1/Record 3/FVP 5, etc.) multidimentional indexing
*** Allow specific lookups/sets by multidimentional array index to return FVP (`.GetIndex(idx)` where `idx` is a fixed-size array of dimensions for object's children paths); e.g. `<Response>.GetIndex(idx)`, `idx` is `[3]int` and returns FVP)
*** Allow lookups/sets by variable length index (`.GetIndexDynamic(idx)`, where `idx` is a `1` to `n`-size slice of dimensions for object's children paths (e.g. `<Response>.GetIndexDynamic([]int{0, 0})` returns `any(<Record>)` but `<Response>.GetIndexDynamic([]int{0, 0, 0})` returns `any(FieldValuePair)`)
**** negative value indicates *all* children
*** Lookups/sets at fixed levels (e.g. `<RecordGroup>.GetRecord(idx)`, `idx` is `[1]int`, but `<RecordGroup>.GetFVP(idx)`, `idx` is `[2]int`) for type safety
*** All objects have `.ID()` that returns their index/"path"/"key" from the root, and `.Index()` that returns their index within their immediate parent
**** This obviously requires a `.Resolve()` first