Module doc_howto 

How to declare a configuration type

Getting started

Every configuration type should implement at least Clone and Debug; it should almost¹ always implement PartialEq too. In addition to these, you should use derive(Deftly) and derive_deftly(TorConfig) to use this macro.

You can start out by copying this template:

use derive_deftly::Deftly;
use tor_config::derive::prelude::*;

#[derive(Deftly, Clone, Debug, PartialEq)]
#[derive_deftly(TorConfig)]
pub struct XyzzyConfig {
    // ...
}

Declaring fields

At this point, you start declaring the fields that should appear in the configuration. You declare them as struct fields (as usual); but to avoid mistakes, you need to specify the default behavior for each field. You typically do this in one of the following ways:

// If the user doesn't set this field, we set it by calling some_function().
#[deftly(tor_config(default="some_function()"))]
value1: u32,

// If the user doesn't set this field, we set it by calling Default::default().
#[deftly(tor_config(default))]
value2: String,

// This field has no default!  It's an error if the user doesn't set this.
// (See warnings on no_default below.)
#[deftly(tor_config(no_default))]
value3: u16,

Notes:

• There is no “default” behavior for the unset fields: you need to say which one you want. This requirement is meant to avoid programming errors.
• Try to avoid using no_default on any configuration element unless you truly want the user to specify it in their configuration file every time this section exists. It’s okay to use no_default on something like the address of a fallback directory (where each one needs to be fully specified) or the nickname of an onion service (which needs to be specified for every onion service that exists).
• If you use no_default, you will need to use no_default_trait on the structure as a whole.

Other things you can do

There are many other attributes you can set on struct and fields to control their behavior. See the reference for more information.

---

1. If you decide not to implement PartialEq for some reason, you will need to use the no_test_default attribute to suppress a test that requires it. (I do not really know why you would do this. Just implement PartialEq, or edit this documentation to explain why people would sometimes not want to implement it.) ↩