<!--
  Copyright (c) 2009-2026 ASN Lab
  All rights reserved.
-->

# ASN.1 Go Compiler Guide

The ASN.1 Go Compiler (`asngc`) generates Go source code from ASN.1 modules.
Generated types are Go structs and work with the Go runtime library for
encoding and decoding.

## Compiler Options

| Field             | Type    | Default            | Description |
|-------------------|---------|--------------------|-------------|
| `output-folder`   | string  | `"go"`             | Output directory for generated Go sources. |
| `mapping.integer` | ENUM    | `automatic-int64`  | See [Integer Mapping](#integer-mapping). |
| `mapping.real`    | ENUM    | `automatic`        | `automatic`, `float32`, `float64`. |
| `generate.equals` | BOOLEAN | --                 | Generate `Equals` methods. |
| `generate.prints` | BOOLEAN | --                 | Generate `String` methods. |

## Integer Mapping

Controls how ASN.1 INTEGER is mapped to Go types:

| Option             | Go type |
|--------------------|---------|
| `automatic`        | `int64` (same as `automatic-int64`). |
| `automatic-int64`  | `int64`. |
| `automatic-bigint` | `*big.Int`. |
| `int32`            | `int32`. |
| `int64`            | `int64`. |
| `big-integer`      | `*big.Int`. |

## Real Mapping

| Option      | Go type |
|-------------|---------|
| `automatic` | `float64`. |
| `float32`   | `float32`. |
| `float64`   | `float64`. |

## Project Configuration Example

```asn1
compilers {
    {
        id "asngc",
        language "go",
        options {
            output-folder "go",
            mapping {
                integer automatic-int64,
                real automatic
            }
        }
    }
}
```

## Runtime Library Usage

After the compiler generates Go source files for your ASN.1 modules, import
the generated package and the runtime interface. The runtime is loaded as a
plugin; each generated module provides a `GetRuntime()` function.

### Encoding

Populate your generated struct, obtain the runtime, and call `Encode`:

```go
import (
    "github.com/asnlab/asnrt"
    "example.com/myproject/mymodule"
)

pdu := mymodule.MyPdu{Field1: 42}
// ... populate other fields ...

runtime := mymodule.GetRuntime()
buf, _ := runtime.Allocate(1024, asnrt.ALIGNED_PACKED_ENCODING_RULES)
err := runtime.Encode(buf, &pdu, mymodule.MYPDU_TYPE)
if err != nil {
    // handle error
}
encoded := buf.Array()
```

### Decoding

Wrap received bytes and call `Decode`:

```go
runtime := mymodule.GetRuntime()
buf, _ := runtime.Wrap(receivedBytes, asnrt.ALIGNED_PACKED_ENCODING_RULES)
var pdu mymodule.MyPdu
err := runtime.Decode(buf, &pdu, mymodule.MYPDU_TYPE)
if err != nil {
    // handle error
}
// use pdu.Field1, etc.
```

Each generated package exports a `*_TYPE` variable for each top-level PDU
type and a `GetRuntime()` function that returns the `asnrt.Runtime` instance.

### Encoding Rules

Constants in `asnrt`:

| Constant | Encoding |
|---|---|
| `BASIC_ENCODING_RULES` | BER |
| `CANONICAL_ENCODING_RULES` | CER |
| `DISTINGUISHED_ENCODING_RULES` | DER |
| `UNALIGNED_PACKED_ENCODING_RULES` | UPER |
| `ALIGNED_PACKED_ENCODING_RULES` | APER |
| `OCTET_ENCODING_RULES` | OER |
| `JSON_ENCODING_RULES` | JER |
| `ASN_VALUE_NOTATION` | AVN |

### Error Handling

`Encode` and `Decode` return an `error`. The runtime provides
`NoSuchInformationObjectError` for table constraint lookup failures.

```go
err := runtime.Decode(buf, &pdu, mymodule.MYPDU_TYPE)
if err != nil {
    // handle error
}
```

## Generated Output

With `output "build"` and `go.output-folder "go"`, output is written under
`build/go/`. Each ASN.1 module produces a Go package.
