2 unstable releases
new 0.4.0 | Oct 30, 2024 |
---|---|
0.3.0 | Sep 20, 2024 |
#538 in Data structures
125 downloads per month
Used in codas-macros
170KB
3.5K
SLoC
Compact and streamable data format that works anywhere--from web apps to robots.
If you're primarily using Codas with Rust, the easiest
way to get started is via the
codas-macros
crate.
What's a Coda?
Codas document the structure of related types of data, each containing one or more fields. Codas' data can encode to and decode from raw binary data streams, which makes them extra-helpful for building distributed or embedded apps that speak different languages or rely on low-level networking.
Note: For those familiar with other data interchange formats, codas are similar to Protocol Buffers and Cap'n Proto.
Each data type in a coda can have the following kinds of fields:
- Unsigned integers from
8
to64
bits (u8
,u16
,u32
, andu64
). - Signed integers from
8
to64
bits (i8
,i16
,i32
, andi64
). - Signed floating-point integers from
32
to64
bits (f32
andf64
). - Booleans (
bool
). - UTF-8 encoded text (
text
). - Other user-defined data types ("nested" data)
- Lists of any of the things listed above.
For information on how codas' data is coded to and
from binary data, refer to the codec
docs.
How do I make a Coda?
Codas are made with Markdown:
# `Greeter` Coda
An example coda.
## `Request` Data
Data type in this coda named `Request`.
+ `message` text
## `Response` Data
Another data type in this coda named `Response`.
+ `message` text
+ `friends` list of text
This field of a `Response` is a list
of text, instead of a single `text`.
+ `request` Request
This field of a `Response` is a copy of the
`Request` that the response is for, showing
how we can nest data types within each other.
This example describes a Greeter
coda with two
kinds of data: Request
and Response
. Both of
these data contain a message
text, while the
Response
data contains a list of text called
friends
and a copy of the original Request
:
-
Every coda begins with a header (
#
) containing the name of the coda (Greeter
, in this example) followed by the wordCoda
. -
Every data description begins with a header (
##
) containing the name of the data type (Request
orResponse
, in this example) followed by the wordData
. -
Each field inside of a data description is a list item, starting with a
+
and followed by the name and then the type of the field. -
Any text directly below a coda header, data header, or field item will be parsed as Markdown documentation for that item.
The order of Data
and their fields (+
) matters: If
data or fields are re-arranged, the binary encoding of that
data may also change.
Can I evolve or extend my Codas?
Yes! Codas are designed to evolve as a system's needs change:
- New data types can be added to the end of a coda.
- New fields can be added to the end of a data type.
- Existing fields and data types can be renamed.
If a system receives data of a new type it doesn't support, or containing new fields it doesn't support, the new information will be gracefully ignored.
Conversely, if a system receives data that's missing newly-added fields, the missing fields will be gracefully populated with default values.
License
Copyright 2024 Alicorn Systems, Inc.
Licensed under the GNU Affero General Public License version 3, as published by the Free Software Foundation. Refer to the license file for more information.
If you have any questions, please reach out to [hello@alicorn.systems
].
Dependencies
~4–6MB
~131K SLoC