Overview

This package provides a comprehensive set of tools for managing discloud.config files. It allows you to read, write, and validate your Discloud configurations with ease. The package is designed to be used in Dart applications that interact with the Discloud hosting service.

Useful links

• Discloud
• Discloud Docs
• Discloud Config Docs

Installation

Add it to your pubspec.yaml as a dependencies by running the following command.

dart pub add discloud_config

Usage

Import

import 'package:discloud_config/discloud_config.dart';

Make an instance

You can create a DiscloudConfig instance in several ways:

// From a File
final configFile = File('path/to/your/project/discloud.config');
final config = DiscloudConfig(configFile);

// From a directory path (asynchronously)
final configFromPath = await DiscloudConfig.fromPath('path/to/your/project');

// From a FileSystemEntity (asynchronously)
final directory = Directory('path/to/your/project');
final configFromEntity = await DiscloudConfig.fromFileSystemEntity(directory);

// From a Uri (asynchronously)
final uri = Uri.file('path/to/your/project');
final configFromUri = await DiscloudConfig.fromUri(uri);

All constructors accept an optional autoSave parameter. See the "Auto-saving" section for more details.

Watch configuration file

• DiscloudConfigData is read-only, see Updating DiscloudConfigData

// Stream<DiscloudConfigData?>
await for (final DiscloudConfigData? data in config.watch()) {
  // ...
}

Auto-saving

The autoSave parameter in the constructors (DiscloudConfig.fromPath, DiscloudConfig.fromFileSystemEntity, etc.) controls whether changes are automatically written to the file.

• If autoSave is true (the default), any call to set or setData will immediately save the changes to the discloud.config file.

• If autoSave is false, you must manually call the save method to persist any changes you've made. This can be useful for batching multiple changes together.

Example:

// With autoSave enabled (default)
final config = await DiscloudConfig.fromPath('path/to/your/project'); // autoSave is true
await config.set(DiscloudScope.RAM, 1024); // Changes are saved automatically

// With autoSave disabled
final config2 = await DiscloudConfig.fromPath('path/to/your/project', autoSave: false);
await config2.set(DiscloudScope.RAM, 2048); // Changes are not saved yet
await config2.save(); // Manually save the changes

Create a new DiscloudConfigData from JSON

DiscloudConfigData.fromJson(Map<String, dynamic>);

Updating DiscloudConfigData

// Use copyWith
final DiscloudConfigData newData = oldData.copyWith(TYPE: DiscloudAppType.bot.name/*"bot"*/);

List all configuration files recursively

// Stream<File>
await for (final File file in listDiscloudConfigFiles(Directory)) {
  // ...
}

Recursively list configuration structures by ID

// Stream<DiscloudConfig>
await for (final DiscloudConfig config in listDiscloudConfigByAppId(Directory, String)) {
  // ...
}

Contributing

We welcome a diverse set of contributions, including, but not limited to:

• Filing bugs and feature requests
• Send a pull request
• Or, create something awesome using this API and share with us and others!

For the stability of the API and existing users, consider opening an issue first before implementing a large new feature or breaking an API. For smaller changes (like documentation, minor bug fixes), just send a pull request.

Testing

All pull requests are validated against CI, and must pass.

Ensure build runs

dart run build_runner build

Ensure code passes all our analyzer checks:

dart analyze

Ensure all code is formatted with the latest dev-channel SDK.

dart format .
dart fix --apply

Run all of our unit tests:

dart test

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.