cell/scripts/base.cm

Object.mixin = function (target, source) {
  if (typeof source !== "object") return target;
  Object.defineProperties(target, Object.getOwnPropertyDescriptors(source));
  return target;
};

Object.mixin[cell.DOC] = `Copy all property descriptors from 'source' into 'target'.
  
:param target: The object that will receive properties.
:param source: The object whose properties are to be copied.
:return: The updated 'target' object.
`;

Object.defineProperty(Object.prototype, "mixin", {
  value: function mixin(obj) {
    if (typeof obj === "string") obj = use(obj);
    if (obj) Object.mixin(this, obj);
  },
});

(Object.prototype.mixin)[cell.DOC] = `Mix properties from 'obj' into the current object. If 'obj' is a string,
it first calls 'use(obj)' to retrieve the object. 

:param obj: The object (or string reference to an object) to mix in.
:return: None
`;

/* STRING DEFS */
Object.defineProperty(String.prototype, "rm", {
  value: function (index, endidx = index + 1) {
    return this.slice(0, index) + this.slice(endidx);
  },
});

(String.prototype.rm)[cell.DOC] = `Remove characters from this string between 'index' (inclusive)
and 'endidx' (exclusive). If 'endidx' is omitted, it defaults to 'index + 1'.

:param index: The starting index to remove.
:param endidx: The ending index (exclusive).
:return: A new string with the specified characters removed.
`;

Object.defineProperty(String.prototype, "tolast", {
  value: function (val) {
    var idx = this.lastIndexOf(val);
    if (idx === -1) return this.slice();
    return this.slice(0, idx);
  },
});

(String.prototype.tolast)[cell.DOC] = `Return the substring of this string up to the last occurrence of 'val'. 
If 'val' is not found, the entire string is returned.

:param val: The substring to locate from the end.
:return: A substring up to the last occurrence of 'val'.
`;

Object.defineProperty(String.prototype, "dir", {
  value: function () {
    if (!this.includes("/")) return "";
    return this.tolast("/");
  },
});

(String.prototype.dir)[cell.DOC] = `Return everything before the last slash ('/') in the string.
If no slash is found, return an empty string.

:return: The directory portion of the path.
`;

Object.defineProperty(String.prototype, "next", {
  value: function (char, from) {
    if (!Array.isArray(char)) char = [char];
    if (from > this.length - 1) return -1;
    else if (!from) from = 0;

    var find = this.slice(from).search(char[0]);
    if (find === -1) return -1;
    else return from + find;

    var i = 0;
    var c = this.charAt(from + i);
    while (!char.includes(c)) {
      i++;
      if (from + i > this.length - 1) return -1;
      c = this.charAt(from + i);
    }
    return from + i;
  },
});

(String.prototype.next)[cell.DOC] = `Search for the next occurrence of 'char' in this string, starting at 'from'.
If 'char' is an array, any of those characters qualifies. Return the matching index,
or -1 if none is found.

:param char: A character (or array of characters) to locate.
:param from: The index to start from.
:return: The index of the next occurrence, or -1 if not found.
`;

Object.defineProperty(String.prototype, "prev", {
  value: function (char, from, count = 0) {
    if (from > this.length - 1) return -1;
    else if (!from) from = this.length - 1;

    var find = this.slice(0, from).lastIndexOf(char);

    while (count > 1) {
      find = this.slice(0, find).lastIndexOf(char);
      count--;
    }

    if (find === -1) return 0;
    else return find;
  },
});

(String.prototype.prev)[cell.DOC] = `Search for the previous occurrence of 'char' before index 'from'. 
If 'count' is greater than 1, skip multiple occurrences going backward. 
Return the found index or 0 if not found.

:param char: The character to locate.
:param from: The index to start from (defaults to the end of the string).
:param count: How many occurrences to skip backward (default 0).
:return: The index of the previous occurrence, or 0 if not found.
`;

Object.defineProperty(String.prototype, "strip_ext", {
  value: function () {
    return this.tolast(".");
  },
});

(String.prototype.strip_ext)[cell.DOC] = `Return the string up to (but not including) the last '.' character.
If '.' is not found, the entire string is returned.

:return: The string without its last extension.
`;

Object.defineProperty(String.prototype, "ext", {
  value: function () {
    return this.fromlast(".");
  },
});

(String.prototype.ext)[cell.DOC] = `Return the substring after the last '.' in this string.
If '.' is not found, return an empty string.

:return: The file extension or an empty string.
`;

Object.defineProperty(String.prototype, "up_path", {
  value: function () {
    var base = this.base();
    var dirs = this.dir().split("/");
    dirs.pop();
    return dirs.join("/") + base;
  },
});

(String.prototype.up_path)[cell.DOC] = `Go up one directory level from the current path, preserving the file name at the end. 

:return: A new path string one directory up, with the base filename preserved.
`;

Object.defineProperty(String.prototype, "fromlast", {
  value: function (val) {
    var idx = this.lastIndexOf(val);
    if (idx === -1) return "";
    return this.slice(idx + 1);
  },
});

(String.prototype.fromlast)[cell.DOC] = `Return the substring that appears after the last occurrence of 'val'.
If 'val' is not found, an empty string is returned.

:param val: The substring to locate.
:return: The substring after the last occurrence of 'val'.
`;

Object.defineProperty(String.prototype, "tofirst", {
  value: function (val) {
    var idx = this.indexOf(val);
    if (idx === -1) return this.slice();
    return this.slice(0, idx);
  },
});

(String.prototype.tofirst)[cell.DOC] = `Return the substring from the start of this string up to the first occurrence
of 'val' (excluded). If 'val' is not found, the entire string is returned.

:param val: The substring to locate.
:return: A substring up to the first occurrence of 'val'.
`;

