diff --git a/CHANGELOG.md b/CHANGELOG.md index c3cca22..bab56a9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,7 @@ +## 0.4.2-wip + +- Add `sdkPath` getter, deprecate `getSdkPath` function. + ## 0.4.1 - Fix a broken link in the readme. diff --git a/README.md b/README.md index c5a1b8b..d1add7c 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ A package to help in building Dart command-line apps. ## What's this? `package:cli_util` provides: -- utilities to find the Dart SDK directory (`getSdkPath()`) +- utilities to find the Dart SDK directory (`sdkPath`) - utilities to find the settings directory for a tool (`applicationConfigHome()`) - utilities to aid in showing rich CLI output and progress information (`cli_logging.dart`) @@ -20,11 +20,11 @@ import 'package:cli_util/cli_util.dart'; import 'package:path/path.dart' as path; main(args) { - // Get sdk dir from cli_util. - var sdkPath = getSdkPath(); + // Get SDK directory from cli_util. + var sdkDir = sdkPath; // Do stuff... For example, print version string - var versionFile = File(path.join(sdkPath, 'version')); + var versionFile = File(path.join(sdkDir, 'version')); print(versionFile.readAsStringSync()); } ``` diff --git a/lib/cli_util.dart b/lib/cli_util.dart index c7b867b..82ce9ea 100644 --- a/lib/cli_util.dart +++ b/lib/cli_util.dart @@ -2,7 +2,7 @@ // for details. All rights reserved. Use of this source code is governed by a // BSD-style license that can be found in the LICENSE file. -/// Utilities to return the Dart SDK location. +/// Utilities to locate the Dart SDK. library cli_util; import 'dart:async'; @@ -10,11 +10,14 @@ import 'dart:io'; import 'package:path/path.dart' as path; -/// Return the path to the current Dart SDK. -String getSdkPath() => path.dirname(path.dirname(Platform.resolvedExecutable)); +/// The path to the current Dart SDK. +String get sdkPath => path.dirname(path.dirname(Platform.resolvedExecutable)); -/// Get the user-specific application configuration folder for the current -/// platform. +/// Returns the path to the current Dart SDK. +@Deprecated("Use 'sdkPath' instead") +String getSdkPath() => sdkPath; + +/// The user-specific application configuration folder for the current platform. /// /// This is a location appropriate for storing application specific /// configuration for the current user. The [productName] should be unique to @@ -29,12 +32,12 @@ String getSdkPath() => path.dirname(path.dirname(Platform.resolvedExecutable)); /// (if `$XDG_CONFIG_HOME` is defined), and, /// * `$HOME/.config/` otherwise. /// -/// This aims follows best practices for each platform, honoring the -/// [XDG Base Directory Specification][1] on Linux and [File System Basics][2] -/// on Mac OS. +/// The chosen location aims to follow best practices for each platform, +/// honoring the [XDG Base Directory Specification][1] on Linux and +/// [File System Basics][2] on Mac OS. /// -/// Throws an [EnvironmentNotFoundException] if `%APPDATA%` or `$HOME` is needed -/// but undefined. +/// Throws an [EnvironmentNotFoundException] if an environment entry, +/// `%APPDATA%` or `$HOME`, is needed and not available. /// /// [1]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html /// [2]: https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html#//apple_ref/doc/uid/TP40010672-CH2-SW1 @@ -43,16 +46,11 @@ String applicationConfigHome(String productName) => String get _configHome { if (Platform.isWindows) { - final appdata = _env['APPDATA']; - if (appdata == null) { - throw EnvironmentNotFoundException( - 'Environment variable %APPDATA% is not defined!'); - } - return appdata; + return _requireEnv('APPDATA'); } if (Platform.isMacOS) { - return path.join(_home, 'Library', 'Application Support'); + return path.join(_requireEnv('HOME'), 'Library', 'Application Support'); } if (Platform.isLinux) { @@ -62,26 +60,26 @@ String get _configHome { } // XDG Base Directory Specification says to use $HOME/.config/ when // $XDG_CONFIG_HOME isn't defined. - return path.join(_home, '.config'); + return path.join(_requireEnv('HOME'), '.config'); } // We have no guidelines, perhaps we should just do: $HOME/.config/ // same as XDG specification would specify as fallback. - return path.join(_home, '.config'); + return path.join(_requireEnv('HOME'), '.config'); } -String get _home { - final home = _env['HOME']; - if (home == null) { - throw EnvironmentNotFoundException( - r'Environment variable $HOME is not defined!'); - } - return home; -} +String _requireEnv(String name) => + _env[name] ?? (throw EnvironmentNotFoundException(name)); +/// Exception thrown if a required environment entry does not exist. +/// +/// Thrown by [applicationConfigHome] if an expected and required +/// platform specific environment entry is not available. class EnvironmentNotFoundException implements Exception { - final String message; - EnvironmentNotFoundException(this.message); + /// Name of environment entry which was needed, but not found. + final String entryName; + String get message => 'Environment variable \'$entryName\' is not defined!'; + EnvironmentNotFoundException(this.entryName); @override String toString() => message; } diff --git a/pubspec.yaml b/pubspec.yaml index b3e05ed..a28627f 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -1,5 +1,5 @@ name: cli_util -version: 0.4.1 +version: 0.4.2-wip description: A library to help in building Dart command-line apps. repository: https://github.com/dart-lang/cli_util diff --git a/test/cli_util_test.dart b/test/cli_util_test.dart index 349b629..e16bc59 100644 --- a/test/cli_util_test.dart +++ b/test/cli_util_test.dart @@ -9,12 +9,10 @@ import 'package:cli_util/cli_util.dart'; import 'package:path/path.dart' as p; import 'package:test/test.dart'; -void main() => defineTests(); - -void defineTests() { - group('getSdkPath', () { +void main() { + group('sdkPath', () { test('sdkPath', () { - expect(getSdkPath(), isNotNull); + expect(sdkPath, isNotNull); }); });