yavascript 0.0.2 → 0.0.3

package/README.md

@@ -0,0 +1,43 @@
+# yavascript
+
+<!-- NOTE: this file is also used as help text by the CLI. Don't use markdown syntax below this line unless said syntax would also be clearly readable as plain text. -->
+
+YavaScript is a bash-like script runner which is distributed as a single
+statically-linked binary. Scripts are written in JavaScript. There are global
+APIs available for all the things you'd normally want to do in a bash script,
+such as:
+
+- Running programs
+- Accessing environment variables
+- Reading and writing file contents
+- Checking if files/folders exist
+- Removing files/folders
+- Reading and changing the current working directory
+- Using globs to get large lists of files
+- Printing stylized text to the terminal
+
+Additionally, since it's JavaScript, you get some other features that are
+either not present in bash or are cumbersome to use in bash, namely:
+
+- Arrays (lists) and Objects (key/value dictionaries)
+- Working with path strings
+- Working with JSON
+- Cross-file import/export using ECMAScript Modules
+- Splitting strings on delimeters
+- Pretty-printing of objects
+- Getting the path to the currently-running script (via import.meta.url or `__filename`)
+- Getting the absolute path to the root folder of the current git/mercurial repo (repoRoot function)
+
+To view the APIs, consult the file yavascript.d.ts which was distributed with
+this program, or online at https://github.com/suchipi/yavascript/blob/main/yavascript.d.ts.
+This file contains TypeScript type definitions which can be given to your IDE
+to assist you when writing scripts.
+
+YavaScript is powered by a fork of the QuickJS JavaScript Engine, originally
+written by Fabrice Bellard. QuickJS is a small, fast JavaScript engine
+supporting the ES2020 specification.
+
+- Original QuickJS engine: https://bellard.org/quickjs/
+- The fork we use: https://github.com/suchipi/quickjs/
+
+YavaScript is written with <3 by Lily Scott.

package/lib/binary-path.js

@@ -2,9 +2,25 @@ var path = require("path");
 
 var binaryPath;
 if (process.platform === "win32") {
-  binaryPath = path.resolve(__dirname, "..", "bin", "win32", "yavascript.exe");
+  binaryPath = path.resolve(
+    __dirname,
+    "..",
+    "bin",
+    "windows",
+    "yavascript.exe"
+  );
 } else if (process.platform === "darwin") {
-  binaryPath = path.resolve(__dirname, "..", "bin", "darwin", "yavascript");
+  if (process.arch.startsWith("arm")) {
+    binaryPath = path.resolve(
+      __dirname,
+      "..",
+      "bin",
+      "darwin-arm",
+      "yavascript"
+    );
+  } else {
+    binaryPath = path.resolve(__dirname, "..", "bin", "darwin", "yavascript");
+  }
 } else if (process.platform === "linux") {
   binaryPath = path.resolve(__dirname, "..", "bin", "linux", "yavascript");
 } else {

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "yavascript",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "main": "lib/index.js",
   "bin": "lib/cli.js",
   "types": "yavascript.d.ts",
   "author": "Lily Scott <me@suchipi.com>",
-  "license": "MIT"
+  "license": "MIT",
+  "repository": "suchipi/yavascript"
 }

package/yavascript.d.ts

@@ -3,8 +3,28 @@
 // YavaScript APIs
 // ---------------
 
+/** The name of the current file (whether script or module). Alias for `os.realpath(std.getFileNameFromStack())`. */
+declare const __filename: string;
+
+/** The name of the directory the current file is inside of. */
+declare const __dirname: string;
+
+/**
+ * An object representing the process's environment variables. You can read
+ * from it to read environment variables, write into it to set environment
+ * variables, and/or delete properties from it to unset environment variables.
+ * Any value you write will be coerced into a string.
+ */
 declare const env: { [key: string]: string | undefined };
 
