The magic derive macro.

It can currently derive decoding for regular struct types with named fields and
simple enums (without fields). There is currently no support for tuples,
newtypes, or more complex enums.

In its simplest form, the following struct definition:

```rust
#[derive(Debug, Derpscfg)]
struct FooBar {
    foo: String,
    baz: String,
}
```

can be used to parse the following scfg document:

```scfg
foo foovalue
baz bazvalue
```

Often, scfg documents are structured to have a single toplevel node, for
example:

```scfg
config {
    foo foovalue
    baz bazvalue
}
```

There is no special mechanism or attribute to accomplish this. Instead, a
simple wrapper struct has to be used:

```rust
#[derive(Debug, Derpscfg)]
struct FooBar {
    foo: String,
    baz: String,
}

#[derive(Debug, Derpscfg)]
struct Config {
    config: FooBar,
}
```

## Field names

Type names are irrelevant for decoding, but field names are important. The
field names in the scfg document have to reflect the struct field names. There
is only one exception: an underscore in a struct field name can be represented
by either an underscore or a dash in the scfg document. Both will work, but
usage has to be consistent. For example:

```rust
#[derive(Debug, Derpscfg)]
struct FooBar {
    foo_bar: String,
    baz: String,
}

#[derive(Debug, Derpscfg)]
struct Config {
    config: FooBar,
}
```

can parse the following document:

```scfg
config {
    foo-bar foovalue
    baz bazvalue
}
```

Field names can also be overridden, using the `name` annotation. Note that this
will remove all ambiguity of hyphens or dashes, only the exact provided value
will work.

For example:

```rust
#[derive(Debug, Derpscfg)]
struct FooBar {
    #[scfg(name="barfoo")]
    foo_bar: String,
    baz: String,
}

#[derive(Debug, Derpscfg)]
struct Config {
    config: FooBar,
}
```

can parse the following document:

```scfg
config {
    barfoo foovalue
    baz bazvalue
}
```

## Field types and cardinality

Fields can be one of most standard library types that implement `FromStr`. A
full list is available in the [docs][docs-types]. Such fields _must_ be present
in the parsed scfg document. Fields can also be an `Option` of said types, in
which case they can be omitted in the scfg document. Or they can be a `Vec`,
`VecDeque`, or `LinkedList` of said types, in which case they can show up zero
or more times. There are currently no means to restrict cardinality on the list
types.

[docs-types]: https://docs.rs/derpscfg/latest/derpscfg/trait.DecodeScalar.html#foreign-impls

The following structs for example:

```rust
#[derive(Debug, Derpscfg)]
struct FooBar {
    foo_bar: Option<String>,
    baz: Vec<String>,
}

#[derive(Debug, Derpscfg)]
struct Config {
    config: FooBar,
}
```

would accept the following document:

```scfg
config {
# foo-bar is optional, baz has cardinality * (zero or more), so empty node
# satisfies all requirements
}
```

but also:

```scfg
config {
    baz bazvalue1 bazvalue2 bazvalue3
}
```

Note that a list of scalars can come from either repeated directives, or a
directive with multiple parameters, hence the following document is equivalent
to the one above:

```scfg
config {
    baz bazvalue1
    baz bazvalue2
    baz bazvalue3
}
```

## Parameters

Fields annotated with `#[scfg(param)]` are taken from a directive's parameters
in order of declaration. The struct field names are irrelevant in this case. Be
careful with cardinality: a `Vec` will always take _all_ available params, so
there can only be one, and it must be the last field from parameters.

Example:

```rust
#[derive(Debug, Derpscfg)]
struct FooBar {
    #[scfg(param)]
    cfgtype: String,
    foo_bar: String,
    baz: String,
}

#[derive(Debug, Derpscfg)]
struct Config {
    config: FooBar,
}
```

will parse the following:

```scfg
config debug {
    foo-bar foovalue
    baz bazvalue
}
```

where `FooBar.cfgtype` will be `"debug"`.

The toplevel `derpscfg::parse()` function can **only be used on types that _do
not_ declare any fields with `param`**, as the toplevel element does not have
any.

## Enums

The required glue for simple enums can also be derived. The enum variants must
not have any fields. The last example above could be refined accordingly:

```rust
#[derive(Debug, Derpscfg)]
enum CfgType {
    Debug,
    Release,
    ReleaseOptimized,
}

#[derive(Debug, Derpscfg)]
struct FooBar {
    #[scfg(param)]
    cfgtype: String,
    foo_bar: String,
    baz: String,
}

#[derive(Debug, Derpscfg)]
struct Config {
    config: FooBar,
}
```

This will (again) parse the following:

```scfg
config debug {
    foo-bar foovalue
    baz bazvalue
}
```

but the following would produce an error, as `prod` cannot be mapped to a
variant of `CfgType`:

```scfg
config prod {
    foo-bar foovalue
    baz bazvalue
}
```

Enum values can be written in lower, camel or snake case, so valid values would
be `Debug`, `Release`, `ReleaseOptimized`, `debug`, `release`,
`releaseoptimized`, or `release_optimized`. However, consistency matters.

## Generic key-value maps

If you need the map-style genericity of scfg in parts of your data you can
parse a field to a `Directive` (or `Option`/`Vec`/etc. thereof):

```rust
#[derive(Debug, Derpscfg)]
struct FooBar {
    foo_bar: String,
    baz: Directive,
}

#[derive(Debug, Derpscfg)]
struct Config {
    config: FooBar,
}
```

This allows arbitrary data for `baz`, such as:

```
config {
    foo-bar value
    baz takes arbitrary params {
        and arbitrary
        nested {
            child nodes
        }
    }
}
```

This defers validation to the application code, but can be useful to let users
supply arbitrary key-value-pairs or other semi-structured data.

## Default values

Fields with a cardinality of one (i.e. that are not `Option`/`Vec`/etc.) can be
declared to have a default value if not present. Annotating a field with
`#[scfg(default)]` will use the type's default value. The type must implement
`Default` for this. If the type does not implement `Default`, or a different
default value is desired, a default expression can be provided. A field
annotated for example with `#[scfg(default=String::from("default"))]` would
default to the string `"default"` as opposed to the empty string (which is the
String type's default value).

For example:

```rust
#[derive(Debug, Derpscfg)]
struct FooBar {
    #[scfg(default)]
    foo: String,
    #[scfg(default=String::from("bazvalue"))]
    baz: String,
}

#[derive(Debug, Derpscfg)]
struct Config {
    config: FooBar,
}
```

would parse an empty document:

```scfg
config {
}
```

and end up with `foo` being the empty string and `baz` being `"bazvalue"`.
