WANF

https://github.com/wjqserver/wanf
Admin
WANF is an expressive, unambiguous declarative configuration language designed for Go applications...
Tokens:40,967
Snippets:549
Trust Score:7
License:Apache-2.0
Update:3 months ago
Show doc for...
Tokens:
Raw
### Example: Linting and Formatting WANF Data

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/types.md

Demonstrates how to lint WANF data to get an AST and then format the AST with specified options.

```go
ast, errors := wanf.Lint(data)
if len(errors) == 0 {
    formatted := wanf.Format(ast, wanf.FormatOptions{Style: wanf.StyleAllSorted})
}
```

--------------------------------

### List Literal Examples

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/syntax.md

Demonstrates creating lists of strings, integers, and an empty list.

```wanf
servers = ["api", "web", "db"]
ports = [8080, 8443, 9000]
empty = []
```

--------------------------------

### Environment Variable Reference Examples

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/syntax.md

Shows how to reference required and optional environment variables.

```wanf
password = env("DB_PASSWORD")
host = env("DB_HOST", "localhost")
```

--------------------------------

### Install wanflint

Source: https://github.com/wjqserver/wanf/blob/main/vscode/README.md

Install the `wanflint` command-line tool using Go. This tool is necessary for the linting and formatting features of the VS Code extension.

```sh
go install github.com/WJQSERVER/wanf/wanflint@latest
```

--------------------------------

### Examples Provided

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/GENERATION_SUMMARY.txt

Lists the types of practical examples included in the documentation, covering various use cases and features.

```APIDOC
## Examples Provided

- Basic configuration decoding
- Collections (slices, maps, maps of structs)
- Duration handling
- Variables and environment variables
- File-based configuration
- Encoding with different styles
- Linting and validation
- High-performance (Neo) codec usage
- Complex real-world configuration
- Error handling patterns
```

--------------------------------

### Create and Use NeoEncoder

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/api-reference.md

Example demonstrating the creation, encoding, and closing of a NeoEncoder to a bytes.Buffer.

```go
var buf bytes.Buffer
enc := wanf.NewNeoEncoder(&buf)
err := enc.Encode(&cfg)
enc.Close()
```

--------------------------------

### Integer Literal Examples

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/syntax.md

Shows examples of positive, negative, and large integer literals.

```wanf
port = 8080
retries = -1
max_connections = 10000
```

--------------------------------

### Environment Variable Usage Example

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/configuration.md

Shows how to use env() for both required and optional environment variables, assigning them to configuration parameters.

```wanf
var username = env("APP_USER", "guest")

server {
    user = "${username}"
    password = env("APP_PASSWORD")  // Must be set
}
```

--------------------------------

### Install Node.js Dependencies

Source: https://github.com/wjqserver/wanf/blob/main/vscode/README.md

Install all necessary Node.js dependencies for the VS Code extension. This command should be run after navigating to the extension's directory.

```sh
npm install
```

--------------------------------

### Create and Use StreamEncoder

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/api-reference.md

Example of creating a StreamEncoder and encoding a configuration with specific style options.

```go
file, err := os.Create("stream-output.wanf")
defer file.Close()

enc := wanf.NewStreamEncoder(file)
err = enc.Encode(&cfg, wanf.WithStyle(wanf.StyleAllSorted))
```

--------------------------------

### String Literal Examples

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/syntax.md

Demonstrates the usage of simple, escaped, and multi-line string literals.

```wanf
simple = "hello"
escaped = "line1\nline2\ttab"
multiline = `line 1
line 2
line 3`
```

--------------------------------

### WANF Block Statement Example

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/types.md

Illustrates the syntax for a server block in WANF, specifying a name, host, and port.

```wanf
server "production" {
    host = "prod.example.com"
    port = 443
}
```

--------------------------------

### Boolean Literal Examples

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/syntax.md

Provides examples of boolean true and false values.

```wanf
enabled = true
debug = false
```

--------------------------------

### Variable Substitution Example

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/configuration.md

Demonstrates using variables for configuration values like port numbers and boolean flags. Ensure variables are declared before use.

```wanf
var ssl_port = 443
var ssl_enabled = true

server "main" {
    port = "${ssl_port}"
    tls = "${ssl_enabled}"
}
```

--------------------------------

### Import Structure Example

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/configuration.md

Illustrates how to structure imported files within a project directory. Imports are spliced into the importing file's location.

```wanf
// main.wanf
import "database.wanf"
import "server/production.wanf"

// database.wanf
database {
    host = "db.internal"
    port = 5432
}

// server/production.wanf
server {
    host = "0.0.0.0"
    port = 8080
}
```

--------------------------------

### WANF Configuration File Example

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/comparison-and-migration.md

Defines server host and port using environment variables with default values. This file is intended to be decoded by WANF.

```wanf
server {
    host = env("APP_HOST", "0.0.0.0")
    port = env("APP_PORT", "8080")
}
```

--------------------------------

### Block Literal Example

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/syntax.md

Illustrates a block literal used for configuration settings.

```wanf
config = {
    host = "localhost"
    port = 8080
}
```

--------------------------------

### Variable Reference Example

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/syntax.md

Demonstrates how to reference a declared variable within a string.

```wanf
var db_host = "db.internal"
server {
    db = "${db_host}"
}
```

--------------------------------

### WANF Comments Example

Source: https://github.com/wjqserver/wanf/blob/main/spec.md

WANF supports standard Go comment formats: single-line comments starting with // and multi-line block comments enclosed in /* */. These comments are ignored during parsing.

```go
// main.wanf
port = 8080 // 服务监听端口

/*
 这是一个块注释,
 用于详细描述下面的配置块。
*/
log {
    level = "info"
}
```

