Add CLI definitions; CLI restructure

.gitattributes

@@ -1,5 +1,3 @@
-bin/asc text eol=lf
+bin/* text eol=lf
-bin/asinit text eol=lf
+dist/* -diff
-dist/asc.js -diff
+scripts/*.sh eol=lf
-dist/assemblyscript.js -diff
-scripts/check-pr.sh eol=lf

README.md

@@ -41,7 +41,7 @@ Once the project is set up, it's just a matter of using your existing [TypeScrip
 $> npm run asbuild
 ```
 
-The compiler's API can also [be used programmatically](./bin).
+The CLI API can also [be used programmatically](./cli).
 
 If you rather prefer an installation suitable for development, pretty much the same can be achieved by cloning the GitHub repository instead:
 

bin/asc

@@ -1,5 +1,3 @@
 #!/usr/bin/env node
-const asc = module.exports = require("./asc.js");
+const asc = module.exports = require("../cli/asc.js");
-if (/\basc$/.test(process.argv[1])) {
+if (/\basc$/.test(process.argv[1])) process.exitCode = asc.main(process.argv.slice(2));
-  process.exitCode = asc.main(process.argv.slice(2));
-}

cli/README.md

@@ -16,7 +16,7 @@ API
 The API accepts the same options as the CLI but also lets you override stdout and stderr and/or provide a callback. Example:
 
 ```js
-const asc = require("assemblyscript/bin/asc");
+const asc = require("assemblyscript/cli/asc");
 asc.main([
   "myModule.ts",
   "--binaryFile", "myModule.wasm",
@@ -36,7 +36,7 @@ asc.main([
 Available command line options can also be obtained programmatically:
 
 ```js
-const options = require("assemblyscript/bin/asc.json");
+const options = require("assemblyscript/cli/asc.json");
 ...
 ```
 

cli/asc.d.ts

@@ -0,0 +1,118 @@
+/** Whether this is a webpack bundle or not. */
+export const isBundle: boolean;
+
+/** Whether asc runs the sources directly or not. */
+export const isDev: boolean;
+
+/** AssemblyScript version. */
+export const version: string;
+
+/** Command line option description. */
+export interface OptionDescription {
+  /** Textual description. */
+  description: string | string[];
+  /** Option type, e.g. `string`. */
+  type: string;
+  /** Option aliases, if any. */
+  aliases?: string[];
+}
+
+/** Available CLI options. */
+export const options: { [key: string]: OptionDescription };
+
+/** Common root used in source maps. */
+export var sourceMapRoot: string;
+
+/** Prefix used for library files. */
+export var libraryPrefix: string;
+
+/** Default Binaryen optimization level. */
+export var defaultOptimizeLevel: number;
+
+/** Default Binaryen shrink level. */
+export var defaultShrinkLevel: number;
+
+/** Bundled library files. */
+export const libraryFiles: { [key: string]: string };
+
+/** Bundled definition files. */
+export const definitionFiles: { assembly: string, portable: string };
+
+/** A compatible output stream. */
+export interface OutputStream {
+  /** Writes another chunk of data to the stream. */
+  write(chunk: Uint8Array | string): void;
+  /** Converts the output to a buffer. */
+  toBuffer(): Uint8Array;
+  /** Converts the output to a string. */
+  toString(): string;
+}
+
+/** Compiler API options. */
+interface CompilerOptions {
+  /** Standard output stream to use. */
+  stdout?: OutputStream;
+  /** Standard error stream to use. */
+  stderr?: OutputStream;
+  /** Reads a file from disk (or memory). */
+  readFile?: (name: string) => string | null;
+  /** Writes a file to disk (or memory). */
+  writeFile?: (name: string, contents: Uint8Array) => void;
+  /** Lists all files within a directory. */
+  listFiles?: (dir: string) => string[] | null;
+}
+
+/** Convenience function that parses and compiles source strings directly. */
+export function compileString(sources: { [key: string]: string } | string, options?: CompilerOptions): {
+  /** Standard output. */
+  stdout: OutputStream,
+  /** Standard error. */
+  stderr: OutputStream,
+  /** Emitted binary. */
+  binary: Uint8Array | null,
+  /** Emitted text format. */
+  text: string | null
+}
+
+/** Runs the command line utility using the specified arguments array. */
+export function main(argv: string[], options: CompilerOptions, callback?: (err: Error | null) => number): number;
+export function main(argv: string[], callback?: (err: Error | null) => number): number;
+
+/** Checks diagnostics emitted so far for errors. */
+export function checkDiagnostics(emitter: any, stderr?: OutputStream): boolean;
+
+/** An object of stats for the current task. */
+export interface Stats {
+  readTime: number,
+  readCount: number,
+  writeTime: number,
+  writeCount: number,
+  parseTime: number,
+  parseCount: number,
+  compileTime: number,
+  compileCount: number,
+  emitTime: number,
+  emitCount: number,
+  validateTime: number,
+  validateCount: number,
+  optimizeTime: number,
+  optimizeCount: number
+}
+
+/** Creates an empty set of stats. */
+export function createStats(): Stats;
+
+/** Measures the execution time of the specified function.  */
+export function measure(fn: Function): number;
+
+/** Formats a high resolution time to a human readable string. */
+export function formatTime(time: number): string;
+
+/** Formats and prints out the contents of a set of stats. */
+export function printStats(stats: Stats, output: OutputStream): void;
+
+/** Creates a memory stream that can be used in place of stdout/stderr. */
+export function createMemoryStream(fn?: (chunk: Uint8Array | string) => void): OutputStream;
+
+/** Compatible TypeScript compiler options for syntax highlighting etc. */
+export const tscOptions: { [key: string]: any };

