docs: Added README and code examples for the config library #44
Conversation
📝 WalkthroughWalkthroughThis update finalizes the 0.5.0 release by consolidating previous beta changelog entries, introducing a new Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant BetterCommandRunner
participant BetterCommand
participant ConfigParser
participant ConfigurationBroker
participant Env
User->>BetterCommandRunner: run(args)
BetterCommandRunner->>BetterCommand: run(args)
BetterCommand->>ConfigParser: parse(args, env, configBroker)
ConfigParser->>Env: (if env not provided) use Platform.environment
ConfigParser->>ConfigurationBroker: (optional) fetch config values
ConfigParser->>BetterCommand: return Configuration
BetterCommand->>User: runWithConfig(Configuration)
Possibly related PRs
Suggested reviewers
Tip ⚡️ Faster reviews with caching
Enjoy the performance boost—your workflow just got faster. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (8)
CHANGELOG.md (1)
14-14: Consider more concise wordingThe phrase "in order to" could be simplified to just "to" for more concise documentation.
- fix: Replaced `yaml_codec` dependency with `yaml` in order to support Dart 3.3 + fix: Replaced `yaml_codec` dependency with `yaml` to support Dart 3.3🧰 Tools
🪛 LanguageTool
[style] ~14-~14: Consider a more concise word here.
Context: ...cedyaml_codecdependency withyamlin order to support Dart 3.3 - chore: Require Dart ...(IN_ORDER_TO_PREMIUM)
README_config.md (5)
10-10: Spelling consistency suggestionConsider standardizing on either "multi-valued" (hyphenated) or "multivalued" (single word) throughout the documentation. The common technical spelling is "multivalued".
- - Multi-valued options are typed, e.g. `List<MyEnum>`. + - Multivalued options are typed, e.g. `List<MyEnum>`.🧰 Tools
🪛 LanguageTool
[misspelling] ~10-~10: This word is normally spelled as one.
Context: ...n/max for int and DateTime options. - Multi-valued options are typed, e.g.List<MyEnum>....(EN_COMPOUNDS_MULTI_VALUED)
41-41: Consider removing intensifier for more direct writingRemoving the intensifier "very" would make the sentence more direct and professional.
- `ArgParser`, and returns a `ConfigResults` object that implements `ArgResults`. - **Usage**: You can directly replace `ArgParser` in your existing code: from the `args` package. Its purpose is to make it very easy to transition + `ArgParser`, and returns a `ConfigResults` object that implements `ArgResults`. - **Usage**: You can directly replace `ArgParser` in your existing code: from the `args` package. Its purpose is to make it easy to transition🧰 Tools
🪛 LanguageTool
[style] ~41-~41: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...rgs` package. Its purpose is to make it very easy to transition to the config library - j...(EN_WEAK_ADJECTIVE)
223-223: Consider more concise wordingThe phrase "In order to" could be simplified to just "To" for more concise documentation.
- In order to use the config library with these, they need to be subclassed + To use the config library with these, they need to be subclassed🧰 Tools
🪛 LanguageTool
[style] ~223-~223: Consider a more concise word here.
Context: ...ommandRunnerfrom theargs` package. In order to use the config library with these, they...(IN_ORDER_TO_PREMIUM)
232-232: Consider more concise wordingSimilar to previous comment, simplify "In order to" to "To" for more concise writing.
- In order to use configuration files as a source of option values, + To use configuration files as a source of option values,🧰 Tools
🪛 LanguageTool
[style] ~232-~232: Consider a more concise word here.
Context: ...e.dart). ## Using configuration files In order to use configuration files as a source of ...(IN_ORDER_TO_PREMIUM)
247-247: Add comma for improved readabilityAdding a comma after "In this example" would improve readability and flow.
- In this example the configuration file is a JSON or + In this example, the configuration file is a JSON or🧰 Tools
🪛 LanguageTool
[typographical] ~247-~247: It appears that a comma is missing.
Context: ...ition, specify theconfigKey. In this example the configuration file is a JSON or YAM...(DURING_THAT_TIME_COMMA)
example/config_file_example.dart (2)
44-44: Consider using an absolute path for the default config file.The default config file path is relative, which could cause issues if the working directory is different from the expected location.
-File _defaultConfigFilePath() => File('example/config.yaml'); +File _defaultConfigFilePath() => File(Platform.script.resolve('example/config.yaml').toFilePath());Don't forget to add the import:
import 'dart:io' show File, Platform;
1-88: Consider adding documentation comments to enhance the example.As this is an example file, adding documentation comments (///) would help users understand how to use the config library more effectively.
+/// Example demonstrating the use of the CLI tools config library. +/// +/// This example shows how to: +/// - Define typed options using an enum +/// - Create a command that extends BetterCommand +/// - Load configuration from multiple sources (args, env vars, config file) +/// - Implement a custom ConfigurationBroker import 'dart:io' show File;
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (10)
CHANGELOG.md(1 hunks)README.md(1 hunks)README_config.md(1 hunks)example/config.yaml(1 hunks)example/config_file_example.dart(1 hunks)example/config_simple_example.dart(1 hunks)example/main.dart(4 hunks)lib/config.dart(1 hunks)lib/src/config/config_parser.dart(3 hunks)pubspec.yaml(1 hunks)
🧰 Additional context used
🪛 LanguageTool
CHANGELOG.md
[style] ~14-~14: Consider a more concise word here.
Context: ...ced yaml_codec dependency with yaml in order to support Dart 3.3 - chore: Require Dart ...
(IN_ORDER_TO_PREMIUM)
README_config.md
[misspelling] ~10-~10: This word is normally spelled as one.
Context: ...n/max for int and DateTime options. - Multi-valued options are typed, e.g. List<MyEnum>....
(EN_COMPOUNDS_MULTI_VALUED)
[style] ~41-~41: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...rgs` package. Its purpose is to make it very easy to transition to the config library - j...
(EN_WEAK_ADJECTIVE)
[style] ~223-~223: Consider a more concise word here.
Context: ...ommandRunnerfrom theargs` package. In order to use the config library with these, they...
(IN_ORDER_TO_PREMIUM)
[style] ~232-~232: Consider a more concise word here.
Context: ...e.dart). ## Using configuration files In order to use configuration files as a source of ...
(IN_ORDER_TO_PREMIUM)
[typographical] ~247-~247: It appears that a comma is missing.
Context: ...ition, specify the configKey. In this example the configuration file is a JSON or YAM...
(DURING_THAT_TIME_COMMA)
🔇 Additional comments (27)
example/config.yaml (1)
1-2: Simple configuration file looks goodThis YAML configuration file provides a clean example with a single interval setting of 3 seconds, which will be used by the example CLI applications to demonstrate configuration loading.
pubspec.yaml (1)
2-2: Version bump to stable release 0.5.0The version has been updated from the beta version to a stable release, which is appropriate for finalizing this feature set and introducing the new config library.
README.md (2)
5-6: Improved introduction claritySplitting the introduction into two sentences improves readability and clarifies the purpose of the package.
8-14: Good addition of config library sectionThe new section provides a concise overview of the config library's capabilities and directs users to the detailed README. This helps users quickly understand the value proposition without overwhelming them with details.
lib/config.dart (1)
2-3: Appropriate export of UsageExceptionRe-exporting the
UsageExceptionfrom the args package is a good practice as it allows users of the config library to handle exceptions without requiring an additional import. This supports clean error handling in client code.example/main.dart (4)
3-3: Improved main function signatureChanging from
void maintoFuture<int> mainfollows best practices for CLI applications by allowing proper exit code propagation through the return value rather than callingexit().
18-18: Better error handling approachReturning an exit code instead of calling
exit(1)directly is more testable and follows better async practices for CLI applications.
42-42: Added explicit success return codeAdding an explicit return of
0on successful completion provides clarity and consistency with the error case handling.
99-99: Simplified method signatureChanging
runWithConfigfromFutureOr<void>?tovoidsimplifies the signature. Since the implementation is synchronous, this is appropriate and reduces complexity.CHANGELOG.md (1)
3-15: Well-structured changelog entries with clear semantic versioningThe changelog effectively consolidates all the beta releases into a clean 0.5.0 release, with clear categorization of features, fixes, and breaking changes. This organization makes it easy for users to understand what changed in this version.
🧰 Tools
🪛 LanguageTool
[style] ~14-~14: Consider a more concise word here.
Context: ...cedyaml_codecdependency withyamlin order to support Dart 3.3 - chore: Require Dart ...(IN_ORDER_TO_PREMIUM)
lib/src/config/config_parser.dart (3)
1-2: LGTM: Added import for Platform.environmentThe added import for dart:io provides access to Platform.environment, which is used as the default value for environment variables in the parse method.
218-232: Well-documented method with clear parameter descriptionsThe extended documentation for the parse method clearly explains the new parameters and their purpose, making it easy for users to understand how to use this enhanced functionality.
233-250: Enhanced parse method with robust configuration sources supportThe implementation correctly allows for multiple configuration sources: command-line arguments, environment variables, configuration files, and preset values. The default to Platform.environment when env is not provided is a sensible choice for real-world usage.
example/config_simple_example.dart (3)
1-17: Clear main function with proper error handlingThe main function is well-structured with appropriate error handling for UsageException. It demonstrates the recommended pattern for setting up a CLI application with the BetterCommandRunner.
19-33: Well-designed option definition using enumThe TimeSeriesOption enum provides a clean, type-safe way to define CLI options. The use of a DurationOption with min/max constraints demonstrates the library's ability to enforce validation rules.
35-49: Clean command implementation with typed configurationThe TimeSeriesCommand class shows how to implement a command that uses the typed configuration. The runWithConfig method demonstrates the type-safe access to option values.
README_config.md (8)
1-37: Excellent introduction to the config library's capabilitiesThe introduction clearly outlines the key features and improvements over the standard args package. The bullet points provide a good overview of what makes this library valuable for CLI application developers.
🧰 Tools
🪛 LanguageTool
[misspelling] ~10-~10: This word is normally spelled as one.
Context: ...n/max for int and DateTime options. - Multi-valued options are typed, e.g.List<MyEnum>....(EN_COMPOUNDS_MULTI_VALUED)
38-65: Helpful drop-in replacement sectionThis section effectively communicates how developers can gradually migrate from the args package to the config library, making adoption easier.
🧰 Tools
🪛 LanguageTool
[style] ~41-~41: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...rgs` package. Its purpose is to make it very easy to transition to the config library - j...(EN_WEAK_ADJECTIVE)
66-159: Comprehensive usage examples with clear explanationsThe usage examples provide both enum-based and list-based option definitions, clearly showing how to define and access configuration values. The note about nullable vs. non-nullable return types is particularly helpful.
160-194: Well-structured option types table and feature listThe options table and feature list provide a clear overview of the library's capabilities, making it easy for users to understand what's available.
195-218: Excellent sequence diagram for configuration resolutionThe mermaid sequence diagram provides a visual explanation of how configuration is resolved, which helps users understand the internal workings of the library.
219-230: Clear integration guide with commandsThis section effectively explains how to integrate the config library with command-line applications using the BetterCommand and BetterCommandRunner classes.
🧰 Tools
🪛 LanguageTool
[style] ~223-~223: Consider a more concise word here.
Context: ...ommandRunnerfrom theargs` package. In order to use the config library with these, they...(IN_ORDER_TO_PREMIUM)
231-285: Thorough explanation of configuration file integrationThis section provides a clear explanation of how to use configuration files as a source of option values, including support for multiple configuration sources with domains.
🧰 Tools
🪛 LanguageTool
[style] ~232-~232: Consider a more concise word here.
Context: ...e.dart). ## Using configuration files In order to use configuration files as a source of ...(IN_ORDER_TO_PREMIUM)
[typographical] ~247-~247: It appears that a comma is missing.
Context: ...ition, specify theconfigKey. In this example the configuration file is a JSON or YAM...(DURING_THAT_TIME_COMMA)
286-306: Clear contribution guidelines and attributionThe contribution guidelines are straightforward, and the attribution to Serverpod is appropriately highlighted.
example/config_file_example.dart (3)
6-20: Well-structured main function with proper error handling.The main function follows best practices by using the BetterCommandRunner, properly handling usage exceptions, and returning appropriate exit codes.
22-42: Good use of enum-based option definitions with constraints.The TimeSeriesOption enum effectively implements OptionDefinition with well-defined constraints:
- configFile option properly validates file existence
- interval option includes appropriate min/max bounds
- JSON pointer notation used correctly for hierarchical config
This demonstrates best practices for creating strongly-typed options.
46-70: Good command implementation with clear configuration resolution.The TimeSeriesCommand class demonstrates:
- Proper extension of BetterCommand with typed options
- Clear command name and description
- Simple implementation of runWithConfig
- Comprehensive configuration resolution using multiple sources
This shows the layered configuration approach working correctly.
dkbast
left a comment
dkbast
left a comment
There was a problem hiding this comment.
🚀 this is super nice and makes me want to build a cli tool just for fun :)!
The docs might need a few more links so the user can find their way around more quickly and some features might need a bit more clarification.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (4)
README_config.md (4)
1-4: Consider adding a Table of Contents for easier navigation
This README is quite long—adding a linked Table of Contents right after the# Configheader would help readers jump to sections of interest (e.g., “Usage”, “Resolution order”, “Supported option types”).
47-49: Streamline phrasing & improve link
Instead of“with the exception of
addCommand()”
you can write:
“except foraddCommand()”
for brevity. Also, rather than linking directly to the source file, consider linking to the published Dart API docs forBetterCommandRunner(e.g.,https://pub.dev/documentation/cli_tools/latest/cli_tools/BetterCommandRunner-class.html) to give users direct reference.🧰 Tools
🪛 LanguageTool
[style] ~47-~47: Consider using “except” or “except for”
Context: ...compatibility with the original package with the exception of addCommand(), which you can replace wit...(WITH_THE_EXCEPTION_OF)
187-189: Avoid repeating the same phrase
In the “Resolution order” list:2. **Environment variables** - Environment variables have second precedence...Consider omitting the repeated “Environment variables” in the bullet text, e.g.:
2. **Environment variables** - Have second precedence after CLI arguments...🧰 Tools
🪛 LanguageTool
[grammar] ~187-~187: This phrase is duplicated. You should probably use “Environment variables” only once.
Context: ...gName,argAbbrev, andargPos` 2. Environment variables - Environment variables have second precedence after CLI argume...(PHRASE_REPETITION)
220-221: Correct verb form for consistency
Change “helps constructing specific test cases” to “helps construct specific test cases” for grammatical accuracy.-helps constructing specific test cases. +helps construct specific test cases.🧰 Tools
🪛 LanguageTool
[grammar] ~221-~221: The verb ‘helps’ is used with an infinitive.
Context: ... sources depending on context and helps constructing specific test cases. ### Supported opt...(ADVISE_VBG)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
README_config.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
README_config.md
[style] ~47-~47: Consider using “except” or “except for”
Context: ...compatibility with the original package with the exception of addCommand(), which you can replace wit...
(WITH_THE_EXCEPTION_OF)
[grammar] ~187-~187: This phrase is duplicated. You should probably use “Environment variables” only once.
Context: ...gName, argAbbrev, and argPos` 2. Environment variables - Environment variables have second precedence after CLI argume...
(PHRASE_REPETITION)
[duplication] ~196-~196: Possible typo: you repeated a word.
Context: ...lue providers** - Values from custom callbacks - Callbacks are allowed to depend on other option v...
(ENGLISH_WORD_REPEAT_RULE)
[grammar] ~221-~221: The verb ‘helps’ is used with an infinitive.
Context: ... sources depending on context and helps constructing specific test cases. ### Supported opt...
(ADVISE_VBG)
[grammar] ~362-~362: Did you mean “these”?
Context: ... is the remainder after the match.\ This makes prefix matching simple. - If th...
(THIS_NNS_VB)
[grammar] ~363-~363: Make sure that the adjective ‘entire’ is correct. Possibly, it should be an adverb (typically ~ly) that modifies ‘qualified’. Possibly, it should be the first word in a compound adjective (hyphenated adjective). Possibly, it is correct.
Context: ...ire qualified key, the value key is the entire qualified key.\ This can be used for specific...
(ADVERB_OR_HYPHENATED_ADJECTIVE)
dkbast
left a comment
dkbast
left a comment
There was a problem hiding this comment.
🚀 looks good to me - personally I would love to have a short example about "define from file" as a parameter, since thats the "problem" which I have been facing the most in this specific context.
Thank you! Added a direct link to that section and there is also a complete but short example how to implement it. |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (6)
README_config.md (6)
1-4: Add context and hyperlinks in the introductionConsider linking to the Dart
argspackage documentation and adding a brief note about the package import (e.g.,package:cli_tools/config.dart) and version (0.5.0) at the top to help users get started quickly.- # Config + # Config (v0.5.0) + + Built on top of the Dart [`args`][args-docs] package, this library provides… + +[args-docs]: https://pub.dev/documentation/args/latest/
28-31: Fix typo in 'Traceability'The word "Tracability" is misspelled.
- - Tracability - the information on an option's value source is retained. + - Traceability – the information on an option's value source is retained.
45-50: Simplify phrasing for exception clauseReplace "with the exception of" with "except for" for conciseness.
- It achieves complete compatibility with the original package with the exception - of addCommand(), which you can replace with [`BetterCommandRunner`](…). + It achieves complete compatibility with the original package except for + `addCommand()`, which you can replace with [`BetterCommandRunner`](…).🧰 Tools
🪛 LanguageTool
[style] ~48-~48: Consider using “except” or “except for”
Context: ...compatibility with the original package with the exception of addCommand(), which you can replace wit...(WITH_THE_EXCEPTION_OF)
184-192: Avoid duplicated heading in resolution orderYou list "Environment variables" twice (once as the numbered title and again in the description). Consider removing the redundant phrase in the bullet or merging the two lines.
- 2. **Environment variables** - - Environment variables have second precedence after CLI arguments + 2. **Environment variables** + - Have second precedence after CLI arguments🧰 Tools
🪛 LanguageTool
[grammar] ~188-~188: This phrase is duplicated. You should probably use “Environment variables” only once.
Context: ...gName,argAbbrev, andargPos` 2. Environment variables - Environment variables have second precedence after CLI argume...(PHRASE_REPETITION)
215-222: Correct verb form in resolution sourcesChange "helps constructing specific test cases" to "helps construct specific test cases".
- ... and helps constructing specific test cases. + ... and helps construct specific test cases.🧰 Tools
🪛 LanguageTool
[grammar] ~222-~222: The verb ‘helps’ is used with an infinitive.
Context: ... sources depending on context and helps constructing specific test cases. ### Supported opt...(ADVISE_VBG)
48-50: Link to BetterCommandRunner docsInstead of linking to the source file path, consider linking to the hosted Dart API documentation for
BetterCommandRunnerto improve the UX.- [`BetterCommandRunner`](lib/src/better_command_runner/better_command_runner.dart) + [`BetterCommandRunner`][bcr-docs] + +[bcr-docs]: https://pub.dev/documentation/cli_tools/latest/better_command_runner/BetterCommandRunner-class.html🧰 Tools
🪛 LanguageTool
[style] ~48-~48: Consider using “except” or “except for”
Context: ...compatibility with the original package with the exception of addCommand(), which you can replace wit...(WITH_THE_EXCEPTION_OF)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
README_config.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
README_config.md
[style] ~48-~48: Consider using “except” or “except for”
Context: ...compatibility with the original package with the exception of addCommand(), which you can replace wit...
(WITH_THE_EXCEPTION_OF)
[grammar] ~188-~188: This phrase is duplicated. You should probably use “Environment variables” only once.
Context: ...gName, argAbbrev, and argPos` 2. Environment variables - Environment variables have second precedence after CLI argume...
(PHRASE_REPETITION)
[duplication] ~197-~197: Possible typo: you repeated a word.
Context: ...lue providers** - Values from custom callbacks - Callbacks are allowed to depend on other option v...
(ENGLISH_WORD_REPEAT_RULE)
[grammar] ~222-~222: The verb ‘helps’ is used with an infinitive.
Context: ... sources depending on context and helps constructing specific test cases. ### Supported opt...
(ADVISE_VBG)
[grammar] ~383-~383: Did you mean “these”?
Context: ... is the remainder after the match.\ This makes prefix matching simple. - If th...
(THIS_NNS_VB)
[grammar] ~384-~384: Make sure that the adjective ‘entire’ is correct. Possibly, it should be an adverb (typically ~ly) that modifies ‘qualified’. Possibly, it should be the first word in a compound adjective (hyphenated adjective). Possibly, it is correct.
Context: ...ire qualified key, the value key is the entire qualified key.\ This can be used for specific...
(ADVERB_OR_HYPHENATED_ADJECTIVE)
🔇 Additional comments (1)
README_config.md (1)
310-328:✅ Verification successful
Verify correct factory method on configuration broker
The example uses
ConfigurationParser.fromFilebut it may actually beConfigurationSource.fromFileor similar. Please confirm that this factory exists and matches the public API.
🏁 Script executed:
#!/bin/bash # Search for a `fromFile` factory in config-related classes rg -R "fromFile" -n lib/src/configLength of output: 439
🏁 Script executed:
#!/bin/bash # Correct recursive search for `fromFile` and related classes in the lib directory rg -n "fromFile(" lib rg -n "class ConfigurationParser" lib rg -n "class ConfigurationSource" libLength of output: 342
🏁 Script executed:
#!/bin/bash # Inspect ConfigurationParser for a fromFile factory rg -n -C3 'class ConfigurationParser' lib/src/config/configuration_parser.dart # Search specifically for any ‘fromFile’ occurrences, escaping parentheses rg -n 'fromFile\(' lib # Fallback: simple grep search for the literal string grep -R "fromFile(" -n libLength of output: 596
Confirmed
ConfigurationParser.fromFileExistsThe
ConfigurationParserclass inlib/src/config/configuration_parser.dartdefines a staticfromFilefactory that returns aConfigurationSource, so the example is correct as written.
Added README and code examples for the config library, with link from the main README.
Bump from beta to release 0.5.0.
Summary by CodeRabbit
New Features
Bug Fixes
Documentation
Chores