--------------------------------

### Duration Literal Examples

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/syntax.md

Shows examples of duration literals using different time units.

```wanf
timeout = 5s
interval = 30ms
deadline = 1h30m
```

--------------------------------

### WANF Struct Tag Options Example

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/types.md

Illustrates how to use WANF struct tags for field mapping, omitempty, and key field specification.

```go
type Config struct {
    ServerName string `wanf:"server_name"`
    Timeout time.Duration `wanf:"timeout,omitempty"`
    Services []Service `wanf:"services,key=name"`
}
```

--------------------------------

### Map Literal Examples

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/syntax.md

Shows examples of single-entry and multi-entry map literals, including trailing comma usage.

```wanf
// Single entry (trailing comma optional)
tags = {[
    env = "prod",
]}

// Multiple entries (trailing comma required)
metadata = {[ 
    version = "1.0",
    author = "system",
    debug = "false",
]}
```

--------------------------------

### WANF vs YAML Configuration Example

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/comparison-and-migration.md

Compares the syntax of WANF and YAML for defining database configurations. WANF uses explicit blocks, while YAML relies on indentation.

```wanf
database "primary" {
    host = "localhost"
    port = 5432
}

database "backup" {
    host = "backup.local"
    port = 5432
}
```

```yaml
database:
  primary:
    host: localhost
    port: 5432
  backup:
    host: backup.local
    port: 5432
```

--------------------------------

### WANF Slice/Array Example

Source: https://github.com/wjqserver/wanf/blob/main/docs/encoding_formats.md

Demonstrates WANF encoding for slices and arrays, using square brackets and comma separation for elements.

```wanf
name = []
```

--------------------------------

### WANF vs TOML Configuration Example

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/comparison-and-migration.md

Illustrates the structural differences between WANF and TOML for server configurations, including nested timeouts. WANF uses blocks, while TOML uses sections and dotted keys.

```wanf
server "main" {
    port = 8080
    tls_port = 8443
    hosts = ["api.example.com", "api2.example.com"]
    timeouts {
        read = 30s
        write = 30s
    }
}
```

```toml
[[server]]
name = "main"
port = 8080
tls_port = 8443
hosts = ["api.example.com", "api2.example.com"]

[server.timeouts]
read = 30
write = 30
```

--------------------------------

### WANF Map Example

Source: https://github.com/wjqserver/wanf/blob/main/docs/encoding_formats.md

Shows the WANF syntax for maps, including key-value separation with '=', entry separation with ',', and sorted keys.

```wanf
name {[]}
```

--------------------------------

### Float Literal Examples

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/syntax.md

Illustrates the use of decimal and scientific notation for float literals.

```wanf
ratio = 0.5
percentage = 99.99
scientific = 1.5e-10
```

--------------------------------

### WANF StyleSingleLine Output Example

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/comparison-and-migration.md

StyleSingleLine produces the most minimal output size, suitable for inline configurations or script parameters. It compresses all configuration into a single line.

```wanf
server { host = "localhost"; port = 8080 }; database { host = "localhost"; port = 5432 }
// Use for
// - Minimal size
// - Inline configs
// - Script parameters
```

--------------------------------

### Marshal Struct with Neo Codec

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/api-reference.md

Example of marshaling a configuration struct using the NeoMarshal function.

```go
data, err := wanf.NeoMarshal(&cfg)
```

--------------------------------

### Install vsce Globally

Source: https://github.com/wjqserver/wanf/blob/main/vscode/README.md

Install the Visual Studio Code Extension Manager globally using npm. This tool is required for packaging VS Code extensions from source.

```sh
npm install -g @vscode/vsce
```

--------------------------------

### WANF Struct Example

Source: https://github.com/wjqserver/wanf/blob/main/docs/encoding_formats.md

Illustrates the WANF block format for structs, showing field separation by newlines and handling of empty structs.

```wanf
name {}
```

--------------------------------

### WANF String Examples

Source: https://github.com/wjqserver/wanf/blob/main/docs/encoding_formats.md

Demonstrates WANF string encoding, including general strings with escaped special characters and multi-line strings using backticks.

```wanf
"hello \"world\""
```

```wanf
key = `line 1
line 2`
```

--------------------------------

### WANF Assignment Example

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/types.md

Shows a WANF assignment with both leading comments and an inline line comment.

```wanf
// Leading comment
server = "localhost"  // Line comment
```

--------------------------------

### WANF StyleBlockSorted Output Example

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/comparison-and-migration.md

The default StyleBlockSorted output is human-friendly and suitable for development. It presents configuration blocks in a readable, sorted manner.

```wanf
// Use for
// - Default output
// - Human-friendly files
// - Development
server {
    host = "localhost"
    port = 8080
}
database {
    host = "localhost"
    port = 5432
}
```

--------------------------------

### WANF vs JSON Configuration Example

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/comparison-and-migration.md

Contrasts WANF's human-friendly configuration with JSON's data interchange format. WANF supports comments and unquoted identifiers, unlike JSON.

```wanf
// Production server config
server {
    host = "0.0.0.0"
    port = 8080
    tls = true
}
```

```json
{
  "server": {
    "host": "0.0.0.0",
    "port": 8080,
    "tls": true
  }
}
```

--------------------------------

### Unmarshal Data with Neo Codec

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/api-reference.md

Example of unmarshaling WANF data into a configuration struct using the NeoUnmarshal function.

```go
err := wanf.NeoUnmarshal(data, &cfg)
```

--------------------------------

### WANF Variable Declaration Example

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/types.md

Shows how to declare a variable `db_host` and use it within a database block in WANF. Variables declared in imported files remain local.

