update README.md

domchen · domchen · commit 161369110e01 · 2016-10-13T11:11:53.000+08:00
diff --git a/.npmignore b/.npmignore
@@ -14,4 +14,5 @@ Jakefile.js
 .settings/
 .travis.yml
 .vscode/
-.idea/
+.idea/
+/tools
diff --git a/README.md b/README.md
@@ -31,17 +31,14 @@ npm install typescript-plus
 tsc-plus [input files] [options]
 ```
 
-
-## Documentation
-
 To learn how to use the original typescript compiler, please visit the following links:
 
 *  [Quick tutorial](http://www.typescriptlang.org/Tutorial)
 *  [Programming handbook](http://www.typescriptlang.org/Handbook)
 *  [Language specification](https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md)
 *  [Homepage](http://www.typescriptlang.org/)
 
-##Extra Options
+## Extra Options
 
 | Option                  | Type    | Default| Description                                        |
 |:----------------------- |:-------:|:------:| :------------------------------------------------- |
@@ -50,8 +47,6 @@ To learn how to use the original typescript compiler, please visit the following
 | defines                 | Object  |        | Replace the global variables with the constants defined in the "defines"" object. |
 
 
-**Note: The "defines" option is only allowed in tsconfig.json, and not through command-line switches.**
-
 Example tsconfig.json file:
 
 ```
@@ -65,7 +60,7 @@ Example tsconfig.json file:
         "emitReflection": true,
         "accessorOptimization": true,
         "defines": {
-            "DEBUG": false,  // the value can be boolean, number or string.
+            "DEBUG": false,
             "RELEASE": true
         }
 
@@ -76,4 +71,184 @@ Example tsconfig.json file:
     ]  
 }
 