+type BaseExecOptions = {
+  /** Sets the current working directory for the child process. */
+  cwd?: string;
+
+  /** Sets environment variables within the process. */
+  env?: { [key: string | number]: string | number | boolean };
+};
+
 interface Exec {
   (args: Array<string>): void;
 
@@ -12,7 +32,7 @@ interface Exec {
 
   (
     args: Array<string>,
-    options: {
+    options: BaseExecOptions & {
       /**
        * Whether an Error should be thrown when the process exits with a nonzero
        * status code.
@@ -32,7 +52,7 @@ interface Exec {
 
   (
     args: Array<string>,
-    options: {
+    options: BaseExecOptions & {
       /**
        * Whether an Error should be thrown when the process exits with a nonzero
        * status code.
@@ -52,7 +72,7 @@ interface Exec {
 
   (
     args: Array<string>,
-    options: {
+    options: BaseExecOptions & {
       /**
        * Whether an Error should be thrown when the process exits with a nonzero
        * status code.
@@ -65,7 +85,7 @@ interface Exec {
 
   (
     args: Array<string>,
-    options: {
+    options: BaseExecOptions & {
       /**
        * Whether an Error should be thrown when the process exits with a nonzero
        * status code.
@@ -85,7 +105,7 @@ interface Exec {
 
   (
     args: Array<string>,
-    options: {
+    options: BaseExecOptions & {
       /**
        * If true, stdout and stderr will be collected into strings and returned
        * instead of being printed to the screen.
@@ -98,7 +118,7 @@ interface Exec {
 
   (
     args: Array<string>,
-    options: {
+    options: BaseExecOptions & {
       /**
        * Whether an Error should be thrown when the process exits with a nonzero
        * status code.
@@ -114,11 +134,10 @@ interface Exec {
 /** Run a child process using the provided arguments. The first value in the arguments array is the program to run. */
 declare const exec: Exec;
 
-/** Alias for `exec(args, { captureOutput: true, failOnNonZeroStatus: false })` */
+/** Alias for `exec(args, { captureOutput: true })` */
 declare function $(args: Array<string>): {
   stdout: string;
   stderr: string;
-  status: number;
 };
 
 /** Read the contents of a file from disk, as a string. */
@@ -142,6 +161,69 @@ declare function cd(path: string): void;
 /** Return the process's current working directory. */
 declare function pwd(): string;
 
+/** Removes the final component from a path string. */
+declare function dirname(path: string): string;
+
+/**
+ * The separator character the host operative system uses between path
+ * components, ie. the slashes in a filepath. On windows, it's a backslash, and
+ * on all other OSes, it's a forward slash.
+ */
+declare const OS_PATH_SEPARATOR: "/" | "\\";
+
+/**
+ * Create a path string from one or more path or path component strings.
+ * 
+ * Trailing slashes and duplicate path separators will be removed. Any slashes
+ * or backslashes that do not match the requested path separator character
+ * (which defaults to {@link OS_PATH_SEPARATOR}) will be converted to the
+ * requested path separator. If multiple strings are passed, they will be
+ * joined together using the requested path separator.
+ * 
+ * This function does not resolve `..` or `.`. Use {@link realpath} for that.
+ * 
+ * To request a path separator other than {@link OS_PATH_SEPARATOR}, pass an
+ * object like `{ separator: "/" }` as the final argument to `makePath`.
+ *
+ * @param parts strings containing path components that should be present in
+ * the returned path string.
+ */
+declare function makePath(
+  ...parts: Array<string | { separator: string }>
+): string;
+
+/**
+ * Returns the absolute path to the root folder of the git/hg repo.
+ * 
+ * This is done by running `git rev-parse --show-toplevel` and `hg root`.
+ * 
+ * If `relativeTo` is provided, the git and hg commands will be executed in that 
+ */
+declare function repoRoot(relativeTo?: string): string;
+
+/**
+ * Returns whether the provided path is ignored by git.
+ */
+declare function isGitignored(path: string): boolean
+
+/**
+ * Return the contents of a directory, as absolute paths. `.` and `..` are
+ * omitted.
+ *
+ * Use the `relativePaths` option to get relative paths instead (relative to
+ * the parent directory).
+ */
+declare function ls(
+  dir?: string,
+  options?: { relativePaths?: boolean }
+): Array<string>;
+
+/** Get the absolute path given a relative path. Symlinks are also resolved. */
+declare function realpath(path: string): string;
+
+/** Read a symlink. */
+declare function readlink(path: string): string;
+
 /**
  * Search the filesystem for files matching the specified glob patterns. Uses [minimatch](https://www.npmjs.com/package/minimatch) with its default options.
  *
@@ -301,6 +383,15 @@ declare module "std" {
    */
   export function loadFile(filename: string): string;
 
+  /**
+   * Read the script of module filename from an active stack frame, then return it as a string.
+   * 
+   * If there isn't a valid filename for the specified stack frame, an error will be thrown.
+   * 
+   * @param stackLevels - How many levels up the stack to search for a filename. Defaults to 0, which uses the current stack frame.
+   */
+  export function getFileNameFromStack(stackLevels: number): string;
+
   /**
    * Open a file (wrapper to the libc `fopen()`).
    * Return the FILE object.