```wanf
var db_host = "localhost"
database { host = "${db_host}" }
```

--------------------------------

### Encode with Per-Call Options

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/api-reference.md

Example of encoding a struct to a stream using per-call formatting options, such as disabling empty lines.

```go
err = enc.Encode(&cfg, wanf.WithoutEmptyLines())
```

--------------------------------

### Corresponding WANF Configuration File

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/examples.md

This WANF file defines a configuration structure that mirrors the Go `Config` struct. It utilizes variables, environment lookups, and nested blocks for a clear and organized setup.

```wanf
var api_domain = "example.com"
var default_timeout = 30s

environment = "production"

servers "main" {
    host = "api.${api_domain}"
    port = 8080
}

servers "backup" {
    host = "api-backup.${api_domain}"
    port = 8080
}

database {
    host = env("DB_HOST", "db.${api_domain}")
    port = 5432
    user = env("DB_USER", "admin")
    password = env("DB_PASSWORD")
    timeout = "${default_timeout}"
}

cache {
    enabled = true
    ttl = 5m
}

allowed_ips = ["10.0.0.0/8", "192.168.0.0/16"]
```

--------------------------------

### WANF Integer Literals

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/configuration.md

Shows examples of integer literals, including decimal, negative, and large values, noting the default base 10 and int64 range.

```wanf
decimal = 42
negative = -10
large = 9223372036854775807  // max int64
```

--------------------------------

### WANF Duration Literals

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/configuration.md

Provides examples of duration literals, showing various units like seconds (s), minutes (m), and hours (h).

```wanf
timeout = 30s
interval = 1m30s
deadline = 2h
```

--------------------------------

### WANF List Syntax Example

Source: https://github.com/wjqserver/wanf/blob/main/spec.md

WANF supports standard lists ([...]) for Go slices, requiring comma separation between elements. Trailing commas are permitted but discouraged and will be removed by the official formatter.

```wanf
// WANF 配置
// services 列表, 映射到 []string.
// 结尾逗号是不推荐的, lint会发出警告.
services = [
    "auth",
    "payment",
] // 推荐格式

```

--------------------------------

### WANF StyleAllSorted Output Example

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/comparison-and-migration.md

StyleAllSorted provides canonical output, ideal for version control diffs and reproducible builds. It ensures that all configuration blocks are consistently sorted.

```wanf
// Use for
// - Canonical output
// - Version control diffs
// - Reproducible builds
database {
    host = "localhost"
    port = 5432
}
server {
    host = "localhost"
    port = 8080
}
```

--------------------------------

### WANF File Import Example

Source: https://github.com/wjqserver/wanf/blob/main/spec.md

The 'import' directive allows modularizing WANF configuration files. Paths are relative to the current file, and imported variables do not pollute the importing file's scope. StreamDecoder supports imports with built-in cycle detection.

```wanf
// main.wanf
import "./shared/database.wanf"

// 多个 server 声明通过换行符在顶层分隔
server "app_a" {
    port = 8080
}

server "app_b" {
    port = 8081
}

// shared/database.wanf
database {
    host = "localhost"
    user = "admin"
}
```

--------------------------------

### Basic Configuration Marshal (Go)

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/examples.md

Demonstrates how to marshal a Go struct into Wanf format using `wanf.Marshal`. The output format is human-readable and preserves the structure of the input data.

```Go
type Config struct {
    Server struct {
        Host string `wanf:"host"`
        Port int    `wanf:"port"`
    } `wanf:"server"`
}

cfg := Config{
    Server: struct {
        Host string `wanf:"host"`
        Port int    `wanf:"port"`
    }{
        Host: "localhost",
        Port: 8080,
    },
}

// Marshal with default formatting
data, err := wanf.Marshal(&cfg)
// Output:
// server {
//     host = "localhost"
//     port = 8080
// }
```

--------------------------------

### Decoding Configuration with Environment Variables in Go

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/examples.md

Illustrates how to set environment variables in Go and then decode a WANF configuration that utilizes them. This is useful for providing dynamic settings like database credentials.

```Go
// Set environment variables
os.Setenv("DB_USER", "prod_user")
os.Setenv("DB_PASSWORD", "secure_password")

var cfg Config
wanf.Decode([]byte(configContent), &cfg)
// cfg.Server.Host → "api.example.com"
// cfg.Database.User → "prod_user"
```

--------------------------------

### Go Config vs WANF Config

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/comparison-and-migration.md

Demonstrates the direct mapping between Go struct literal syntax and WANF configuration syntax for server settings.

```go
cfg := Config{
    Server: struct{ Host string; Port int }{
        Host: "localhost",
        Port: 8080,
    },
}
```

```wanf
server {
    host = "localhost"
    port = 8080
}
```

--------------------------------

### Marshal with Style Options (Go)

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/examples.md

Shows how to customize the output format of Wanf marshaling using `wanf.NewEncoder` with various style options. These options control determinism, field order preservation, output compactness, and the inclusion of empty lines.

```Go
import "os"

// StyleAllSorted: fully deterministic output
encoder := wanf.NewEncoder(os.Stdout, wanf.WithStyle(wanf.StyleAllSorted))
encoder.Encode(&cfg)

// StyleStreaming: fast, preserves struct field order
encoder := wanf.NewEncoder(os.Stdout, wanf.WithStyle(wanf.StyleStreaming))
encoder.Encode(&cfg)

// StyleSingleLine: compact output
encoder := wanf.NewEncoder(os.Stdout, wanf.WithStyle(wanf.StyleSingleLine))
encoder.Encode(&cfg)

// Without empty lines
encoder := wanf.NewEncoder(os.Stdout, wanf.WithoutEmptyLines())
encoder.Encode(&cfg)
```

