doc.go

// Copyright 2012 The Gorilla Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

/*
Package config provides convenient access methods to configuration stored as
JSON or YAML.

Let's start with a simple YAML example:

    development:
      database:
        host: localhost
      users:
        - name: calvin
          password: yukon
        - name: hobbes
          password: tuna
    production:
      database:
        host: 192.168.1.1

We can parse it using ParseYaml(), which will return a *Config instance on
success:

    cfg, err := config.ParseYaml(yamlString)

An equivalent JSON configuration could be built using ParseJson():

    cfg, err := config.ParseJson(jsonString)

From now, we can retrieve configuration values using a path in dotted notation:

    // "localhost"
    host, err := cfg.String("development.database.host")

    // or...

    // "192.168.1.1"
    host, err := cfg.String("production.database.host")

Besides String(), other types can be fetched directly: Bool(), Float64(),
Int(), Map() and List(). All these methods will return an error if the path
doesn't exist, or the value doesn't match or can't be converted to the
requested type.

A nested configuration can be fetched using Get(). Here we get a new *Config
instance with a subset of the configuration:

    cfg, err := cfg.Get("development")

Then the inner values are fetched relatively to the subset:

    // "localhost"
    host, err := cfg.String("database.host")

For lists, the dotted path must use an index to refer to a specific value.
To retrieve the information from a user stored in the configuration above:

    // map[string]interface{}{ ... }
    user1, err := cfg.Map("development.users.0")
    // map[string]interface{}{ ... }
    user2, err := cfg.Map("development.users.1")

    // or...

    // "calvin"
    name1, err := cfg.String("development.users.0.name")
    // "hobbes"
    name2, err := cfg.String("development.users.1.name")

JSON or YAML strings can be created calling the appropriate Render*()
functions. Here's how we render a configuration like the one used in these
examples:

    cfg := map[string]interface{}{
        "development": map[string]interface{}{
            "database": map[string]interface{}{
                "host": "localhost",
            },
            "users": []interface{}{
                map[string]interface{}{
                    "name":     "calvin",
                    "password": "yukon",
                },
                map[string]interface{}{
                    "name":     "hobbes",
                    "password": "tuna",
                },
            },
        },
        "production": map[string]interface{}{
            "database": map[string]interface{}{
                "host": "192.168.1.1",
            },
        },
    }

    json, err := config.RenderJson(cfg)

    // or...

    yaml, err := config.RenderYaml(cfg)

This results in a configuration string to be stored in a file or database.
*/
package config