Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(441)

Side by Side Diff: packages/path/README.md

Issue 1400473008: Roll Observatory packages and add a roll script (Closed) Base URL: git@github.com:dart-lang/observatory_pub_packages.git@master
Patch Set: Created 5 years, 2 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
« no previous file with comments | « packages/path/LICENSE ('k') | packages/path/benchmark/benchmark.dart » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
(Empty)
1 A comprehensive, cross-platform path manipulation library for Dart.
2
3 The path package provides common operations for manipulating paths:
4 joining, splitting, normalizing, etc.
5
6 We've tried very hard to make this library do the "right" thing on whatever
7 platform you run it on, including in the browser. When you use the top-level
8 functions, it will assume the current platform's path style and work with
9 that. If you want to explicitly work with paths of a specific style, you can
10 construct a `path.Context` for that style.
11
12 ## Using
13
14 The path library was designed to be imported with a prefix, though you don't
15 have to if you don't want to:
16
17 ```dart
18 import 'package:path/path.dart' as path;
19 ```
20
21 The most common way to use the library is through the top-level functions.
22 These manipulate path strings based on your current working directory and
23 the path style (POSIX, Windows, or URLs) of the host platform. For example:
24
25 ```dart
26 path.join("directory", "file.txt");
27 ```
28
29 This calls the top-level [join] function to join "directory" and
30 "file.txt" using the current platform's directory separator.
31
32 If you want to work with paths for a specific platform regardless of the
33 underlying platform that the program is running on, you can create a
34 [Context] and give it an explicit [Style]:
35
36 ```dart
37 var context = new path.Context(style: Style.windows);
38 context.join("directory", "file.txt");
39 ```
40
41 This will join "directory" and "file.txt" using the Windows path separator,
42 even when the program is run on a POSIX machine.
43
44 ## FAQ
45
46 ### Where can I use this?
47
48 Pathos runs on the Dart VM and in the browser under both dart2js and Dartium.
49 Under dart2js, it currently returns "." as the current working directory, while
50 under Dartium it returns the current URL.
51
52 ### Why doesn't this make paths first-class objects?
53
54 When you have path *objects*, then every API that takes a path has to decide if
55 it accepts strings, path objects, or both.
56
57 * Accepting strings is the most convenient, but then it seems weird to have
58 these path objects that aren't actually accepted by anything that needs a
59 path. Once you've created a path, you have to always call `.toString()` on
60 it before you can do anything useful with it.
61
62 * Requiring objects forces users to wrap path strings in these objects, which
63 is tedious. It also means coupling that API to whatever library defines this
64 path class. If there are multiple "path" libraries that each define their
65 own path types, then any library that works with paths has to pick which one
66 it uses.
67
68 * Taking both means you can't type your API. That defeats the purpose of
69 having a path type: why have a type if your APIs can't annotate that they
70 expect it?
71
72 Given that, we've decided this library should simply treat paths as strings.
73
74 ### How cross-platform is this?
75
76 We believe this library handles most of the corner cases of Windows paths
77 (POSIX paths are generally pretty straightforward):
78
79 * It understands that *both* "/" and "\" are valid path separators, not just
80 "\".
81
82 * It can accurately tell if a path is absolute based on drive-letters or UNC
83 prefix.
84
85 * It understands that "/foo" is not an absolute path on Windows.
86
87 * It knows that "C:\foo\one.txt" and "c:/foo\two.txt" are two files in the
88 same directory.
89
90 ### What is a "path" in the browser?
91
92 If you use this package in a browser, then it considers the "platform" to be
93 the browser itself and uses URL strings to represent "browser paths".
OLDNEW
« no previous file with comments | « packages/path/LICENSE ('k') | packages/path/benchmark/benchmark.dart » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698