--------------------------------

### Loading Configuration Directly from File in Go

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/examples.md

Demonstrates loading WANF configuration directly from a file using `wanf.DecodeFile`. This method resolves imported files relative to the directory of the file being loaded.

```Go
package main

import (
    "github.com/WJQSERVER/wanf"
)

type Config struct {
    Server struct {
        Host string `wanf:"host"`
        Port int    `wanf:"port"`
    } `wanf:"server"`
}

func main() {
    var cfg Config
    
    // Load directly from file
    // Resolves imports relative to file directory
    if err := wanf.DecodeFile("config.wanf", &cfg); err != nil {
        panic(err)
    }
}
```

--------------------------------

### Best Practice for WANF Key Naming

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/configuration.md

Shows the recommended practice of using lowercase with underscores for WANF keys to ensure consistency.

```Go
type Config struct {
    DatabaseURL string `wanf:"database_url"`
}
```

--------------------------------

### Documentation Quality Metrics

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/GENERATION_SUMMARY.txt

Details the quantitative metrics for the documentation quality, including the number of code examples and their characteristics.

```APIDOC
## Documentation Quality Metrics

Code Examples: 50+
- Real, working examples
- Production-ready patterns
- Error handling included
- Comments explaining non-obvious parts
```

--------------------------------

### Base WANF Config with Environment-Specific Includes

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/comparison-and-migration.md

Sets up a base configuration file that imports environment-specific configuration files. This allows for modular configuration management.

```wanf
// config.wanf (base)
import "env/${ENVIRONMENT}.wanf"

server {
    debug = false
    db_timeout = 30s
}
```

--------------------------------

### Complex Go Configuration Structure

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/examples.md

Demonstrates a comprehensive Go application structure for parsing a complex WANF configuration file. It includes nested structs, maps, slices, and environment variable lookups.

```go
package main

import (
    "fmt"
    "os"
    "github.com/WJQSERVER/wanf"
)

type ServerConfig struct {
    Host string `wanf:"host"`
    Port int    `wanf:"port"`
}

type DatabaseConfig struct {
    Host     string        `wanf:"host"`
    Port     int           `wanf:"port"`
    User     string        `wanf:"user"`
    Password string        `wanf:"password"`
    Timeout  time.Duration `wanf:"timeout,omitempty"`
}

type CacheConfig struct {
    Enabled bool   `wanf:"enabled"`
    TTL     time.Duration `wanf:"ttl"`
}

type Config struct {
    Environment string                `wanf:"environment"`
    Servers     map[string]ServerConfig `wanf:"servers"`
    Database    DatabaseConfig        `wanf:"database"`
    Cache       CacheConfig           `wanf:"cache,omitempty"`
    AllowedIPs  []string              `wanf:"allowed_ips,omitempty"`
}

func main() {
    data := []byte(`
        environment = "production"
        
        servers "main" {
            host = "api.example.com"
            port = 8080
        }
        
        servers "backup" {
            host = "api-backup.example.com"
            port = 8080
        }
        
        database {
            host = env("DB_HOST", "localhost")
            port = 5432
            user = env("DB_USER", "admin")
            password = env("DB_PASSWORD", "")
            timeout = 30s
        }
        
        cache {
            enabled = true
            ttl = 5m
        }
        
        allowed_ips = ["10.0.0.0/8", "192.168.0.0/16"]
    `)

    var cfg Config
    if err := wanf.Decode(data, &cfg); err != nil {
        fmt.Fprintf(os.Stderr, "Failed to decode: %v\n", err)
        os.Exit(1)
    }

    fmt.Printf("Environment: %s\n", cfg.Environment)
    fmt.Printf("Main Server: %s:%d\n", cfg.Servers["main"].Host, cfg.Servers["main"].Port)
    fmt.Printf("Database: %s:%d (%s)\n", cfg.Database.Host, cfg.Database.Port, cfg.Database.User)
    
    if cfg.Cache != nil {
        fmt.Printf("Cache: enabled=%v, ttl=%v\n", cfg.Cache.Enabled, cfg.Cache.TTL)
    }
}
```

--------------------------------

### Neo Streaming Encode and Decode

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/examples.md

Demonstrates stream-based Neo encoding to a file and decoding from a file using Wanf's encoder and decoder. Requires os and wanf packages.

```go
import (
    "os"
    "github.com/WJQSERVER/wanf"
)

// Stream-based Neo encoding
file, _ := os.Create("output.wanf")
defer file.Close()

encoder := wanf.NewNeoEncoder(file)
err := encoder.Encode(&cfg)
encoder.Close()

// Stream-based Neo decoding
file, _ = os.Open("input.wanf")
defer file.Close()

decoder := wanf.NewNeoDecoder(file)
err = decoder.Decode(&cfg)
decoder.Close()
```

--------------------------------

### Basic Field Mapping with WANF Tags

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/configuration.md

Demonstrates explicit mapping of struct fields to WANF keys using custom names.

```Go
type Database struct {
    User     string `wanf:"user"`
    Password string `wanf:"password"`
}

// Maps to WANF:
// user = "admin"
// password = "secret"
```

--------------------------------

### Load Configuration with Custom Decoder and Base Path (Go)

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/examples.md

Use `wanf.NewDecoder` with `wanf.WithBasePath` to specify a directory for resolving relative import paths within configuration files. This is useful when configuration files themselves import other configuration files.

