Various comment updates and little fixes (#51)
* Update travis.sh to use .analysis_options…
Was accidentally pointing to a non-existing file before.
* Replace uses of !<collection>isEmpty with
… isNotEmpty, as-per Dart style guide.
* Run all tests when calculating coverage
* Various comment cleanups, specifically…
… around having the first line be standalone (more readable) and not repeating comments too much. No actual changes otherwise.
* Remove unneeded @TestOn/library directives.
* Address comments.
diff --git a/lib/chroot.dart b/lib/chroot.dart
index aec1804..0001231 100644
--- a/lib/chroot.dart
+++ b/lib/chroot.dart
@@ -1,7 +1 @@
-/// A file system implementation that provides a view onto another file
-/// system, taking a path in the underlying file system, and making that the
-/// apparent root of the new file system. This is similar in concept to a
-/// `chroot` operation on Linux operating systems. Such a modified file system
-/// cannot name (and therefore normally cannot access) files outside the
-/// designated directory tree.
export 'src/backends/chroot.dart';
diff --git a/lib/src/backends/chroot/chroot_file_system.dart b/lib/src/backends/chroot/chroot_file_system.dart
index df407ba..ca573f1 100644
--- a/lib/src/backends/chroot/chroot_file_system.dart
+++ b/lib/src/backends/chroot/chroot_file_system.dart
@@ -3,44 +3,48 @@
const String _thisDir = '.';
const String _parentDir = '..';
-/// A file system implementation that provides a view onto another file
-/// system, taking a path in the underlying file system, and making that the
-/// apparent root of the new file system. This is similar in concept to a
-/// `chroot` operation on Linux operating systems. Such a modified file system
-/// cannot name (and therefore normally cannot access) files outside the
-/// designated directory tree.
+/// File system that provides a view into _another_ [FileSystem] via a path.
///
-/// This file system maintains its own [currentDirectory], distinct from that
-/// of the underlying file system. This means that setting the current directory
-/// of this file system will have no bearing on the current directory of the
-/// underlying file system, and vice versa. When new instances of this file
-/// system are created, their current directory is initialized to `/` (the root
-/// of this file system).
+/// This is similar in concept to the `chroot` operation in Linux operating
+/// systems. Such a modified file system cannot name or access files outside of
+/// the designated directory tree.
///
-/// Note that the implementation of this file system does *not* leverage any
-/// underlying OS system calls (such as `chroot`), so the developer needs to
-/// take care to not assume any more of a secure environment than is actually
-/// being provided. Notably, users of this file system have direct access to
-/// the underlying file system via the [delegate] property, which underscores
-/// the fact that this file system is intended as a convenient abstraction,
-/// not as a sucurity measure.
+/// ## Example use:
+/// ```dart
+/// // Create a "file system" where the root directory is /tmp/some-dir.
+/// var fs = new ChrootFileSystem(existingFileSystem, '/tmp/some-dir');
+/// ```
///
-/// Also note that this file system *necessarily* carries a certain performance
-/// overhead. This is due to the fact that symbolic links must be resolved
-/// manually by this file system (link resolution may not be delegated to the
-/// underlying file system). Thus, all paths must be walked to check for
-/// symbolic links at every element of the path.
+/// **Notes on usage**:
+///
+/// * This file system maintains its _own_ [currentDirectory], distinct from
+/// that of the underlying file system, and new instances automatically start
+/// at the root (i.e. `/`).
+///
+/// * This file system does _not_ leverage any underlying OS system calls (such
+/// as `chroot` itself), so the developer needs to take care to not assume any
+/// more of a secure environment than is actually provided. For instance, the
+/// underlying system is available via the [delegate] - which underscores this
+/// file system is intended to be a convenient abstraction, not a security
+/// measure.
+///
+/// * This file system _necessarily_ carries certain performance overhead due
+/// to the fact that symbolic links are resolved manually (not delegated).
class ChrootFileSystem extends FileSystem {
+ /// Underlying file system.
final FileSystem delegate;
+
+ /// Directory in [delegate] file system that is treated as the root here.
final String root;
String _systemTemp;
+
+ /// Path to the synthetic current working directory in this file system.
String _cwd;
- /// Creates a new `ChrootFileSystem` backed by the specified [delegate] file
- /// system, but making [root] the apparent root of the new file system.
+ /// Creates a new file system backed by [root] path in [delegate] file system.
///
- /// [root] must be a canonicalized path, or an [ArgumentError] will be thrown.
+ /// **NOTE**: [root] must be a _canonicalized_ path; see [p.canonicalize].
ChrootFileSystem(this.delegate, this.root) {
if (root != p.canonicalize(root)) {
throw new ArgumentError.value(root, 'root', 'Must be canonical path');
@@ -48,9 +52,6 @@
_cwd = _localRoot;
}
- /// Gets the path context for this file system given the current working dir.
- p.Context get _context => new p.Context(current: _cwd);
-
/// Gets the root path, as seen by entities in this file system.
String get _localRoot => p.rootPrefix(root);
@@ -75,19 +76,25 @@
return directory(_systemTemp)..createSync();
}
- /// Gets the current working directory for this file system. Note that this
- /// does *not* proxy to the underlying file system's current directory in
- /// any way; the state of this file system's current directory is local to
- /// this file system.
+ p.Context get _context => new p.Context(current: _cwd);
+
+ /// Creates a directory object pointing to the current working directory.
+ ///
+ /// **NOTE** This does _not_ proxy to the underlying file system's current
+ /// directory in any way; the state of this file system's current directory
+ /// is local to this file system.
@override
Directory get currentDirectory => directory(_cwd);
- /// Sets the current working directory for this file system. Note that this
- /// does *not* proxy to the underlying file system's current directory in
- /// any way; the state of this file system's current directory is local to
- /// this file system.
+ /// Sets the current working directory to the specified [path].
+ ///
+ /// **NOTE** This does _not_ proxy to the underlying file system's current
+ /// directory in any way; the state of this file system's current directory
+ /// is local to this file system.
+ /// Gets the path context for this file system given the current working dir.
+
@override
- set currentDirectory(dynamic path) {
+ set currentDirectory(path) {
String value;
if (path is io.Directory) {
value = path.path;
@@ -168,15 +175,19 @@
return delegate.typeSync(realPath, followLinks: false);
}
- /// Converts a path in the underlying delegate file system to a local path
- /// in this file system. If [relative] is true, then the resulting
- /// path will be relative to [currentDirectory]; otherwise the resulting
- /// path will be absolute.
+ /// Converts a [realPath] in the underlying file system to a local path here.
///
- /// If [realPath] represents a path outside of this file system's root, a
- /// [_ChrootJailException] will be thrown, unless [keepInJail] is true, in
- /// which case this will return the path of the root of this file system.
- String _local(String realPath, {relative: false, keepInJail: false}) {
+ /// If [relative] is set to `true`, then the resulting path will be relative
+ /// to [currentDirectory], otherwise the resulting path will be absolute.
+ ///
+ /// An exception is thrown if the path is outside of this file system's root
+ /// directory unless [keepInJail] is true, in which case this will instead
+ /// return the path of the root of this file system.
+ String _local(
+ String realPath, {
+ bool relative: false,
+ bool keepInJail: false,
+ }) {
assert(_context.isAbsolute(realPath));
if (!realPath.startsWith(root)) {
if (keepInJail) {
@@ -196,15 +207,15 @@
return result;
}
- /// Converts a local path in this file system to the underlying path in the
- /// delegate file system. The returned path will always be absolute.
+ /// Converts [localPath] in this file system to the real path in the delegate.
+ ///
+ /// The returned path will always be absolute.
///
/// If [resolve] is true, symbolic links will be resolved in the local file
- /// system before converting the path to the delegate file system's namespace.
- /// This ensures that symbolic link resolution will work as intended. When
- /// [resolve] is true, if the tail element of the path is a symbolic link,
- /// it will only be resolved if [followLinks] is true (whereas symbolic links
- /// found in the middle of the path will always be resolved).
+ /// system _before_ converting the path to the delegate file system's
+ /// namespace, and if the tail element of the path is a symbolic link, it will
+ /// only be resolved if [followLinks] is true (where-as symbolic links found
+ /// in the middle of the path will always be resolved).
String _real(
String localPath, {
bool resolve: true,
@@ -218,20 +229,19 @@
return '$root$localPath';
}
- /// Resolves symbolic links on [path] and returns the resulting resolved
- /// path. The return value will always be an absolute path; if [path] is
- /// relative, it will be interpreted relative to [from] (or
- /// [currentDirectory] if [from] is null).
+ /// Resolves symbolic links on [path] and returns the resulting resolved path.
+ ///
+ /// The return value will always be an absolute path; if [path] is relative
+ /// it will be interpreted relative to [from] (or [currentDirectory] if
+ /// `null`).
///
/// If the tail element is a symbolic link, then the link will be resolved
- /// only if [followLinks] is true. Symbolic links found in the middle of the
- /// path will always be resolved.
+ /// only if [followLinks] is `true`. Symbolic links found in the middle of
+ /// the path will always be resolved.
///
- /// If [throwIfNotFound] is true and the path cannot be resolved to a valid
- /// file system entity, a [FileSystemException] will be thrown. If
- /// [throwIfNotFound] is false, then resolution will halt as soon as a
- /// non-existent path segment is encountered, and the partially resolved path
- /// will be returned.
+ /// If [throwIfNotFound] is `true`, and the path cannot be resolved, a file
+ /// system exception is thrown - otherwise the resolution will halt and the
+ /// partially resolved path will be returned.
String _resolve(
String path, {
String from,
@@ -331,12 +341,10 @@
}
}
-/// Exception thrown when a real path is encountered that exists outside of
-/// this file system's root.
+/// Thrown when a path is encountered that exists outside of the root path.
class _ChrootJailException implements IOException {}
-/// Enum specifying the behavior to exhibit when ancountering `NOT_FOUND` paths
-/// in [_resolve].
+/// What to do when `NOT_FOUND` paths are encountered while resolving.
enum _NotFoundBehavior {
ALLOW,
ALLOW_AT_TAIL,
@@ -344,21 +352,28 @@
MKDIR,
}
-/// File stat representing a not found entity.
+/// A [FileStat] representing a `NOT_FOUND` entity.
class _NotFoundFileStat implements FileStat {
const _NotFoundFileStat();
+
@override
DateTime get changed => null;
+
@override
DateTime get modified => null;
+
@override
DateTime get accessed => null;
+
@override
FileSystemEntityType get type => FileSystemEntityType.NOT_FOUND;
+
@override
int get mode => 0;
+
@override
int get size => -1;
+
@override
String modeString() => '---------';
}
diff --git a/lib/src/interface/file_system.dart b/lib/src/interface/file_system.dart
index 9391b70..9f93a47 100644
--- a/lib/src/interface/file_system.dart
+++ b/lib/src/interface/file_system.dart
@@ -37,8 +37,9 @@
/// Creates a directory object pointing to the current working directory.
Directory get currentDirectory;
- /// Sets the current working directory to the specified path. The new value
- /// set can be either a [Directory] or a [String].
+ /// Sets the current working directory to the specified [path].
+ ///
+ /// The new value set can be either a [Directory] or a [String].
///
/// Relative paths will be resolved by the underlying file system
/// implementation (meaning it is up to the underlying implementation to
diff --git a/test/local_test.dart b/test/local_test.dart
index c3b0980..5e84c5e 100644
--- a/test/local_test.dart
+++ b/test/local_test.dart
@@ -1,6 +1,4 @@
@TestOn('vm')
-library file.test.local_test;
-
import 'dart:io' as io;
import 'package:file/local.dart';