cli/asc.js

@@ -8,7 +8,7 @@
  * Can also be packaged as a bundle suitable for in-browser use with the standard library injected
  * in the build step. See dist/asc.js for the bundle and webpack.config.js for building details.
  *
- * @module asc
+ * @module cli/asc
  */
 
 const fs = require("fs");
@@ -43,10 +43,10 @@ exports.isBundle = typeof BUNDLE_VERSION === "string";
 /** Whether asc runs the sources directly or not. */
 exports.isDev = isDev;
 
-/** AssemblyScript veresion. */
+/** AssemblyScript version. */
 exports.version = exports.isBundle ? BUNDLE_VERSION : require("../package.json").version;
 
-/** Available options. */
+/** Available CLI options. */
 exports.options = require("./asc.json");
 
 /** Common root used in source maps. */
@@ -159,15 +159,15 @@ exports.main = function main(argv, options, callback) {
       while (text.length < indent) {
         text += " ";
       }
-      if (Array.isArray(option.desc)) {
+      if (Array.isArray(option.description)) {
-        opts.push(text + option.desc[0] + option.desc.slice(1).map(line => {
+        opts.push(text + option.description[0] + option.description.slice(1).map(line => {
           for (let i = 0; i < indent; ++i) {
             line = " " + line;
           }
           return EOL + line;
         }).join(""));
       } else {
-        opts.push(text + option.desc);
+        opts.push(text + option.description);
       }
     });
 
@@ -762,17 +762,17 @@ function parseArguments(argv) {
   return require("minimist")(argv, opts);
 }
 
-exports.parseArguments = parseArguments;
-
 /** Checks diagnostics emitted so far for errors. */
 function checkDiagnostics(emitter, stderr) {
   var diagnostic;
   var hasErrors = false;
   while ((diagnostic = assemblyscript.nextDiagnostic(emitter)) != null) {
-    stderr.write(
+    if (stderr) {
-      assemblyscript.formatDiagnostic(diagnostic, stderr.isTTY, true) +
+      stderr.write(
-      EOL + EOL
+        assemblyscript.formatDiagnostic(diagnostic, stderr.isTTY, true) +
-    );
+        EOL + EOL
+      );
+    }
     if (assemblyscript.isError(diagnostic)) hasErrors = true;
   }
   return hasErrors;
@@ -814,6 +814,7 @@ function measure(fn) {
 
 exports.measure = measure;
 
+/** Formats a high resolution time to a human readable string. */
 function formatTime(time) {
   return time ? (time / 1e6).toFixed(3) + " ms" : "N/A";
 }
@@ -875,7 +876,7 @@ function createMemoryStream(fn) {
 
 exports.createMemoryStream = createMemoryStream;
 
-/** Compatible TypeScript compiler options. */
+/** Compatible TypeScript compiler options for syntax highlighting etc. */
 exports.tscOptions = {
   alwaysStrict: true,
   noImplicitAny: true,

cli/asc.json

@@ -1,16 +1,16 @@
 {
   "version": {
-    "desc": "Prints just the compiler's version and exits.",
+    "description": "Prints just the compiler's version and exits.",
     "type": "boolean",
     "aliases": [ "v" ]
   },
   "help": {
-    "desc": "Prints this message and exits.",
+    "description": "Prints this message and exits.",
     "type": "boolean",
     "aliases": [ "h" ]
   },
   "optimize": {
-    "desc": [
+    "description": [
       "Optimizes the module. Also accepts the optimize level:",
       "",
       " -O     Uses defaults. Equivalent to -O2s",
@@ -26,104 +26,104 @@
     "aliases": [ "O" ]
   },
   "optimizeLevel": {
-    "desc": "How much to focus on optimizing code. [0-3]",
+    "description": "How much to focus on optimizing code. [0-3]",
     "type": "number"
   },
   "shrinkLevel": {
-    "desc": "How much to focus on shrinking code size. [0-2, s=1, z=2]",
+    "description": "How much to focus on shrinking code size. [0-2, s=1, z=2]",
     "type": "number"
   },
   "validate": {
-    "desc": "Validates the module using Binaryen. Exits if invalid.",
+    "description": "Validates the module using Binaryen. Exits if invalid.",
     "type": "boolean",
     "aliases": [ "c", "check" ]
   },
   "baseDir": {
-    "desc": "Specifies the base directory of input and output files.",
+    "description": "Specifies the base directory of input and output files.",
     "type": "string"
   },
   "outFile": {
-    "desc": "Specifies the output file. File extension indicates format.",
+    "description": "Specifies the output file. File extension indicates format.",
     "type": "string",
     "aliases": [ "o" ]
   },
   "binaryFile": {
-    "desc": "Specifies the binary output file (.wasm).",
+    "description": "Specifies the binary output file (.wasm).",
     "type": "string",
     "aliases": [ "b" ]
   },
   "textFile": {
-    "desc": "Specifies the text output file (.wat).",
+    "description": "Specifies the text output file (.wat).",
     "type": "string",
     "aliases": [ "t" ]
   },
   "asmjsFile": {
-    "desc": "Specifies the asm.js output file (.js).",
+    "description": "Specifies the asm.js output file (.js).",
     "type": "string",
     "aliases": [ "a" ]
   },
   "idlFile": {
-    "desc": "Specifies the WebIDL output file (.webidl).",
+    "description": "Specifies the WebIDL output file (.webidl).",
     "type": "string",
     "aliases": [ "i" ]
   },
   "tsdFile": {
-    "desc": "Specifies the TypeScript definition output file (.d.ts).",
+    "description": "Specifies the TypeScript definition output file (.d.ts).",
     "type": "string",
     "aliases": [ "d", "dtsFile" ]
   },
   "sourceMap": {
-    "desc": [
+    "description": [
       "Enables source map generation. Optionally takes the URL",
       "used to reference the source map from the binary file."
     ],
     "type": "string"
   },
   "noTreeShaking": {
-    "desc": "Disables compiler-level tree-shaking, compiling everything.",
+    "description": "Disables compiler-level tree-shaking, compiling everything.",
     "type": "boolean"
   },
   "noDebug": {
-    "desc": "Disables maintaining of debug information in binaries.",
+    "description": "Disables maintaining of debug information in binaries.",
     "type": "boolean"
   },
   "noAssert": {
-    "desc": "Replaces assertions with just their value without trapping.",
+    "description": "Replaces assertions with just their value without trapping.",
     "type": "boolean"
   },
   "noEmit": {
-    "desc": "Performs compilation as usual but does not emit code.",
+    "description": "Performs compilation as usual but does not emit code.",
     "type": "boolean"
   },
   "noMemory": {
-    "desc": "Does not set up a memory. Useful for low-level WebAssembly.",
+    "description": "Does not set up a memory. Useful for low-level WebAssembly.",
     "type": "boolean"
   },
   "importMemory": {
-    "desc": "Imports the memory instance provided by the embedder.",
+    "description": "Imports the memory instance provided by the embedder.",
     "type": "boolean"
   },
   "memoryBase": {
-    "desc": "Sets the start offset of compiler-generated static memory.",
+    "description": "Sets the start offset of compiler-generated static memory.",
     "type": "number"
   },
   "importTable": {
-    "desc": "Imports the function table instance provided by the embedder.",
+    "description": "Imports the function table instance provided by the embedder.",
     "type": "boolean"
   },
   "noLib": {
-    "desc": "Does not include the shipped standard library.",
+    "description": "Does not include the shipped standard library.",
     "type": "boolean"
   },
   "lib": {
-    "desc": [
+    "description": [
       "Adds one or multiple paths to custom library components and",
       "uses exports of all top-level files at this path as globals."
     ],
     "type": "string"
   },
   "use": {
-    "desc": [
+    "description": [
       "Aliases a global object under another name, e.g., to switch",
       "the default 'Math' implementation used: --use Math=JSMath"
     ],
@@ -131,7 +131,7 @@
     "aliases": [ "u" ]
   },
   "trapMode": {
-    "desc": [
+    "description": [
       "Sets the trap mode to use.",
       "",
       " allow  Allow trapping operations. This is the default.",
@@ -143,14 +143,14 @@
     "default": "allow"
   },
   "runPasses": {
-    "desc":  [
+    "description":  [
       "Specifies additional Binaryen passes to run after other",
       "optimizations, if any. See: Binaryen/src/passes/pass.cpp"
     ],
     "type": "string"
   },
   "enable": {
-    "desc": [
+    "description": [
       "Enables additional (experimental) WebAssembly features.",
       "",
       " sign-extension  Enables sign-extension operations",
@@ -161,11 +161,11 @@
     "aliases": [ "feature" ]
   },
   "transform": {
-    "desc": "Specifies the path to a custom transform to 'require'.",
+    "description": "Specifies the path to a custom transform to 'require'.",
     "type": "string"
   },
   "measure": {
-    "desc": "Prints measuring information on I/O and compile times.",
+    "description": "Prints measuring information on I/O and compile times.",
     "type": "boolean"
   }
 }

cli/transform.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Definitions for custom compiler transforms that can be applied with the `--transform` option.
+ * @module cli/transform
+ *//***/
+
+import { Parser } from "../src/parser";
+
+export interface Transform {
+  /** Called when parsing is complete, before a program is instantiated from the AST. */
+  afterParse(parser: Parser): void;
+}

lib/webpack/index.js

@@ -1,6 +1,6 @@
 const fs = require("fs");
 const path = require("path");
-const asc = require("assemblyscript/bin/asc.js");
+const asc = require("assemblyscript/cli/asc.js");
 const base64 = require("@protobufjs/base64");
 
 const MAGIC = Buffer.from([ 0x00, 0x61, 0x73, 0x6D ]);

package.json

@@ -57,6 +57,7 @@
   },
   "files": [
     "bin/",
+    "cli/",
     "dist/",
     "index.d.ts",
     "index.js",

tests/compiler.js

@@ -6,7 +6,7 @@ const glob = require("glob");
 const minimist = require("minimist");
 
 const diff = require("./util/diff");
-const asc = require("../bin/asc.js");
+const asc = require("../cli/asc.js");
 
 const args = minimist(process.argv.slice(2), {
   boolean: [ "create", "help" ],

webpack.config.js

@@ -33,7 +33,7 @@ const lib = {
 
 // Build asc for browser usage
 const bin = {
-  context: path.join(__dirname, "bin"),
+  context: path.join(__dirname, "cli"),
   entry: [ "./asc.js" ],
   externals: [{
     "../dist/assemblyscript.js": "assemblyscript"