```Go
import (
    "os"
    "path/filepath"
    "github.com/WJQSERVER/wanf"
)

func LoadConfig(configDir string) (*Config, error) {
    file, err := os.Open(filepath.Join(configDir, "config.wanf"))
    if err != nil {
        return nil, err
    }
    defer file.Close()

    // WithBasePath sets the directory for resolving relative imports
    decoder, err := wanf.NewDecoder(file, wanf.WithBasePath(configDir))
    if err != nil {
        return nil, err
    }

    var cfg Config
    if err := decoder.Decode(&cfg); err != nil {
        return nil, err
    }
    
    return &cfg, nil
}
```

--------------------------------

### Configuration Explained

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/GENERATION_SUMMARY.txt

Describes the configuration aspects covered, such as struct tag options, decoder/encoder behavior, type mappings, and duration format.

```APIDOC
## Configuration Explained

- All struct tag options (omitempty, key=, etc.)
- Decoder options and behavior
- Encoder options and output styles
- Type mappings between Go and WANF
- Duration format
- Comment handling
```

--------------------------------

### WANF Identifier Syntax

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/syntax.md

Specifies the rules for valid identifiers. Identifiers must start with a letter or underscore and can contain letters, digits, and underscores.

```wanf
identifier = [a-zA-Z_] [a-zA-Z0-9_]*
```

```wanf
server, database, user_name, _internal, config2
```

```wanf
123invalid    // Starts with digit
server-name   // Contains hyphen (not underscore)
my.field      // Contains dot
my-var        // Contains hyphen
```

--------------------------------

### Format Wanf Configuration

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/examples.md

Parses, lints, and formats Wanf configuration data with specified options, then writes the formatted output to a file.

```go
data := []byte(configContent)

// Parse with linting
ast, errors := wanf.Lint(data)
if len(errors) > 0 {
    return errors
}

// Format with options
formatted := wanf.Format(ast, wanf.FormatOptions{
    Style:      wanf.StyleAllSorted,
    EmptyLines: true,
    NoSort:     false,
})

// Write back to file
os.WriteFile("formatted.wanf", formatted, 0644)
```

--------------------------------

### Combining WANF Tag Options

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/configuration.md

Demonstrates combining 'omitempty' and 'key=' options for WANF struct tags.

```Go
type Config struct {
    Timeout time.Duration `wanf:"timeout_ms,omitempty"`
    Servers []Server       `wanf:"servers,key=hostname,omitempty"`
}
```

--------------------------------

### WANF File with Variables and Environment Variables

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/examples.md

Shows how to define and use variables within a WANF file, and how to reference environment variables for sensitive or dynamic values. The `env()` function provides a default value if the environment variable is not set.

```WANF
var environment = "production"
var base_domain = "example.com"

server "main" {
    env = "${environment}"
    host = "api.${base_domain}"
    port = 8080
}

database {
    host = "db.${base_domain}"
    port = 5432
    user = env("DB_USER", "admin")
    password = env("DB_PASSWORD")
}
```

--------------------------------

### WANF Database Configuration with Environment Variables

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/comparison-and-migration.md

Configures database connection parameters using environment variables. Defaults are provided for the port if not specified.

```wanf
database {
    host = env("DB_HOST")
    user = env("DB_USER")
    password = env("DB_PASSWORD")
    port = env("DB_PORT", "5432")
}
```

--------------------------------

### Hypothetical Python WANF Parsing

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/comparison-and-migration.md

Illustrates how a WANF configuration string might be parsed in Python using a hypothetical 'wanf' package.

```python
import wanf  # Hypothetical package

config = wanf.parse(wanf_string)
print(config['server']['host'])
```

--------------------------------

### Package VS Code Extension

Source: https://github.com/wjqserver/wanf/blob/main/vscode/README.md

Package the VS Code extension into a `.vsix` file using the `vsce package` command. This command compiles the TypeScript code and prepares the extension for installation.

```sh
vsce package
```

--------------------------------

### WANF Statement Separator Example

Source: https://github.com/wjqserver/wanf/blob/main/spec.md

Statements in WANF, such as assignments or block definitions, must be separated by newlines (standard layout) or semicolons (compact layout). Semicolons are equivalent to newlines for statement separation.

```wanf
// 标准的多行布局
host = "localhost"
port = 8080
// 等效的单行紧凑布局
host = "localhost"; port = 8080
```

--------------------------------

### Import WANF Files

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/configuration.md

Include statements to incorporate configurations from other WANF files. Paths are resolved relative to the importing file.

```wanf
import "database.wanf"
import "server.wanf"
```

--------------------------------

### Load Config from File with Environment Overrides (Go)

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/comparison-and-migration.md

Loads configuration from a WANF file and allows specific fields to be overridden by environment variables. Ensure the Config struct is defined elsewhere.

```go
// 1. Load from file
var cfg Config
if err := wanf.DecodeFile("config.wanf", &cfg); err != nil {
    log.Fatal(err)
}

// 2. Environment variables override specific fields
if envPort := os.Getenv("APP_PORT"); envPort != "" {
    port, _ := strconv.Atoi(envPort)
    cfg.Server.Port = port
}
```

--------------------------------

### Directory Structure for File-Based Configuration

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/examples.md

Shows a typical directory structure for organizing WANF configuration files, including a main configuration file that imports others. This promotes modularity and separation of concerns.

```Directory Structure
config/
├── config.wanf
├── server.wanf
└── database.wanf

// config.wanf
import "server.wanf"
import "database.wanf"

// server.wanf
server {
    host = "0.0.0.0"
    port = 8080
}

// database.wanf
database {
    host = "localhost"
    port = 5432
}
```

--------------------------------

### WANF Block Syntax Example

Source: https://github.com/wjqserver/wanf/blob/main/spec.md

Blocks ({...}) in WANF are used to define key-value pairs that map to Go structs. Elements within a block must be separated by newlines for standard layout, though comma separation is supported for compact layouts.

