more details

Author: yjbanov

.gitignore

@@ -1,3 +1,6 @@
+# Emacs temp files
+*~
+
 # Don’t commit the following directories created by pub.
 .buildlog
 .pub/

README.md

@@ -2,12 +2,26 @@ NOTE: This is work in progress
 
 # const functions and methods for Dart
 
-## Definition
+## Goal
 
-A `const` function/method (CFM) is a function/method whose result can be used as
-a fragment of a `const` expression.
+Introduce syntax for `const` function/method (CFM). CFM is:
 
-## Declaration syntax
+* a function/method whose result can be used as a fragment of a `const`
+  expression.
+
+## Non-goals
+
+This proposal is simply syntactic sugar on top of the existing `const`
+expressions. The proposed expressions can be syntactically and lexically
+transformed to the existing syntax that is accepted by current Dart
+implementations. Anything that requires more than static transformation
+is beyond the scope of this proposal. For example, this proposal does
+not include:
+
+* control flow in `const` expressions
+* lazy evaluation
+
+## Syntax
 
 A CFM is declared like a normal function/method and:
 
@@ -21,13 +35,100 @@ imposed on the _const constructors_.
 
 Because CFMs are also normal functions they may be used in non-`const`
 expressions. In `const` expressions, however, the following restrictions are
-imposed:
+imposed (both means applied to both functions and methods):
 
 * (both) their arguments must be `const` expressions
-* (methods only) they may only be called on a `const` value
+* (both) must be preceded by `const` (see also
+  [optional const proposal](https://github.com/lrhn/dep-const/blob/master/proposal.md))
+* (methods only) they may only be called on a `const` value (and therefore may
+  only be defined on classes with `const` constructors)
+
+## Motivating examples
+
+Here's a very simplified
+"[fluent](http://en.wikipedia.org/wiki/Fluent_interface)"
+binding API for Angular 2 dependency injection:
+
+```dart
+class Binding {
+  final Type type;
+  final dynamic value;
+
+  const Binding(this.type, this.value);
+}
+
+class BindingBuilder {
+  final Type type;
+
+  /// Note that class declaring `const` method is itself `const`.
+  const BindingBuilder(this.type);
+
+  /// A const method.
+  ///
+  /// Body of a `const` method is a `const` expression.
+  const toValue(value) => const Binding(
+    this.type,  // ok to refer to `this` as `this` is itself const
+    value  // parameters are enforced to be `const` so can also be used
+  );
+}
+
+/// A const function.
+///
+/// Body of a `const` function is a `const` expression.
+const bind(Type t) => const BindingBuilder(t);
+
+void main() {
+  const binding = const bind(String).toValue('hello, world!');
+}
+
+// In Angular 2 apps, this fluent syntax may be used to declare bindings in
+// component annotations, e.g.:
+@Component(
+  injector: const [
+    const bind(String).toValue('hello, world!')
+  ]
+)
+class MyComponent {
+}
+```
 
 ## Semantics
 
 A call to a `const` function in a `const` expression is semantically equivalent
 to inlining the function into the expression.
-==================================== 80 ========================================
+
+### Example
+
+```dart
+// the example expression from above:
+const bind(String).toValue('hello, world!');
+
+// is unwrapped by inlining functions and methods:
+
+// Step 1: inline `bind`
+const BindingBuilder(String).toValue('hello, world!');
+
+// Step 2: inline `toValue`
+const Binding(String, 'hello, world!');
+```
+
+Note that the final unwrapped version of the expression is compiant with the
+existing language spec.
+
+## Optional const
+
+With optional `const` proposed
+[here](https://github.com/lrhn/dep-const/blob/master/proposal.md)
+the syntax could be improved further:
+
+```dart
+@Component(
+  injector: [
+    bind(String).toValue('hello, world!')
+  ]
+)
+class MyComponent {
+}
+```
+
+<!--- ============================ 80 chars ================================ -->