dasm - npm Package Compare versions

Comparing version 4.3.0 to 4.4.0

lib/index.d.ts

@@ -0,1 +1,2 @@
+export { default as resolveIncludes } from "./resolveIncludes";
 export interface IOptions {
@@ -32,2 +33,11 @@ quick?: boolean;
 }
+export interface IIncludeInfo {
+    line: number;
+    column: number;
+    entryRelativeUri: string;
+    parentRelativeUri: string;
+    isBinary: boolean;
+    includes: IIncludeInfo[];
+    contents?: string | Uint8Array | undefined;
+}
 export default function (src: string, options?: IOptions): {
@@ -34,0 +44,0 @@ data: Uint8Array;

lib/index.js

 Object.defineProperty(exports, "__esModule", { value: true });
 var dasm = require("./dasm");
+// Re-exports
+var resolveIncludes_1 = require("./resolveIncludes");
+exports.resolveIncludes = resolveIncludes_1.default;
 // Configuration constants
@@ -4,0 +7,0 @@ var FILENAME_IN = "file.a";

package.json

 {
   "name": "dasm",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "description": "An emscripten-compiled version of the dasm macro assembler",
@@ -47,3 +47,6 @@ "main": "./lib/index.js",
     "typescript": "^2.4.1"
+  },
+  "dependencies": {
+    "path": "^0.12.7"
   }
 }

README.md

@@ -8,3 +8,3 @@ # The dasm macro assembler (for JavaScript)
 
-The dasm macro assembler transforms assembly code into 6502-compatible executable binary code. Since this is a JavaScript port of dasm, it allows that compilation process from JavaScript programs; more especifically, it can be used to create Atari VCS 2600 and Fairchild Channel F ROMs from a string containing dasm-compatible assembly source code.
+The dasm macro assembler transforms assembly code into 6502-compatible executable binary code. Since this is a JavaScript port of dasm, it allows that compilation process from JavaScript programs; more especifically, it can be used to create ROMs for Atari VCS 2600 and Fairchild Channel F (and others!) from a string containing dasm-compatible assembly source code.
 
@@ -48,2 +48,7 @@ In other words, it turns something like this:
 
+On top of that, this JavaScript port also offers:
+
+* More high-level parsing of symbols and labels' information (including declaration origin, type, etc)
+* A direct library interface for assembling (rather than a command-line interface)
+
 This port of dasm was created so I could have dasm compiling working in [vscode-dasm](https://github.com/zeh/vscode-dasm), my Visual Studio Code extension that aims to allow Atari development and debugging from within Visual Studio Code.
@@ -117,4 +122,4 @@
 * `parameters`: string. List of switches passed to dasm as if it was being called from the command line.
-* `include`: key-value object. This is a list of files that should be made available for the source code to `include`. The key contains the filename, and the value, its content.
-* `machine`: target machine. Similarly to dasm's `-I` switch, this picks a list of (embedded) files to make available to the `include` command.
+* `include`: key-value object. This is a list of files that should be made available for the source code to `include`. The key contains the complete file path, and the value contains its content.
+* `machine`: target machine as a string. Similarly to dasm's `-I` switch, this picks a list of (embedded) files to make available to the `include` command.
   * `"atari2600"`: includes dasm's own `atari2600/macro.h` and `atari2600/vcs.h` files.
@@ -142,2 +147,51 @@ * `"channel-f"`: includes dasm's own `channel-f/macro.h` and `channel-f/ves.h` files.
 
+### Convenience functions
+
+For convenience, this library also exposes one additional function that can be useful when processing assembly sources, `resolveIncludes`. This function parses all `include`, `incbin` and `incdir` pseudo-ops from the source, and resolves them to their respective file URIs and content. Use it like so:
+
+```JavaScript
+import { resolveIncludes } from "./../lib/index";
+
+const includes = resolveIncludes(source, getFile = undefined, baseFolder = "");
+```
+
+These are its parameters:
+
+* `source`: `string` containing assembly source code. The same source that is passed to the `dasm()` call.
+* `getFile`: a `function` that takes two parameters: `sourceEntryRelativeUri` (relative location of a file as `string`) and `isBinary` (whether it's a binary include, as `boolean`) and returns contents of that file (as either a `string` for text files, an `Uint8Array` for binary files, or `undefined` for files that were not found).
+
+  This function is optional and should be used as a convenience function to allow `resolveIncludes` to parse file contents and children includes (includes of includes). It ommitted, `resolveIncludes` returns a list of includes for the original source file without their contents (but with their best bet of a `uri`).
+
+  When using dasm inside node, a typical implementation of `getFile` that just gets file contents from the file system (`fs`) is as such:
+
+  ```JavaScript
+  function bufferToArray(b) {
+      const arr = new Uint8Array(b.length);
+      return arr.map((v, i) => b[i]);
+  }
+
+  function getFile(sourceEntryRelativeUri, isBinary) {
+      const fullUri = path(__dirname, sourceEntryRelativeUri);
+      if (fs.existsSync(fullUri)) {
+          if (isBinary) {
+              return bufferToArray(fs.readFileSync(fullUri));
+          } else {
+              return fs.readFileSync(fullUri, "utf8");
+          }
+      }
+  }
+  ```
+  It's important to check for a file existence because `getFile` might get called with uris that do not exist. This inevitable if the `incdir` pseud-op is used in the code.
+* `baseFolder`: uri `string` to be used when generating possible include file uris.
+
+This function returns an array of `IIncludeInfo`, each containing:
+
+* `line`: `number`. Line in the source file where this resource filename is.
+* `column`: `number`. Column in the source file where this resource filename is.
+* `entryRelativeUri`: `string`. The uri of this include, relative to the original entry source (and its `baseFolder`, if any).
+* `parentRelativeUri`: `string`. The uri actually used when including this file.
+* `isBinary`: `boolean`. Whether it's a binary file (used with `incbin`) or a text file (used with `include`).
+* `includes`: `IIncludeInfo[]`. Child dependencies of this file.
+* `contents`: `string|Uint8Array|undefined`. Contents of this file: a `string` if text, `Uint8Array` if binary, or `undefined` if not found or if `getFile` was not passed.
+
 ### More information
@@ -147,8 +201,8 @@
 
-## Todo
+## Todo and ideas
 
-* Run as a worker?
+* Allow asynchronous assembly (run as a worker?)
+* Allow asynchronous `resolveIncludes`?
 * Command-line package? (`dasm-cli`)
   * Allow direct FS use?
-  * Build file dependencies by itself?
 
@@ -155,0 +209,0 @@ Contributions are welcome.

No alert changes

Improved metrics

Total package byte prevSize

743808

increased by2.29%

Number of package files

13

increased by62.5%

Lines of code

17898

increased by1.42%

Number of lines in readme file

217

increased by33.13%

Worsened metrics

Dependency count

1

increased byInfinity%

Dependency changes

• + Addedpath@^0.12.7

• + Addedinherits@2.0.3(transitive)

• + Addedpath@0.12.7(transitive)

• + Addedprocess@0.11.10(transitive)

• + Addedutil@0.10.4(transitive)