```wanf
// WANF 配置
// database 块的内容映射到单一的 DatabaseConfig 结构体。
// 因此, 其内部使用换行符分隔。
database {
    host = "localhost"
    port = 5432
}

// 非常规紧凑布局
database {host = "localhost", port = 5432}

// 即使 server 块最终成为 map 的一部分, 其块内语法也只与其
// 直接映射的 ServerConfig 结构体相关, 故同样使用换行符。
server "http_api" {
    port = 8080
    protocol = "http"
}

// 映射字面量, 同样被视为空行分隔的“块”
// Map literals are also treated as "blocks" for empty line separation.
user_roles = {[
    admin = "all_permissions",
    guest = "read_only",
]}
```

--------------------------------

### Decode Slice as Map Configuration in Go

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/examples.md

Decodes a WANF configuration into a slice of structs, but uses a specified field (e.g., 'name') as the key for map-like access. This is achieved by adding `,key=<field_name>` to the `wanf` tag. The example shows how services are defined and then accessed as if they were in a map.

```Go
type Service struct {
    Name string `wanf:"name"`
    Port int    `wanf:"port"`
}

type Config struct {
    // Slice converted to map using "name" field as key
    Services []Service `wanf:"services,key=name"`
}

var cfg Config
wanf.Decode([]byte(`
    services "api" {
        name = "api"
        port = 8080
    }
    
    services "web" {
        name = "web"
        port = 3000
    }
`), &cfg)

// Automatically converted to map-like access
// cfg.Services[0].Name → "api"
// cfg.Services[1].Name → "web"
```

--------------------------------

### Format .wanf Files with wanflint fmt

Source: https://github.com/wjqserver/wanf/blob/main/README.md

Use `wanflint fmt` to automatically format `.wanf` files. It preserves comments and can sort fields alphabetically or maintain original order with `--nosort`. Use `-d` to output to stdout.

```shell
# Format file (default sort)
wanflint fmt your_config.wanf
```

```shell
# Format file and disable sorting
wanflint fmt --nosort your_config.wanf
```

--------------------------------

### Define Go Structs for WANF Configuration

Source: https://github.com/wjqserver/wanf/blob/main/README.md

Define Go structs with `wanf` tags to map configuration keys. Use `omitempty` to ignore zero values for specific fields.

```go
package main

import (
    "fmt"
    "github.com/WJQSERVER/wanf"
    "time"
)

type Config struct {
    Server   map[string]ServerConfig `wanf:"server"`
    Database DatabaseConfig        `wanf:"database"`
    Services []string                `wanf:"services"`
}

type ServerConfig struct {
    Host       string        `wanf:"host"`
    Port       int           `wanf:"port"`
    MaxStreams int           `wanf:"max_streams,omitempty"` // Ignore zero value
}

type DatabaseConfig struct {
    User     string `wanf:"user"`
    Password string `wanf:"password"`
}
```

--------------------------------

### High-Performance Neo Codec

Source: https://github.com/wjqserver/wanf/blob/main/README.md

Utilize the experimental Neo codec for near-zero memory allocation during serialization and deserialization in Go.

```go
// Use Neo for fast encoding and decoding
data, err := wanf.NeoMarshal(&cfg)
err = wanf.NeoUnmarshal(data, &cfg)
```

--------------------------------

### Dockerfile for Container Configuration

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/comparison-and-migration.md

Copies a WANF configuration file into the container and sets default environment variables for database connection. These environment variables can be overridden.

```dockerfile
# Dockerfile
COPY config.wanf /etc/app/config.wanf
ENV DB_HOST=postgres
ENV DB_USER=appuser
ENV DB_PASSWORD=secret
```

--------------------------------

### TOML Array of Tables to WANF Labeled Blocks

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/comparison-and-migration.md

Demonstrates converting TOML's array of tables into WANF's labeled blocks, useful for lists of similar configurations like servers.

```toml
[[servers]]
name = "main"
port = 8080

[[servers]]
name = "backup"
port = 8080
```

```wanf
servers "main" {
    port = 8080
}

servers "backup" {
    port = 8080
}
```

--------------------------------

### Standard WANF Marshal Encoding

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/comparison-and-migration.md

Use Marshal() for typical configuration files, development, debugging, or when comment preservation and mixed data types are needed. This is the standard and simplest encoding method.

```go
data, err := wanf.Marshal(&config)  // Simple, standard
```

--------------------------------

### Reformat WANF with Options

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/README.md

Format takes a RootNode representing parsed WANF data and reformats it into WANF bytes according to specified FormatOptions. This is useful for standardizing WANF files.

```Go
func Format(program *RootNode, opts FormatOptions) []byte
```

--------------------------------

### TOML to WANF Block Migration

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/comparison-and-migration.md

Shows the transformation of TOML's section syntax to WANF's block syntax for nested configuration like database settings.

```toml
[database]
host = "localhost"
port = 5432
```

```wanf
database {
    host = "localhost"
    port = 5432
}
```

--------------------------------

### Create a WANF Decoder from an io.Reader

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/api-reference.md

Use NewDecoder to create a Decoder instance from any io.Reader, such as a file. Options like `WithBasePath` can be provided to configure import path resolution.

```Go
file, err := os.Open("config.wanf")
defer file.Close()

dec, err := wanf.NewDecoder(file, wanf.WithBasePath("./configs"))
var cfg Config
err = dec.Decode(&cfg)
```

--------------------------------

### WithStyle

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/api-reference.md

Creates an EncoderOption that sets the output formatting style.

