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

Unified Diff: pkg/code_transformers/lib/src/messages.dart

Issue 513023002: Step one towards stable error messages with details: (Closed) Base URL: https://dart.googlecode.com/svn/branches/bleeding_edge/dart
Patch Set: Created 6 years, 3 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 side-by-side diff with in-line comments
Download patch
Index: pkg/code_transformers/lib/src/messages.dart
diff --git a/pkg/code_transformers/lib/src/messages.dart b/pkg/code_transformers/lib/src/messages.dart
new file mode 100644
index 0000000000000000000000000000000000000000..edf0857f249b6b74b6bc8d285c8aedc9becb60b0
--- /dev/null
+++ b/pkg/code_transformers/lib/src/messages.dart
@@ -0,0 +1,171 @@
+// Copyright (c) 2014, the Dart project authors. Please see the AUTHORS file
+// 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.
+
+/// Contains all warning messages produced by the code_transformers package.
+library code_transformers.src.messages;
+
+import 'package:code_transformers/messages/messages.dart';
+
+const noAbsolutePaths = const MessageTemplate(
jakemac 2014/09/03 17:20:41 These should really be all caps names since they a
Siggi Cherem (dart-lang) 2014/09/04 02:32:13 :) I think there is not consensus on that part of
jakemac 2014/09/04 14:42:37 Weird, but ok :). To me all caps constants is the
+ const MessageId('code_transformers', 1),
+ 'absolute paths not allowed: "%-url-%"',
+ 'Absolute paths not allowed',
+ '''
+The transformers processing your code were trying to resolve a URL and identify
+a file that they correspond to. Currently only relative paths can be resolved.
+''');
+
+const invalidUrlToOtherPackage = const MessageTemplate(
+ const MessageId('code_transformers', 2),
+ 'Invalid url to reach to another package: %-url-%. Path '
Kathy Walrath 2014/09/03 18:56:36 Global change to text: url -> URL
Siggi Cherem (dart-lang) 2014/09/04 02:32:14 Done.
+ 'reaching to other packages must first reach up all the '
+ 'way to the %-prefix-% folder. For example, try changing the url above '
Kathy Walrath 2014/09/03 18:56:35 is it clear what "above" means?
Kathy Walrath 2014/09/03 18:56:36 Be consistent about using folder vs. directory. I
Siggi Cherem (dart-lang) 2014/09/04 02:32:13 Done.
Siggi Cherem (dart-lang) 2014/09/04 02:32:14 It seems we didn't need it :). removed
+ 'to: %-fixedUrl-%',
+ 'Invalid url to reach another package',
+ '''
+To reach an asset that belongs to another package, we use `package:` URLs in
Kathy Walrath 2014/09/03 18:56:35 we use -> use In general, avoid "we" in messages.
Siggi Cherem (dart-lang) 2014/09/04 02:32:14 Done.
+Dart code, but in any other language (like HTML or CSS) we use relative URLs.
Kathy Walrath 2014/09/03 18:56:36 we use -> use
Siggi Cherem (dart-lang) 2014/09/04 02:32:13 Done.
+
+These are the rules you must follow to write URLs that refer to files in other
Kathy Walrath 2014/09/03 18:56:35 -> Follow these rules when writing... This is way
Siggi Cherem (dart-lang) 2014/09/04 02:32:13 I was debating about this - one idea I was thinkin
+packages:
+
+ * if the file containing the relative URL is an entrypoint under `web`, use
Kathy Walrath 2014/09/03 18:56:36 if -> If
Siggi Cherem (dart-lang) 2014/09/04 02:32:14 Done.
+ `packages/package_name/path_to_file`
+
+ * if the file containing the URL is under `web`, but on a different directory
Kathy Walrath 2014/09/03 18:56:35 if -> If on -> in
Siggi Cherem (dart-lang) 2014/09/04 02:32:13 Done.
+ than your entrypoint, walk out to the same level as the entrypoint first,
+ then enter the `packages` folder.
+
+ **Note**: this means that if you have two entrypoints including this file,
Kathy Walrath 2014/09/03 18:56:36 this means that if you have two entrypoints includ
Siggi Cherem (dart-lang) 2014/09/04 02:32:14 Done.
+ either both entrypoints have to live in the same directory, or you need to
+ move the file to the `lib` folder.
+
+ * if the file containing the URL lives under `lib`, walk up as many levels as
Kathy Walrath 2014/09/03 18:56:36 if -> If
Siggi Cherem (dart-lang) 2014/09/04 02:32:14 Done.
+ directories you have + 1. This is because code in `lib/a/b` is loaded from
+ `packages/package_name/a/b`.
+
+The rules are easier to follow if you know how the code is layed out for
Kathy Walrath 2014/09/03 18:56:35 layed -> laid (global)
Siggi Cherem (dart-lang) 2014/09/04 02:32:14 <facepalm> thx!
Kathy Walrath 2014/09/04 17:07:28 I had to look it up to be sure. :)
+Dartium before you build, and how it is layed out after you build it with `pub
+build`. Consider the following example:
+
+ package a
+ lib/
+ '- a1.html
Kathy Walrath 2014/09/03 18:56:35 Could you use | instead of '? You used | below (fo
Siggi Cherem (dart-lang) 2014/09/04 02:32:13 Sure, I was basically using the style that pub use
+
+ web/
+ '- a2.html
+
+ package b
+ lib/
+ |- b1.html
+ '- b2/
+ '- b3.html
+
+ package c
+ lib/
+ '- c3.html
+
+ web/
+ |- index.html
+ |- index.dart
+ |- c1/
+ '- c2.html
+
+If your app is package `c`, you'll notice that in your file system there is a
Kathy Walrath 2014/09/03 18:56:36 you'll notice that in your file system there is a
Siggi Cherem (dart-lang) 2014/09/04 02:32:13 Done.
+packages folder generated in the web folder, like this:
+
+ web/
+ |- index.html
+ |- index.dart
+ |- c1/
+ | '- c2.html
+ '- packages/
+ |- a/
+ | '- a1.html
+ |- b/
+ | |- b1.html
+ | '- b2/
+ | '- b3.html
+ '- c/
+ '- c3.html
+
+Note that there is no `lib` folder under the `packages` folder. When you load
+`index.html` in Dartium, it will infer that the package root is under
Kathy Walrath 2014/09/03 18:56:35 what is "it"? Also, avoid "there is" when possible
Siggi Cherem (dart-lang) 2014/09/04 02:32:13 Good points. Thanks - here is what I ended up with
+`web/packages/`.
+
+If you need to refer to any file in other packages from `index.html`, you can
+simply do `packages/package_name/path_to_file`. For example
+`packages/b/b2/b3.html`. From `index.html` you can also refer to files under the
+web folder of the same package using a simple relative URL, like `c1/c2.html`.
+
+However, if you want to load `a1.html` from `c2.html`, you need to reach out to
+the packages folder that lives next to your entrypoint and then load the file
+from there, for example `../packages/a/a1.html`. Because pub generates symlinks
+to the packages folder also under c1, you may be tempted to write
+`packages/a/a1.html`, but that is incorrect - it would yield a canonicalization
+error (see more below).
+
+If you want to load a file from the lib folder of your own package, you
+should also use a package URL. For example, `packages/c/c3.html` and not
+`../lib/c3.html`. This will allow you to write code in `lib` in a way that it
+can be used within and outside your package without making any changes to it.
+
+Because any time you reach inside a `lib/` folder you do so using a `packages/`
+URL, the rules for reaching into other files in other packages are always
+consistent: go up to exit the `packages` folder and go back inside to the file you
+are looking for. For example, to reach `a1.html` from `b3.html` you need to
+write `../../../packages/a/a1.html`.
+
+The motivation behind all these rules is that we would like to have URLs that
+work under many scenarios at once:
+
+ * They need to work in Dartium without any code transformation: resolving the
+ path in the context of a simple HTTP server, or using `file:///` URLs,
+ should yield a valid path to assets. Since pub already creates a `packages`
+ directory next to entrypoints of your application, we assume we can use it.
+
+ * They need to be canonical. To take advantage of caching, multiple URLs
+ reaching the same asset should resolve to the same absolute URL.
+
+ Also, in projects that use HTML imports (like polymer) we make sure that if
+ you reach a library twice, once with Dart imports, and a second time with
+ HTML imports, then they are correctly resolved to be the same library. Our
+ rules are designed to allow tools to ensure this.
+
+ For example, consider you have an import might like:
+
+ <link rel=import href=packages/a/a.html>
+
+ where a.html has `<script type="application/dart" src="a.dart">`. If your
+ Dart entrypoint also loads `"package:a/a.dart"`, then we need to make sure
+ that both versions of `a.dart` are loaded from the same URL. Otherwise, you
+ may see errors at runtime like: `A is not a subtype of A`, which can be
+ extremely confusing.
+
+ When you follow the rules above, our tools can detect the pattern in the
+ HTML-import URL containing `packages/` and canonicalize the import
+ by converting `packages/a/a.dart` into `package:a/a.dart` under the hood.
+
+ * They need to continue to be valid after applications are built.
+ Technically this could be done automatically with pub transformers, but to
+ make sure that code works also in Dartium with a simple HTTP Server,
+ existing transformers do not fix URLs, they just detect inconsistencies and
+ produce an error message like this one, instead.
Kathy Walrath 2014/09/03 18:56:36 This is a lot of doc! How about I put it in a page
Siggi Cherem (dart-lang) 2014/09/04 02:32:14 That's actually how it works, I'm just storing the
Kathy Walrath 2014/09/04 17:07:27 What I meant was I didn't want to bury this doc (a
+''');
+
+const incompletePrefixPath = const MessageTemplate(
+ const MessageId('code_transformers', 3),
+ 'incomplete %-prefix-%/ path. It should have at least 3 '
+ 'segments %-prefix-%/name/path_from_name\'s_%-folder-%_dir',
+ 'Incomplete import to asset in another package',
Kathy Walrath 2014/09/03 18:56:36 to -> of?
Siggi Cherem (dart-lang) 2014/09/04 02:32:14 rephrased, I should not use the word import here a
+ '''
+Currently we require that URLs that refer to assets in other packages to
+explicitly mention the `packages/` folder. In the future we might remove this
+requiremnt, but for now we ask that you use a canonical URL form for it.
Kathy Walrath 2014/09/03 18:56:36 requiremnt -> requirement
Siggi Cherem (dart-lang) 2014/09/04 02:32:14 Done.
+
+For example, if you have `packages/a/a.html` using an HTML import to
+`packages/b/b.html`, you could technically just write `../b/b.html`, but we
Kathy Walrath 2014/09/03 18:56:35 who is "we" really? polymer.dart? The polymer tran
Siggi Cherem (dart-lang) 2014/09/04 02:32:14 Done. also removed `we` elsewhere...
+require that you write `../../packages/b/b.html`.
+See [issue 15797](http://dartbug.com/15797).
+''');

Powered by Google App Engine
This is Rietveld 408576698