Add CLI definitions; CLI restructure

Author: dcodeIO

.gitattributes

@@ -1,5 +1,3 @@
-bin/asc text eol=lf
-bin/asinit text eol=lf
-dist/asc.js -diff
-dist/assemblyscript.js -diff
-scripts/check-pr.sh eol=lf
+bin/* text eol=lf
+dist/* -diff
+scripts/*.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");
-if (/\basc$/.test(process.argv[1])) {
-  process.exitCode = asc.main(process.argv.slice(2));
-}
+const asc = module.exports = require("../cli/asc.js");
+if (/\basc$/.test(process.argv[1])) process.exitCode = asc.main(process.argv.slice(2));

bin/README.md renamed to 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 };

bin/asc.js renamed to 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)) {
-        opts.push(text + option.desc[0] + option.desc.slice(1).map(line => {
+      if (Array.isArray(option.description)) {
+        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(
-      assemblyscript.formatDiagnostic(diagnostic, stderr.isTTY, true) +
-      EOL + EOL
-    );
+    if (stderr) {
+      stderr.write(
+        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,