```APIDOC
## WithStyle

### Description
Creates an EncoderOption that sets the output formatting style.

### Method
N/A (Function Signature)

### Parameters
#### Path Parameters
- **style** (OutputStyle) - Required - One of: StyleBlockSorted, StyleAllSorted, StyleStreaming, StyleSingleLine

### Returns
`EncoderOption` — option function

### Styles:
- `StyleBlockSorted` (default) — Sorts fields within nested blocks, preserves top-level order
- `StyleAllSorted` — Sorts all fields alphabetically at all levels (deterministic)
- `StyleStreaming` — Preserves struct field definition order (fastest)
- `StyleSingleLine` — Single-line format with semicolon separators (most compact)

### Example
```go
enc := wanf.NewEncoder(w, wanf.WithStyle(wanf.StyleAllSorted))
```
```

--------------------------------

### Create a WANF Encoder

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/api-reference.md

Instantiate an Encoder using NewEncoder to write WANF data to an io.Writer. Options allow customization of formatting, such as output style and disabling empty lines.

```go
func NewEncoder(w io.Writer, opts ...EncoderOption) *Encoder
```

```go
file, err := os.Create("output.wanf")
defer file.Close()

enc := wanf.NewEncoder(file, wanf.WithStyle(wanf.StyleAllSorted))
err = enc.Encode(&cfg)
```

--------------------------------

### WANF Empty Collections

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/syntax.md

Demonstrates the syntax for creating empty lists and maps. Empty lists result in nil or zero-length slices, while empty maps result in nil or zero-entry maps.

```wanf
empty_list = []
empty_map = {[]}
```

--------------------------------

### Environment Variable Reference Syntax

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/syntax.md

Defines the syntax for referencing environment variables with optional default values.

```wanf
env_call = 'env' LPAREN STRING [',' STRING] RPAREN
```

--------------------------------

### Set Decoder Base Path

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/api-reference.md

Use WithBasePath to specify a directory for resolving relative import paths when creating a decoder.

```go
dec, err := wanf.NewDecoder(file, wanf.WithBasePath("./config"))
```

--------------------------------

### Set Base Path for Import Resolution in Go

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/errors.md

Configure the base path for resolving imported configurations by using `wanf.WithBasePath`. This is useful when your configuration files reference other files relative to a specific directory.

```go
// Set base path for imports
absPath, _ := filepath.Abs("./config")
dec, err := wanf.NewDecoder(
    file, 
    wanf.WithBasePath(absPath),
)
if err != nil {
    return fmt.Errorf("could not create decoder: %w", err)
}

var cfg Config
if err := dec.Decode(&cfg); err != nil {
    return fmt.Errorf("import resolution failed: %w", err)
}
```

--------------------------------

### Key Option for List to Map Conversion

Source: https://github.com/wjqserver/wanf/blob/main/docs/tags.md

Use the `key` option to parse a list of objects from the WANF configuration into a map in Go, using a specified field as the map key. Note that zero-length maps are always ignored in the output for backward compatibility.

```WANF
users = [
    { id = "alice", age = 30 },
    { id = "bob", age = 25 }
]
```

```Go
type User struct {
    ID  string `wanf:"id"`
    Age int    `wanf:"age"`
}

type Config struct {
    // Parses the users list into a map with User.ID as the key
    Users map[string]User `wanf:"users,key=id"`
}
```

--------------------------------

### Clone WANF Repository

Source: https://github.com/wjqserver/wanf/blob/main/vscode/README.md

Clone the official WANF repository from GitHub. This is the first step to building the VS Code extension from source.

```sh
git clone https://github.com/WJQSERVER/wanf.git
```

--------------------------------

### Using key= Option for Slice Structs in WANF

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/configuration.md

Illustrates how to specify a key field for slice structs when encoding to WANF, converting slices to maps.

```Go
type Service struct {
    Name string `wanf:"name"`
    Port int    `wanf:"port"`
}

type Config struct {
    Services []Service `wanf:"services,key=name"`
}

cfg := Config{
    Services: []Service{
        {Name: "api", Port: 8080},
        {Name: "web", Port: 3000},
    },
}

data, _ := wanf.Marshal(&cfg)
// Output:
// services "api" {
//     name = "api"
//     port = 8080
// }
// services "web" {
//     name = "web"
//     port = 3000
// }
```

--------------------------------

### Lint .wanf Files with wanflint lint

Source: https://github.com/wjqserver/wanf/blob/main/README.md

Use `wanflint lint` to check for syntax errors, style warnings, and potential logic errors in `.wanf` files. Output can be formatted as JSON using the `--json` flag for integration with editors and CI/CD.

```shell
# Check file
wanflint lint your_config.wanf
```

```shell
# Output check results in JSON format
wanflint lint --json your_config.wanf
```

--------------------------------

### Format WANF AST

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/api-reference.md

Formats a WANF Abstract Syntax Tree (AST) into WANF text according to specified options. Use this to generate or reformat WANF content programmatically.

```go
func Format(program *RootNode, opts FormatOptions) []byte
```

```go
ast, _ := wanf.Lint(data)
formatted := wanf.Format(ast, wanf.FormatOptions{
    Style:      wanf.StyleAllSorted,
    EmptyLines: true,
    NoSort:     false,
})
```

--------------------------------

### Basic Struct Tag Mapping

Source: https://github.com/wjqserver/wanf/blob/main/docs/tags.md

Use the `wanf` tag to specify the configuration key name for a struct field.

```Go
type Config struct {
    Host string `wanf:"server_host"`
}
```

--------------------------------

### Streaming Large WANF Configuration Files

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/examples.md

Loads a large WANF configuration file using a stream decoder for memory efficiency. Ensures the decoder is closed after use.

