https://github.com/marcuwynu23/godan
A Go library for DAN (Data Advanced Notation) — a human-readable data format for structured configs, datasets, and annotations, with tables, arrays, and comments.
https://github.com/marcuwynu23/godan
dan dan-py godan
Last synced: about 2 months ago
JSON representation
A Go library for DAN (Data Advanced Notation) — a human-readable data format for structured configs, datasets, and annotations, with tables, arrays, and comments.
- Host: GitHub
- URL: https://github.com/marcuwynu23/godan
- Owner: marcuwynu23
- Created: 2026-04-12T10:16:07.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-12T11:41:58.000Z (3 months ago)
- Last Synced: 2026-04-12T13:11:44.521Z (3 months ago)
- Topics: dan, dan-py, godan
- Language: Go
- Homepage: https://pkg.go.dev/github.com/marcuwynu23/godan
- Size: 48.8 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# DAN for Go (`godan`)
**A Go library for [DAN](https://github.com/marcuwynu23/danjs) (Data Advanced Notation)** — a human-readable data format for structured **configs**, **datasets**, and **annotations**, with **tables**, **arrays**, and **comments**.
This package **parses** DAN text into Go values and **serializes** them back. The API is **`Decode`** and **`Encode`** on `map[string]interface{}` (nested maps, table rows as `[]map[string]interface{}`, arrays as `[]interface{}`, plus strings, numbers, and booleans). Line-oriented syntax includes **nested blocks** `{ … }`, **key–value** lines, **`table(col1, col2) [ … ]`**, and **`#` / `//` comments** during parse.
---
## Module and package
| | Path |
| ------------------- | ---------------------------------- |
| **Go module** | `github.com/marcuwynu23/godan` |
| **Library package** | `github.com/marcuwynu23/godan/lib` |
Import the library as:
```go
import "github.com/marcuwynu23/godan/lib"
```
The `lib` package exposes **`Decode`** and **`Encode`** as the complete public surface for round-tripping DAN documents.
---
## Install
```bash
go get github.com/marcuwynu23/godan
```
Requires **Go 1.23.5** or compatible toolchain (see `go.mod`).
---
## API overview
### `Decode(text interface{}) (map[string]interface{}, error)`
- **Input:** `string` or `[]byte`. Any other type returns an error.
- **Output:** A single root `map[string]interface{}` representing the document. Empty or whitespace-only input yields an **empty map**, not an error.
- **Model:** Nested objects are nested `map[string]interface{}`. Tables become **`[]map[string]interface{}`**. Arrays in values become **`[]interface{}`**. Scalars use `string`, `float64`, or `bool` as inferred from the text.
### `Encode(obj map[string]interface{}) string`
- **Input:** The same shape of data `Decode` produces (root must be a map).
- **Output:** DAN text with **2-space indentation** for blocks and nested values. **`nil` map values** encode as **`""`** (empty quoted string) so output stays valid DAN.
- **Ordering:** Map iteration order in Go is **not stable**; key order in blocks and table column order in headers can differ between encodings of the same logical data.
---
## DAN constructs this library understands
| Construct | Example | Decoded shape (typical) |
| -------------- | ---------------------------------- | ------------------------------- |
| Key–value | `name: "Ada"` | `map` entry `string` |
| Number | `port: 8080` | `float64` |
| Boolean | `tls: true` | `bool` |
| Unquoted token | `env: production` | `string` |
| Array value | `tags: [a, b, c]` | `[]interface{}` |
| Block | `server { host: "h" }` | nested `map[string]interface{}` |
| Table | `rows: table(id, name) [ 1, "a" ]` | `[]map[string]interface{}` |
| Comments | `# …` or `// …` | stripped during parse |
Table rows are split on **commas**; values are trimmed and passed through the same literal rules as scalar fields.
---
## Usage examples
### Minimal decode / encode
```go
import "github.com/marcuwynu23/godan/lib"
m, err := lib.Decode(`name: "Ada"`)
if err != nil {
log.Fatal(err)
}
out := lib.Encode(m)
```
### From bytes
```go
data, _ := os.ReadFile("config.dan")
m, err := lib.Decode(data)
```
### Nested document
```go
const doc = `app {
name: "demo"
server {
port: 3000
}
}`
m, _ := lib.Decode(doc)
// m["app"].(map[string]interface{})["server"] ...
```
---
## Tests
```bash
go test ./...
```
Tests live under **`lib/`** (`*_test.go`, benchmarks, integration-style cases).
---
## Using this module in your project
- Prefer **pinning** a version or commit in production (`go get` with version, or your workspace policy).
- Treat decoded maps as **untrusted** until you validate fields for your application.
- For **CLI** access to the same implementation, see [**dan-cli**](https://github.com/marcuwynu23/dan-cli). For **lint/format**, see [**danlint**](https://github.com/marcuwynu23/danlint). For the **JavaScript** package, see [**danjs**](https://github.com/marcuwynu23/danjs) ([`@marcuwynu23/danjs`](https://www.npmjs.com/package/@marcuwynu23/danjs)).
---
## Community
- [Contributing](CONTRIBUTING.md)
- [Code of Conduct](CODE_OF_CONDUCT.md)
- [Security](SECURITY.md)
- [Funding](.github/FUNDING.yml) — [PayPal](https://paypal.me/wynumarcu23) via the repository **Sponsor** button
---
## License
SPDX and full license text are added when the repository is published for redistribution (commonly **MIT**). If no `LICENSE` file is present yet, coordinate with the maintainers before redistributing.