-```
+```
+
+## Reflection
+
+Pass `--emitReflection` to the command-line tool or add `"emitReflection": true` to the `compilerOptions` in tsconfig.json file to enable this feature.
+
+TypeScript:
+
+```
+namespace ts {
+    export interface IPerson {
+        name:string;
+    }
+    
+    export class Student implements IPerson {
+        public name:string = "";
+    }
+}
+```
+JavaScript:
+
+```
+var ts;
+(function (ts) {
+    var Student = (function () {
+        function Student() {
+            this.name = "";
+        }
+        return Student;
+    }());
+    ts.Student = Student;
+    __reflect(Student.prototype, "ts.Student", ["ts.IPerson"]);
+})(ts || (ts = {}));
+
+```
+The `__reflect` helper function is just like the `__extends` function, it is emitted only once in one file.
+
+Then you can use the helper funtions in [reflection.ts](tools/reflection.ts) to get the qualified class name of an instance:
+
+```
+let student = new ts.Student();
+ts.getQualifiedClassName(student);  // "ts.Student"
+```
+or do some type checking:
+
+```
+ts.is(student, "ts.Student"); // true
+ts.is(student, "ts.IPersion"); // true
+```
+
+## Accessor Optimization
+
+Pass `--accessorOptimization` to the command-line tool or add `"accessorOptimization": true` to the `compilerOptions` in tsconfig.json file to enable this feature.
+
+As we know, we can't override the get / set accessors of super class in TypeScript. To solve the problem, we usually forward the call to the set accessor to another method:
+
+TypeScript:
+
+```
+class Student {
+
+    public _name:string;
+
+    protected setName(value:string):void {
+        this._name = value;
+    }
+
+    public get name():string {
+        return this._name;
+    }
+
+    public set name(value:string) {
+        this.setName(value);
+    }
+}
+```
+It does solve the problem, but also brings a performance issue, that two functions have to be called each time we call a set accessor. With the `--accessorOptimization` switch on, if the accessor contains only one call to another method, the compiler use that method to define accessor directly.
+
+Javascript:
+
+```
+var Student = (function () {
+    function Student() {
+    }
+    Student.prototype.setName = function (value) {
+        this._name = value;
+    };
+    Object.defineProperty(Student.prototype, "name", {
+        get: function () {
+            return this._name;
+        },
+        set: Student.prototype.setName,
+        enumerable: true,
+        configurable: true
+    });
+    return Student;
+}());
+```
+
+If you define the `setName()` method after the set accessor, the final result looks like this:
+
+```
+var Student = (function () {
+    function Student() {
+    }
+    Object.defineProperty(Student.prototype, "name", {
+        get: function () {
+            return this._name;
+        },
+        set: setName,
+        enumerable: true,
+        configurable: true
+    });
+    Student.prototype.setName = setName;
+    function setName(value) {
+        this._name = value;
+    };
+    return Student;
+}());
+```
+Either way, it works.
+
+## Conditional Compilation
+
+The `defines` option is only allowed in tsconfig.json, and not through command-line switches.
+
+You can use the `defines` option to declare global variables that the compiler will assume to be constants (unless defined in scope). Then all the defined global variables will be replaced with the corresponding constants. For example:
+
+tsconfig.json:
+
+```
+{
+    "compilerOptions": {
+        "defines": {
+            "DEBUG": false,
+            "LANGUAGE": "en_US"
+        }
+    }
+}
+
+```
+TypeScript:
+
+```
+declare var DEBUG:boolean;
+declare var LANGUAGE:string;
+
+if (DEBUG) {
+    console.log("DEBUG is true");
+}
+
+console.log("The language is : " + LANGUAGE);
+
+function someFunction():void {
+    let DEBUG = true;
+    if (DEBUG) {
+        console.log("DEBUG is true");
+    }
+}
+
+```
+JavaScript:
+
+```
+if (false) {
+    console.log("DEBUG is true");
+}
+
+console.log("The language is : " + "en_US");
+
+function someFunction() {
+    var DEBUG = true;
+    if (DEBUG) {
+        console.log("DEBUG is true");
+    }
+}
+```
+As you can see, the second `if(DEBUG)` in `someFunction` is not replaced because it is defined in scope.
+
+Note that the compiler does not dropping the unreachable code, because it is can be easily done by other tools like [UglifyJS](http://lisperator.net/uglifyjs/) or [Google Closure Compiler](https://developers.google.com/closure/compiler/).
+
diff --git a/src/compiler/emitter.ts b/src/compiler/emitter.ts
@@ -5275,7 +5275,7 @@ const _super = (function (geti, seti) {
             }
 
             /**
-             * If the accessor method contains only one call to another method, use that method as the accessor directly.
+             * If the accessor method contains only one call to another method, use that method to define the accessor directly.
              */
             function emitAccessorOrTargetMethod(accessor:AccessorDeclaration,
                                                 member:ClassElement,
diff --git a/tools/reflection.d.ts b/tools/reflection.d.ts
@@ -0,0 +1,63 @@
+//////////////////////////////////////////////////////////////////////////////////////
+//
+//  The MIT License (MIT)
+//
+//  Copyright (c) 2015-present, Dom Chen.
+//  All rights reserved.
+//
+//  Permission is hereby granted, free of charge, to any person obtaining a copy of
+//  this software and associated documentation files (the "Software"), to deal in the
+//  Software without restriction, including without limitation the rights to use, copy,
+//  modify, merge, publish, distribute, sublicense, and/or sell copies of the Software,
+//  and to permit persons to whom the Software is furnished to do so, subject to the
+//  following conditions:
+//
+//      The above copyright notice and this permission notice shall be included in all
+//      copies or substantial portions of the Software.
+//
+//  THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+//  INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+//  PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+//  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+//  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+//  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+//
+//////////////////////////////////////////////////////////////////////////////////////
+
+declare namespace ts {
+    /**
+     * Returns a reference to the class object of the class specified by the name parameter.
+     * @param name The name of a class.
+     */
+    function getDefinitionByName(name: string): any;
+    /**
+     * Return the fully qualified class name of an object
+     * @param value The object for which a fully qualified class name is desired. Any JavaScript value may be passed to
+     * this method including all available JavaScript types, object instances, primitive types such as number, and class objects.
+     * @returns A string containing the fully qualified class name.
+     */
+    function getQualifiedClassName(value: any): string;
+    /**
+     * Returns the fully qualified class name of the base class of the object specified by the value parameter.
+     * @param value The object for which a parent class is desired. Any JavaScript value may be passed to this method including
+     * all available JavaScript types, object instances, primitive types such as number, and class objects.
+     * @returns  A fully qualified base class name, or null if none exists.
+     */
+    function getQualifiedSuperclassName(value: any): string;
+    /**
+     * Indicates whether an object is a instance of the class or interface specified as the parameter.This method can indicate
+     * whether an object is a instance of the specific interface even though the interface does not exist at JavaScript runtime.
+     * @param instance the instance to be checked.
+     * @param typeName the string value representing a specific class or interface.
+     * @returns A value of true if the object is a instance of the class or interface specified as the parameter.
+     * @example
+     * <pre>
+     *     var instance = new ts.Sprite();
+     *     console.log(ts.is(instance,"ts.Sprite"))                  // true
+     *     console.log(ts.is(instance,"ts.DisplayObjectContainer"))  // true, because ts.DisplayObjectContainer is the superclass of ts.Sprite.
+     *     console.log(ts.is(instance,"ts.Bitmap"))                  // false, because ts.Bitmap is not the superclass of ts.Sprite.
+     * </pre>
+     */
+    function is(instance: any, typeName: string): boolean;
+}
+declare var __global: any;
diff --git a/tools/reflection.min.js b/tools/reflection.min.js
@@ -0,0 +1,37 @@
+//////////////////////////////////////////////////////////////////////////////////////
+//
+//  The MIT License (MIT)
+//
+//  Copyright (c) 2015-present, Dom Chen.
+//  All rights reserved.
+//
+//  Permission is hereby granted, free of charge, to any person obtaining a copy of
+//  this software and associated documentation files (the "Software"), to deal in the
+//  Software without restriction, including without limitation the rights to use, copy,
+//  modify, merge, publish, distribute, sublicense, and/or sell copies of the Software,
+//  and to permit persons to whom the Software is furnished to do so, subject to the
+//  following conditions:
+//
+//      The above copyright notice and this permission notice shall be included in all
+//      copies or substantial portions of the Software.
+//
+//  THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+//  INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+//  PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+//  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+//  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+//  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+//
+//////////////////////////////////////////////////////////////////////////////////////
+
+var ts,__global
+!function(t){function e(t){var e,r,o,n,u
+    if(!t)return null
+    if(e=l[t])return e
+    for(r=t.split("."),o=r.length,e=__global,n=0;o>n;n++)if(u=r[n],e=e[u],!e)return null
+    return l[t]=e,e}function r(t){var e,r,o,n,l=typeof t
+    return!t||"object"!=l&&!t.prototype?l:(e=t.prototype?t.prototype:Object.getPrototypeOf(t),e.hasOwnProperty("__class__")?e.__class__:(r=(""+e.constructor).trim(),o=r.indexOf("("),n=r.substring(9,o),Object.defineProperty(e,"__class__",{value:n,enumerable:!1,writable:!0}),n))}function o(t){var e,o,n
+    return!t||"object"!=typeof t&&!t.prototype?null:(e=t.prototype?t.prototype:Object.getPrototypeOf(t),(o=Object.getPrototypeOf(e))?(n=r(o.constructor),n?n:null):null)}function n(t,e){var r,o
+    return t&&"object"==typeof t?(r=Object.getPrototypeOf(t),o=r?r.__types__:null,o?-1!==o.indexOf(e):!1):!1}var l={}
+    t.getDefinitionByName=e,t.getQualifiedClassName=r,t.getQualifiedSuperclassName=o,t.is=n}(ts||(ts={})),__global=this.__global||this
+
diff --git a/tools/reflection.ts b/tools/reflection.ts

Original file line number	Diff line number	Diff line change
`@@ -5275,7 +5275,7 @@ const _super = (function (geti, seti) {`
`5275`	`5275`	`}`
`5276`	`5276`
`5277`	`5277`	`/**`
`5278`		`- * If the accessor method contains only one call to another method, use that method as the accessor directly.`
	`5278`	`+ * If the accessor method contains only one call to another method, use that method to define the accessor directly.`
`5279`	`5279`	`*/`
`5280`	`5280`	`function emitAccessorOrTargetMethod(accessor:AccessorDeclaration,`
`5281`	`5281`	`member:ClassElement,`