Object.defineProperty(String.prototype, "fromfirst", {
  value: function (val) {
    var idx = this.indexOf(val);
    if (idx === -1) return this;
    return this.slice(idx + val.length);
  },
});

(String.prototype.fromfirst)[cell.DOC] = `Return the substring after the first occurrence of 'val'. 
If 'val' is not found, the entire string is returned.

:param val: The substring to locate.
:return: The substring after 'val', or the entire string if 'val' not found.
`;

Object.defineProperty(String.prototype, "name", {
  value: function () {
    var idx = this.indexOf("/");
    if (idx === -1) return this.tolast(".");
    return this.fromlast("/").tolast(".");
  },
});

(String.prototype.name)[cell.DOC] = `Return the "name" portion of the path without extension.
If no slash is found, it's up to the last '.' in the entire string. 
If there is a slash, it's from the last slash up to (but not including) the last '.'.

:return: The name portion of the path without extension.
`;

Object.defineProperty(String.prototype, "set_name", {
  value: function (name) {
    var dir = this.dir();
    return this.dir() + "/" + name + "." + this.ext();
  },
});

(String.prototype.set_name)[cell.DOC] = `Set the base name (excluding extension) of the path to 'name', preserving
the original directory and extension.

:param name: The new name to use.
:return: A new path string with the updated name.
`;

Object.defineProperty(String.prototype, "base", {
  value: function () {
    return this.fromlast("/");
  },
});

(String.prototype.base)[cell.DOC] = `Return the portion of this string after the last '/' character. 
If no '/' is present, the entire string is returned.

:return: The base name of the path.
`;

Object.defineProperty(String.prototype, "updir", {
  value: function () {
    if (this.lastIndexOf("/") === this.length - 1) return this.slice(0, this.length - 1);
    var dir = (this + "/").dir();
    return dir.dir();
  },
});

(String.prototype.updir)[cell.DOC] = `Go up one directory from the current path, removing the last directory name.
If the path ends with a slash, remove it first. Then remove the final directory.

:return: A new string representing one directory level up.
`;

/* ARRAY DEFS */
Object.defineProperty(Array.prototype, "filter!", {
  value: function array_dofilter(fn) {
    for (let i = 0; i < this.length; i++) {
      if (!fn.call(this, this[i], i, this)) {
        this.splice(i, 1);
        i--;
      }
    }
    return this;
  },
});

(Array.prototype["filter!"])[cell.DOC] = `Perform an in-place filter of this array using the provided callback 'fn'. 
Any element for which 'fn' returns a falsy value is removed. The array is modified
and then returned.

:param fn: A callback function(element, index, array) => boolean.
:return: The filtered (modified) array.
`;

Object.defineProperty(Array.prototype, "delete", {
  value: function(item) {
    var idx = this.indexOf(item);
    if (idx > -1) this.splice(idx,1);
    return undefined;
  }
});

(Array.prototype.delete)[cell.DOC] = `Remove the first occurrence of 'item' from the array, if it exists.
Returns undefined.

:param item: The item to remove.
:return: undefined
`;

Object.defineProperty(Array.prototype, "copy", {
  value: function () {
    var c = [];
    this.forEach(function (x, i) {
      c[i] = deep_copy(x);
    });
    return c;
  },
});

(Array.prototype.copy)[cell.DOC] = `Return a deep copy of this array by applying 'deep_copy' to each element.
The resulting array is entirely new.

:return: A new array that is a deep copy of the original.
`;

Object.defineProperty(Array.prototype, "equal", {
  value: function equal(b) {
    if (this.length !== b.length) return false;
    if (b == null) return false;
    if (this === b) return true;
    return JSON.stringify(this) === JSON.stringify(b);

    for (var i = 0; i < this.length; i++) {
      if (!this[i] === b[i]) return false;
    }
    return true;
  },
});

(Array.prototype.equal)[cell.DOC] = `Check if this array and array 'b' have the same elements in the same order. 
If they are of different lengths, return false. Otherwise compare them via JSON.

:param b: Another array to compare against.
:return: True if they match, false otherwise.
`;

Object.defineProperty(Array.prototype, "last", {
  value: function () {
    return this[this.length - 1];
  },
});

(Array.prototype.last)[cell.DOC] = `Return the last element of this array. If the array is empty, returns undefined.

:return: The last element of the array, or undefined if empty.
`;

Object.defineProperty(Array.prototype, "wrapped", {
  value: function (x) {
    var c = this.slice(0, this.length);
    for (var i = 0; i < x; i++) c.push(this[i]);
    return c;
  },
});

(Array.prototype.wrapped)[cell.DOC] = `Return a copy of the array with the first 'x' elements appended to the end.
Does not modify the original array.

:param x: The number of leading elements to re-append.
:return: A new array with the leading elements wrapped to the end.
`;

Object.defineProperty(Array.prototype, "wrap_idx", {
  value: function (x) {
    while (x >= this.length) {
      x -= this.length;
    }
    return x;
  },
});

(Array.prototype.wrap_idx)[cell.DOC] = `Wrap the integer 'x' around this array's length, ensuring the resulting index 
lies within [0, this.length - 1].

:param x: The index to wrap.
:return: A wrapped index within this array's bounds.
`;

Object.defineProperty(Array.prototype, "mirrored", {
  value: function (x) {
    var c = this.slice(0);
    if (c.length <= 1) return c;
    for (var i = c.length - 2; i >= 0; i--) c.push(c[i]);
    return c;
  },
});

(Array.prototype.mirrored)[cell.DOC] = `Return a new array that appends a reversed copy (excluding the last element) 
of itself to the end. For example, [1,2,3] -> [1,2,3,2,1]. If the array has length 
<= 1, a copy of it is returned directly.

:return: A new "mirrored" array.
`;