safe_config 2.0.1

  • README.md
  • CHANGELOG.md
  • Installing
  • Versions
  • 81

safe_config

A library to add type and name safety to YAML configuration files.

Basic Usage

safe_config is simple - it maps YAML files to Dart objects using the keys as property names. This mapping ensures that the types of your YAML values are checked at runtime and that you haven't typo'ed any YAML key names.

Consider a case where you want to configure the port and the Server header of your application. You define a subclass of Configuration with those properties:

class ApplicationConfiguration extends Configuration {
 	ApplicationConfiguration(String fileName) : 
 		super.fromFile(fileName);
	
	int port;
	String serverHeader;
}

Your YAML file should contain those two, case-sensitive keys:

port: 8000
serverHeader: booyah/1

To read your configuration file:

var config = new ApplicationConfiguration("config.yaml");
print("${config.port}"); // -> 8000
print("${config.serverHeader}"); // -> "booyah/1"

If port is not an int or is missing, you will get an exception. If serverHeader is not a String or missing, you will get an exception.

Useful Usage

You may mark properties in Configurations as optional.

class ApplicationConfiguration extends Configuration {
 	ApplicationConfiguration(String fileName) : 
 		super.fromFile(fileName);
	
	int port;
	
	@optionalConfiguration
	String serverHeader;
}

If serverHeader is omitted from your YAML when read, its value will be null and no exception is thrown.

There are two built-in Configuration, DatabaseConfiguration and APIConfiguration. These contain typical properties for common configuration values.

You may nest Configuration as deeply as you wish:

class ApplicationConfiguration extends Configuration {
 	ApplicationConfiguration(String fileName) : 
 		super.fromFile(fileName);
	
	int port;
	
	DatabaseConfiguration userDatabase;
}

For which the YAML may be:

port: 8000
userDatabase:
  databaseName: dartstuff
  host: stablekernel.com
  port: 5432

You may also use arrays and maps, for which the values can be primitive types or Configuration subclasses.

class ApplicationConfiguration extends Configuration {
 	ApplicationConfiguration(String fileName) : 
 		super.fromFile(fileName);
		
	Map<String, DatabaseConfiguration> databases;
}

The YAML here may be:

databases:
  db1:
    databaseName: dartstuff
    host: stablekernel.com
    port: 5432
  db2:
    databaseName: otherstuff
    host: somewhereoutthere.com
    port: 5432

Then, you may access it as such:

var config = new ApplicationConfig("config.yaml");

var databaseOne = config.databases["db1"];
await database.connect(databaseOne.host, 
	databaseOne.port, 
	databaseOne.databaseName);

A configuration may have multiple YAML representations. For example, a DatabaseConfiguration can be represented as a Map<String, dynamic> of each component (username, host, etc.). It may also be represented as a connection string, e.g. "postgres://user:password@host:port/database". You may allow this behavior by overriding decode in a subclass of Configuration:

class AuthorityConfiguration extends Configuration {
  String username;
  String password;

  void decode(dynamic anyValue) {
    if (anyValue is! String) {
      throw new ConfigurationException("Expected a String for AuthorityConfiguration.";
    }

    username = anyValue.split(":").first;
    password = anyValue.split(":").last;
  }
}

This configuration could be read in either of these two scenarios:

authority:
    username: "Bob"
    password: "Fred"

// or

authority: "Bob:Fred"

Configurations may also be redirected to use environment variables. To reference an environment variable in a configuration file, use the '$VARIABLE' syntax as a value:

port: $PORT

When read, this configuration file would replace '$PORT' with the environment variable named 'PORT'.

See the tests for more examples.

Features and bugs

Please file feature requests and bugs at the issue tracker.

Changelog

2.0.1

  • Better error messaging for incorrect types
  • Allow 'bool' data type, fix regression in 2.0.0
  • Allow default values, fix regression in 2.0.0

2.0.0