```go
import (
    "os"

    "github.com/WJQSERVER/wanf"
)

// Assuming Config struct is defined elsewhere
// type Config struct {
//     Server struct {
//         Port int
//     }
// }

func loadLargeConfig(path string) (*Config, error) {
    file, err := os.Open(path)
    if err != nil {
        return nil, err
    }
    defer file.Close()

    // StreamDecoder for memory efficiency on large files
    decoder, err := wanf.NewStreamDecoder(file)
    if err != nil {
        return nil, err
    }
    defer decoder.Close()

    var cfg Config
    if err := decoder.Decode(&cfg); err != nil {
        return nil, err
    }

    return &cfg, nil
}
```

--------------------------------

### Navigate to VS Code Extension Directory

Source: https://github.com/wjqserver/wanf/blob/main/vscode/README.md

Change the current directory to the `vscode` subdirectory within the cloned WANF repository. This is where the extension's source code resides.

```sh
cd wanf/vscode
```

--------------------------------

### Error Handling During WANF Decoding

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/examples.md

Loads a WANF configuration file with robust error checking for file opening, decoder creation, decoding process, and configuration validation.

```go
package main

import (
    "fmt"
    "os"

    "github.com/WJQSERVER/wanf"
)

// Assuming Config struct is defined elsewhere
// type Config struct {
//     Server struct {
//         Port int
//     }
// }

func loadAndValidate(path string) error {
    file, err := os.Open(path)
    if err != nil {
        return fmt.Errorf("cannot open file: %w", err)
    }
    defer file.Close()

    // Create decoder with error handling
    decoder, err := wanf.NewDecoder(file)
    if err != nil {
        return fmt.Errorf("cannot create decoder: %w", err)
    }

    var cfg Config
    if err := decoder.Decode(&cfg); err != nil {
        return fmt.Errorf("decode failed: %w", err)
    }

    // Validate configuration
    if cfg.Server.Port < 1 || cfg.Server.Port > 65535 {
        return fmt.Errorf("invalid port: %d", cfg.Server.Port)
    }

    return nil
}
```

--------------------------------

### JSON to WANF Configuration Migration

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/comparison-and-migration.md

Shows the conversion of a JSON object with nested server and database configurations into WANF format, including adding comments and removing quotes from keys.

```json
{
  "server": {
    "host": "localhost",
    "port": 8080
  },
  "database": {
    "host": "db.local",
    "port": 5432
  }
}
```

```wanf
// Web server configuration
server {
    host = "localhost"
    port = 8080
}

// Database configuration  
database {
    host = "db.local"
    port = 5432
}
```

--------------------------------

### Wanf Env Function with Default

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/errors.md

To avoid errors when an environment variable is not set, provide a default value as the second argument to the `env` function.

```wanf
database {
    password = env("DB_PASSWORD", "default_password")  // With default
}
```

--------------------------------

### Create NeoDecoder from Reader

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/api-reference.md

Creates a high-performance Neo decoder from an io.Reader. Use this for streaming input.

```go
func NewNeoDecoder(r io.Reader) *NeoDecoder
```

--------------------------------

### Neo Marshal Configuration

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/examples.md

Encodes a Go struct into high-performance binary data using Wanf's NeoMarshal function. Requires the wanf package.

```go
import "github.com/WJQSERVER/wanf"

type Config struct {
    Database struct {
        Host string `wanf:"host"`
        Port int    `wanf:"port"`
    } `wanf:"database"`
}

cfg := Config{}
cfg.Database.Host = "localhost"
cfg.Database.Port = 5432

// High-performance encoding (unsafe operations)
data, err := wanf.NeoMarshal(&cfg)
```

--------------------------------

### Decoding Durations in Go

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/examples.md

Demonstrates how to decode time.Duration values from WANF configuration. Ensure your WANF file uses valid duration strings (e.g., '30s', '5m').

```Go
import "time"

type Config struct {
    ReadTimeout  time.Duration `wanf:"read_timeout"`
    WriteTimeout time.Duration `wanf:"write_timeout"`
    IdleTimeout  time.Duration `wanf:"idle_timeout"`
}

var cfg Config
wanf.Decode([]byte(`
    read_timeout = 30s
    write_timeout = 30s
    idle_timeout = 5m
`), &cfg)

// cfg.ReadTimeout → 30 * time.Second
// cfg.IdleTimeout → 5 * time.Minute
```

--------------------------------

### Define FormatOptions in Go

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/types.md

Controls the formatting behavior when encoding or formatting AST nodes. Use to specify output style, empty lines, and field sorting.

```go
type FormatOptions struct {
    Style      OutputStyle
    EmptyLines bool
    NoSort     bool
}
```

--------------------------------

### WithBasePath

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/api-reference.md

Creates a DecoderOption that sets the base directory for resolving relative import paths.

```APIDOC
## WithBasePath

### Description
Creates a DecoderOption that sets the base directory for resolving relative import paths.

### Method
N/A (Function Signature)

### Parameters
#### Path Parameters
- **path** (string) - Required - Base directory path

### Returns
`DecoderOption` — option function for use with decoder constructors

### Example
```go
dec, err := wanf.NewDecoder(file, wanf.WithBasePath("./config"))
```
```

--------------------------------

### Declare and Use File-Scoped Variables

Source: https://github.com/wjqserver/wanf/blob/main/_autodocs/configuration.md

Declare variables using the 'var' keyword. Variables are scoped to the file where they are declared and can be substituted into strings and map keys using the ${varname} syntax.

```wanf
var environment = "production"
var db_host = "db.internal"

server {
    env = "${environment}"
    db_host = "${db_host}"
}
```
Tokens:
Raw