  • Dart 2.0 compatability.
  • Rename ConfigurationItem -> Configuration.
  • Rename DatabaseConnectionConfiguration -> DatabaseConfiguration.

1.2.2

  • Fixes issue where environment variables could not be decoded as ConfigurationItems

1.2.1

  • Throws exception when parsing if environment variable does not exist and is required.

1.2.0

  • Allow ConfigurationItem to validate their values by overriding validate (Thanks to Denis Albuquerque, @zidenis)

1.1.3

  • Ignore private variables declared in ConfigurationItem subclasses

1.1.2

  • Ignore static variables declared in ConfigurationItem subclasses

1.1.1

  • Throw exception if an unexpected key is found when reading configuration.

1.1.0

  • Enable support for reading environment variables.
  • Allow decoders for ConfigurationItem subclasses that may have multiple representations, e.g. a DatabaseConnectionConfiguration from a database connection string.

1.0.4

  • Fix issue where nested ConfigurationItems marked as optional would fail to parse.

1.0.3

  • Add ConfigurationItem.fromMap to pass a Map as the source for a ConfigurationItem.

1.0.2

  • Add library level documentation.

1.0.1

  • Add documentation generation.
  • Update readme.

1.0.0

  • Initial version.

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  safe_config: ^2.0.1

2. Install it

You can install packages from the command line:

with pub:


$ pub get

Alternatively, your editor might support pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:safe_config/safe_config.dart';
  
Version Uploaded Documentation Archive
2.0.1 Sep 20, 2018 Go to the documentation of safe_config 2.0.1 Download safe_config 2.0.1 archive
2.0.0 Aug 6, 2018 Go to the documentation of safe_config 2.0.0 Download safe_config 2.0.0 archive
1.2.2 Apr 2, 2018 Go to the documentation of safe_config 1.2.2 Download safe_config 1.2.2 archive
1.2.1 Nov 28, 2017 Go to the documentation of safe_config 1.2.1 Download safe_config 1.2.1 archive
1.2.0 Jun 6, 2017 Go to the documentation of safe_config 1.2.0 Download safe_config 1.2.0 archive
1.1.3 Dec 31, 2016 Go to the documentation of safe_config 1.1.3 Download safe_config 1.1.3 archive
1.1.2 Dec 30, 2016 Go to the documentation of safe_config 1.1.2 Download safe_config 1.1.2 archive
1.1.1 Nov 10, 2016 Go to the documentation of safe_config 1.1.1 Download safe_config 1.1.1 archive
1.1.0 Sep 29, 2016 Go to the documentation of safe_config 1.1.0 Download safe_config 1.1.0 archive
1.0.4 Aug 28, 2016 Go to the documentation of safe_config 1.0.4 Download safe_config 1.0.4 archive

All 16 versions...

Popularity:
Describes how popular the package is relative to other packages. [more]
73
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
70
Overall:
Weighted score of the above. [more]
81
Learn more about scoring.

We analyzed this package on Sep 20, 2018, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.0.0
  • pana: 0.12.3

Platforms

Detected platforms: other

Primary library: package:safe_config/safe_config.dart with components: io, mirrors.

Suggestions

The description is too short.

Add more detail about the package, what it does and what is its target use case. Try to write at least 60 characters.

Maintain an example.

Create a short demo in the example/ directory to show how to use this package. Common file name patterns include: main.dart, example.dart or you could also use safe_config.dart.

Format lib/safe_config.dart.

Run dartfmt to format lib/safe_config.dart.

Format lib/src/configuration.dart.

Run dartfmt to format lib/src/configuration.dart.

Format lib/src/default_configurations.dart.

Run dartfmt to format lib/src/default_configurations.dart.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0 <3.0.0
yaml >=2.1.8 <3.0.0 2.1.15
Transitive dependencies
charcode 1.1.2
collection 1.14.11
meta 1.1.6
path 1.6.2
source_span 1.4.1
string_scanner 1.0.4
Dev dependencies
test ^1.3.0