diff --git a/docs/.pages b/docs/.pages index 92d9e67c..d0dda36d 100644 --- a/docs/.pages +++ b/docs/.pages @@ -6,7 +6,7 @@ nav: - resources.md - input.md - exporting.md - - dull.md - ... + - Appendix A - dull: dull - Appendix B - api: api \ No newline at end of file diff --git a/docs/api/actor.md b/docs/api/actor.md index faf6ca7e..fdafbd98 100644 --- a/docs/api/actor.md +++ b/docs/api/actor.md @@ -1,13 +1,11 @@ # actor -## actor +### toString() function -### toString +### spawn(script, config, callback) function -### spawn(script, config, callback) +### clear() function -### clear +### kill() function -### kill - -### delay(fn, seconds) +### delay(fn, seconds) function diff --git a/docs/api/console.md b/docs/api/console.md index b39f919e..a1a65453 100644 --- a/docs/api/console.md +++ b/docs/api/console.md @@ -2,36 +2,36 @@ The console object provides various logging, debugging, and output methods. -### print +### print() function -### spam(msg) +### spam(msg) function Output a spam-level message for very verbose logging. -### debug(msg) +### debug(msg) function Output a debug-level message. -### info(msg) +### info(msg) function Output info level message. -### warn(msg) +### warn(msg) function Output warn level message. -### log(msg) +### log(msg) function Output directly to in game console. -### error(e) +### error(e) function Output error level message, and print stacktrace. -### panic(e) +### panic(e) function Output a panic-level message and exit the program. -### assert(op, str = `assertion failed [value '${op}']`) +### assert(op, str = `assertion failed [value '${op}']`) function If the condition is false, print an error and panic. diff --git a/docs/api/modules/actor.md b/docs/api/modules/actor.md index b05ba122..5f3d9b8b 100644 --- a/docs/api/modules/actor.md +++ b/docs/api/modules/actor.md @@ -6,7 +6,7 @@ as managing tag-based lookups. Objects are assumed to have a "objects" property, pointing to children or sub-objects, forming a tree. -### all_objects(fn, startobj) +### all_objects(fn, startobj) function Iterate over each object (and its sub-objects) in the hierarchy, calling fn for each one. @@ -20,7 +20,7 @@ Iterate over each object (and its sub-objects) in the hierarchy, calling fn for **Returns**: The first truthy value returned by fn, or undefined if none. -### find_object(fn, startobj) +### find_object(fn, startobj) function Intended to find a matching object within the hierarchy. @@ -34,7 +34,7 @@ Intended to find a matching object within the hierarchy. **Returns**: Not yet implemented. -### tag_add(tag, obj) +### tag_add(tag, obj) function Associate the given object with the specified tag. Creates a new tag set if it does not exist. @@ -48,7 +48,7 @@ Associate the given object with the specified tag. Creates a new tag set if it d **Returns**: None -### tag_rm(tag, obj) +### tag_rm(tag, obj) function Remove the given object from the specified tag’s set, if it exists. @@ -62,7 +62,7 @@ Remove the given object from the specified tag’s set, if it exists. **Returns**: None -### tag_clear_guid(obj) +### tag_clear_guid(obj) function Remove the object from all tag sets. @@ -74,7 +74,7 @@ Remove the object from all tag sets. **Returns**: None -### objects_with_tag(tag) +### objects_with_tag(tag) function Retrieve all objects currently tagged with the specified tag. diff --git a/docs/api/modules/cmd.md b/docs/api/modules/cmd.md index 749dd8c0..46f5e07f 100644 --- a/docs/api/modules/cmd.md +++ b/docs/api/modules/cmd.md @@ -1,3 +1,7 @@ # cmd -## cmd +### length number + +### name string + +### prototype object diff --git a/docs/api/modules/color.md b/docs/api/modules/color.md index b0a84fac..d12a896f 100644 --- a/docs/api/modules/color.md +++ b/docs/api/modules/color.md @@ -1,3 +1,7 @@ # color -## color +### Color object + +### esc object + +### ColorMap object diff --git a/docs/api/modules/doc.md b/docs/api/modules/doc.md index bc7a3359..413e4549 100644 --- a/docs/api/modules/doc.md +++ b/docs/api/modules/doc.md @@ -1,7 +1,5 @@ # doc -## doc +### writeDocFile(obj, title) function -### writeDocFile(obj, title) - -Return a markdown string for a given obj, with optional title. +Return a markdown string for a given obj, with an optional title. diff --git a/docs/api/modules/draw2d.md b/docs/api/modules/draw2d.md index aa4fd624..d1e27197 100644 --- a/docs/api/modules/draw2d.md +++ b/docs/api/modules/draw2d.md @@ -5,7 +5,7 @@ A collection of 2D drawing functions that operate in screen space. Provides prim for lines, rectangles, text, sprite drawing, etc. -### point(pos, size, color) +### point(pos, size, color) function @@ -20,7 +20,7 @@ for lines, rectangles, text, sprite drawing, etc. **Returns**: None -### line(points, color, thickness, pipeline) +### line(points, color, thickness, pipeline) function @@ -37,7 +37,7 @@ for lines, rectangles, text, sprite drawing, etc. **Returns**: None -### cross(pos, size, color, thickness, pipe) +### cross(pos, size, color, thickness, pipe) function @@ -56,7 +56,7 @@ for lines, rectangles, text, sprite drawing, etc. **Returns**: None -### arrow(start, end, color, wingspan, wingangle, pipe) +### arrow(start, end, color, wingspan, wingangle, pipe) function @@ -77,7 +77,7 @@ for lines, rectangles, text, sprite drawing, etc. **Returns**: None -### rectangle(rect, color, pipeline) +### rectangle(rect, color, pipeline) function @@ -92,7 +92,7 @@ for lines, rectangles, text, sprite drawing, etc. **Returns**: None -### tile(image, rect, color, tile, pipeline) +### tile(image, rect, color, tile, pipeline) function :raises Error: If no image is provided. @@ -112,7 +112,7 @@ for lines, rectangles, text, sprite drawing, etc. **Returns**: None -### slice9(image, rect, slice, color, info, pipeline) +### slice9(image, rect, slice, color, info, pipeline) function :raises Error: If no image is provided. @@ -134,7 +134,7 @@ for lines, rectangles, text, sprite drawing, etc. **Returns**: None -### image(image, rect, rotation, color, pipeline) +### image(image, rect, rotation, color, pipeline) function :raises Error: If no image is provided. @@ -154,7 +154,7 @@ for lines, rectangles, text, sprite drawing, etc. **Returns**: A sprite object that was created for this draw call. -### images(image, rects, config) +### images(image, rects, config) function :raises Error: If no image is provided. @@ -170,7 +170,7 @@ for lines, rectangles, text, sprite drawing, etc. **Returns**: An array of sprite objects created and queued for rendering. -### sprites(sprites, sort, pipeline) +### sprites(sprites, sort, pipeline) function @@ -185,7 +185,7 @@ for lines, rectangles, text, sprite drawing, etc. **Returns**: None -### circle(pos, radius, color, inner_radius, pipeline) +### circle(pos, radius, color, inner_radius, pipeline) function @@ -204,7 +204,7 @@ for lines, rectangles, text, sprite drawing, etc. **Returns**: None -### text(text, rect, font, size, color, wrap, pipeline) +### text(text, rect, font, size, color, wrap, pipeline) function diff --git a/docs/api/modules/event.md b/docs/api/modules/event.md index 4b8275c8..2b4a6e13 100644 --- a/docs/api/modules/event.md +++ b/docs/api/modules/event.md @@ -1,8 +1,6 @@ # event -## event - -### push_event(event) +### push_event(event) function Push a custom user event into SDL's queue, passing a callback function. @@ -14,7 +12,7 @@ Push a custom user event into SDL's queue, passing a callback function. **Returns**: None -### engine_input(callback) +### engine_input(callback) function Poll all system events (keyboard, mouse, etc.) and call the given function with each event object. diff --git a/docs/api/modules/geometry.md b/docs/api/modules/geometry.md index 754904a1..26f2fb2b 100644 --- a/docs/api/modules/geometry.md +++ b/docs/api/modules/geometry.md @@ -5,7 +5,7 @@ A collection of geometry-related functions for circles, spheres, boxes, polygons and rectangle utilities. Some functionality is implemented in C and exposed here. -### rect_intersection(a, b) +### rect_intersection(a, b) function Return the intersection of two rectangles. The result may be empty if no intersection. @@ -19,7 +19,7 @@ Return the intersection of two rectangles. The result may be empty if no interse **Returns**: A rectangle that is the intersection of the two. May have zero width/height if no overlap. -### rect_intersects(a, b) +### rect_intersects(a, b) function @@ -32,7 +32,7 @@ Return the intersection of two rectangles. The result may be empty if no interse **Returns**: A boolean indicating whether the two rectangles overlap. -### rect_expand(a, b) +### rect_expand(a, b) function Merge or combine two rectangles, returning their bounding rectangle. @@ -46,7 +46,7 @@ Merge or combine two rectangles, returning their bounding rectangle. **Returns**: A new rectangle that covers the bounds of both input rectangles. -### rect_inside(inner, outer) +### rect_inside(inner, outer) function @@ -59,7 +59,7 @@ Merge or combine two rectangles, returning their bounding rectangle. **Returns**: True if 'inner' is completely inside 'outer', otherwise false. -### rect_random(rect) +### rect_random(rect) function @@ -70,7 +70,7 @@ Merge or combine two rectangles, returning their bounding rectangle. **Returns**: A random point within the rectangle (uniform distribution). -### cwh2rect(center, wh) +### cwh2rect(center, wh) function Helper: convert a center point and width/height vector to a rect object. @@ -84,7 +84,7 @@ Helper: convert a center point and width/height vector to a rect object. **Returns**: A rectangle {x, y, w, h} with x,y set to center and w,h set to the given size. -### rect_point_inside(rect, point) +### rect_point_inside(rect, point) function @@ -97,7 +97,7 @@ Helper: convert a center point and width/height vector to a rect object. **Returns**: True if the point lies inside the rectangle, otherwise false. -### rect_pos(rect) +### rect_pos(rect) function @@ -108,7 +108,7 @@ Helper: convert a center point and width/height vector to a rect object. **Returns**: A 2D vector [x,y] giving the rectangle's position. -### rect_move(rect, offset) +### rect_move(rect, offset) function @@ -121,7 +121,7 @@ Helper: convert a center point and width/height vector to a rect object. **Returns**: A new rectangle with updated x,y offset. -### box(w, h) +### box(w, h) function Construct a box centered at the origin with the given width and height. This overrides the box object above. @@ -135,38 +135,15 @@ Construct a box centered at the origin with the given width and height. This ove **Returns**: An array of four 2D points representing the corners of a rectangle centered at [0,0]. +### sphere object + Sphere-related geometry functions: - volume(r): Return the volume of a sphere with radius r. - random(r, theta, phi): Return a random point on or inside a sphere. -#### volume(r) - - - - -**r**: The sphere radius. - - -**Returns**: The volume of the sphere, calculated as (4/3) * pi * r^3. - - -#### random(r, theta, phi) - - -Generate a random point inside a sphere of variable radius, distributing angles in the specified ranges. - - -**r**: A single number (radius) or a 2-element array [minRadius, maxRadius]. - -**theta**: A single number or 2-element array defining the range in turns for the theta angle, default [0,1]. - -**phi**: A single number or 2-element array defining the range in turns for the phi angle, default [-0.5,0.5]. - - -**Returns**: A 3D point (x,y,z) randomly placed within a sphere. - +### circle object Circle-related geometry functions: @@ -174,45 +151,7 @@ Circle-related geometry functions: - random(r, theta): Return a random 2D point on a circle; uses sphere.random internally and extracts x,z. -#### area(r) - - - - -**r**: Radius of the circle. - - -**Returns**: The area, pi * r^2. - - -#### random(r, theta) - - - - -**r**: A radius or [minRadius, maxRadius]. - -**theta**: Angle range in turns (single number or [min,max]). - - -**Returns**: A 2D point (x,z) in the circle, using the sphere random generator and ignoring y. - - -#### points(radius, n) - - -Shortcut for geometry.arc(radius, 360, n). - - -**radius**: The circle's radius. - -**n**: Number of points around the circle. - - -**Returns**: An array of 2D points equally spaced around a full 360-degree circle. - - -### ngon(radius, n) +### ngon(radius, n) function Generates a regular n-gon by calling geometry.arc with full 360 degrees. @@ -226,7 +165,7 @@ Generates a regular n-gon by calling geometry.arc with full 360 degrees. **Returns**: An array of 2D points forming a regular n-gon. -### arc(radius, angle, n, start) +### arc(radius, angle, n, start) function Generate an arc (or partial circle) of n points, each angle spread equally over 'angle' degrees from 'start'. @@ -244,7 +183,7 @@ Generate an arc (or partial circle) of n points, each angle spread equally over **Returns**: An array of 2D points along the arc. -### corners2points(ll, ur) +### corners2points(ll, ur) function Similar to box.points, but calculates differently. @@ -258,7 +197,7 @@ Similar to box.points, but calculates differently. **Returns**: A four-point array of corners [ll, lower-right, upper-right, upper-left]. -### sortpointsccw(points) +### sortpointsccw(points) function Sort an array of points in CCW order based on their angles from the centroid. @@ -270,7 +209,7 @@ Sort an array of points in CCW order based on their angles from the centroid. **Returns**: A new array of the same points, sorted counterclockwise around their centroid. -### points2cm(points) +### points2cm(points) function diff --git a/docs/api/modules/graphics.md b/docs/api/modules/graphics.md index 0b99ca6a..165270c5 100644 --- a/docs/api/modules/graphics.md +++ b/docs/api/modules/graphics.md @@ -6,7 +6,7 @@ Includes both JavaScript and C-implemented routines for creating geometry buffer rectangle packing, etc. -### make_sprite_mesh(sprites) +### make_sprite_mesh(sprites) function :param oldMesh (optional): An existing mesh object to reuse/resize if possible. @@ -19,7 +19,7 @@ Given an array of sprites, build a single geometry mesh for rendering them. **Returns**: A GPU mesh object with pos, uv, color, and indices buffers for all sprites. -### make_sprite_queue(sprites, camera, pipeline, sort) +### make_sprite_queue(sprites, camera, pipeline, sort) function Given an array of sprites, optionally sort them, then build a queue of pipeline commands. @@ -38,7 +38,7 @@ Each group with a shared image becomes one command. **Returns**: An array of pipeline commands: geometry with mesh references, grouped by image. -### make_text_buffer(text, rect, angle, color, wrap, font) +### make_text_buffer(text, rect, angle, color, wrap, font) function Generate a GPU buffer mesh of text quads for rendering with a font, etc. @@ -60,7 +60,7 @@ Generate a GPU buffer mesh of text quads for rendering with a font, etc. **Returns**: A geometry buffer mesh (pos, uv, color, indices) for rendering text. -### rectpack(width, height, sizes) +### rectpack(width, height, sizes) function Perform a rectangle packing using the stbrp library. Return positions for each rect. @@ -76,7 +76,7 @@ Perform a rectangle packing using the stbrp library. Return positions for each r **Returns**: An array of [x,y] coordinates placing each rect, or null if they don't fit. -### make_rtree +### make_rtree() function Create a new R-Tree for geometry queries. @@ -85,7 +85,7 @@ Create a new R-Tree for geometry queries. **Returns**: An R-Tree object for quickly querying many rectangles or sprite bounds. -### make_texture(data) +### make_texture(data) function Convert raw image bytes into an SDL_Surface object. @@ -97,7 +97,7 @@ Convert raw image bytes into an SDL_Surface object. **Returns**: An SDL_Surface object representing the decoded image in RAM, for use with GPU or software rendering. -### make_gif(data) +### make_gif(data) function Load a GIF, returning its frames. If it's a single-frame GIF, the result may have .surface only. @@ -109,7 +109,7 @@ Load a GIF, returning its frames. If it's a single-frame GIF, the result may hav **Returns**: An object with frames[], each frame having its own .surface. Some also have a .texture for GPU use. -### make_aseprite(data) +### make_aseprite(data) function Load an Aseprite/ASE file from an array of bytes, returning frames or animations. @@ -121,7 +121,7 @@ Load an Aseprite/ASE file from an array of bytes, returning frames or animations **Returns**: An object containing frames or animations, each with .surface. May also have top-level .surface for a single-layer case. -### cull_sprites(sprites, camera) +### cull_sprites(sprites, camera) function Filter an array of sprites to only those visible in the provided camera’s view. @@ -135,7 +135,7 @@ Filter an array of sprites to only those visible in the provided camera’s view **Returns**: A new array of sprites that are visible in the camera's view. -### rects_to_sprites(rects, image) +### rects_to_sprites(rects, image) function Convert an array of rect coords into sprite objects referencing a single image. @@ -149,7 +149,7 @@ Convert an array of rect coords into sprite objects referencing a single image. **Returns**: An array of sprite objects referencing the 'image' and each rect for UV or position. -### make_surface(dimensions) +### make_surface(dimensions) function Create a blank surface in RAM. @@ -161,7 +161,7 @@ Create a blank surface in RAM. **Returns**: A blank RGBA surface with the given dimensions, typically for software rendering or icons. -### make_cursor(opts) +### make_cursor(opts) function @@ -172,7 +172,7 @@ Create a blank surface in RAM. **Returns**: An SDL_Cursor object referencing the given surface for a custom mouse cursor. -### make_font(data, size) +### make_font(data, size) function Load a font from TTF/OTF data at the given size. @@ -186,7 +186,7 @@ Load a font from TTF/OTF data at the given size. **Returns**: A font object with surface, texture, and glyph data, for text rendering with make_text_buffer. -### make_sprite +### make_sprite() function Create a new sprite object, storing default properties. @@ -195,7 +195,7 @@ Create a new sprite object, storing default properties. **Returns**: A new sprite object, which typically has .rect, .color, .layer, .image, etc. -### make_line_prim(points, thickness, startCap, endCap, color) +### make_line_prim(points, thickness, startCap, endCap, color) function Build a GPU mesh representing a thick polyline from an array of points, using parsl or a similar library under the hood. @@ -215,7 +215,7 @@ Build a GPU mesh representing a thick polyline from an array of points, using pa **Returns**: A geometry mesh object suitable for rendering the line via a pipeline command. -### is_image(obj) +### is_image(obj) function @@ -226,7 +226,7 @@ Build a GPU mesh representing a thick polyline from an array of points, using pa **Returns**: True if 'obj' has a .texture and a .rect property, indicating it's an image object. -### texture(path) +### texture(path) function Load or retrieve a cached image, converting it into a GPU texture. If 'path' is already an object, it’s returned directly. @@ -238,7 +238,7 @@ Load or retrieve a cached image, converting it into a GPU texture. If 'path' is **Returns**: An image object with {surface, texture, frames?, etc.} depending on the format. -### tex_hotreload(file) +### tex_hotreload(file) function Reload the image for the given file, updating the cached copy in memory and GPU. @@ -250,7 +250,7 @@ Reload the image for the given file, updating the cached copy in memory and GPU. **Returns**: None -### get_font(path, size) +### get_font(path, size) function Load a font from file if not cached, or retrieve from cache if already loaded. @@ -264,7 +264,7 @@ Load a font from file if not cached, or retrieve from cache if already loaded. **Returns**: A font object with .surface and .texture for rendering text. -### queue_sprite_mesh(queue) +### queue_sprite_mesh(queue) function Builds a single geometry mesh for all sprite-type commands in the queue, storing first_index/num_indices diff --git a/docs/api/modules/imgui.md b/docs/api/modules/imgui.md index 7dab89df..b00474ac 100644 --- a/docs/api/modules/imgui.md +++ b/docs/api/modules/imgui.md @@ -1,3 +1 @@ # imgui - -## imgui diff --git a/docs/api/modules/input.md b/docs/api/modules/input.md index b6947eac..5bc62d31 100644 --- a/docs/api/modules/input.md +++ b/docs/api/modules/input.md @@ -1,8 +1,6 @@ # input -## input - -### mouse_show(show) +### mouse_show(show) function Show or hide the mouse cursor. Pass true to show, false to hide. @@ -14,7 +12,7 @@ Show or hide the mouse cursor. Pass true to show, false to hide. **Returns**: None -### mouse_lock(lock) +### mouse_lock(lock) function Capture or release the mouse, confining it within the window if locked. @@ -26,7 +24,7 @@ Capture or release the mouse, confining it within the window if locked. **Returns**: None -### cursor_set(cursor) +### cursor_set(cursor) function Set the given cursor (created by os.make_cursor) as the active mouse cursor. @@ -38,7 +36,7 @@ Set the given cursor (created by os.make_cursor) as the active mouse cursor. **Returns**: None -### keyname(keycode) +### keyname(keycode) function Given a numeric keycode, return the corresponding key name (e.g., from SDL). @@ -50,7 +48,7 @@ Given a numeric keycode, return the corresponding key name (e.g., from SDL). **Returns**: A string with the key name. -### keymod +### keymod() function Return an object describing the current modifier keys, e.g. {shift:true, ctrl:true}. @@ -59,7 +57,7 @@ Return an object describing the current modifier keys, e.g. {shift:true, ctrl:tr **Returns**: An object with boolean fields for each modifier key. -### mousestate +### mousestate() function Return an object describing the current mouse state, including x,y coordinates and booleans for pressed buttons (left, middle, right, x1, x2). @@ -69,14 +67,22 @@ and booleans for pressed buttons (left, middle, right, x1, x2). **Returns**: Object { x, y, left, middle, right, x1, x2 } -### print_pawn_kbm(pawn) +### mouse object -### procdown +### keyboard object -### print_md_kbm(pawn) +### print_pawn_kbm(pawn) function -### has_bind(pawn, bind) +### procdown() function -### tabcomplete(val, list) +### print_md_kbm(pawn) function -### do_uncontrol(pawn) +### has_bind(pawn, bind) function + +### action object + +### tabcomplete(val, list) function + +### do_uncontrol(pawn) function + +### player object diff --git a/docs/api/modules/io.md b/docs/api/modules/io.md index b2761e32..0b237e16 100644 --- a/docs/api/modules/io.md +++ b/docs/api/modules/io.md @@ -1,8 +1,6 @@ # io -## io - -### rm(path) +### rm(path) function Remove the file or empty directory at the given path. @@ -14,7 +12,7 @@ Remove the file or empty directory at the given path. **Returns**: None -### mkdir(path) +### mkdir(path) function Create a directory at the given path. @@ -26,7 +24,7 @@ Create a directory at the given path. **Returns**: None -### stat(path) +### stat(path) function Return an object describing file metadata for the given path. The object includes filesize, modtime, createtime, and accesstime. Throw an error if the path does not exist. @@ -39,7 +37,7 @@ filesize, modtime, createtime, and accesstime. Throw an error if the path does n **Returns**: An object with metadata (filesize, modtime, createtime, accesstime). -### globfs(patterns) +### globfs(patterns) function Return an array of files that do not match any of the provided glob patterns. It recursively enumerates the filesystem within PHYSFS. Each pattern is treated as an @@ -53,7 +51,7 @@ recursively enumerates the filesystem within PHYSFS. Each pattern is treated as **Returns**: An array of matching file paths. -### match(pattern, string) +### match(pattern, string) function Return boolean indicating whether the given wildcard pattern matches the provided string. Dots must match dots. Case is not ignored. @@ -77,7 +75,7 @@ Patterns can incorporate: **Returns**: True if matched, otherwise false. -### exists(path) +### exists(path) function Return a boolean indicating whether the file or directory at the given path exists. @@ -89,7 +87,7 @@ Return a boolean indicating whether the file or directory at the given path exis **Returns**: True if the path exists, otherwise false. -### mount(archiveOrDir, mountPoint) +### mount(archiveOrDir, mountPoint) function Mount a directory or archive at the specified mount point. An undefined mount point mounts to '/'. Throw on error. @@ -104,7 +102,7 @@ point mounts to '/'. Throw on error. **Returns**: None -### unmount(path) +### unmount(path) function Unmount a previously mounted directory or archive. Throw on error. @@ -116,7 +114,7 @@ Unmount a previously mounted directory or archive. Throw on error. **Returns**: None -### slurp(path) +### slurp(path) function Read the entire file at the given path as a string. Throw on error. @@ -128,7 +126,7 @@ Read the entire file at the given path as a string. Throw on error. **Returns**: A string with the file’s contents. -### slurpbytes(path) +### slurpbytes(path) function Read the entire file at the given path as a raw ArrayBuffer. Throw on error. @@ -140,7 +138,7 @@ Read the entire file at the given path as a raw ArrayBuffer. Throw on error. **Returns**: An ArrayBuffer containing the file’s raw bytes. -### slurpwrite(data, path) +### slurpwrite(data, path) function Write data (string or ArrayBuffer) to the given file path. Overwrite if it exists. Throw on error. @@ -155,7 +153,7 @@ Throw on error. **Returns**: None -### writepath(path) +### writepath(path) function Set the write directory. Subsequent writes will go here by default. Throw on error. @@ -167,7 +165,7 @@ Set the write directory. Subsequent writes will go here by default. Throw on err **Returns**: None -### basedir +### basedir() function Return the application's base directory (where the executable is located). @@ -176,7 +174,7 @@ Return the application's base directory (where the executable is located). **Returns**: A string with the base directory path. -### userdir +### userdir() function Return the user's directory, often used for saving data. @@ -185,7 +183,7 @@ Return the user's directory, often used for saving data. **Returns**: A string with the user's directory path. -### realdir(path) +### realdir(path) function Return the actual, real directory (on the host filesystem) that contains the given file path. Return undefined if not found. @@ -198,7 +196,7 @@ file path. Return undefined if not found. **Returns**: A string with the real directory path, or undefined. -### open(path) +### open(path) function Open a file for writing, returning a file object that can be used for further operations. Throw on error. @@ -211,7 +209,7 @@ operations. Throw on error. **Returns**: A file object for subsequent write operations. -### searchpath +### searchpath() function Return an array of all directories in the current paths. @@ -220,7 +218,7 @@ Return an array of all directories in the current paths. **Returns**: An array of directory paths in the search path. -### enumerate(path, recurse) +### enumerate(path, recurse) function Return an array of files within the given directory, optionally recursing into subdirectories. @@ -235,6 +233,6 @@ subdirectories. **Returns**: An array of file (and directory) paths found. -### mount_core +### mount_core() function -### is_directory +### is_directory() function diff --git a/docs/api/modules/js.md b/docs/api/modules/js.md index 66039d6f..af7b08f2 100644 --- a/docs/api/modules/js.md +++ b/docs/api/modules/js.md @@ -5,7 +5,7 @@ Provides functions for introspecting and configuring the QuickJS runtime engine. Includes debug info, memory usage, GC controls, code evaluation, etc. -### cycle_hook(callback) +### cycle_hook(callback) function or undefined to remove the callback. @@ -21,7 +21,7 @@ is undefined, the hook is removed. **Returns**: None -### dump_shapes +### dump_shapes() function Use this for internal debugging of object shapes. @@ -30,7 +30,7 @@ Use this for internal debugging of object shapes. **Returns**: A debug string describing the internal shape hierarchy used by QuickJS. -### dump_atoms +### dump_atoms() function known by QuickJS. Helpful for diagnosing memory usage or potential key collisions. @@ -39,7 +39,7 @@ known by QuickJS. Helpful for diagnosing memory usage or potential key collision **Returns**: A debug string listing all currently registered atoms (internal property keys/symbols) -### dump_class +### dump_class() function Shows how many objects of each class exist, useful for advanced memory or performance profiling. @@ -48,7 +48,7 @@ Shows how many objects of each class exist, useful for advanced memory or perfor **Returns**: A debug string describing the distribution of JS object classes in the QuickJS runtime. -### dump_objects +### dump_objects() function useful for debugging memory leaks or object lifetimes. @@ -57,7 +57,7 @@ useful for debugging memory leaks or object lifetimes. **Returns**: A debug string listing certain internal QuickJS objects and their references, -### dump_type_overheads +### dump_type_overheads() function Displays memory usage breakdown for different internal object types. @@ -66,7 +66,7 @@ Displays memory usage breakdown for different internal object types. **Returns**: A debug string describing the overheads for various JS object types in QuickJS. -### stack_info +### stack_info() function Internal debugging utility to examine call stack details. @@ -75,7 +75,7 @@ Internal debugging utility to examine call stack details. **Returns**: An object or string describing the runtime's current stack usage and capacity. -### calc_mem(value) +### calc_mem(value) function @@ -88,7 +88,7 @@ Compute the approximate size of a single JS value in memory. This is a best-effo **Returns**: Approximate memory usage (in bytes) of that single value. -### mem +### mem() function including total allocated bytes, object counts, and more. @@ -99,7 +99,7 @@ Retrieve an overview of the runtime’s memory usage. **Returns**: An object containing a comprehensive snapshot of memory usage for the current QuickJS runtime, -### mem_limit(bytes) +### mem_limit(bytes) function @@ -113,7 +113,7 @@ fail or throw errors. **Returns**: None -### gc_threshold(bytes) +### gc_threshold(bytes) function @@ -126,7 +126,7 @@ Set the threshold (in bytes) for QuickJS to perform an automatic GC pass when me **Returns**: None -### max_stacksize(bytes) +### max_stacksize(bytes) function @@ -139,7 +139,7 @@ Set the maximum stack size for QuickJS. If exceeded, the runtime may throw a sta **Returns**: None -### memstate +### memstate() function @@ -149,7 +149,7 @@ Gives a quick overview of the memory usage, including malloc size and other allo **Returns**: A simpler memory usage object (malloc sizes, etc.) for the QuickJS runtime. -### gc +### gc() function @@ -159,7 +159,7 @@ Force an immediate, full garbage collection pass, reclaiming unreachable memory. **Returns**: None -### eval(src, filename) +### eval(src, filename) function diff --git a/docs/api/modules/json.md b/docs/api/modules/json.md index a825b701..572292b6 100644 --- a/docs/api/modules/json.md +++ b/docs/api/modules/json.md @@ -1,8 +1,6 @@ # json -## json - -### encode(val,space,replacer,whitelist) +### encode(val,space,replacer,whitelist) function Produce a JSON text from a Javascript object. If a record value, at any level, contains a json() method, it will be called, and the value it returns (usually a simpler record) will be JSONified. @@ -10,7 +8,7 @@ If the record does not have a json() method, and if whitelist is a record, then If the space input is true, then line breaks and extra whitespace will be included in the text. -### decode(text,reviver) +### decode(text,reviver) function The text text is parsed, and the resulting value (usually a record or an array) is returned. diff --git a/docs/api/modules/loop.md b/docs/api/modules/loop.md index 26c51f4f..cf3e6540 100644 --- a/docs/api/modules/loop.md +++ b/docs/api/modules/loop.md @@ -1,5 +1,3 @@ # loop -## loop - -### step +### step() function diff --git a/docs/api/modules/math.md b/docs/api/modules/math.md index e248d112..0574abc0 100644 --- a/docs/api/modules/math.md +++ b/docs/api/modules/math.md @@ -1,115 +1,115 @@ # math -## math - -### dot +### dot() function Compute the dot product between two numeric arrays, returning a scalar. Extra elements are ignored. -### project +### project() function Project one vector onto another, returning a new array of the same dimension. -### rotate +### rotate() function Rotate a 2D point (or array of length 2) by the given angle (in turns) around an optional pivot. -### midpoint +### midpoint() function Compute the midpoint of two arrays of numbers. Only the first two entries are used if 2D is intended. -### reflect +### reflect() function Reflect a vector across a plane normal. Both arguments must be numeric arrays. -### distance +### distance() function Compute the Euclidean distance between two numeric arrays of matching length. -### direction +### direction() function Compute the normalized direction vector from the first array to the second. -### angle +### angle() function Given a 2D vector, return its angle from the X-axis in radians or some chosen units. -### norm +### norm() function Return a normalized copy of the given numeric array. For 2D/3D/4D or arbitrary length. -### angle_between +### angle_between() function Compute the angle between two vectors (2D/3D/4D). -### lerp +### lerp() function Linear interpolation between two numbers: lerp(a, b, t). -### gcd +### gcd() function Compute the greatest common divisor of two integers. -### lcm +### lcm() function Compute the least common multiple of two integers. -### clamp +### clamp() function Clamp a number between low and high. clamp(value, low, high). -### angledist +### angledist() function Compute the signed distance between two angles in 'turn' units, e.g. 0..1 range. -### jitter +### jitter() function Apply a random +/- percentage noise to a number. Example: jitter(100, 0.05) -> ~95..105. -### mean +### mean() function Compute the arithmetic mean of an array of numbers. -### sum +### sum() function Sum all elements of an array of numbers. -### sigma +### sigma() function Compute standard deviation of an array of numbers. -### median +### median() function Compute the median of an array of numbers. -### length +### length() function Return the length of a vector (i.e. sqrt of sum of squares). -### from_to +### from_to() function Return an array of points from a start to an end, spaced out by a certain distance. -### rand +### rand() function Return a random float in [0,1). -### randi +### randi() function Return a random 32-bit integer. -### srand +### srand() function Seed the random number generator with the given integer, or with current time if none. -### deg2rad(deg) +### TAU number -### rad2deg(rad) +### deg2rad(deg) function -### turn2rad(x) +### rad2deg(rad) function -### rad2turn(x) +### turn2rad(x) function -### turn2deg(x) +### rad2turn(x) function -### deg2turn(x) +### turn2deg(x) function + +### deg2turn(x) function diff --git a/docs/api/modules/miniz.md b/docs/api/modules/miniz.md index 31685e10..7a8ee0f8 100644 --- a/docs/api/modules/miniz.md +++ b/docs/api/modules/miniz.md @@ -1,3 +1,27 @@ # miniz -## miniz +### read(data) function + +Create a zip reader from the given ArrayBuffer containing an entire ZIP archive. +Return undefined if the data is invalid. + + + +**data**: An ArrayBuffer with the entire ZIP file. + + +**Returns**: A 'zip reader' object with methods for reading from the archive (mod, exists, slurp). + + +### write(path) function + +Create a zip writer that writes to the specified file path. Overwrites the file if +it already exists. Return undefined on error. + + + +**path**: The file path where the ZIP archive will be written. + + +**Returns**: A 'zip writer' object with methods for adding files to the archive (add_file). + diff --git a/docs/api/modules/os.md b/docs/api/modules/os.md index 06811325..5ad4494e 100644 --- a/docs/api/modules/os.md +++ b/docs/api/modules/os.md @@ -1,103 +1,101 @@ # os -## os - -### make_transform +### make_transform() function Create a new transform object that can be used for 2D/3D positioning, scaling, and rotation. -### clean_transforms +### clean_transforms() function Force an update on all transforms to remove dangling references or perform house-keeping. -### platform +### platform() function Return a string with the underlying platform name, like 'Windows', 'Linux', or 'macOS'. -### arch +### arch() function Return the CPU architecture string for this system (e.g. 'x64', 'arm64'). -### totalmem +### totalmem() function Return the total system RAM in bytes. -### freemem +### freemem() function Return the amount of free system RAM in bytes, if known. -### hostname +### hostname() function Return the system's hostname, or an empty string if not available. -### version +### version() function Return the OS or kernel version string, if the platform provides it. -### kill +### kill() function Send a signal (e.g., 'SIGINT', 'SIGTERM', etc.) to the current process. -### exit +### exit() function Exit the application with the specified exit code. -### now +### now() function Return current time (in seconds as a float) with high resolution. -### openurl +### openurl() function Open the provided URL in the default web browser, if possible. -### make_timer +### make_timer() function Create a new timer object that will call a specified function after a certain delay. -### update_timers +### update_timers() function Advance all timers by the provided time delta (in seconds). -### sleep +### sleep() function Block execution for the specified number of seconds. -### battery_pct +### battery_pct() function Return the battery level (percentage) or negative if unknown. -### battery_voltage +### battery_voltage() function Return the current battery voltage in volts, if available. -### battery_seconds +### battery_seconds() function Return the estimated remaining battery time in seconds, or negative if unknown. -### power_state +### power_state() function Return a string describing power status: 'on battery', 'charging', 'charged', etc. -### on +### on() function Register a global callback for certain engine-wide or system-level events. -### rt_info +### rt_info() function Return internal QuickJS runtime info, such as object counts. -### rusage +### rusage() function Return resource usage stats for this process, if the platform supports it. -### mallinfo +### mallinfo() function Return detailed memory allocation info (arena size, free blocks, etc.) on some platforms. -### env +### env() function Fetch the value of a given environment variable, or undefined if it doesn't exist. -### system +### system() function Execute a shell command using the system() call. Returns the command's exit code. diff --git a/docs/api/modules/packer.md b/docs/api/modules/packer.md index 77c49bf9..5db63459 100644 --- a/docs/api/modules/packer.md +++ b/docs/api/modules/packer.md @@ -1,8 +1,6 @@ # packer -## packer - -### getAllFiles(dir) +### getAllFiles(dir) function Return a list of all files in the given directory that are not matched by .prosperonignore, @@ -16,7 +14,7 @@ skipping directories. **Returns**: An array of file paths found. -### gatherStats(filePaths) +### gatherStats(filePaths) function Analyze a list of files and categorize them as modules, programs, images, or other. @@ -29,7 +27,7 @@ Analyze a list of files and categorize them as modules, programs, images, or oth **Returns**: An object { modules, programs, images, other, total } with counts. -### pack(dir, outPath) +### pack(dir, outPath) function Create a ZIP archive of all files (skipping those matched by .prosperonignore) in the diff --git a/docs/api/modules/render.md b/docs/api/modules/render.md index abdc94ee..93e65537 100644 --- a/docs/api/modules/render.md +++ b/docs/api/modules/render.md @@ -1,25 +1,15 @@ # render -## render +### _main object A handle for low-level GPU operations via SDL GPU. Freed on GC. -An application window, created via prosperon.engine_start or SDL calls. Freed on GC. +### device object +### stencil_writer(...args) function -#### present - -Perform the per-frame rendering and present the final swapchain image, including imgui pass if available. - - - -**Returns**: None - - -### stencil_writer(...args) - -### fillmask(ref) +### fillmask(ref) function Draw a fullscreen shape using a 'screenfill' shader to populate the stencil buffer with a given reference. @@ -31,7 +21,7 @@ Draw a fullscreen shape using a 'screenfill' shader to populate the stencil buff **Returns**: None -### mask(image, pos, scale, rotation, ref) +### mask(image, pos, scale, rotation, ref) function Draw an image to the stencil buffer, marking its area with a specified reference value. @@ -51,7 +41,7 @@ Draw an image to the stencil buffer, marking its area with a specified reference **Returns**: None -### viewport(rect) +### viewport(rect) function Set the GPU viewport to the specified rectangle. @@ -63,7 +53,7 @@ Set the GPU viewport to the specified rectangle. **Returns**: None -### scissor(rect) +### scissor(rect) function Set the GPU scissor region to the specified rectangle (alias of render.viewport). @@ -75,7 +65,7 @@ Set the GPU scissor region to the specified rectangle (alias of render.viewport) **Returns**: None -### queue(cmd) +### queue(cmd) function Enqueue one or more draw commands. These commands are batched until render_camera is called. @@ -87,7 +77,7 @@ Enqueue one or more draw commands. These commands are batched until render_camer **Returns**: None -### setup_draw +### setup_draw() function Switch the current queue to the primary scene render queue, then invoke 'prosperon.draw' if defined. @@ -96,7 +86,7 @@ Switch the current queue to the primary scene render queue, then invoke 'prosper **Returns**: None -### setup_hud +### setup_hud() function Switch the current queue to the HUD render queue, then invoke 'prosperon.hud' if defined. diff --git a/docs/api/modules/resources.md b/docs/api/modules/resources.md index 2cb3ce69..a0af8811 100644 --- a/docs/api/modules/resources.md +++ b/docs/api/modules/resources.md @@ -1,18 +1,26 @@ # resources -## resources +### scripts object -### canonical(file) +### images object -### find_image(...args) +### sounds object -### find_sound(...args) +### fonts object -### find_script(...args) +### lib object -### find_font(...args) +### canonical(file) function -### getAllFiles(dir) +### find_image(...args) function + +### find_sound(...args) function + +### find_script(...args) function + +### find_font(...args) function + +### getAllFiles(dir) function Return a list of recognized files in the given directory that are not matched by @@ -27,7 +35,7 @@ images, sounds, fonts, and libs. **Returns**: An array of recognized file paths. -### gatherStats(filePaths) +### gatherStats(filePaths) function Analyze a list of recognized files and categorize them by scripts, images, sounds, @@ -41,7 +49,7 @@ fonts, libs, or other. Return a stats object with these counts and the total. **Returns**: { scripts, images, sounds, fonts, lib, other, total } -### pack(dir, outPath) +### pack(dir, outPath) function Create a ZIP archive of all recognized files (skipping those matched by .prosperonignore) diff --git a/docs/api/modules/sound.md b/docs/api/modules/sound.md index 09344755..d7cd2afc 100644 --- a/docs/api/modules/sound.md +++ b/docs/api/modules/sound.md @@ -1,11 +1,11 @@ # sound -## sound +### undefined string -### pcm(file) +### pcm(file) function -### play(file) +### play(file) function -### cry(file) +### cry(file) function -### music(file, fade = 0.5) +### music(file, fade = 0.5) function diff --git a/docs/api/modules/spline.md b/docs/api/modules/spline.md index 9d3c069a..b070ddcb 100644 --- a/docs/api/modules/spline.md +++ b/docs/api/modules/spline.md @@ -1,11 +1,9 @@ # spline -## spline - -### catmull +### catmull() function Perform Catmull-Rom spline sampling on an array of 2D points, returning an array of samples. -### bezier +### bezier() function Perform a Bezier spline (or catmull) sampling on 2D points, returning an array of sampled points. diff --git a/docs/api/modules/time.md b/docs/api/modules/time.md index 650adb6c..158567a9 100644 --- a/docs/api/modules/time.md +++ b/docs/api/modules/time.md @@ -2,54 +2,102 @@ The main time object, handling date/time utilities in earth-seconds. -### now +### now() function Return the current system time in seconds (implemented in C extension). -### computer_dst +### computer_dst() function Return true if local system time is currently in DST (implemented in C extension). -### computer_zone +### computer_zone() function Return local time zone offset from UTC in hours (implemented in C extension). -### hour2minute +### second number + +Number of seconds in a (real) second (always 1). + +### minute number + +Number of seconds in a minute (60). + +### hour number + +Number of seconds in an hour (3600). + +### day number + +Number of seconds in a day (86400). + +### week number + +Number of seconds in a week (604800). + +### weekdays object + +Names of the days of the week, Sunday through Saturday. + +### monthstr object + +Full names of the months of the year, January through December. + +### epoch number + +Base epoch year, from which day 0 is calculated (default 1970). + +### hour2minute() function Return the ratio of hour to minute in seconds, e.g. 3600 / 60 => 60. -### day2hour +### day2hour() function Return the ratio of day to hour in seconds, e.g. 86400 / 3600 => 24. -### minute2second +### minute2second() function Return the ratio of minute to second in seconds, e.g. 60 / 1 => 60. -### week2day +### week2day() function Return the ratio of week to day in seconds, e.g. 604800 / 86400 => 7. -### isleap(year) +### strparse object + +Mapping of format tokens (yyyy, mm, dd, etc.) to time fields (year, month, day...). + +### isleap(year) function Return true if a given year is leap, based on whether it has 366 days. -### yearsize(y) +### yearsize(y) function Given a year, return 365 or 366 depending on leap-year rules. -### timecode(t, fps = 24) +### timecode(t, fps = 24) function Convert seconds into a "S:frames" timecode string, with optional FPS (default 24). -### record(num, zone = this.computer_zone() +### monthdays object + +An array of days in each month for a non-leap year. + +### zones object + +Table of recognized time zone abbreviations, with offsets (e.g., "-12" -> "IDLW"). + +### record(num, zone = this.computer_zone() function Convert a timestamp (in seconds) into a record with fields like day, month, year, etc. -### number(rec) +### number(rec) function Convert a record back into a numeric timestamp (seconds). -### text(num, fmt = this.fmt, zone) +### fmt string + +Default format string for time.text(), containing tokens like 'yyyy', 'dd', 'hh', etc. + +### text(num, fmt = this.fmt, zone) function Format a numeric or record time into a string using a format pattern, e.g. 'hh:nn:ss'. diff --git a/docs/api/modules/tween.md b/docs/api/modules/tween.md index 967dc0a3..f987a249 100644 --- a/docs/api/modules/tween.md +++ b/docs/api/modules/tween.md @@ -1,6 +1,6 @@ # tween -## tween +### Tween object An object providing methods to create and control tweens with additional features @@ -13,17 +13,7 @@ Methods: - make: Alias of start. -#### start(obj, target, tvals, options) - - -Alias of Tween.start. See Tween.start for usage details. - - -#### make(obj, target, tvals, options) - - -Alias of Tween.start. See Tween.start for usage details. - +### Ease object This object provides multiple easing functions that remap a 0..1 input to produce @@ -44,15 +34,7 @@ Available functions: All easing functions expect t in [0..1] and return a remapped value in [0..1]. -#### linear(t) - -#### in(t) - -#### out(t) - -#### inout(t) - -### tween(from, to, time, fn, cb) +### tween(from, to, time, fn, cb) function diff --git a/docs/api/modules/util.md b/docs/api/modules/util.md index c0a363a6..7f6f951c 100644 --- a/docs/api/modules/util.md +++ b/docs/api/modules/util.md @@ -5,7 +5,7 @@ A collection of general-purpose utility functions for object manipulation, mergi deep copying, safe property access, etc. -### guid +### guid() function Return a random 32-character hexadecimal UUID-like string (not guaranteed RFC4122-compliant). @@ -14,7 +14,7 @@ Return a random 32-character hexadecimal UUID-like string (not guaranteed RFC412 **Returns**: A random 32-character string (hex). -### insertion_sort(arr, cmp) +### insertion_sort(arr, cmp) function In-place insertion sort of an array using cmp(a,b)->Number for ordering. @@ -28,7 +28,7 @@ In-place insertion sort of an array using cmp(a,b)->Number for ordering. **Returns**: The same array, sorted in-place. -### deepfreeze(obj) +### deepfreeze(obj) function Recursively freeze an object and all of its nested objects so they cannot be modified. @@ -40,7 +40,7 @@ Recursively freeze an object and all of its nested objects so they cannot be mod **Returns**: None -### dainty_assign(target, source) +### dainty_assign(target, source) function Copy non-function properties from source into matching keys of target without overwriting @@ -55,7 +55,7 @@ keys that don't exist in target. Arrays are deep-copied, and objects are recursi **Returns**: None -### get(obj, path, defValue) +### get(obj, path, defValue) function Safely retrieve a nested property from obj at path (array or dot-string). @@ -72,7 +72,7 @@ Returns defValue if the property is undefined. **Returns**: The nested property or defValue. -### isEmpty(o) +### isEmpty(o) function Return true if the object has no own properties, otherwise false. @@ -84,7 +84,7 @@ Return true if the object has no own properties, otherwise false. **Returns**: Boolean indicating if the object is empty. -### dig(obj, path, def) +### dig(obj, path, def) function Ensure a nested path of objects exists inside obj; create objects if missing, and set @@ -101,7 +101,7 @@ the final path component to def. **Returns**: The assigned final value. -### access(obj, name) +### access(obj, name) function Traverse obj by dot-separated path name, returning the final value or undefined @@ -116,7 +116,7 @@ if any step is missing. **Returns**: The value at that path, or undefined if missing. -### mergekey(o1, o2, k) +### mergekey(o1, o2, k) function Helper for merge, updating key k from o2 into o1. Arrays are deep-copied and objects are @@ -133,7 +133,7 @@ recursively merged. **Returns**: None -### merge(target, objs) +### merge(target, objs) function Merge all passed objects into target, copying or merging each key as needed. @@ -148,7 +148,7 @@ Arrays are deep-copied, objects are recursively merged, etc. **Returns**: The updated target object. -### copy(proto, objs) +### copy(proto, objs) function Create a new object with proto as its prototype, then mix in additional objects’ properties. @@ -162,7 +162,7 @@ Create a new object with proto as its prototype, then mix in additional objects **Returns**: The newly created object. -### obj_lerp(a, b, t) +### obj_lerp(a, b, t) function Linearly interpolate between two objects a and b by factor t, assuming each property @@ -179,7 +179,7 @@ supports .lerp(). **Returns**: A new object with interpolated properties. -### normalizeSpacing(spacing) +### normalizeSpacing(spacing) function Normalize any spacing input into a {l, r, t, b} object. diff --git a/docs/api/modules/video.md b/docs/api/modules/video.md index 58c228b0..92ac692c 100644 --- a/docs/api/modules/video.md +++ b/docs/api/modules/video.md @@ -1,7 +1,5 @@ # video -## video - -### make_video +### make_video() function Decode a video file (MPEG, etc.) from an ArrayBuffer, returning a datastream object. diff --git a/docs/api/prosperon.md b/docs/api/prosperon.md index dc3b25a2..9cf244a3 100644 --- a/docs/api/prosperon.md +++ b/docs/api/prosperon.md @@ -1,51 +1,103 @@ # prosperon -## prosperon +### c_types object -### engine_start +### argv object -### on(type, callback) +### version string -### dispatch(type, data) +### revision string -### appupdate(...args) +### engine_start() function -### update(...args) +### DOC symbol -### physupdate(...args) +### on(type, callback) function -### gui(...args) +### dispatch(type, data) function -### hud(...args) +### PATH object -### draw(...args) +### appupdate(...args) function -### imgui(...args) +### update(...args) function -### app(...args) +### physupdate(...args) function -### camera +### gui(...args) function -A hierarchical transform storing 3D or 2D position, rotation (as a quaternion), -and scale. Can have a parent transform. Freed automatically on GC. +### hud(...args) function +### draw(...args) function + +### imgui(...args) function + +### app(...args) function + +### date string + +### camera object + +### debug boolean + +### semver object + +### title string + +### width number + +### height number + +### size object + +### icon object + +### high_dpi number + +### alpha number + +### fullscreen number + +### sample_count number + +### enable_clipboard boolean + +### enable_dragndrop boolean + +### max_dropped_files number + +### swap_interval number + +### name string + +### identifier string + +### creator string + +### copyright string + +### type string + +### url string + +### postvals object + +### hudcam object + +### appcam object + +### screencolor object + +### window object An application window, created via prosperon.engine_start or SDL calls. Freed on GC. +### font object + +### gpu object + A handle for low-level GPU operations via SDL GPU. Freed on GC. -An application window, created via prosperon.engine_start or SDL calls. Freed on GC. - - -#### present - -Perform the per-frame rendering and present the final swapchain image, including imgui pass if available. - - - -**Returns**: None - - -### exit +### exit() function diff --git a/docs/api/types/PHYSFS_File.md b/docs/api/types/PHYSFS_File.md index 3facc1b9..46803890 100644 --- a/docs/api/types/PHYSFS_File.md +++ b/docs/api/types/PHYSFS_File.md @@ -3,7 +3,7 @@ A file handle opened via PhysFS for writing or reading. Freed automatically when references go away. -### close +### close() function Close this file handle. Throws on error. @@ -12,7 +12,7 @@ Close this file handle. Throws on error. **Returns**: None -### write(data) +### write(data) function Write data (string or ArrayBuffer) to the file. Throws on error. @@ -24,7 +24,7 @@ Write data (string or ArrayBuffer) to the file. Throws on error. **Returns**: None -### buffer(size) +### buffer(size) function Enable an internal write buffer of the given size on this file. @@ -36,7 +36,7 @@ Enable an internal write buffer of the given size on this file. **Returns**: None -### tell +### tell() function Return the current position in the file. @@ -45,7 +45,7 @@ Return the current position in the file. **Returns**: A numeric offset. -### eof +### eof() function Return whether the file pointer is at end-of-file. diff --git a/docs/api/types/SDL_Camera.md b/docs/api/types/SDL_Camera.md index 75b201f7..de33f0fd 100644 --- a/docs/api/types/SDL_Camera.md +++ b/docs/api/types/SDL_Camera.md @@ -3,7 +3,7 @@ A handle to a physical camera device. Freed when references drop or camera is closed. -### frame +### frame() function Acquire the latest camera frame (as an SDL_Surface). Returns undefined if no new frame is available yet. Throws on error. @@ -13,7 +13,7 @@ new frame is available yet. Throws on error. **Returns**: SDL_Surface or undefined. -### release_frame(surface) +### release_frame(surface) function Release a frame surface previously acquired via camera.frame(). Must be done for each acquired frame. diff --git a/docs/api/types/SDL_GPUBuffer.md b/docs/api/types/SDL_GPUBuffer.md index 17093b30..6c54bdf5 100644 --- a/docs/api/types/SDL_GPUBuffer.md +++ b/docs/api/types/SDL_GPUBuffer.md @@ -1,5 +1,3 @@ # SDL_GPUBuffer -## SDL_GPUBuffer - -### name +### name() function diff --git a/docs/api/types/SDL_GPUCommandBuffer.md b/docs/api/types/SDL_GPUCommandBuffer.md index 5eb56b10..cebb8fa2 100644 --- a/docs/api/types/SDL_GPUCommandBuffer.md +++ b/docs/api/types/SDL_GPUCommandBuffer.md @@ -3,7 +3,7 @@ A command buffer that accumulates rendering, copy, and compute operations. Freed after submission or GC. -### render_pass(passDesc) +### render_pass(passDesc) function Begin a render pass with color/depth attachments. Provide an object with 'color_targets' and optional 'depth_stencil'. Returns an SDL_GPURenderPass handle. @@ -16,7 +16,7 @@ Begin a render pass with color/depth attachments. Provide an object with **Returns**: SDL_GPURenderPass -### compute_pass(storageTextures, storageBuffers) +### compute_pass(storageTextures, storageBuffers) function Begin a compute pass reading/writing given arrays of textures and buffers. @@ -30,7 +30,7 @@ Begin a compute pass reading/writing given arrays of textures and buffers. **Returns**: SDL_GPUComputePass -### swapchain_pass(clearColor) +### swapchain_pass(clearColor) function Begin a render pass that directly targets the swapchain (the window). Clears with the specified color. @@ -43,7 +43,7 @@ with the specified color. **Returns**: SDL_GPURenderPass -### acquire_swapchain +### acquire_swapchain() function Acquire the current swapchain texture from the window. Internal usage. @@ -52,7 +52,7 @@ Acquire the current swapchain texture from the window. Internal usage. **Returns**: SDL_GPUTexture handle -### bind_vertex_buffer(slot, buffer) +### bind_vertex_buffer(slot, buffer) function Bind a GPU buffer as the vertex buffer at a given slot. @@ -66,7 +66,7 @@ Bind a GPU buffer as the vertex buffer at a given slot. **Returns**: None -### bind_index_buffer(buffer, offset) +### bind_index_buffer(buffer, offset) function Bind a GPU buffer as the index buffer (16-bit or 32-bit). @@ -80,7 +80,7 @@ Bind a GPU buffer as the index buffer (16-bit or 32-bit). **Returns**: None -### bind_fragment_sampler(slot, texture, sampler) +### bind_fragment_sampler(slot, texture, sampler) function Bind a texture+sampler pair to a particular fragment shader slot. @@ -96,7 +96,7 @@ Bind a texture+sampler pair to a particular fragment shader slot. **Returns**: None -### push_vertex_uniform_data(slot, data) +### push_vertex_uniform_data(slot, data) function Push raw data to a vertex shader uniform block. @@ -110,7 +110,7 @@ Push raw data to a vertex shader uniform block. **Returns**: None -### push_fragment_uniform_data(slot, data) +### push_fragment_uniform_data(slot, data) function Push raw data to a fragment shader uniform block. @@ -124,7 +124,7 @@ Push raw data to a fragment shader uniform block. **Returns**: None -### push_compute_uniform_data(slot, data) +### push_compute_uniform_data(slot, data) function Push raw data to a compute shader uniform buffer. @@ -138,7 +138,7 @@ Push raw data to a compute shader uniform buffer. **Returns**: None -### submit +### submit() function Submit this command buffer to the GPU and return a fence for synchronization. @@ -147,7 +147,7 @@ Submit this command buffer to the GPU and return a fence for synchronization. **Returns**: An SDL_GPUFence -### cancel +### cancel() function Cancel (discard) this command buffer without submitting. @@ -156,7 +156,7 @@ Cancel (discard) this command buffer without submitting. **Returns**: None -### camera(cameraTransform, uniformSlot) +### camera(cameraTransform, uniformSlot) function Write a camera transform (projection/view) to a uniform slot for 3D or 2D usage. @@ -170,7 +170,7 @@ Write a camera transform (projection/view) to a uniform slot for 3D or 2D usage. **Returns**: None -### hud(sizeVec2, uniformSlot) +### hud(sizeVec2, uniformSlot) function Write an orthographic full-screen "HUD" matrix to a uniform slot. Typically used for 2D overlays. @@ -185,7 +185,7 @@ for 2D overlays. **Returns**: None -### push_debug_group(name) +### push_debug_group(name) function Push a named debug group marker onto the GPU command list (for debuggers/profilers). @@ -197,7 +197,7 @@ Push a named debug group marker onto the GPU command list (for debuggers/profile **Returns**: None -### pop_debug_group +### pop_debug_group() function Pop the most recent debug group marker. @@ -206,7 +206,7 @@ Pop the most recent debug group marker. **Returns**: None -### debug_label(label) +### debug_label(label) function Insert a one-off debug label at the current spot in the command list. @@ -218,7 +218,7 @@ Insert a one-off debug label at the current spot in the command list. **Returns**: None -### blit(blitDesc) +### blit(blitDesc) function Blit one GPU texture to another with optional flip mode, filter, and clear operations. diff --git a/docs/api/types/SDL_GPUComputePass.md b/docs/api/types/SDL_GPUComputePass.md index 63997dc6..99ea7abf 100644 --- a/docs/api/types/SDL_GPUComputePass.md +++ b/docs/api/types/SDL_GPUComputePass.md @@ -3,7 +3,7 @@ A compute pass for dispatching compute pipelines. Freed after end() or GC. -### dispatch(x, y, z) +### dispatch(x, y, z) function Dispatch the compute pipeline with the specified threadgroup counts. @@ -19,7 +19,7 @@ Dispatch the compute pipeline with the specified threadgroup counts. **Returns**: None -### end +### end() function End this compute pass. @@ -28,7 +28,7 @@ End this compute pass. **Returns**: None -### pipeline(computePipeline) +### pipeline(computePipeline) function Bind a compute pipeline in this pass. @@ -40,7 +40,7 @@ Bind a compute pipeline in this pass. **Returns**: None -### samplers(arrayOfSamplerBindings, firstSlot) +### samplers(arrayOfSamplerBindings, firstSlot) function Bind a set of texture/sampler pairs for compute usage. @@ -54,7 +54,7 @@ Bind a set of texture/sampler pairs for compute usage. **Returns**: None -### storage_buffers(arrayOfBuffers, firstSlot) +### storage_buffers(arrayOfBuffers, firstSlot) function Bind an array of storage buffers for the compute shader. @@ -68,7 +68,7 @@ Bind an array of storage buffers for the compute shader. **Returns**: None -### storage_textures(arrayOfTextures, firstSlot) +### storage_textures(arrayOfTextures, firstSlot) function Bind an array of storage textures for the compute shader. diff --git a/docs/api/types/SDL_GPUDevice.md b/docs/api/types/SDL_GPUDevice.md index 3e8968c0..809e1f26 100644 --- a/docs/api/types/SDL_GPUDevice.md +++ b/docs/api/types/SDL_GPUDevice.md @@ -3,7 +3,7 @@ A handle for low-level GPU operations via SDL GPU. Freed on GC. -### claim_window(window) +### claim_window(window) function Claim an existing SDL_Window so this GPU device can render to it. @@ -15,7 +15,7 @@ Claim an existing SDL_Window so this GPU device can render to it. **Returns**: None -### make_pipeline(pipelineDesc) +### make_pipeline(pipelineDesc) function Create a new graphics pipeline from a descriptor object specifying shaders, blend states, vertex format, etc. @@ -28,7 +28,7 @@ blend states, vertex format, etc. **Returns**: A SDL_GPUGraphicsPipeline handle. -### compute_pipeline(desc) +### compute_pipeline(desc) function Create a compute pipeline from a descriptor (shader code, threadgroup sizes, etc.). @@ -40,7 +40,7 @@ Create a compute pipeline from a descriptor (shader code, threadgroup sizes, etc **Returns**: SDL_GPUComputePipeline handle. -### set_swapchain(composition, presentMode) +### set_swapchain(composition, presentMode) function Specify how the swapchain (final rendered image) is composed, e.g. 'sdr', 'hdr', and present mode like 'vsync' or 'immediate'. @@ -55,7 +55,7 @@ and present mode like 'vsync' or 'immediate'. **Returns**: None -### sort_sprite(a, b) +### sort_sprite(a, b) function A comparator function used for sorting sprite objects by layer, y, and texture. Usually used internally. @@ -70,7 +70,7 @@ Usually used internally. **Returns**: <0, 0, or >0 for sort ordering. -### make_sampler(samplerDesc) +### make_sampler(samplerDesc) function Create a sampler object specifying filtering, wrapping, anisotropy, etc. @@ -82,7 +82,7 @@ Create a sampler object specifying filtering, wrapping, anisotropy, etc. **Returns**: SDL_GPUSampler handle. -### load_texture(surface, compressionLevel) +### load_texture(surface, compressionLevel) function Upload an SDL_Surface into a GPU texture, optionally compressing with DXT. Freed automatically. @@ -96,7 +96,7 @@ Upload an SDL_Surface into a GPU texture, optionally compressing with DXT. Freed **Returns**: SDL_GPUTexture -### texture(desc) +### texture(desc) function Create a GPU texture with the specified format usage. @@ -108,7 +108,7 @@ Create a GPU texture with the specified format usage. **Returns**: SDL_GPUTexture -### make_quad +### make_quad() function Return a simple 2-triangle quad geometry covering [0,1]x[0,1]. Useful for post-processing passes. @@ -118,7 +118,7 @@ Useful for post-processing passes. **Returns**: A mesh {pos, uv, color, indices}. -### driver +### driver() function Return the name of the underlying GPU driver in use (e.g. 'OpenGL'). @@ -127,7 +127,7 @@ Return the name of the underlying GPU driver in use (e.g. 'OpenGL'). **Returns**: A string with driver name. -### make_shader(desc) +### make_shader(desc) function Compile raw shader code (vertex or fragment) in e.g. SPIR-V, MSL, or DXIL format. @@ -139,7 +139,7 @@ Compile raw shader code (vertex or fragment) in e.g. SPIR-V, MSL, or DXIL format **Returns**: SDL_GPUShader object -### acquire_cmd_buffer +### acquire_cmd_buffer() function Obtain a new command buffer for recording GPU commands. Must be submitted or canceled. @@ -148,7 +148,7 @@ Obtain a new command buffer for recording GPU commands. Must be submitted or can **Returns**: SDL_GPUCommandBuffer handle -### upload(cmdBuffer, buffers, transferBuffer) +### upload(cmdBuffer, buffers, transferBuffer) function Upload CPU data into a list of GPU buffers, optionally reusing or returning a transfer buffer. Typically you provide (cmdBuf, arrayOfTypedArrays, [transferBuffer]). @@ -165,7 +165,7 @@ transfer buffer. Typically you provide (cmdBuf, arrayOfTypedArrays, [transferBuf **Returns**: The transfer buffer used or newly created. -### wait_for_fences(fences, waitAll) +### wait_for_fences(fences, waitAll) function Wait on an array of GPU fence objects, optionally requiring all or any. @@ -179,7 +179,7 @@ Wait on an array of GPU fence objects, optionally requiring all or any. **Returns**: True if fences signaled, false on timeout or error. -### query_fence(fence) +### query_fence(fence) function Check if the given fence has been signaled yet. Non-blocking. @@ -191,7 +191,7 @@ Check if the given fence has been signaled yet. Non-blocking. **Returns**: True if signaled, false if still pending -### shader_format +### shader_format() function Return an array of supported GPU shader binary formats (like 'spv', 'dxbc', etc.). @@ -200,7 +200,7 @@ Return an array of supported GPU shader binary formats (like 'spv', 'dxbc', etc. **Returns**: Array of strings naming supported formats. -### slice9(texture, dstRect, edges) +### slice9(texture, dstRect, edges) function Generate a 9-slice tiling geometry in one shot. For advanced usage with GPU pipeline. @@ -216,7 +216,7 @@ Generate a 9-slice tiling geometry in one shot. For advanced usage with GPU pipe **Returns**: A mesh object -### tile(texture, srcRect, dstRect, tileInfo) +### tile(texture, srcRect, dstRect, tileInfo) function Generate geometry to tile a texture portion inside a dest rect. Often used for repeating backgrounds. diff --git a/docs/api/types/SDL_GPURenderPass.md b/docs/api/types/SDL_GPURenderPass.md index 787c3be6..df258a7c 100644 --- a/docs/api/types/SDL_GPURenderPass.md +++ b/docs/api/types/SDL_GPURenderPass.md @@ -3,7 +3,7 @@ A single pass of drawing commands with color/depth attachments. Freed after end() or GC. -### bind_pipeline(pipeline) +### bind_pipeline(pipeline) function Bind a previously created graphics pipeline (shaders, states, vertex layouts, etc.). @@ -15,7 +15,7 @@ Bind a previously created graphics pipeline (shaders, states, vertex layouts, et **Returns**: None -### viewport(rect) +### viewport(rect) function Set the viewport for clipping or scaling draws, in pass-local coordinates. @@ -27,7 +27,7 @@ Set the viewport for clipping or scaling draws, in pass-local coordinates. **Returns**: None -### scissor(rect) +### scissor(rect) function Set a scissor rectangle for discarding pixels outside it. @@ -39,7 +39,7 @@ Set a scissor rectangle for discarding pixels outside it. **Returns**: None -### draw(primitiveType, baseVertex, firstVertex, vertexCount) +### draw(primitiveType, baseVertex, firstVertex, vertexCount) function Issue a non-indexed draw call. @@ -57,7 +57,7 @@ Issue a non-indexed draw call. **Returns**: None -### draw_indexed(primitiveType, baseVertex, firstIndex, indexCount, instanceCount) +### draw_indexed(primitiveType, baseVertex, firstIndex, indexCount, instanceCount) function Issue an indexed draw call from the bound index buffer. @@ -77,7 +77,7 @@ Issue an indexed draw call from the bound index buffer. **Returns**: None -### end +### end() function End this render pass, finalizing the draw operations. @@ -86,7 +86,7 @@ End this render pass, finalizing the draw operations. **Returns**: None -### bind_index_buffer(buffer, elementSize16bit) +### bind_index_buffer(buffer, elementSize16bit) function Bind an index buffer inside this pass, possibly overriding the global one. @@ -100,7 +100,7 @@ Bind an index buffer inside this pass, possibly overriding the global one. **Returns**: None -### bind_buffers(firstSlot, arrayOfBuffers) +### bind_buffers(firstSlot, arrayOfBuffers) function Bind multiple vertex buffers at consecutive slots. @@ -114,7 +114,7 @@ Bind multiple vertex buffers at consecutive slots. **Returns**: None -### bind_samplers(vertexOrFragment, firstSlot, samplerBindings) +### bind_samplers(vertexOrFragment, firstSlot, samplerBindings) function Bind multiple texture/sampler pairs to either vertex or fragment slots. @@ -130,7 +130,7 @@ Bind multiple texture/sampler pairs to either vertex or fragment slots. **Returns**: None -### bind_storage_buffers(firstSlot, buffers) +### bind_storage_buffers(firstSlot, buffers) function Bind one or more storage buffers for read/write in the pipeline. @@ -144,7 +144,7 @@ Bind one or more storage buffers for read/write in the pipeline. **Returns**: None -### bind_storage_textures(firstSlot, textures) +### bind_storage_textures(firstSlot, textures) function Bind one or more storage textures for read/write in the pipeline. diff --git a/docs/api/types/SDL_GPUTexture.md b/docs/api/types/SDL_GPUTexture.md index 1fb0918a..fa1b2161 100644 --- a/docs/api/types/SDL_GPUTexture.md +++ b/docs/api/types/SDL_GPUTexture.md @@ -1,5 +1,3 @@ # SDL_GPUTexture -## SDL_GPUTexture - -### name +### name() function diff --git a/docs/api/types/SDL_Renderer.md b/docs/api/types/SDL_Renderer.md index 8b8aa38c..69041077 100644 --- a/docs/api/types/SDL_Renderer.md +++ b/docs/api/types/SDL_Renderer.md @@ -3,7 +3,7 @@ A 2D rendering context using the SDL renderer API. Freed automatically. -### draw_color(color) +### draw_color(color) function Set the render draw color for subsequent primitive calls (rect, line, etc.). @@ -15,7 +15,7 @@ Set the render draw color for subsequent primitive calls (rect, line, etc.). **Returns**: None -### present +### present() function Display whatever has been rendered (swap buffers). Must be called each frame. @@ -24,7 +24,7 @@ Display whatever has been rendered (swap buffers). Must be called each frame. **Returns**: None -### clear +### clear() function Clear the current render target with the renderer's draw color. @@ -33,7 +33,7 @@ Clear the current render target with the renderer's draw color. **Returns**: None -### rect(rectOrArray, color) +### rect(rectOrArray, color) function Draw one or more outlines of rectangles. @@ -47,7 +47,7 @@ Draw one or more outlines of rectangles. **Returns**: None -### fillrect(rectOrArray, color) +### fillrect(rectOrArray, color) function Fill one or more rectangles with the renderer's current color or an optional override. @@ -61,7 +61,7 @@ Fill one or more rectangles with the renderer's current color or an optional ove **Returns**: None -### line(points, color) +### line(points, color) function Draw a sequence of lines connecting points in an array. @@ -75,7 +75,7 @@ Draw a sequence of lines connecting points in an array. **Returns**: None -### point(points, color) +### point(points, color) function Draw a list of points (pixels). @@ -89,7 +89,7 @@ Draw a list of points (pixels). **Returns**: None -### load_texture(surface) +### load_texture(surface) function Create an SDL_Texture from a given SDL_Surface for use with this renderer. @@ -101,7 +101,7 @@ Create an SDL_Texture from a given SDL_Surface for use with this renderer. **Returns**: An SDL_Texture object. -### texture(tex, dstRect, srcRect, color) +### texture(tex, dstRect, srcRect, color) function Draw a texture onto the render target. @@ -119,7 +119,7 @@ Draw a texture onto the render target. **Returns**: None -### slice9(tex, dstRect, edges, srcRect) +### slice9(tex, dstRect, edges, srcRect) function Draw a texture with 9-slice scaling. The argument includes edges {l, r, t, b} for the corners/borders that remain unscaled. The rest is tiled or stretched. @@ -138,7 +138,7 @@ for the corners/borders that remain unscaled. The rest is tiled or stretched. **Returns**: None -### tile(tex, dstRect, srcRect, scale) +### tile(tex, dstRect, srcRect, scale) function Tile a texture repeatedly within the specified region. Optionally use a srcRect. @@ -156,7 +156,7 @@ Tile a texture repeatedly within the specified region. Optionally use a srcRect. **Returns**: None -### get_image(rect) +### get_image(rect) function Read back the rendered pixels into a new SDL_Surface. If rect is undefined, capture entire output. @@ -168,7 +168,7 @@ Read back the rendered pixels into a new SDL_Surface. If rect is undefined, capt **Returns**: An SDL_Surface with the requested region's pixels. -### fasttext(text, pos, color) +### fasttext(text, pos, color) function Draw debug text using an internal fast path. Typically used for quick debugging overlays. @@ -184,7 +184,7 @@ Draw debug text using an internal fast path. Typically used for quick debugging **Returns**: None -### geometry(texture, meshObject) +### geometry(texture, meshObject) function Render custom geometry from a mesh object {pos, uv, color, indices, count} with an optional texture. @@ -198,7 +198,7 @@ Render custom geometry from a mesh object {pos, uv, color, indices, count} with **Returns**: None -### scale(scaleVec2) +### scale(scaleVec2) function Set a scaling factor for all subsequent rendering on this renderer. @@ -210,7 +210,7 @@ Set a scaling factor for all subsequent rendering on this renderer. **Returns**: None -### logical_size(size) +### logical_size(size) function Set a "logical" size that the renderer will scale to. For example, (320, 240) can auto-scale up to the window resolution. @@ -223,7 +223,7 @@ For example, (320, 240) can auto-scale up to the window resolution. **Returns**: None -### viewport(rect) +### viewport(rect) function Set the clipping viewport for rendering. Pass undefined to use the full render target. @@ -235,7 +235,7 @@ Set the clipping viewport for rendering. Pass undefined to use the full render t **Returns**: None -### clip(rect) +### clip(rect) function Set or clear the clipping rectangle for drawing. Pass undefined to clear. @@ -247,7 +247,7 @@ Set or clear the clipping rectangle for drawing. Pass undefined to clear. **Returns**: None -### vsync(flag) +### vsync(flag) function Enable or disable vertical sync. This may have no effect depending on the driver. @@ -259,7 +259,7 @@ Enable or disable vertical sync. This may have no effect depending on the driver **Returns**: None -### coords(pos) +### coords(pos) function Convert window coordinates to this renderer's coordinate space. @@ -271,7 +271,7 @@ Convert window coordinates to this renderer's coordinate space. **Returns**: [x, y] in renderer coordinate space. -### camera(cameraTransform, centered) +### camera(cameraTransform, centered) function Set up a basic 2D camera matrix from a given transform. If 'centered' is true, the origin is the center of the viewport, else top-left. @@ -286,7 +286,7 @@ the origin is the center of the viewport, else top-left. **Returns**: None -### get_viewport +### get_viewport() function Return the current viewport rect. @@ -295,7 +295,7 @@ Return the current viewport rect. **Returns**: {x, y, w, h} -### screen2world(pos) +### screen2world(pos) function Convert a screen coordinate to world space based on the current camera transform. @@ -307,7 +307,7 @@ Convert a screen coordinate to world space based on the current camera transform **Returns**: [wx, wy] in world space -### target(texture) +### target(texture) function Set or clear the current render target texture. Pass undefined to reset to the default/window. @@ -319,7 +319,7 @@ Set or clear the current render target texture. Pass undefined to reset to the d **Returns**: None -### make_sprite_mesh(sprites) +### make_sprite_mesh(sprites) function Generate a mesh from an array of sprite objects, combining their positions, UVs, and colors into a single geometry block. diff --git a/docs/api/types/SDL_Surface.md b/docs/api/types/SDL_Surface.md index 69ddb312..bb0662d8 100644 --- a/docs/api/types/SDL_Surface.md +++ b/docs/api/types/SDL_Surface.md @@ -4,7 +4,7 @@ A software (CPU) image in memory. Freed when references vanish. Typically conver to SDL_Texture for drawing, or used as raw pixel data. -### blit(dstRect, srcSurface, srcRect) +### blit(dstRect, srcSurface, srcRect) function Blit (copy) another surface onto this surface, scaling if needed. @@ -20,7 +20,7 @@ Blit (copy) another surface onto this surface, scaling if needed. **Returns**: None -### scale(newSize) +### scale(newSize) function Return a new SDL_Surface scaled to [width, height] using linear filtering. @@ -32,7 +32,7 @@ Return a new SDL_Surface scaled to [width, height] using linear filtering. **Returns**: A new SDL_Surface with the scaled result. -### fill(color) +### fill(color) function Fill the entire surface with a single color. @@ -44,7 +44,7 @@ Fill the entire surface with a single color. **Returns**: None -### rect(rect, color) +### rect(rect, color) function Fill a sub-rectangle of the surface with a color. @@ -58,7 +58,7 @@ Fill a sub-rectangle of the surface with a color. **Returns**: None -### dup +### dup() function Make a copy of this surface in RGBA format. diff --git a/docs/api/types/SDL_Texture.md b/docs/api/types/SDL_Texture.md index 6cdf949a..9b1c9289 100644 --- a/docs/api/types/SDL_Texture.md +++ b/docs/api/types/SDL_Texture.md @@ -3,7 +3,7 @@ A 2D GPU-accelerated texture for rendering with SDL_Renderer. Freed automatically. -### mode(mode) +### mode(mode) function Set texture scale mode or filtering mode (nearest/linear). diff --git a/docs/api/types/SDL_Thread.md b/docs/api/types/SDL_Thread.md index fde026fd..f1cc239e 100644 --- a/docs/api/types/SDL_Thread.md +++ b/docs/api/types/SDL_Thread.md @@ -5,7 +5,7 @@ A handle to an SDL-created thread. Freed on GC after join. Note: The engine generally doesn't expose custom usage for threads. -### wait +### wait() function Block until this thread terminates. diff --git a/docs/api/types/SDL_Window.md b/docs/api/types/SDL_Window.md index 2abc513d..9a6d57d9 100644 --- a/docs/api/types/SDL_Window.md +++ b/docs/api/types/SDL_Window.md @@ -3,7 +3,7 @@ An application window, created via prosperon.engine_start or SDL calls. Freed on GC. -### fullscreen +### fullscreen() function Toggle fullscreen mode for this window (SDL_WINDOW_FULLSCREEN). @@ -12,7 +12,7 @@ Toggle fullscreen mode for this window (SDL_WINDOW_FULLSCREEN). **Returns**: None -### make_renderer(name) +### make_renderer(name) function Create an SDL_Renderer for 2D rendering tied to this window. @@ -24,7 +24,7 @@ Create an SDL_Renderer for 2D rendering tied to this window. **Returns**: An SDL_Renderer object. -### make_gpu(debug, driverName) +### make_gpu(debug, driverName) function Create an SDL_GPUDevice for low-level GPU rendering on this window. @@ -38,7 +38,7 @@ Create an SDL_GPUDevice for low-level GPU rendering on this window. **Returns**: An SDL_GPUDevice. -### keyboard_shown +### keyboard_shown() function Return whether the on-screen keyboard is visible (mobile/tablet). @@ -47,7 +47,7 @@ Return whether the on-screen keyboard is visible (mobile/tablet). **Returns**: True if shown, false otherwise. -### theme +### theme() function Currently returns undefined. Placeholder for retrieving OS window theme info. @@ -56,7 +56,7 @@ Currently returns undefined. Placeholder for retrieving OS window theme info. **Returns**: undefined -### safe_area +### safe_area() function Return a rect describing any OS-specific "safe" region for UI, e.g. on iPhone with a notch. @@ -65,7 +65,7 @@ Return a rect describing any OS-specific "safe" region for UI, e.g. on iPhone wi **Returns**: A rect object {x, y, w, h}. -### bordered(flag) +### bordered(flag) function Enable or disable window borders. @@ -77,7 +77,7 @@ Enable or disable window borders. **Returns**: None -### set_icon(surface) +### set_icon(surface) function Set the window's icon from an SDL_Surface. @@ -89,7 +89,7 @@ Set the window's icon from an SDL_Surface. **Returns**: None -### title +### title accessor Get or set the window's title text in the title bar. @@ -101,7 +101,7 @@ Get or set the window's title text in the title bar. **Returns**: The current title if getting, or None if setting. -### size +### size accessor Get or set the window's size as [width, height]. @@ -113,7 +113,7 @@ Get or set the window's size as [width, height]. **Returns**: The current [width, height] or None if setting. -### mouse_grab(flag) +### mouse_grab(flag) function Grab or ungrab the mouse for this window (so the pointer won't leave). diff --git a/docs/api/types/datastream.md b/docs/api/types/datastream.md index ed96aeb3..89204b0a 100644 --- a/docs/api/types/datastream.md +++ b/docs/api/types/datastream.md @@ -3,7 +3,7 @@ A streaming media handle, typically for MPEG video. Freed automatically. -### time +### time() function Return the current playback time in seconds. @@ -12,7 +12,7 @@ Return the current playback time in seconds. **Returns**: Current time as a float in seconds. -### seek(seconds) +### seek(seconds) function Seek to the specified time (in seconds). @@ -24,7 +24,7 @@ Seek to the specified time (in seconds). **Returns**: None -### advance(seconds) +### advance(seconds) function Advance by a certain number of seconds, decoding video as needed. @@ -36,7 +36,7 @@ Advance by a certain number of seconds, decoding video as needed. **Returns**: None -### duration +### duration() function Return the total duration of the video stream, in seconds, if known. @@ -45,7 +45,7 @@ Return the total duration of the video stream, in seconds, if known. **Returns**: Float seconds duration, or 0 if unknown. -### framerate +### framerate() function Return the framerate (FPS) of the stream if known. @@ -54,7 +54,7 @@ Return the framerate (FPS) of the stream if known. **Returns**: Float frames per second, or 0 if unknown. -### callback +### callback accessor A function to call whenever a new frame is decoded. If not set, no callback is invoked. diff --git a/docs/api/types/font.md b/docs/api/types/font.md index 1dcd8d0f..8a7bf576 100644 --- a/docs/api/types/font.md +++ b/docs/api/types/font.md @@ -4,7 +4,7 @@ A bitmap or TTF-based font object storing glyph data. Used for measuring/drawing text. Freed when GC sees no references. -### linegap +### linegap accessor Get or set the font's additional line spacing above the built-in metrics. @@ -16,7 +16,7 @@ Get or set the font's additional line spacing above the built-in metrics. **Returns**: The current line gap (when getting), or None (when setting). -### height +### height accessor (read only) @@ -27,7 +27,7 @@ The baseline-to-baseline height in pixels. **Returns**: The font's total height in px. -### ascent +### ascent accessor (read only) @@ -38,7 +38,7 @@ How far above the baseline the font extends. **Returns**: A scalar float for ascent. -### descent +### descent accessor (read only) @@ -49,7 +49,7 @@ How far below baseline the font extends. **Returns**: A scalar float for descent. -### text_size(text, letterSpacing, wrap) +### text_size(text, letterSpacing, wrap) function Measure a piece of text's width/height when rendered with this font. diff --git a/docs/api/types/rtree.md b/docs/api/types/rtree.md index 63bb249b..d936737c 100644 --- a/docs/api/types/rtree.md +++ b/docs/api/types/rtree.md @@ -3,7 +3,7 @@ An R-tree for spatial lookups. Insert bounding boxes, query by bounding box, etc. -### add(obj) +### add(obj) function Insert an object that has a 'rect' property {x, y, w, h} into the tree. @@ -15,7 +15,7 @@ Insert an object that has a 'rect' property {x, y, w, h} into the tree. **Returns**: None -### delete(obj) +### delete(obj) function Remove an object from the tree. Must match the same rect as used when adding. @@ -27,7 +27,7 @@ Remove an object from the tree. Must match the same rect as used when adding. **Returns**: None -### query(rect) +### query(rect) function Return an array of objects whose bounding boxes intersect the given rect. @@ -39,7 +39,18 @@ Return an array of objects whose bounding boxes intersect the given rect. **Returns**: Array of objects that overlap that region. -### forEach(callback) +### size accessor + +(read only) + +Indicates how many items are stored in the rtree. + + + +**Returns**: Integer count of items in the tree. + + +### forEach(callback) function Call a function for every item in the rtree. @@ -51,7 +62,7 @@ Call a function for every item in the rtree. **Returns**: None -### has(obj) +### has(obj) function Return true if the specified object is in the tree, false otherwise. @@ -63,7 +74,7 @@ Return true if the specified object is in the tree, false otherwise. **Returns**: True if found, else false. -### values +### values() function Return an array of all items currently in the rtree. diff --git a/docs/api/types/sprite.md b/docs/api/types/sprite.md index ad042ef9..27354d1a 100644 --- a/docs/api/types/sprite.md +++ b/docs/api/types/sprite.md @@ -5,7 +5,7 @@ UV coordinates, color, and layer, as well as an associated 'image' object. The s can be drawn via GPU or SDL_Renderer. Freed when no JS references remain. -### set_affine(transform) +### set_affine(transform) function Update this sprite's position and size from a transform's pos and scale. @@ -17,7 +17,7 @@ Update this sprite's position and size from a transform's pos and scale. **Returns**: None -### set_rect(rect) +### set_rect(rect) function Set the sprite's rect (x, y, w, h) directly. @@ -29,7 +29,7 @@ Set the sprite's rect (x, y, w, h) directly. **Returns**: None -### set_image(image) +### set_image(image) function Assign or replace the sprite's underlying image. Automatically updates UV if the image has a 'rect' property. @@ -42,7 +42,7 @@ the image has a 'rect' property. **Returns**: None -### layer +### layer accessor Get or set the sprite's z-layer integer. Sprites with higher layers typically draw on top of lower layers. @@ -55,7 +55,7 @@ draw on top of lower layers. **Returns**: The current layer (when getting), or None (when setting). -### color +### color accessor Get or set the sprite's color tint as [r, g, b, a]. diff --git a/docs/api/types/timer.md b/docs/api/types/timer.md index 73209cac..6a39a91e 100644 --- a/docs/api/types/timer.md +++ b/docs/api/types/timer.md @@ -4,7 +4,7 @@ A scheduled callback or countdown. Freed automatically once no longer referenced or once it completes. -### remain +### remain accessor Get or set how many seconds remain before the timer triggers. @@ -16,7 +16,7 @@ Get or set how many seconds remain before the timer triggers. **Returns**: The current time left (when getting), or None (when setting). -### fn +### fn accessor Get or set the function called when the timer expires. diff --git a/docs/api/types/transform.md b/docs/api/types/transform.md index 17e7c663..1f94fdf0 100644 --- a/docs/api/types/transform.md +++ b/docs/api/types/transform.md @@ -4,7 +4,7 @@ A hierarchical transform storing 3D or 2D position, rotation (as a quaternion), and scale. Can have a parent transform. Freed automatically on GC. -### pos +### pos accessor Get or set the transform's position as a 3D vector [x, y, z]. @@ -16,7 +16,7 @@ Get or set the transform's position as a 3D vector [x, y, z]. **Returns**: The current position vector (when getting), or None (when setting). -### scale +### scale accessor Get or set the transform's scale as a 3D vector [x, y, z]. For 2D usage, z is often 1. @@ -29,7 +29,7 @@ For 2D usage, z is often 1. **Returns**: The current scale (when getting), or None (when setting). -### rotation +### rotation accessor Get or set the transform's rotation as a quaternion [x, y, z, w]. Angles in degrees or radians must first be converted prior to making a quaternion. @@ -42,7 +42,7 @@ Angles in degrees or radians must first be converted prior to making a quaternio **Returns**: The current quaternion (when getting), or None (when setting). -### parent +### parent accessor Get or set the transform's parent. If set, this transform becomes a child of the parent (re-parenting). Must be another transform object or undefined. @@ -55,7 +55,7 @@ the parent (re-parenting). Must be another transform object or undefined. **Returns**: The current parent transform (when getting), or None (when setting). -### change_hook +### change_hook accessor A user-supplied function that's called whenever the transform's local matrix changes. If undefined, no hook is called. @@ -68,7 +68,7 @@ If undefined, no hook is called. **Returns**: The current function or undefined. -### trs(pos, quat, scale) +### trs(pos, quat, scale) function Set the transform's position, rotation, and scale in one call. @@ -84,7 +84,7 @@ Set the transform's position, rotation, and scale in one call. **Returns**: None -### phys2d(velocity, angularVel, dt) +### phys2d(velocity, angularVel, dt) function Apply simple 2D velocity and angular velocity to this transform. @@ -100,7 +100,7 @@ Apply simple 2D velocity and angular velocity to this transform. **Returns**: None -### move(delta) +### move(delta) function Translate this transform by the specified vector. @@ -112,7 +112,7 @@ Translate this transform by the specified vector. **Returns**: None -### rotate(axis, angle) +### rotate(axis, angle) function Rotate this transform by an axis+angle. @@ -126,7 +126,7 @@ Rotate this transform by an axis+angle. **Returns**: None -### angle(axis) +### angle(axis) function Return the transform's rotation about a specified axis (x, y, or z). For example, angle([1,0,0]) returns the roll about the X-axis. @@ -139,7 +139,7 @@ For example, angle([1,0,0]) returns the roll about the X-axis. **Returns**: The numeric angle in 'turns' or radians, depending on usage. -### lookat(target) +### lookat(target) function Rotate this transform so it looks toward the given world position. @@ -151,7 +151,7 @@ Rotate this transform so it looks toward the given world position. **Returns**: None -### direction(localDir) +### direction(localDir) function Rotate a vector by this transform's rotation, effectively "transforming" a direction from local space to world space. @@ -164,7 +164,7 @@ a direction from local space to world space. **Returns**: [dx', dy', dz'] direction in world space. -### unit +### unit() function Reset position, rotation, and scale to [0,0,0], identity rotation, and [1,1,1]. @@ -173,7 +173,7 @@ Reset position, rotation, and scale to [0,0,0], identity rotation, and [1,1,1]. **Returns**: None -### rect(rect) +### rect(rect) function Set this transform's pos and scale from a 2D rect object {x, y, w, h}. @@ -185,7 +185,7 @@ Set this transform's pos and scale from a 2D rect object {x, y, w, h}. **Returns**: None -### array +### array() function Return this transform's matrix as a 16-element float array in column-major order. @@ -194,7 +194,7 @@ Return this transform's matrix as a 16-element float array in column-major order **Returns**: An array of 16 floats. -### torect +### torect() function Convert transform's 2D position/scale to a rect {x, y, w, h}. Rotation is currently ignored. @@ -204,7 +204,7 @@ Rotation is currently ignored. **Returns**: A rect object {x, y, w, h}. -### children +### children() function Return an array of child transforms belonging to this transform. diff --git a/docs/api/use.md b/docs/api/use.md index 3fb56a66..cf3ad058 100644 --- a/docs/api/use.md +++ b/docs/api/use.md @@ -1,3 +1,7 @@ # use -## use +### length number + +### name string + +### prototype object diff --git a/docs/crab.png b/docs/crab.png new file mode 100644 index 00000000..3d7701e2 Binary files /dev/null and b/docs/crab.png differ diff --git a/docs/dull/ArrayBuffer.md b/docs/dull/ArrayBuffer.md new file mode 100644 index 00000000..b2f69e5e --- /dev/null +++ b/docs/dull/ArrayBuffer.md @@ -0,0 +1,7 @@ +# ArrayBuffer + +### byteLength accessor + +(read only) + +### slice() function diff --git a/docs/dull/Function.md b/docs/dull/Function.md new file mode 100644 index 00000000..6632088f --- /dev/null +++ b/docs/dull/Function.md @@ -0,0 +1,27 @@ +# Function + +### length number + +### name string + +### caller accessor + +### arguments accessor + +### call() function + +### apply() function + +### bind() function + +### toString() function + +### fileName accessor + +(read only) + +### lineNumber accessor + +(read only) + +### hashify() function diff --git a/docs/dull/Map.md b/docs/dull/Map.md new file mode 100644 index 00000000..0c95588f --- /dev/null +++ b/docs/dull/Map.md @@ -0,0 +1,120 @@ +# Map + +A Map object holds key-value pairs, where any value (both objects and primitive values) may be used as either a key or a value. Insertion order is remembered, which allows iteration in that order. + +### set(key, value) function + +Add or update an entry in the Map with the specified key and value. + + + +**key**: The key of the element to add or update. + +**value**: The value associated with the key. + + +**Returns**: The Map object (for chaining). + + +### get(key) function + +Return the value associated with the specified key, or undefined if no +such key exists. + + + +**key**: The key of the element to retrieve. + + +**Returns**: The value associated with the key, or undefined if not found. + + +### has(key) function + +Return a boolean indicating whether the Map contains an element with the +specified key. + + + +**key**: The key to test for presence in the Map. + + +**Returns**: True if the key is found, otherwise false. + + +### delete(key) function + +Remove the specified key and its associated value from the Map, if it exists. + + + +**key**: The key to remove. + + +**Returns**: True if an element was removed, otherwise false. + + +### clear() function + +Remove all entries from the Map, leaving it empty. + + + +**Returns**: None + + +### size accessor + +(read only) + +A read-only property returning the number of key-value pairs in the Map. + + + +**Returns**: The number of entries in the Map. + + +### forEach(callbackFn, thisArg) function + +Execute a provided callback function once per each key-value pair in the Map, +in insertion order. + + + +**callbackFn**: A function(value, key, map) to execute on each entry. + +**thisArg**: Optional. A value to use as 'this' when executing callbackFn. + + +**Returns**: None + + +### values() function + +Return a new Iterator object that contains the values for each element +in the Map, in insertion order. + + + +**Returns**: An iterator of the Map's values. + + +### keys() function + +Return a new Iterator object that contains the keys for each element in +the Map, in insertion order. + + + +**Returns**: An iterator of the Map's keys. + + +### entries() function + +Return a new Iterator object that contains the [key, value] pairs for +each element in the Map, in insertion order. + + + +**Returns**: An iterator of [key, value] pairs. + diff --git a/docs/dull/Object.md b/docs/dull/Object.md new file mode 100644 index 00000000..b85511c6 --- /dev/null +++ b/docs/dull/Object.md @@ -0,0 +1,87 @@ +# Object + +### toString() function + +Return a string representing this object. By default, it returns a string of the form '[object ]', where is the object's class. + + + +**Returns**: A string that describes the object. + + +### toLocaleString() function + +Return a localized string representation of this object, calling toString() by default or a locale-specific override if defined. + + + +**Returns**: A locale-sensitive string representation of the object. + + +### valueOf() function + +Return the primitive value of this object if one exists. Typically, an object returns itself, while a wrapped type (e.g. Number, String) may return the underlying primitive value. + + + +**Returns**: The primitive value of the object, or the object itself. + + +### hasOwnProperty(prop) function + +Return a boolean indicating whether the object has a property with the specified name (key) as its own direct property, as opposed to inheriting it. It does not check the prototype chain. + + + +**prop**: The name or Symbol of the property to test. + + +**Returns**: True if the property is found directly on the object, otherwise false. + + +### isPrototypeOf(obj) function + +Return true if the object appears anywhere in the prototype chain of the specified object, otherwise false. + + + +**obj**: The object whose prototype chain will be checked. + + +**Returns**: True if this object is in 'obj's prototype chain, otherwise false. + + +### propertyIsEnumerable(prop) function + +Return a boolean indicating whether the specified property is enumerable, i.e., whether it shows up in a for...in loop or Object.keys() on the object. + + + +**prop**: The name or Symbol of the property to test. + + +**Returns**: True if the property is found and enumerable, otherwise false. + + +### __proto__ accessor + +### __defineGetter__() function + +### __defineSetter__() function + +### __lookupGetter__() function + +### __lookupSetter__() function + +### mixin(obj) function + +Mix properties from 'obj' into the current object. If 'obj' is a string, +it first calls 'use(obj)' to retrieve the object. + + + +**obj**: The object (or string reference to an object) to mix in. + + +**Returns**: None + diff --git a/docs/dull/Set.md b/docs/dull/Set.md new file mode 100644 index 00000000..ae5e3168 --- /dev/null +++ b/docs/dull/Set.md @@ -0,0 +1,104 @@ +# Set + +A Set object lets you store unique values of any type, whether primitive values or object references. It remembers insertion order for iteration. + +### add(value) function + +Add a new element with the given value to the Set, if it’s not already present. + + + +**value**: The value to add. + + +**Returns**: The Set object (for chaining). + + +### has(value) function + +Return a boolean indicating whether the Set contains the specified value. + + + +**value**: The value to check for presence in the Set. + + +**Returns**: True if the value is found, otherwise false. + + +### delete(value) function + +Remove the specified value from the Set if it exists. + + + +**value**: The value to remove. + + +**Returns**: True if the value was present and removed, otherwise false. + + +### clear() function + +Remove all elements from the Set, leaving it empty. + + + +**Returns**: None + + +### size accessor + +(read only) + +A read-only property returning the number of elements in the Set. + + + +**Returns**: The number of unique values in the Set. + + +### forEach(callbackFn, thisArg) function + +Execute a provided callback function once for each value in the Set, +in insertion order. + + + +**callbackFn**: A function(value, valueAgain, set) to execute on each element. + +**thisArg**: Optional. A value to use as 'this' when executing callbackFn. + + +**Returns**: None + + +### values() function + +Alias for values() in a Set. Return a new Iterator object containing all +the values (as keys) in the Set, in insertion order. + + + +**Returns**: An iterator of the Set's values. + + +### keys() function + +Alias for values() in a Set. Return a new Iterator object containing all +the values (as keys) in the Set, in insertion order. + + + +**Returns**: An iterator of the Set's values. + + +### entries() function + +Return a new Iterator object containing [value, value] pairs for each value +in the Set, in insertion order. This maintains API consistency with Map objects. + + + +**Returns**: An iterator of [value, value] pairs. + diff --git a/docs/dull/String.md b/docs/dull/String.md new file mode 100644 index 00000000..f444dc6a --- /dev/null +++ b/docs/dull/String.md @@ -0,0 +1,793 @@ +# String + +### length number + +### at(index) function + +Return the character (or surrogate pair) at the specified index, with support +for negative indices (counting from the end). If the index is out of range, +returns undefined. + + + +**index**: The position of the character to return (can be negative). + + +**Returns**: A string of length 1 representing the character, or undefined if out of range. + + +### charCodeAt(index) function + +Return a number indicating the UTF-16 code unit value at the given index. +If the index is out of range, returns NaN. + + + +**index**: An integer between 0 and string length - 1. + + +**Returns**: An integer in the range [0, 65535] or NaN if out of range. + + +### charAt(index) function + +Return a string consisting of the single UTF-16 code unit at the given index. +If the index is out of range, returns an empty string. + + + +**index**: The zero-based index of the desired character. + + +**Returns**: The single-character string at the specified index, or '' if out of range. + + +### concat(stringN) function + +Concatenate the provided string arguments to the current string and return a +new string. + + + +**stringN**: One or more strings to concatenate. + + +**Returns**: A new string formed by joining the caller with the provided arguments. + + +### codePointAt(position) function + +Return a non-negative integer that is the Unicode code point value at the +given position. Supports code points above 0xFFFF. Returns undefined if index +is out of range. + + + +**position**: The index in the string (can be surrogate pairs). + + +**Returns**: The code point value, or undefined if out of range. + + +### isWellFormed() function + +Return a boolean indicating whether the string is valid Unicode. +If it contains unpaired surrogate code points, return false. + + + +**Returns**: True if the string is well-formed UTF-16, otherwise false. + + +### toWellFormed() function + +Return a new string in which any unpaired surrogate code points have been +replaced by the Unicode replacement character U+FFFD. + + + +**Returns**: A well-formed UTF-16 version of the string. + + +### indexOf(searchValue, fromIndex) function + +Return the zero-based index of the first occurrence of 'searchValue' in the +string, starting at 'fromIndex'. If not found, return -1. + + + +**searchValue**: The substring to search for. + +**fromIndex**: The index at which to begin searching (default 0). + + +**Returns**: The index of the first match, or -1 if not found. + + +### lastIndexOf(searchValue, fromIndex) function + +Return the zero-based index of the last occurrence of 'searchValue' in the +string, searching backwards from 'fromIndex'. If not found, return -1. + + + +**searchValue**: The substring to search for. + +**fromIndex**: The index at which to begin the backward search (defaults to string length - 1). + + +**Returns**: The index of the last match, or -1 if not found. + + +### includes(searchString, position) function + +Return a boolean indicating whether 'searchString' appears within this string. +An optional position can be provided to start searching. + + + +**searchString**: The substring to search for. + +**position**: The position from which to begin searching (default 0). + + +**Returns**: True if the substring is found, otherwise false. + + +### endsWith(searchString, length) function + +Return a boolean indicating whether the string ends with 'searchString'. +An optional 'length' can be provided to treat the string as if it were only +that long. + + + +**searchString**: The substring to search for at the end. + +**length**: An optional length to truncate the string before testing. + + +**Returns**: True if the string ends with 'searchString', otherwise false. + + +### startsWith(searchString, position) function + +Return a boolean indicating whether the string begins with 'searchString'. +An optional position can be provided to start checking at that index. + + + +**searchString**: The substring to search for at the start. + +**position**: The index in the string to start searching (default 0). + + +**Returns**: True if the string starts with 'searchString', otherwise false. + + +### match(regexp) function + +Use a regular expression to match the string. If 'regexp' is not a RegExp, it +is converted to one. Return an array of matches or null if none found. + + + +**regexp**: The pattern to match (RegExp or string). + + +**Returns**: An array of matches or null. + + +### matchAll(regexp) function + +Return an iterator of all RegExp match objects found within the string. +If 'regexp' is not a global or sticky RegExp, a TypeError is thrown. + + + +**regexp**: The global/sticky RegExp to match over this string. + + +**Returns**: An iterator of match arrays. + + +### search(regexp) function + +Use a regular expression to search for a match within the string. Return the +index of the first match, or -1 if no match is found. + + + +**regexp**: A RegExp or string. If a string, it is converted to RegExp. + + +**Returns**: The index of the first match, or -1 if not found. + + +### split(separator, limit) function + +Split the string into an array of substrings using 'separator' (RegExp or +string). An optional 'limit' can be provided to limit the number of splits. + + + +**separator**: A string or RegExp used to divide the string. + +**limit**: Maximum number of splits to include in the result array. + + +**Returns**: An array of the split substrings. + + +### substring(start, end) function + +Return the substring between 'start' and 'end'. Indices outside the range +are clamped. If 'end' < 'start', they swap. + + + +**start**: The starting index (0-based). + +**end**: The ending index (exclusive). + + +**Returns**: The extracted substring. + + +### substr(start, length) function + +Return the substring from 'start' for 'length' characters. Negative 'start' +counts from the end. This method is deprecated but still supported in many +engines. + + + +**start**: The starting index. + +**length**: The number of characters to extract. + + +**Returns**: The extracted substring. + + +### slice(start, end) function + +Extract a section of the string from 'start' up to (but not including) 'end', +and return it as a new string. Supports negative indices. + + + +**start**: The starting index. Negative values count from the end. + +**end**: The ending index (exclusive). Negative values count from the end. + + +**Returns**: The extracted slice. + + +### repeat(count) function + +Construct and return a new string which contains the specified number of copies +of the calling string, concatenated together. + + + +**count**: The number of times to repeat the string (must be >= 0). + + +**Returns**: A new repeated string. + + +### replace(searchValue, replaceValue) function + +Return a new string where the first match (or all matches if 'searchValue' +is a global RegExp) of 'searchValue' is replaced by 'replaceValue'. +If 'searchValue' is a string, only the first occurrence is replaced. + + + +**searchValue**: A string or RegExp to match. + +**replaceValue**: The replacement string or function. + + +**Returns**: A new string with the matched substring(s) replaced. + + +### replaceAll(searchValue, replaceValue) function + +Return a new string where all (non-overlapping) occurrences of 'searchValue' +are replaced by 'replaceValue'. If 'searchValue' is a string, each exact match +is replaced. + + + +**searchValue**: A string or RegExp with the 'g' flag. + +**replaceValue**: The replacement string or function. + + +**Returns**: A new string with all matches replaced. + + +### padEnd(maxLength, padString) function + +Pad the string from the end with the given 'padString' so its length reaches +'maxLength'. The result is a new string. + + + +**maxLength**: The desired length of the resulting string. + +**padString**: The string to pad with (default ' '). + + +**Returns**: A new string padded at the end. + + +### padStart(maxLength, padString) function + +Pad the string from the start with the given 'padString' so its length reaches +'maxLength'. The result is a new string. + + + +**maxLength**: The desired length of the resulting string. + +**padString**: The string to pad with (default ' '). + + +**Returns**: A new string padded at the start. + + +### trim() function + +Return a new string with whitespace trimmed from the start and end of this +string. + + + +**Returns**: The trimmed string. + + +### trimEnd() function + +Alias for trimEnd(). Remove trailing whitespace from the string. + + + +**Returns**: The string without trailing whitespace. + + +### trimRight() function + +Alias for trimEnd(). Remove trailing whitespace from the string. + + + +**Returns**: The string without trailing whitespace. + + +### trimStart() function + +Alias for trimStart(). Remove leading whitespace from the string. + + + +**Returns**: The string without leading whitespace. + + +### trimLeft() function + +Alias for trimStart(). Remove leading whitespace from the string. + + + +**Returns**: The string without leading whitespace. + + +### toString() function + +Return a string representing the specified object (itself). Usually called +implicitly. Overrides Object.prototype.toString. + + + +**Returns**: The string itself. + + +### valueOf() function + +Return the primitive string value of this String object. + + + +**Returns**: The primitive string value. + + +### __quote() function + +(Non-standard) Return a quoted representation of the string, typically for +debug or serialization. Implementation details may vary. + + + +**Returns**: A quoted version of the string. + + +### localeCompare(compareString) function + +Return a number indicating whether this string is less than, equal to, or +greater than 'compareString' in sort order, according to the current locale. + + + +**compareString**: The string to compare against. + + +**Returns**: A negative number if less, 0 if the same, or a positive number if greater. + + +### toLowerCase() function + +Return a new string with all alphabetic characters converted to lowercase. + + + +**Returns**: The lowercase version of this string. + + +### toUpperCase() function + +Return a new string with all alphabetic characters converted to uppercase. + + + +**Returns**: The uppercase version of this string. + + +### toLocaleLowerCase() function + +Return a locale-aware lowercase version of this string, using the host's +current locale or the specified locale if supported. + + + +**Returns**: The locale-sensitive lowercase string. + + +### toLocaleUpperCase() function + +Return a locale-aware uppercase version of this string, using the host's +current locale or the specified locale if supported. + + + +**Returns**: The locale-sensitive uppercase string. + + +### anchor(name) function + +Return a string representing an HTML element with a 'name' attribute +set to the current string. + + + +**name**: The name attribute for the anchor. + + +**Returns**: An HTML ... string. + + +### big() function + +Return a string representing an HTML element containing the current +string. + + + +**Returns**: An HTML ... string. + + +### blink() function + +Return a string representing an HTML element containing the current +string (historical, not recommended). + + + +**Returns**: An HTML ... string. + + +### bold() function + +Return a string representing an HTML element containing the current +string in bold. + + + +**Returns**: An HTML ... string. + + +### fixed() function + +Return a string representing an HTML element containing the current +string in fixed-width font. + + + +**Returns**: An HTML ... string. + + +### fontcolor(color) function + +Return a string representing an HTML element with a 'color' attribute, +containing the current string. + + + +**color**: The color value for the 'font' element. + + +**Returns**: An HTML ... string. + + +### fontsize(size) function + +Return a string representing an HTML element with a 'size' attribute, +containing the current string. + + + +**size**: The size value for the 'font' element. + + +**Returns**: An HTML ... string. + + +### italics() function + +Return a string representing an HTML element containing the current +string in italics. + + + +**Returns**: An HTML ... string. + + +### link(url) function + +Return a string representing an HTML element with an 'href' attribute set +to the current string. + + + +**url**: The URL for the 'href' attribute. + + +**Returns**: An HTML ... string. + + +### small() function + +Return a string representing an HTML element containing the current +string. + + + +**Returns**: An HTML ... string. + + +### strike() function + +Return a string representing an HTML element containing the current +string with strike-through. + + + +**Returns**: An HTML ... string. + + +### sub() function + +Return a string representing an HTML element containing the current +string as subscript. + + + +**Returns**: An HTML ... string. + + +### sup() function + +Return a string representing an HTML element containing the current +string as superscript. + + + +**Returns**: An HTML ... string. + + +### rm(index, endidx) function + +Remove characters from this string between 'index' (inclusive) +and 'endidx' (exclusive). If 'endidx' is omitted, it defaults to 'index + 1'. + + + +**index**: The starting index to remove. + +**endidx**: The ending index (exclusive). + + +**Returns**: A new string with the specified characters removed. + + +### tolast(val) function + +Return the substring of this string up to the last occurrence of 'val'. +If 'val' is not found, the entire string is returned. + + + +**val**: The substring to locate from the end. + + +**Returns**: A substring up to the last occurrence of 'val'. + + +### dir() function + +Return everything before the last slash ('/') in the string. +If no slash is found, return an empty string. + + + +**Returns**: The directory portion of the path. + + +### next(char, from) function + +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. + + + +**char**: A character (or array of characters) to locate. + +**from**: The index to start from. + + +**Returns**: The index of the next occurrence, or -1 if not found. + + +### prev(char, from, count) function + +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. + + + +**char**: The character to locate. + +**from**: The index to start from (defaults to the end of the string). + +**count**: How many occurrences to skip backward (default 0). + + +**Returns**: The index of the previous occurrence, or 0 if not found. + + +### strip_ext() function + +Return the string up to (but not including) the last '.' character. +If '.' is not found, the entire string is returned. + + + +**Returns**: The string without its last extension. + + +### ext() function + +Return the substring after the last '.' in this string. +If '.' is not found, return an empty string. + + + +**Returns**: The file extension or an empty string. + + +### up_path() function + +Go up one directory level from the current path, preserving the file name at the end. + + + +**Returns**: A new path string one directory up, with the base filename preserved. + + +### fromlast(val) function + +Return the substring that appears after the last occurrence of 'val'. +If 'val' is not found, an empty string is returned. + + + +**val**: The substring to locate. + + +**Returns**: The substring after the last occurrence of 'val'. + + +### tofirst(val) function + +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. + + + +**val**: The substring to locate. + + +**Returns**: A substring up to the first occurrence of 'val'. + + +### fromfirst(val) function + +Return the substring after the first occurrence of 'val'. +If 'val' is not found, the entire string is returned. + + + +**val**: The substring to locate. + + +**Returns**: The substring after 'val', or the entire string if 'val' not found. + + +### name() function + +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 '.'. + + + +**Returns**: The name portion of the path without extension. + + +### set_name(name) function + +Set the base name (excluding extension) of the path to 'name', preserving +the original directory and extension. + + + +**name**: The new name to use. + + +**Returns**: A new path string with the updated name. + + +### base() function + +Return the portion of this string after the last '/' character. +If no '/' is present, the entire string is returned. + + + +**Returns**: The base name of the path. + + +### updir() function + +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. + + + +**Returns**: A new string representing one directory level up. + diff --git a/docs/dull/Symbol.md b/docs/dull/Symbol.md new file mode 100644 index 00000000..3d6393eb --- /dev/null +++ b/docs/dull/Symbol.md @@ -0,0 +1,9 @@ +# Symbol + +### toString() function + +### valueOf() function + +### description accessor + +(read only) diff --git a/docs/dull/WeakMap.md b/docs/dull/WeakMap.md new file mode 100644 index 00000000..2541a47d --- /dev/null +++ b/docs/dull/WeakMap.md @@ -0,0 +1,59 @@ +# WeakMap + +A WeakMap object is a collection of key/value pairs in which keys must be +objects. References to key objects in a WeakMap are held weakly, meaning +they do not prevent garbage collection if there are no other references +to the object. WeakMap keys are not iterable. + +### set(key, value) function + +Set the value for the specified key in the WeakMap. The key must be an object. + + + +**key**: The object key. + +**value**: The value associated with the key. + + +**Returns**: The WeakMap object (for chaining). + + +### get(key) function + +Return the value associated with 'key' in the WeakMap, or undefined if +no such key exists. The key must be an object. + + + +**key**: The object key. + + +**Returns**: The value associated with the key, or undefined if not present. + + +### has(key) function + +Return a boolean indicating whether an element with the specified key +exists in the WeakMap. The key must be an object. + + + +**key**: The object key to check. + + +**Returns**: True if the key is found, otherwise false. + + +### delete(key) function + +Remove the specified key and its associated value from the WeakMap, +if it exists. + + + +**key**: The object key to remove. + + +**Returns**: True if an element was removed, otherwise false. + diff --git a/docs/dull/WeakSet.md b/docs/dull/WeakSet.md new file mode 100644 index 00000000..88c6b239 --- /dev/null +++ b/docs/dull/WeakSet.md @@ -0,0 +1,43 @@ +# WeakSet + +A WeakSet object is a collection of unique objects (no primitive values). +References to objects in a WeakSet are held weakly, so they do not prevent +garbage collection if there are no other references to the object. WeakSet +elements are not iterable. + +### add(value) function + +Add a new object to the WeakSet if it is not already present. The value +must be an object. + + + +**value**: The object to add. + + +**Returns**: The WeakSet object (for chaining). + + +### has(value) function + +Return a boolean indicating whether an object is present in the WeakSet. + + + +**value**: The object to check. + + +**Returns**: True if the object is in the WeakSet, otherwise false. + + +### delete(value) function + +Remove the specified object from the WeakSet, if it exists. + + + +**value**: The object to remove. + + +**Returns**: True if the object was present and removed, otherwise false. + diff --git a/docs/dull/array.md b/docs/dull/array.md new file mode 100644 index 00000000..a7050d4c --- /dev/null +++ b/docs/dull/array.md @@ -0,0 +1,661 @@ +# Array + +### length number + +### at(index) function + +Return the item at index 'index', supporting negative indices to count from +the end. If 'index' is out of range, returns undefined. + + + +**index**: The index of the element to return (can be negative). + + +**Returns**: The element at the given index, or undefined. + + +### with(index, value) function + +Return a shallow copy of the array, but with the element at 'index' replaced +by 'value'. If 'index' is negative, it counts from the end. Throws if out of range. + + + +**index**: The zero-based index (can be negative) to replace. + +**value**: The new value for the specified position. + + +**Returns**: A new array with the updated element. + + +### concat(items) function + +Return a new array that is the result of concatenating this array with +any additional arrays or values provided. + + + +**items**: One or more arrays or values to concatenate. + + +**Returns**: A new array with the items appended. + + +### every(callback, thisArg) function + +Return true if the provided callback function returns a truthy value for +every element in the array; otherwise false. + + + +**callback**: A function(element, index, array) => boolean. + +**thisArg**: Optional. A value to use as 'this' within the callback. + + +**Returns**: True if all elements pass the test, otherwise false. + + +### some(callback, thisArg) function + +Return true if the provided callback function returns a truthy value for at +least one element in the array; otherwise false. + + + +**callback**: A function(element, index, array) => boolean. + +**thisArg**: Optional. A value to use as 'this' within the callback. + + +**Returns**: True if at least one element passes the test, otherwise false. + + +### forEach(callback, thisArg) function + +Call the provided callback function once for each element in the array. +Does not produce a return value. + + + +**callback**: A function(element, index, array). + +**thisArg**: Optional. A value to use as 'this' within the callback. + + +**Returns**: None + + +### map(callback, thisArg) function + +Create a new array with the results of calling a provided callback function +on every element in this array. + + + +**callback**: A function(element, index, array) => newElement. + +**thisArg**: Optional. A value to use as 'this' within the callback. + + +**Returns**: A new array of transformed elements. + + +### filter(callback, thisArg) function + +Create a new array containing all elements for which the provided callback +function returns a truthy value. + + + +**callback**: A function(element, index, array) => boolean. + +**thisArg**: Optional. A value to use as 'this' within the callback. + + +**Returns**: A new array of elements that passed the test. + + +### reduce(callback, initialValue) function + +Apply a callback function against an accumulator and each element in the +array (from left to right) to reduce it to a single value. + + + +**callback**: A function(accumulator, element, index, array) => newAccumulator. + +**initialValue**: Optional. The initial value for the accumulator. + + +**Returns**: The single resulting value. + + +### reduceRight(callback, initialValue) function + +Similar to reduce(), except it processes elements from right to left. + + + +**callback**: A function(accumulator, element, index, array) => newAccumulator. + +**initialValue**: Optional. The initial value for the accumulator. + + +**Returns**: The single resulting value. + + +### fill(value, start, end) function + +Fill the array with a static value from 'start' index up to (but not including) +'end' index. Modifies the original array. + + + +**value**: The value to fill. + +**start**: The starting index (default 0). + +**end**: The ending index (default array.length). + + +**Returns**: The modified array (with filled values). + + +### find(callback, thisArg) function + +Return the first element in the array that satisfies the provided callback +function. If none is found, return undefined. + + + +**callback**: A function(element, index, array) => boolean. + +**thisArg**: Optional. A value to use as 'this' within the callback. + + +**Returns**: The first matching element, or undefined if not found. + + +### findIndex(callback, thisArg) function + +Return the index of the first element in the array that satisfies the +provided callback function. If none is found, return -1. + + + +**callback**: A function(element, index, array) => boolean. + +**thisArg**: Optional. A value to use as 'this' within the callback. + + +**Returns**: The index of the first matching element, or -1 if not found. + + +### findLast(callback, thisArg) function + +Return the last element in the array that satisfies the provided callback +function, searching from right to left. If none is found, return undefined. + + + +**callback**: A function(element, index, array) => boolean. + +**thisArg**: Optional. A value to use as 'this' within the callback. + + +**Returns**: The last matching element, or undefined if not found. + + +### findLastIndex(callback, thisArg) function + +Return the index of the last element in the array that satisfies the +provided callback function, searching from right to left. If none is found, +return -1. + + + +**callback**: A function(element, index, array) => boolean. + +**thisArg**: Optional. A value to use as 'this' within the callback. + + +**Returns**: The index of the last matching element, or -1 if not found. + + +### indexOf(searchElement, fromIndex) function + +Return the first index at which a given element can be found. If not present, +return -1. + + + +**searchElement**: The item to locate in the array. + +**fromIndex**: The index at which to start searching (default 0). + + +**Returns**: The index of the found element, or -1 if not found. + + +### lastIndexOf(searchElement, fromIndex) function + +Return the last index at which a given element can be found, or -1 if not +present. Searches backward from 'fromIndex'. + + + +**searchElement**: The item to locate in the array. + +**fromIndex**: The index at which to start searching backward (default array.length - 1). + + +**Returns**: The last index of the found element, or -1 if not found. + + +### includes(searchElement, fromIndex) function + +Return a boolean indicating whether the array contains the given element, +comparing elements using the SameValueZero algorithm. + + + +**searchElement**: The value to search for. + +**fromIndex**: The position in the array to start searching (default 0). + + +**Returns**: True if the element is found, otherwise false. + + +### join(separator) function + +Join all elements of the array into a string, separated by 'separator'. + + + +**separator**: The delimiter string to separate elements (default ','). + + +**Returns**: A string of array elements joined by the separator. + + +### toString() function + +Return a string representing the elements of the array, separated by commas. +Overrides Object.prototype.toString. + + + +**Returns**: A comma-separated string of array elements. + + +### toLocaleString() function + +Return a localized string representing the array and its elements, calling +each element's toLocaleString if available. + + + +**Returns**: A locale-sensitive, comma-separated string of array elements. + + +### pop() function + +Remove the last element from the array and return it. This changes the length +of the array. + + + +**Returns**: The removed element, or undefined if the array is empty. + + +### push(items) function + +Append one or more elements to the end of the array and return the new length +of the array. + + + +**items**: One or more items to append. + + +**Returns**: The new length of the array. + + +### shift() function + +Remove the first element from the array and return it. This changes the length +of the array. + + + +**Returns**: The removed element, or undefined if the array is empty. + + +### unshift(items) function + +Insert one or more elements at the start of the array and return the new +length of the array. + + + +**items**: One or more elements to insert at the start. + + +**Returns**: The new length of the array. + + +### reverse() function + +Reverse the elements of the array in place and return the modified array. + + + +**Returns**: The reversed array. + + +### toReversed() function + +Return a shallow copy of the array in reverse order, without modifying the original array. + + + +**Returns**: A new reversed array. + + +### sort(compareFunction) function + +Sort the array in place, returning it. By default, sorts elements as strings in ascending order. An optional compareFunction may be used for custom sorting. + + + +**compareFunction**: A function(a, b) => number, defining sort order. + + +**Returns**: The sorted array. + + +### toSorted(compareFunction) function + +Return a shallow copy of the array, sorted according to the optional compare +function, without modifying the original array. + + + +**compareFunction**: A function(a, b) => number, defining sort order. + + +**Returns**: A new sorted array. + + +### slice(start, end) function + +Return a shallow copy of a portion of the array into a new array object, selected from 'start' to 'end' (end not included). + + + +**start**: The beginning index (0-based). Negative values count from the end. + +**end**: The end index (exclusive). Negative values count from the end. + + +**Returns**: A new array containing the extracted elements. + + +### splice(start, deleteCount, items) function + +Change the contents of the array by removing or replacing existing elements and/or adding new elements in place. Returns an array of removed elements. + + + +**start**: The index at which to start changing the array. + +**deleteCount**: Number of elements to remove. + +**items**: Elements to add in place of the removed elements. + + +**Returns**: An array containing the removed elements (if any). + + +### toSpliced(start, deleteCount, items) function + +Return a shallow copy of the array, with a splice-like operation applied at 'start' removing 'deleteCount' elements and adding 'items'. Does not mutate the original array. + + + +**start**: The index at which to start the splice operation. + +**deleteCount**: Number of elements to remove. + +**items**: Elements to add in place of the removed elements. + + +**Returns**: A new array with the splice applied. + + +### copyWithin(target, start, end) function + +Copy a sequence of array elements within the array, overwriting existing values. This operation is performed in place and returns the modified array. + + + +**target**: The index at which to copy the sequence to. + +**start**: The beginning index of the sequence to copy. + +**end**: The end index (exclusive) of the sequence to copy (default array.length). + + +**Returns**: The modified array. + + +### flatMap(callback, thisArg) function + +Return a new array formed by applying a callback function to each element and then flattening the result by one level. + + + +**callback**: A function(element, index, array) => array or value. + +**thisArg**: Optional. A value to use as 'this' within the callback. + + +**Returns**: A new array with the flattened results. + + +### flat(depth) function + +Return a new array with all sub-array elements concatenated into it recursively up to the specified depth. + + + +**depth**: The maximum depth to flatten (default 1). + + +**Returns**: A new flattened array. + + +### values() function + +Return a new Array Iterator object that contains the values for each index in the array. + + + +**Returns**: An iterator over the array's elements. + + +### keys() function + +Return a new Array Iterator object that contains the keys (indexes) for each index in the array. + + + +**Returns**: An iterator over the array's indices. + + +### entries() function + +Return a new Array Iterator object that contains key/value pairs for each index in the array. Each entry is [index, value]. + + + +**Returns**: An iterator over [index, value] pairs. + + +### add(other) function + +Non-standard. Add corresponding elements of the current array and 'other' element-wise, returning a new array. Behavior depends on data types. + + + +**other**: Another array or scalar to add to each element. + + +**Returns**: A new array with element-wise sum results. + + +### sub(other) function + +Non-standard. Subtract corresponding elements of 'other' from the current array element-wise, returning a new array. Behavior depends on data types. + + + +**other**: Another array or scalar to subtract from each element. + + +**Returns**: A new array with element-wise difference results. + + +### div(other) function + +Non-standard. Divide each element of the current array by the corresponding element of 'other' (or a scalar) element-wise, returning a new array. Behavior depends on data types. + + + +**other**: Another array or scalar for the division. + + +**Returns**: A new array with element-wise division results. + + +### scale() function + +### lerp() function + +### x accessor + +### y accessor + +### xy accessor + +### r accessor + +### g accessor + +### b accessor + +### a accessor + +### rgb accessor + +### rgba accessor + +### filter!(fn) function + +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. + + + +**fn**: A callback function(element, index, array) => boolean. + + +**Returns**: The filtered (modified) array. + + +### delete(item) function + +Remove the first occurrence of 'item' from the array, if it exists. +Returns undefined. + + + +**item**: The item to remove. + + +**Returns**: undefined + + +### copy() function + +Return a deep copy of this array by applying 'deep_copy' to each element. +The resulting array is entirely new. + + + +**Returns**: A new array that is a deep copy of the original. + + +### equal(b) function + +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. + + + +**b**: Another array to compare against. + + +**Returns**: True if they match, false otherwise. + + +### last() function + +Return the last element of this array. If the array is empty, returns undefined. + + + +**Returns**: The last element of the array, or undefined if empty. + + +### wrapped(x) function + +Return a copy of the array with the first 'x' elements appended to the end. +Does not modify the original array. + + + +**x**: The number of leading elements to re-append. + + +**Returns**: A new array with the leading elements wrapped to the end. + + +### wrap_idx(x) function + +Wrap the integer 'x' around this array's length, ensuring the resulting index +lies within [0, this.length - 1]. + + + +**x**: The index to wrap. + + +**Returns**: A wrapped index within this array's bounds. + + +### mirrored(x) function + +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. + + + +**Returns**: A new "mirrored" array. + diff --git a/docs/dull.png b/docs/dull/dull.png similarity index 100% rename from docs/dull.png rename to docs/dull/dull.png diff --git a/docs/dull/globals/Array.md b/docs/dull/globals/Array.md new file mode 100644 index 00000000..efd6335c --- /dev/null +++ b/docs/dull/globals/Array.md @@ -0,0 +1,47 @@ +# Array + +### length number + +### name string + +### prototype object + +### isArray(value) function + +Determine if the given value is an Array. Returns true if the argument is an array, otherwise false. + + + +**value**: The value to be checked. + + +**Returns**: True if 'value' is an array, otherwise false. + + +### from(arrayLike, mapFn, thisArg) function + +Create a new array from an array-like or iterable object. An optional map function can be invoked on each element before it is added to the new array. + + + +**arrayLike**: An array-like or iterable object to convert. + +**mapFn**: Optional. A function to call on every element of the new array. + +**thisArg**: Optional. A value to use as 'this' within the map function. + + +**Returns**: A new array populated with elements processed from arrayLike. + + +### of(elements) function + +Create a new array with a variable number of arguments, regardless of the number or type of the arguments. Unlike the Array constructor, there is no special treatment for a single numeric argument. + + + +**elements**: A variable number of arguments which become array elements. + + +**Returns**: A new array containing the provided arguments. + diff --git a/docs/dull/globals/Error.md b/docs/dull/globals/Error.md new file mode 100644 index 00000000..c8764757 --- /dev/null +++ b/docs/dull/globals/Error.md @@ -0,0 +1,7 @@ +# Error + +### length number + +### name string + +### prototype object diff --git a/docs/dull/globals/Function.md b/docs/dull/globals/Function.md new file mode 100644 index 00000000..f6d9f62a --- /dev/null +++ b/docs/dull/globals/Function.md @@ -0,0 +1,7 @@ +# Function + +### length number + +### name string + +### prototype() function diff --git a/docs/dull/globals/Math.md b/docs/dull/globals/Math.md new file mode 100644 index 00000000..362ca5d8 --- /dev/null +++ b/docs/dull/globals/Math.md @@ -0,0 +1,458 @@ +# Math + +### min(values) function + +Return the smallest of the zero or more given numbers. If no arguments are provided, the result is Infinity. If any value is NaN, the result is NaN. + + + +**values**: One or more numeric values. + + +**Returns**: The smallest numeric value, Infinity if no arguments, or NaN if any argument cannot be converted to a number. + + +### max(values) function + +Return the largest of the zero or more given numbers. If no arguments are provided, the result is -Infinity. If any value is NaN, the result is NaN. + + + +**values**: One or more numeric values. + + +**Returns**: The largest numeric value, -Infinity if no arguments, or NaN if any argument cannot be converted to a number. + + +### abs(x) function + +Return the absolute value of the given number. For example, -5 becomes 5. + + + +**x**: A numeric value. + + +**Returns**: The absolute value of x. + + +### floor(x) function + +Return the greatest integer less than or equal to x, effectively rounding down to the nearest integer. + + + +**x**: A numeric value. + + +**Returns**: The largest integer <= x. + + +### ceil(x) function + +Return the smallest integer greater than or equal to x, effectively rounding up to the nearest integer. + + + +**x**: A numeric value. + + +**Returns**: The smallest integer >= x. + + +### round(x) function + +Return x rounded to the nearest integer. If the fractional portion is 0.5 or +greater, rounds up; otherwise, rounds down. Ties away from zero in modern ECMAScript. + + + +**x**: A numeric value. + + +**Returns**: x rounded to the nearest integer. + + +### sqrt(x) function + +Return the positive square root of x. If x is negative, the result is NaN. + + + +**x**: A non-negative numeric value. + + +**Returns**: The positive square root of x, or NaN if x is negative. + + +### acos(x) function + +Return the arccosine (in radians) of x, in the range [0, π]. If x is outside +the range [-1, 1], the result is NaN. + + + +**x**: A numeric value in [-1, 1]. + + +**Returns**: The arccosine of x in radians, or NaN if out of range. + + +### asin(x) function + +Return the arcsine (in radians) of x, in the range [-π/2, π/2]. If x is +outside [-1, 1], the result is NaN. + + + +**x**: A numeric value in [-1, 1]. + + +**Returns**: The arcsine of x in radians, or NaN if out of range. + + +### atan(x) function + +Return the arctangent (in radians) of x, in the range [-π/2, π/2]. + + + +**x**: A numeric value. + + +**Returns**: The arctangent of x in radians. + + +### atan2(y, x) function + +Return the arctangent of the quotient of its arguments (y / x), in the range +(-π, π]. This takes into account the signs of both x and y to determine +the correct quadrant. + + + +**y**: The y coordinate. + +**x**: The x coordinate. + + +**Returns**: The angle in radians between the positive x-axis and the point (x, y). + + +### cos(x) function + +Return the cosine of x, where x is in radians. + + + +**x**: A numeric value in radians. + + +**Returns**: The cosine of x, in the range [-1, 1]. + + +### exp(x) function + +Return e^x, where e is Euler's number (approximately 2.71828). + + + +**x**: A numeric exponent. + + +**Returns**: The value of e raised to x. + + +### log(x) function + +Return the natural logarithm (base e) of x. If x is <= 0, the result is NaN. + + + +**x**: A positive numeric value. + + +**Returns**: The natural logarithm of x. + + +### pow(base, exponent) function + +Return base raised to the power exponent, i.e. base^exponent. If base is +negative and exponent is not an integer, result is NaN. + + + +**base**: The base number. + +**exponent**: The exponent number. + + +**Returns**: base raised to exponent. + + +### sin(x) function + +Return the sine of x, where x is in radians. + + + +**x**: A numeric value in radians. + + +**Returns**: The sine of x, in the range [-1, 1]. + + +### tan(x) function + +Return the tangent of x, where x is in radians. If x is (π/2 + nπ), the +result is ±Infinity or NaN. + + + +**x**: A numeric value in radians. + + +**Returns**: The tangent of x. + + +### trunc(x) function + +Return the integer part of x by removing any fractional digits. Does not +round, just truncates. + + + +**x**: A numeric value. + + +**Returns**: x truncated toward zero. + + +### sign(x) function + +Return the sign of x, indicating whether x is positive, negative, or zero. +Returns 1 if x > 0, -1 if x < 0, 0 if x is 0, and NaN if x is NaN. + + + +**x**: A numeric value. + + +**Returns**: 1, -1, 0, -0, or NaN, depending on x. + + +### cosh(x) function + +Return the hyperbolic cosine of x, (e^x + e^-x) / 2. + + + +**x**: A numeric value. + + +**Returns**: The hyperbolic cosine of x. + + +### sinh(x) function + +Return the hyperbolic sine of x, (e^x - e^-x) / 2. + + + +**x**: A numeric value. + + +**Returns**: The hyperbolic sine of x. + + +### tanh(x) function + +Return the hyperbolic tangent of x, (e^x - e^-x) / (e^x + e^-x). + + + +**x**: A numeric value. + + +**Returns**: The hyperbolic tangent of x. + + +### acosh(x) function + +Return the inverse hyperbolic cosine of x, defined as ln(x + sqrt(x^2 - 1)). +If x < 1, the result is NaN. + + + +**x**: A numeric value >= 1. + + +**Returns**: The inverse hyperbolic cosine of x. + + +### asinh(x) function + +Return the inverse hyperbolic sine of x, defined as ln(x + sqrt(x^2 + 1)). + + + +**x**: A numeric value. + + +**Returns**: The inverse hyperbolic sine of x. + + +### atanh(x) function + +Return the inverse hyperbolic tangent of x, defined as 1/2 * ln((1 + x) / (1 - x)). +If |x| >= 1, the result is NaN. + + + +**x**: A numeric value in the range (-1, 1). + + +**Returns**: The inverse hyperbolic tangent of x. + + +### expm1(x) function + +Return e^x - 1, for small values of x this provides higher precision than +Math.exp(x) - 1. + + + +**x**: A numeric exponent. + + +**Returns**: e^x - 1. + + +### log1p(x) function + +Return the natural logarithm of (1 + x). More accurate than Math.log(1 + x) +for small x. + + + +**x**: A numeric value > -1. + + +**Returns**: ln(1 + x). + + +### log2(x) function + +Return the base-2 logarithm of x. If x <= 0, the result is NaN. + + + +**x**: A positive numeric value. + + +**Returns**: The base-2 logarithm of x. + + +### log10(x) function + +Return the base-10 logarithm of x. If x <= 0, the result is NaN. + + + +**x**: A positive numeric value. + + +**Returns**: The base-10 logarithm of x. + + +### cbrt(x) function + +Return the cube root of x, including negative values. + + + +**x**: A numeric value (can be negative). + + +**Returns**: The cube root of x. + + +### hypot(values) function + +Return the square root of the sum of squares of its arguments, i.e. +sqrt(x1^2 + x2^2 + ...). If any value is ±Infinity, returns Infinity. If +any value is NaN, returns NaN. + + + +**values**: One or more numeric values. + + +**Returns**: The square root of the sum of squares of the arguments. + + +### random() function + +Return a pseudo-random floating-point number in the range [0, 1). +The result is usually seeded by an engine-defined source of randomness. + + + +**Returns**: A number >= 0 and < 1. + + +### fround(x) function + +Return the nearest 32-bit single-precision float representation of x. + + + +**x**: A numeric value. + + +**Returns**: The 32-bit float representation of x. + + +### imul(a, b) function + +Return the result of a 32-bit integer multiplication of two values. +Effectively (a * b) | 0 in many implementations. + + + +**a**: A numeric value. + +**b**: A numeric value. + + +**Returns**: The 32-bit integer result of multiplying a by b. + + +### clz32(x) function + +Return the number of leading zero bits in the 32-bit binary representation +of x. If x is 0, returns 32. + + + +**x**: A numeric value, treated as a 32-bit unsigned integer. + + +**Returns**: The count of leading zero bits, in the range [0, 32]. + + +### E number + +### LN10 number + +### LN2 number + +### LOG2E number + +### LOG10E number + +### PI number + +### SQRT1_2 number + +### SQRT2 number diff --git a/docs/dull/globals/Number.md b/docs/dull/globals/Number.md new file mode 100644 index 00000000..481f2663 --- /dev/null +++ b/docs/dull/globals/Number.md @@ -0,0 +1,99 @@ +# Number + +### length number + +### name string + +### prototype object + +### parseInt(string, radix) function + +Parse a string argument and return an integer of the specified radix (base). +If the string does not start with a valid integer, return NaN. Leading +whitespace is ignored. + + + +**string**: The string to parse as an integer. + +**radix**: An integer between 2 and 36 indicating the base of the number in the string. + + +**Returns**: The parsed integer, or NaN if the input is not a valid integer. + + +### parseFloat(string) function + +Parse a string argument and return a floating-point number. If the string does not represent a valid number, return NaN. Leading whitespace is ignored, and the string can include a decimal point or exponent. + + + +**string**: The string to parse as a floating-point number. + + +**Returns**: The parsed number, or NaN if invalid. + + +### isNaN(value) function + +Determine if a value is the special numeric value NaN, without converting the argument. Unlike the global isNaN(), this returns false for non-numeric values. + + + +**value**: The value to test. + + +**Returns**: True if the value is NaN, otherwise false. + + +### isFinite(value) function + +Determine if a value is a finite number. Unlike the global isFinite(), this returns false for non-numeric values without attempting to convert them. + + + +**value**: The value to test. + + +**Returns**: True if the value is a finite number, otherwise false. + + +### isInteger(value) function + +Check if the given value is a finite number and also an integer (no fractional part). Returns false for non-numeric values or NaN. + + + +**value**: The value to test. + + +**Returns**: True if value is an integer, otherwise false. + + +### isSafeInteger(value) function + +Check if the given value is a safe integer. A safe integer is one that can be exactly represented as an IEEE-754 double-precision number (i.e., between -9007199254740991 and 9007199254740991 inclusive). + + + +**value**: The value to test. + + +**Returns**: True if value is an integer within the safe range, otherwise false. + + +### MAX_VALUE number + +### MIN_VALUE number + +### NaN number + +### NEGATIVE_INFINITY number + +### POSITIVE_INFINITY number + +### EPSILON number + +### MAX_SAFE_INTEGER number + +### MIN_SAFE_INTEGER number diff --git a/docs/dull/globals/Object.md b/docs/dull/globals/Object.md new file mode 100644 index 00000000..16f49aaa --- /dev/null +++ b/docs/dull/globals/Object.md @@ -0,0 +1,331 @@ +# Object + +### length number + +### name string + +### prototype object + +### create(proto, propertiesObject) function + +Create a new object, using the specified prototype object and optional property descriptors. + + + +**proto**: The object to be used as the prototype. + +**propertiesObject**: Optional. An object specifying properties to be added. + + +**Returns**: A new object with the given prototype and properties. + + +### getPrototypeOf(obj) function + +Return the prototype of the specified object. If no prototype is found (e.g. the object has null as its prototype), return null. + + + +**obj**: The object whose prototype is to be returned. + + +**Returns**: The prototype of 'obj', or null. + + +### setPrototypeOf(obj, proto) function + +Set the prototype of the specified object to the provided value. Throws a TypeError if the object is non-extensible and the prototype is changed. + + + +**obj**: The object whose prototype is set. + +**proto**: The new prototype or null. + + +**Returns**: The object 'obj' after setting its prototype. + + +### defineProperty(obj, prop, descriptor) function + +Define or modify a property on an object using a property descriptor, returning the object. Throws a TypeError if the descriptor is invalid. + + + +**obj**: The object on which to define or modify a property. + +**prop**: The name or Symbol of the property. + +**descriptor**: A property descriptor object (e.g., {value, writable, get, set, ...}). + + +**Returns**: The object with the newly defined or updated property. + + +### defineProperties(obj, props) function + +Define new or modify existing properties on an object, given an object of property descriptors. Returns the modified object. + + + +**obj**: The object on which to define or modify properties. + +**props**: An object mapping property names to property descriptors. + + +**Returns**: The modified object. + + +### getOwnPropertyNames(obj) function + +Return an array of all own (non-Symbol) property names found directly on the given object, in the same order as a for...in loop would return. + + + +**obj**: The object whose own property names are returned. + + +**Returns**: An array of strings that correspond to the properties. + + +### getOwnPropertySymbols(obj) function + +Return an array of all own Symbol properties found directly on the given object. + + + +**obj**: The object to retrieve Symbol keys from. + + +**Returns**: An array of Symbol keys. + + +### groupBy(obj, fn) function + +Non-standard / Proposed. Group the own properties of an object according to the return value of a grouping function. Typically returns a new object whose keys are the group identifiers. + + + +**obj**: The object to group. + +**fn**: A function(key, value) => groupingKey, applied to each property. + + +**Returns**: An object where properties are grouped by the returned keys. + + +### keys(obj) function + +Return an array of the object's own enumerable (non-Symbol) property names, in the same order that a normal loop would. + + + +**obj**: The object whose property names are to be returned. + + +**Returns**: An array of property names. + + +### values(obj) function + +Return an array of the object's own enumerable (non-Symbol) property values, in the same order as Object.keys(). + + + +**obj**: The object whose property values are to be returned. + + +**Returns**: An array of property values. + + +### entries(obj) function + +Return an array of [key, value] pairs for the object's own enumerable (non-Symbol) properties, in the same order as Object.keys(). + + + +**obj**: The object whose [key, value] pairs are to be returned. + + +**Returns**: An array of [key, value] pairs. + + +### isExtensible(obj) function + +Return a boolean indicating whether new properties can be added to the specified object. + + + +**obj**: The object to test. + + +**Returns**: True if the object is extensible, otherwise false. + + +### preventExtensions(obj) function + +Prevent new properties from ever being added to an object. Existing properties are not affected. + + + +**obj**: The object to mark as non-extensible. + + +**Returns**: The non-extensible object. + + +### getOwnPropertyDescriptor(obj, prop) function + +Return the property descriptor for a named property on the specified object, if it exists, otherwise undefined. + + + +**obj**: The object in which to look for the property. + +**prop**: The name or Symbol of the property. + + +**Returns**: The property descriptor, or undefined if not found. + + +### getOwnPropertyDescriptors(obj) function + +Return an object containing all own property descriptors for the given object, keyed by property names (and Symbols). + + + +**obj**: The object to retrieve property descriptors from. + + +**Returns**: An object mapping property keys to property descriptors. + + +### is(value1, value2) function + +Compare two values for strict equality, like '===' but without special treatment for +0 and -0, and treating NaN as equal to NaN. + + + +**value1**: A value to compare. + +**value2**: Another value to compare. + + +**Returns**: True if both values are the same, otherwise false. + + +### assign(target, sources) function + +Copy all enumerable own properties from one or more source objects to a target object, returning the modified target. + + + +**target**: The object to receive properties. + +**sources**: One or more objects containing properties to copy. + + +**Returns**: The updated target object. + + +### seal(obj) function + +Seal an object, preventing new properties from being added and marking all existing properties as non-configurable. Values of present properties can still be changed if they are writable. + + + +**obj**: The object to seal. + + +**Returns**: The sealed object. + + +### freeze(obj) function + +Freeze an object, preventing new properties from being added, existing properties from being removed, or current properties from being changed (to the extent permitted by property descriptors). + + + +**obj**: The object to freeze. + + +**Returns**: The frozen object. + + +### isSealed(obj) function + +Check if an object is sealed. A sealed object has no configurable properties and is non-extensible. + + + +**obj**: The object to test. + + +**Returns**: True if the object is sealed, otherwise false. + + +### isFrozen(obj) function + +Check if an object is frozen. A frozen object is sealed and all data properties are non-writable. + + + +**obj**: The object to test. + + +**Returns**: True if the object is frozen, otherwise false. + + +### __getClass() function + +### fromEntries(entries) function + +Transform a list of key-value pairs into an object. The iterable argument should yield pairs [key, value], which become properties on the resulting object. + + + +**entries**: An iterable of [key, value] pairs. + + +**Returns**: A new object formed from the given entries. + + +### hasOwn(obj, prop) function + +Return a boolean indicating whether the specified property exists on the object as a direct own property (similar to hasOwnProperty, but directly on Object). + + + +**obj**: The object on which to check the property. + +**prop**: The name or Symbol of the property to check. + + +**Returns**: True if the property is found on 'obj', otherwise false. + + +### id(obj) function + +Non-standard. Return a unique identifier for the given object, assigning one if necessary. The same object will always yield the same ID. + + + +**obj**: The object to retrieve or assign a unique ID. + + +**Returns**: A unique identifier (string or number) associated with the object. + + +### mixin(target, source) function + +Copy all property descriptors from 'source' into 'target'. + + + +**target**: The object that will receive properties. + +**source**: The object whose properties are to be copied. + + +**Returns**: The updated 'target' object. + diff --git a/docs/dull/globals/String.md b/docs/dull/globals/String.md new file mode 100644 index 00000000..c87e18d5 --- /dev/null +++ b/docs/dull/globals/String.md @@ -0,0 +1,49 @@ +# String + +### length number + +### name string + +### prototype object + +### fromCharCode(codeUnits) function + +Return a string created from the specified sequence of UTF-16 code units. +Each argument is treated as a code unit in the range [0, 65535]. + + + +**codeUnits**: A series of numbers representing UTF-16 code units. + + +**Returns**: A string constructed by mapping each code unit to a character. + + +### fromCodePoint(codePoints) function + +Return a string created from the specified sequence of code points, +including those above U+FFFF (which will become surrogate pairs). +Throws a RangeError for invalid code points. + + + +**codePoints**: A series of numbers representing Unicode code points. + + +**Returns**: A string constructed from the given code points. + + +### raw(template, substitutions) function + +A tag function of template literals that returns a raw where escape sequences (e.g., '\n', '\u00A9') are not processed. +Commonly used to retrieve the unprocessed text of a template. + + + +**template**: A template literal, or an object with a 'raw' property. + +**substitutions**: Additional values to substitute (if any). + + +**Returns**: The combined raw string from the template. + diff --git a/docs/dull/globals/Symbol.md b/docs/dull/globals/Symbol.md new file mode 100644 index 00000000..097d76e3 --- /dev/null +++ b/docs/dull/globals/Symbol.md @@ -0,0 +1,59 @@ +# Symbol + +### length number + +### name string + +### prototype object + +### for(key) function + +Search the global symbol registry for a symbol with the given key. If found, return that symbol; otherwise, create a new symbol with that key and add it to the registry, then return the new symbol. + + + +**key**: A string key used to identify the symbol in the global registry. + + +**Returns**: A symbol associated with the given key in the global registry. + + +### keyFor(sym) function + +Retrieve a shared symbol’s key from the global symbol registry. If the symbol is not in the global registry, return undefined. + + + +**sym**: The symbol to find the key for. + + +**Returns**: The string key if 'sym' is a global symbol, otherwise undefined. + + +### toPrimitive symbol + +### iterator symbol + +### match symbol + +### matchAll symbol + +### replace symbol + +### search symbol + +### split symbol + +### toStringTag symbol + +### isConcatSpreadable symbol + +### hasInstance symbol + +### species symbol + +### unscopables symbol + +### asyncIterator symbol + +### operatorSet symbol diff --git a/docs/dull.md b/docs/dull/index.md similarity index 100% rename from docs/dull.md rename to docs/dull/index.md diff --git a/scripts/core/base.js b/scripts/core/base.js index c282ff0e..8a9a69a3 100644 --- a/scripts/core/base.js +++ b/scripts/core/base.js @@ -4,14 +4,27 @@ Object.mixin = function (target, source) { return target; }; +Object.mixin[prosperon.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)[prosperon.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) { @@ -19,6 +32,14 @@ Object.defineProperty(String.prototype, "rm", { }, }); +(String.prototype.rm)[prosperon.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); @@ -27,6 +48,13 @@ Object.defineProperty(String.prototype, "tolast", { }, }); +(String.prototype.tolast)[prosperon.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 ""; @@ -34,6 +62,12 @@ Object.defineProperty(String.prototype, "dir", { }, }); +(String.prototype.dir)[prosperon.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]; @@ -41,7 +75,6 @@ Object.defineProperty(String.prototype, "next", { else if (!from) from = 0; var find = this.slice(from).search(char[0]); - if (find === -1) return -1; else return from + find; @@ -52,11 +85,19 @@ Object.defineProperty(String.prototype, "next", { if (from + i > this.length - 1) return -1; c = this.charAt(from + i); } - return from + i; }, }); +(String.prototype.next)[prosperon.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; @@ -74,18 +115,40 @@ Object.defineProperty(String.prototype, "prev", { }, }); +(String.prototype.prev)[prosperon.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)[prosperon.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)[prosperon.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(); @@ -95,6 +158,11 @@ Object.defineProperty(String.prototype, "up_path", { }, }); +(String.prototype.up_path)[prosperon.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); @@ -103,6 +171,13 @@ Object.defineProperty(String.prototype, "fromlast", { }, }); +(String.prototype.fromlast)[prosperon.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); @@ -111,6 +186,13 @@ Object.defineProperty(String.prototype, "tofirst", { }, }); +(String.prototype.tofirst)[prosperon.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); @@ -119,6 +201,13 @@ Object.defineProperty(String.prototype, "fromfirst", { }, }); +(String.prototype.fromfirst)[prosperon.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("/"); @@ -127,6 +216,13 @@ Object.defineProperty(String.prototype, "name", { }, }); +(String.prototype.name)[prosperon.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(); @@ -134,21 +230,39 @@ Object.defineProperty(String.prototype, "set_name", { }, }); +(String.prototype.set_name)[prosperon.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)[prosperon.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)[prosperon.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) { @@ -162,73 +276,1458 @@ Object.defineProperty(Array.prototype, "filter!", { }, }); +(Array.prototype["filter!"])[prosperon.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 + if (idx > -1) this.splice(idx,1); + return undefined; } }); +(Array.prototype.delete)[prosperon.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)[prosperon.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) + 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)[prosperon.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)[prosperon.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)[prosperon.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)[prosperon.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)[prosperon.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. +`; + + + +/// doc for builtin string +(String.prototype.at)[prosperon.DOC] = `Return the character (or surrogate pair) at the specified index, with support +for negative indices (counting from the end). If the index is out of range, +returns undefined. + +:param index: The position of the character to return (can be negative). +:return: A string of length 1 representing the character, or undefined if out of range. +`; + +(String.prototype.charCodeAt)[prosperon.DOC] = `Return a number indicating the UTF-16 code unit value at the given index. +If the index is out of range, returns NaN. + +:param index: An integer between 0 and string length - 1. +:return: An integer in the range [0, 65535] or NaN if out of range. +`; + +(String.prototype.charAt)[prosperon.DOC] = `Return a string consisting of the single UTF-16 code unit at the given index. +If the index is out of range, returns an empty string. + +:param index: The zero-based index of the desired character. +:return: The single-character string at the specified index, or '' if out of range. +`; + +(String.prototype.concat)[prosperon.DOC] = `Concatenate the provided string arguments to the current string and return a +new string. + +:param stringN: One or more strings to concatenate. +:return: A new string formed by joining the caller with the provided arguments. +`; + +(String.prototype.codePointAt)[prosperon.DOC] = `Return a non-negative integer that is the Unicode code point value at the +given position. Supports code points above 0xFFFF. Returns undefined if index +is out of range. + +:param position: The index in the string (can be surrogate pairs). +:return: The code point value, or undefined if out of range. +`; + +(String.prototype.isWellFormed)[prosperon.DOC] = `Return a boolean indicating whether the string is valid Unicode. +If it contains unpaired surrogate code points, return false. + +:return: True if the string is well-formed UTF-16, otherwise false. +`; + +(String.prototype.toWellFormed)[prosperon.DOC] = `Return a new string in which any unpaired surrogate code points have been +replaced by the Unicode replacement character U+FFFD. + +:return: A well-formed UTF-16 version of the string. +`; + +(String.prototype.indexOf)[prosperon.DOC] = `Return the zero-based index of the first occurrence of 'searchValue' in the +string, starting at 'fromIndex'. If not found, return -1. + +:param searchValue: The substring to search for. +:param fromIndex: The index at which to begin searching (default 0). +:return: The index of the first match, or -1 if not found. +`; + +(String.prototype.lastIndexOf)[prosperon.DOC] = `Return the zero-based index of the last occurrence of 'searchValue' in the +string, searching backwards from 'fromIndex'. If not found, return -1. + +:param searchValue: The substring to search for. +:param fromIndex: The index at which to begin the backward search (defaults to string length - 1). +:return: The index of the last match, or -1 if not found. +`; + +(String.prototype.includes)[prosperon.DOC] = `Return a boolean indicating whether 'searchString' appears within this string. +An optional position can be provided to start searching. + +:param searchString: The substring to search for. +:param position: The position from which to begin searching (default 0). +:return: True if the substring is found, otherwise false. +`; + +(String.prototype.endsWith)[prosperon.DOC] = `Return a boolean indicating whether the string ends with 'searchString'. +An optional 'length' can be provided to treat the string as if it were only +that long. + +:param searchString: The substring to search for at the end. +:param length: An optional length to truncate the string before testing. +:return: True if the string ends with 'searchString', otherwise false. +`; + +(String.prototype.startsWith)[prosperon.DOC] = `Return a boolean indicating whether the string begins with 'searchString'. +An optional position can be provided to start checking at that index. + +:param searchString: The substring to search for at the start. +:param position: The index in the string to start searching (default 0). +:return: True if the string starts with 'searchString', otherwise false. +`; + +(String.prototype.match)[prosperon.DOC] = `Use a regular expression to match the string. If 'regexp' is not a RegExp, it +is converted to one. Return an array of matches or null if none found. + +:param regexp: The pattern to match (RegExp or string). +:return: An array of matches or null. +`; + +(String.prototype.matchAll)[prosperon.DOC] = `Return an iterator of all RegExp match objects found within the string. +If 'regexp' is not a global or sticky RegExp, a TypeError is thrown. + +:param regexp: The global/sticky RegExp to match over this string. +:return: An iterator of match arrays. +`; + +(String.prototype.search)[prosperon.DOC] = `Use a regular expression to search for a match within the string. Return the +index of the first match, or -1 if no match is found. + +:param regexp: A RegExp or string. If a string, it is converted to RegExp. +:return: The index of the first match, or -1 if not found. +`; + +(String.prototype.split)[prosperon.DOC] = `Split the string into an array of substrings using 'separator' (RegExp or +string). An optional 'limit' can be provided to limit the number of splits. + +:param separator: A string or RegExp used to divide the string. +:param limit: Maximum number of splits to include in the result array. +:return: An array of the split substrings. +`; + +(String.prototype.substring)[prosperon.DOC] = `Return the substring between 'start' and 'end'. Indices outside the range +are clamped. If 'end' < 'start', they swap. + +:param start: The starting index (0-based). +:param end: The ending index (exclusive). +:return: The extracted substring. +`; + +(String.prototype.substr)[prosperon.DOC] = `Return the substring from 'start' for 'length' characters. Negative 'start' +counts from the end. This method is deprecated but still supported in many +engines. + +:param start: The starting index. +:param length: The number of characters to extract. +:return: The extracted substring. +`; + +(String.prototype.slice)[prosperon.DOC] = `Extract a section of the string from 'start' up to (but not including) 'end', +and return it as a new string. Supports negative indices. + +:param start: The starting index. Negative values count from the end. +:param end: The ending index (exclusive). Negative values count from the end. +:return: The extracted slice. +`; + +(String.prototype.repeat)[prosperon.DOC] = `Construct and return a new string which contains the specified number of copies +of the calling string, concatenated together. + +:param count: The number of times to repeat the string (must be >= 0). +:return: A new repeated string. +`; + +(String.prototype.replace)[prosperon.DOC] = `Return a new string where the first match (or all matches if 'searchValue' +is a global RegExp) of 'searchValue' is replaced by 'replaceValue'. +If 'searchValue' is a string, only the first occurrence is replaced. + +:param searchValue: A string or RegExp to match. +:param replaceValue: The replacement string or function. +:return: A new string with the matched substring(s) replaced. +`; + +(String.prototype.replaceAll)[prosperon.DOC] = `Return a new string where all (non-overlapping) occurrences of 'searchValue' +are replaced by 'replaceValue'. If 'searchValue' is a string, each exact match +is replaced. + +:param searchValue: A string or RegExp with the 'g' flag. +:param replaceValue: The replacement string or function. +:return: A new string with all matches replaced. +`; + +(String.prototype.padEnd)[prosperon.DOC] = `Pad the string from the end with the given 'padString' so its length reaches +'maxLength'. The result is a new string. + +:param maxLength: The desired length of the resulting string. +:param padString: The string to pad with (default ' '). +:return: A new string padded at the end. +`; + +(String.prototype.padStart)[prosperon.DOC] = `Pad the string from the start with the given 'padString' so its length reaches +'maxLength'. The result is a new string. + +:param maxLength: The desired length of the resulting string. +:param padString: The string to pad with (default ' '). +:return: A new string padded at the start. +`; + +(String.prototype.trim)[prosperon.DOC] = `Return a new string with whitespace trimmed from the start and end of this +string. + +:return: The trimmed string. +`; + +(String.prototype.trimEnd)[prosperon.DOC] = `Return a new string with trailing whitespace removed. Alias: trimRight(). + +:return: The string without trailing whitespace. +`; + +(String.prototype.trimRight)[prosperon.DOC] = `Alias for trimEnd(). Remove trailing whitespace from the string. + +:return: The string without trailing whitespace. +`; + +(String.prototype.trimStart)[prosperon.DOC] = `Return a new string with leading whitespace removed. Alias: trimLeft(). + +:return: The string without leading whitespace. +`; + +(String.prototype.trimLeft)[prosperon.DOC] = `Alias for trimStart(). Remove leading whitespace from the string. + +:return: The string without leading whitespace. +`; + +(String.prototype.toString)[prosperon.DOC] = `Return a string representing the specified object (itself). Usually called +implicitly. Overrides Object.prototype.toString. + +:return: The string itself. +`; + +(String.prototype.valueOf)[prosperon.DOC] = `Return the primitive string value of this String object. + +:return: The primitive string value. +`; + +(String.prototype.__quote)[prosperon.DOC] = `(Non-standard) Return a quoted representation of the string, typically for +debug or serialization. Implementation details may vary. + +:return: A quoted version of the string. +`; + +(String.prototype.localeCompare)[prosperon.DOC] = `Return a number indicating whether this string is less than, equal to, or +greater than 'compareString' in sort order, according to the current locale. + +:param compareString: The string to compare against. +:return: A negative number if less, 0 if the same, or a positive number if greater. +`; + +(String.prototype.toLowerCase)[prosperon.DOC] = `Return a new string with all alphabetic characters converted to lowercase. + +:return: The lowercase version of this string. +`; + +(String.prototype.toUpperCase)[prosperon.DOC] = `Return a new string with all alphabetic characters converted to uppercase. + +:return: The uppercase version of this string. +`; + +(String.prototype.toLocaleLowerCase)[prosperon.DOC] = `Return a locale-aware lowercase version of this string, using the host's +current locale or the specified locale if supported. + +:return: The locale-sensitive lowercase string. +`; + +(String.prototype.toLocaleUpperCase)[prosperon.DOC] = `Return a locale-aware uppercase version of this string, using the host's +current locale or the specified locale if supported. + +:return: The locale-sensitive uppercase string. +`; + +(String.prototype.anchor)[prosperon.DOC] = `Return a string representing an HTML element with a 'name' attribute +set to the current string. + +:param name: The name attribute for the anchor. +:return: An HTML ... string. +`; + +(String.prototype.big)[prosperon.DOC] = `Return a string representing an HTML element containing the current +string. + +:return: An HTML ... string. +`; + +(String.prototype.blink)[prosperon.DOC] = `Return a string representing an HTML element containing the current +string (historical, not recommended). + +:return: An HTML ... string. +`; + +(String.prototype.bold)[prosperon.DOC] = `Return a string representing an HTML element containing the current +string in bold. + +:return: An HTML ... string. +`; + +(String.prototype.fixed)[prosperon.DOC] = `Return a string representing an HTML element containing the current +string in fixed-width font. + +:return: An HTML ... string. +`; + +(String.prototype.fontcolor)[prosperon.DOC] = `Return a string representing an HTML element with a 'color' attribute, +containing the current string. + +:param color: The color value for the 'font' element. +:return: An HTML ... string. +`; + +(String.prototype.fontsize)[prosperon.DOC] = `Return a string representing an HTML element with a 'size' attribute, +containing the current string. + +:param size: The size value for the 'font' element. +:return: An HTML ... string. +`; + +(String.prototype.italics)[prosperon.DOC] = `Return a string representing an HTML element containing the current +string in italics. + +:return: An HTML ... string. +`; + +(String.prototype.link)[prosperon.DOC] = `Return a string representing an HTML element with an 'href' attribute set +to the current string. + +:param url: The URL for the 'href' attribute. +:return: An HTML ... string. +`; + +(String.prototype.small)[prosperon.DOC] = `Return a string representing an HTML element containing the current +string. + +:return: An HTML ... string. +`; + +(String.prototype.strike)[prosperon.DOC] = `Return a string representing an HTML element containing the current +string with strike-through. + +:return: An HTML ... string. +`; + +(String.prototype.sub)[prosperon.DOC] = `Return a string representing an HTML element containing the current +string as subscript. + +:return: An HTML ... string. +`; + +(String.prototype.sup)[prosperon.DOC] = `Return a string representing an HTML element containing the current +string as superscript. + +:return: An HTML ... string. +`; + + +// builtin array +(Array.prototype.at)[prosperon.DOC] = `Return the item at index 'index', supporting negative indices to count from +the end. If 'index' is out of range, returns undefined. + +:param index: The index of the element to return (can be negative). +:return: The element at the given index, or undefined. +`; + +(Array.prototype.with)[prosperon.DOC] = `Return a shallow copy of the array, but with the element at 'index' replaced +by 'value'. If 'index' is negative, it counts from the end. Throws if out of range. + +:param index: The zero-based index (can be negative) to replace. +:param value: The new value for the specified position. +:return: A new array with the updated element. +`; + +(Array.prototype.concat)[prosperon.DOC] = `Return a new array that is the result of concatenating this array with +any additional arrays or values provided. + +:param items: One or more arrays or values to concatenate. +:return: A new array with the items appended. +`; + +(Array.prototype.every)[prosperon.DOC] = `Return true if the provided callback function returns a truthy value for +every element in the array; otherwise false. + +:param callback: A function(element, index, array) => boolean. +:param thisArg: Optional. A value to use as 'this' within the callback. +:return: True if all elements pass the test, otherwise false. +`; + +(Array.prototype.some)[prosperon.DOC] = `Return true if the provided callback function returns a truthy value for at +least one element in the array; otherwise false. + +:param callback: A function(element, index, array) => boolean. +:param thisArg: Optional. A value to use as 'this' within the callback. +:return: True if at least one element passes the test, otherwise false. +`; + +(Array.prototype.forEach)[prosperon.DOC] = `Call the provided callback function once for each element in the array. +Does not produce a return value. + +:param callback: A function(element, index, array). +:param thisArg: Optional. A value to use as 'this' within the callback. +:return: None +`; + +(Array.prototype.map)[prosperon.DOC] = `Create a new array with the results of calling a provided callback function +on every element in this array. + +:param callback: A function(element, index, array) => newElement. +:param thisArg: Optional. A value to use as 'this' within the callback. +:return: A new array of transformed elements. +`; + +(Array.prototype.filter)[prosperon.DOC] = `Create a new array containing all elements for which the provided callback +function returns a truthy value. + +:param callback: A function(element, index, array) => boolean. +:param thisArg: Optional. A value to use as 'this' within the callback. +:return: A new array of elements that passed the test. +`; + +(Array.prototype.reduce)[prosperon.DOC] = `Apply a callback function against an accumulator and each element in the +array (from left to right) to reduce it to a single value. + +:param callback: A function(accumulator, element, index, array) => newAccumulator. +:param initialValue: Optional. The initial value for the accumulator. +:return: The single resulting value. +`; + +(Array.prototype.reduceRight)[prosperon.DOC] = `Similar to reduce(), except it processes elements from right to left. + +:param callback: A function(accumulator, element, index, array) => newAccumulator. +:param initialValue: Optional. The initial value for the accumulator. +:return: The single resulting value. +`; + +(Array.prototype.fill)[prosperon.DOC] = `Fill the array with a static value from 'start' index up to (but not including) +'end' index. Modifies the original array. + +:param value: The value to fill. +:param start: The starting index (default 0). +:param end: The ending index (default array.length). +:return: The modified array (with filled values). +`; + +(Array.prototype.find)[prosperon.DOC] = `Return the first element in the array that satisfies the provided callback +function. If none is found, return undefined. + +:param callback: A function(element, index, array) => boolean. +:param thisArg: Optional. A value to use as 'this' within the callback. +:return: The first matching element, or undefined if not found. +`; + +(Array.prototype.findIndex)[prosperon.DOC] = `Return the index of the first element in the array that satisfies the +provided callback function. If none is found, return -1. + +:param callback: A function(element, index, array) => boolean. +:param thisArg: Optional. A value to use as 'this' within the callback. +:return: The index of the first matching element, or -1 if not found. +`; + +(Array.prototype.findLast)[prosperon.DOC] = `Return the last element in the array that satisfies the provided callback +function, searching from right to left. If none is found, return undefined. + +:param callback: A function(element, index, array) => boolean. +:param thisArg: Optional. A value to use as 'this' within the callback. +:return: The last matching element, or undefined if not found. +`; + +(Array.prototype.findLastIndex)[prosperon.DOC] = `Return the index of the last element in the array that satisfies the +provided callback function, searching from right to left. If none is found, +return -1. + +:param callback: A function(element, index, array) => boolean. +:param thisArg: Optional. A value to use as 'this' within the callback. +:return: The index of the last matching element, or -1 if not found. +`; + +(Array.prototype.indexOf)[prosperon.DOC] = `Return the first index at which a given element can be found. If not present, +return -1. + +:param searchElement: The item to locate in the array. +:param fromIndex: The index at which to start searching (default 0). +:return: The index of the found element, or -1 if not found. +`; + +(Array.prototype.lastIndexOf)[prosperon.DOC] = `Return the last index at which a given element can be found, or -1 if not +present. Searches backward from 'fromIndex'. + +:param searchElement: The item to locate in the array. +:param fromIndex: The index at which to start searching backward (default array.length - 1). +:return: The last index of the found element, or -1 if not found. +`; + +(Array.prototype.includes)[prosperon.DOC] = `Return a boolean indicating whether the array contains the given element, +comparing elements using the SameValueZero algorithm. + +:param searchElement: The value to search for. +:param fromIndex: The position in the array to start searching (default 0). +:return: True if the element is found, otherwise false. +`; + +(Array.prototype.join)[prosperon.DOC] = `Join all elements of the array into a string, separated by 'separator'. + +:param separator: The delimiter string to separate elements (default ','). +:return: A string of array elements joined by the separator. +`; + +(Array.prototype.toString)[prosperon.DOC] = `Return a string representing the elements of the array, separated by commas. +Overrides Object.prototype.toString. + +:return: A comma-separated string of array elements. +`; + +(Array.prototype.toLocaleString)[prosperon.DOC] = `Return a localized string representing the array and its elements, calling +each element's toLocaleString if available. + +:return: A locale-sensitive, comma-separated string of array elements. +`; + +(Array.prototype.pop)[prosperon.DOC] = `Remove the last element from the array and return it. This changes the length +of the array. + +:return: The removed element, or undefined if the array is empty. +`; + +(Array.prototype.push)[prosperon.DOC] = `Append one or more elements to the end of the array and return the new length +of the array. + +:param items: One or more items to append. +:return: The new length of the array. +`; + +(Array.prototype.shift)[prosperon.DOC] = `Remove the first element from the array and return it. This changes the length +of the array. + +:return: The removed element, or undefined if the array is empty. +`; + +(Array.prototype.unshift)[prosperon.DOC] = `Insert one or more elements at the start of the array and return the new +length of the array. + +:param items: One or more elements to insert at the start. +:return: The new length of the array. +`; + +(Array.prototype.reverse)[prosperon.DOC] = `Reverse the elements of the array in place and return the modified array. + +:return: The reversed array. +`; + +(Array.prototype.toReversed)[prosperon.DOC] = `Return a shallow copy of the array in reverse order, without modifying the original array. + +:return: A new reversed array. +`; + +(Array.prototype.sort)[prosperon.DOC] = `Sort the array in place, returning it. By default, sorts elements as strings in ascending order. An optional compareFunction may be used for custom sorting. + +:param compareFunction: A function(a, b) => number, defining sort order. +:return: The sorted array. +`; + +(Array.prototype.toSorted)[prosperon.DOC] = `Return a shallow copy of the array, sorted according to the optional compare +function, without modifying the original array. + +:param compareFunction: A function(a, b) => number, defining sort order. +:return: A new sorted array. +`; + +(Array.prototype.slice)[prosperon.DOC] = `Return a shallow copy of a portion of the array into a new array object, selected from 'start' to 'end' (end not included). + +:param start: The beginning index (0-based). Negative values count from the end. +:param end: The end index (exclusive). Negative values count from the end. +:return: A new array containing the extracted elements. +`; + +(Array.prototype.splice)[prosperon.DOC] = `Change the contents of the array by removing or replacing existing elements and/or adding new elements in place. Returns an array of removed elements. + +:param start: The index at which to start changing the array. +:param deleteCount: Number of elements to remove. +:param items: Elements to add in place of the removed elements. +:return: An array containing the removed elements (if any). +`; + +(Array.prototype.toSpliced)[prosperon.DOC] = `Return a shallow copy of the array, with a splice-like operation applied at 'start' removing 'deleteCount' elements and adding 'items'. Does not mutate the original array. + +:param start: The index at which to start the splice operation. +:param deleteCount: Number of elements to remove. +:param items: Elements to add in place of the removed elements. +:return: A new array with the splice applied. +`; + +(Array.prototype.copyWithin)[prosperon.DOC] = `Copy a sequence of array elements within the array, overwriting existing values. This operation is performed in place and returns the modified array. + +:param target: The index at which to copy the sequence to. +:param start: The beginning index of the sequence to copy. +:param end: The end index (exclusive) of the sequence to copy (default array.length). +:return: The modified array. +`; + +(Array.prototype.flatMap)[prosperon.DOC] = `Return a new array formed by applying a callback function to each element and then flattening the result by one level. + +:param callback: A function(element, index, array) => array or value. +:param thisArg: Optional. A value to use as 'this' within the callback. +:return: A new array with the flattened results. +`; + +(Array.prototype.flat)[prosperon.DOC] = `Return a new array with all sub-array elements concatenated into it recursively up to the specified depth. + +:param depth: The maximum depth to flatten (default 1). +:return: A new flattened array. +`; + +(Array.prototype.values)[prosperon.DOC] = `Return a new Array Iterator object that contains the values for each index in the array. + +:return: An iterator over the array's elements. +`; + +(Array.prototype.keys)[prosperon.DOC] = `Return a new Array Iterator object that contains the keys (indexes) for each index in the array. + +:return: An iterator over the array's indices. +`; + +(Array.prototype.entries)[prosperon.DOC] = `Return a new Array Iterator object that contains key/value pairs for each index in the array. Each entry is [index, value]. + +:return: An iterator over [index, value] pairs. +`; + +(Array.prototype.add)[prosperon.DOC] = `Non-standard. Add corresponding elements of the current array and 'other' element-wise, returning a new array. Behavior depends on data types. + +:param other: Another array or scalar to add to each element. +:return: A new array with element-wise sum results. +`; + +(Array.prototype.sub)[prosperon.DOC] = `Non-standard. Subtract corresponding elements of 'other' from the current array element-wise, returning a new array. Behavior depends on data types. + +:param other: Another array or scalar to subtract from each element. +:return: A new array with element-wise difference results. +`; + +(Array.prototype.div)[prosperon.DOC] = `Non-standard. Divide each element of the current array by the corresponding element of 'other' (or a scalar) element-wise, returning a new array. Behavior depends on data types. + +:param other: Another array or scalar for the division. +:return: A new array with element-wise division results. +`; + +// Object +(Object.prototype.toString)[prosperon.DOC] = `Return a string representing this object. By default, it returns a string of the form '[object ]', where is the object's class. + +:return: A string that describes the object. +`; + +(Object.prototype.toLocaleString)[prosperon.DOC] = `Return a localized string representation of this object, calling toString() by default or a locale-specific override if defined. + +:return: A locale-sensitive string representation of the object. +`; + +(Object.prototype.valueOf)[prosperon.DOC] = `Return the primitive value of this object if one exists. Typically, an object returns itself, while a wrapped type (e.g. Number, String) may return the underlying primitive value. + +:return: The primitive value of the object, or the object itself. +`; + +(Object.prototype.hasOwnProperty)[prosperon.DOC] = `Return a boolean indicating whether the object has a property with the specified name (key) as its own direct property, as opposed to inheriting it. It does not check the prototype chain. + +:param prop: The name or Symbol of the property to test. +:return: True if the property is found directly on the object, otherwise false. +`; + +(Object.prototype.isPrototypeOf)[prosperon.DOC] = `Return true if the object appears anywhere in the prototype chain of the specified object, otherwise false. + +:param obj: The object whose prototype chain will be checked. +:return: True if this object is in 'obj's prototype chain, otherwise false. +`; + +(Object.prototype.propertyIsEnumerable)[prosperon.DOC] = `Return a boolean indicating whether the specified property is enumerable, i.e., whether it shows up in a for...in loop or Object.keys() on the object. + +:param prop: The name or Symbol of the property to test. +:return: True if the property is found and enumerable, otherwise false. +`; + +(Object.create)[prosperon.DOC] = `Create a new object, using the specified prototype object and optional property descriptors. + +:param proto: The object to be used as the prototype. +:param propertiesObject: Optional. An object specifying properties to be added. +:return: A new object with the given prototype and properties. +`; + +(Object.getPrototypeOf)[prosperon.DOC] = `Return the prototype of the specified object. If no prototype is found (e.g. the object has null as its prototype), return null. + +:param obj: The object whose prototype is to be returned. +:return: The prototype of 'obj', or null. +`; + +(Object.setPrototypeOf)[prosperon.DOC] = `Set the prototype of the specified object to the provided value. Throws a TypeError if the object is non-extensible and the prototype is changed. + +:param obj: The object whose prototype is set. +:param proto: The new prototype or null. +:return: The object 'obj' after setting its prototype. +`; + +(Object.defineProperty)[prosperon.DOC] = `Define or modify a property on an object using a property descriptor, returning the object. Throws a TypeError if the descriptor is invalid. + +:param obj: The object on which to define or modify a property. +:param prop: The name or Symbol of the property. +:param descriptor: A property descriptor object (e.g., {value, writable, get, set, ...}). +:return: The object with the newly defined or updated property. +`; + +(Object.defineProperties)[prosperon.DOC] = `Define new or modify existing properties on an object, given an object of property descriptors. Returns the modified object. + +:param obj: The object on which to define or modify properties. +:param props: An object mapping property names to property descriptors. +:return: The modified object. +`; + +(Object.getOwnPropertyNames)[prosperon.DOC] = `Return an array of all own (non-Symbol) property names found directly on the given object, in the same order as a for...in loop would return. + +:param obj: The object whose own property names are returned. +:return: An array of strings that correspond to the properties. +`; + +(Object.getOwnPropertySymbols)[prosperon.DOC] = `Return an array of all own Symbol properties found directly on the given object. + +:param obj: The object to retrieve Symbol keys from. +:return: An array of Symbol keys. +`; + +(Object.groupBy)[prosperon.DOC] = `Non-standard / Proposed. Group the own properties of an object according to the return value of a grouping function. Typically returns a new object whose keys are the group identifiers. + +:param obj: The object to group. +:param fn: A function(key, value) => groupingKey, applied to each property. +:return: An object where properties are grouped by the returned keys. +`; + +(Object.keys)[prosperon.DOC] = `Return an array of the object's own enumerable (non-Symbol) property names, in the same order that a normal loop would. + +:param obj: The object whose property names are to be returned. +:return: An array of property names. +`; + +(Object.values)[prosperon.DOC] = `Return an array of the object's own enumerable (non-Symbol) property values, in the same order as Object.keys(). + +:param obj: The object whose property values are to be returned. +:return: An array of property values. +`; + +(Object.entries)[prosperon.DOC] = `Return an array of [key, value] pairs for the object's own enumerable (non-Symbol) properties, in the same order as Object.keys(). + +:param obj: The object whose [key, value] pairs are to be returned. +:return: An array of [key, value] pairs. +`; + +(Object.isExtensible)[prosperon.DOC] = `Return a boolean indicating whether new properties can be added to the specified object. + +:param obj: The object to test. +:return: True if the object is extensible, otherwise false. +`; + +(Object.preventExtensions)[prosperon.DOC] = `Prevent new properties from ever being added to an object. Existing properties are not affected. + +:param obj: The object to mark as non-extensible. +:return: The non-extensible object. +`; + +(Object.getOwnPropertyDescriptor)[prosperon.DOC] = `Return the property descriptor for a named property on the specified object, if it exists, otherwise undefined. + +:param obj: The object in which to look for the property. +:param prop: The name or Symbol of the property. +:return: The property descriptor, or undefined if not found. +`; + +(Object.getOwnPropertyDescriptors)[prosperon.DOC] = `Return an object containing all own property descriptors for the given object, keyed by property names (and Symbols). + +:param obj: The object to retrieve property descriptors from. +:return: An object mapping property keys to property descriptors. +`; + +(Object.is)[prosperon.DOC] = `Compare two values for strict equality, like '===' but without special treatment for +0 and -0, and treating NaN as equal to NaN. + +:param value1: A value to compare. +:param value2: Another value to compare. +:return: True if both values are the same, otherwise false. +`; + +(Object.assign)[prosperon.DOC] = `Copy all enumerable own properties from one or more source objects to a target object, returning the modified target. + +:param target: The object to receive properties. +:param sources: One or more objects containing properties to copy. +:return: The updated target object. +`; + +(Object.seal)[prosperon.DOC] = `Seal an object, preventing new properties from being added and marking all existing properties as non-configurable. Values of present properties can still be changed if they are writable. + +:param obj: The object to seal. +:return: The sealed object. +`; + +(Object.freeze)[prosperon.DOC] = `Freeze an object, preventing new properties from being added, existing properties from being removed, or current properties from being changed (to the extent permitted by property descriptors). + +:param obj: The object to freeze. +:return: The frozen object. +`; + +(Object.isSealed)[prosperon.DOC] = `Check if an object is sealed. A sealed object has no configurable properties and is non-extensible. + +:param obj: The object to test. +:return: True if the object is sealed, otherwise false. +`; + +(Object.isFrozen)[prosperon.DOC] = `Check if an object is frozen. A frozen object is sealed and all data properties are non-writable. + +:param obj: The object to test. +:return: True if the object is frozen, otherwise false. +`; + +(Object.fromEntries)[prosperon.DOC] = `Transform a list of key-value pairs into an object. The iterable argument should yield pairs [key, value], which become properties on the resulting object. + +:param entries: An iterable of [key, value] pairs. +:return: A new object formed from the given entries. +`; + +(Object.hasOwn)[prosperon.DOC] = `Return a boolean indicating whether the specified property exists on the object as a direct own property (similar to hasOwnProperty, but directly on Object). + +:param obj: The object on which to check the property. +:param prop: The name or Symbol of the property to check. +:return: True if the property is found on 'obj', otherwise false. +`; + +(Object.id)[prosperon.DOC] = `Non-standard. Return a unique identifier for the given object, assigning one if necessary. The same object will always yield the same ID. + +:param obj: The object to retrieve or assign a unique ID. +:return: A unique identifier (string or number) associated with the object. +`; + +(String.fromCharCode)[prosperon.DOC] = `Return a string created from the specified sequence of UTF-16 code units. +Each argument is treated as a code unit in the range [0, 65535]. + +:param codeUnits: A series of numbers representing UTF-16 code units. +:return: A string constructed by mapping each code unit to a character. +`; + +(String.fromCodePoint)[prosperon.DOC] = `Return a string created from the specified sequence of code points, +including those above U+FFFF (which will become surrogate pairs). +Throws a RangeError for invalid code points. + +:param codePoints: A series of numbers representing Unicode code points. +:return: A string constructed from the given code points. +`; + +(String.raw)[prosperon.DOC] = `A tag function of template literals that returns a raw where escape sequences (e.g., '\\n', '\\u00A9') are not processed. +Commonly used to retrieve the unprocessed text of a template. + +:param template: A template literal, or an object with a 'raw' property. +:param substitutions: Additional values to substitute (if any). +:return: The combined raw string from the template. +`; + +(Math.min)[prosperon.DOC] = `Return the smallest of the zero or more given numbers. If no arguments are provided, the result is Infinity. If any value is NaN, the result is NaN. + +:param values: One or more numeric values. +:return: The smallest numeric value, Infinity if no arguments, or NaN if any argument cannot be converted to a number. +`; + +(Math.max)[prosperon.DOC] = `Return the largest of the zero or more given numbers. If no arguments are provided, the result is -Infinity. If any value is NaN, the result is NaN. + +:param values: One or more numeric values. +:return: The largest numeric value, -Infinity if no arguments, or NaN if any argument cannot be converted to a number. +`; + +(Math.abs)[prosperon.DOC] = `Return the absolute value of the given number. For example, -5 becomes 5. + +:param x: A numeric value. +:return: The absolute value of x. +`; + +(Math.floor)[prosperon.DOC] = `Return the greatest integer less than or equal to x, effectively rounding down to the nearest integer. + +:param x: A numeric value. +:return: The largest integer <= x. +`; + +(Math.ceil)[prosperon.DOC] = `Return the smallest integer greater than or equal to x, effectively rounding up to the nearest integer. + +:param x: A numeric value. +:return: The smallest integer >= x. +`; + +(Math.round)[prosperon.DOC] = `Return x rounded to the nearest integer. If the fractional portion is 0.5 or +greater, rounds up; otherwise, rounds down. Ties away from zero in modern ECMAScript. + +:param x: A numeric value. +:return: x rounded to the nearest integer. +`; + +(Math.sqrt)[prosperon.DOC] = `Return the positive square root of x. If x is negative, the result is NaN. + +:param x: A non-negative numeric value. +:return: The positive square root of x, or NaN if x is negative. +`; + +(Math.acos)[prosperon.DOC] = `Return the arccosine (in radians) of x, in the range [0, π]. If x is outside +the range [-1, 1], the result is NaN. + +:param x: A numeric value in [-1, 1]. +:return: The arccosine of x in radians, or NaN if out of range. +`; + +(Math.asin)[prosperon.DOC] = `Return the arcsine (in radians) of x, in the range [-π/2, π/2]. If x is +outside [-1, 1], the result is NaN. + +:param x: A numeric value in [-1, 1]. +:return: The arcsine of x in radians, or NaN if out of range. +`; + +(Math.atan)[prosperon.DOC] = `Return the arctangent (in radians) of x, in the range [-π/2, π/2]. + +:param x: A numeric value. +:return: The arctangent of x in radians. +`; + +(Math.atan2)[prosperon.DOC] = `Return the arctangent of the quotient of its arguments (y / x), in the range +(-π, π]. This takes into account the signs of both x and y to determine +the correct quadrant. + +:param y: The y coordinate. +:param x: The x coordinate. +:return: The angle in radians between the positive x-axis and the point (x, y). +`; + +(Math.cos)[prosperon.DOC] = `Return the cosine of x, where x is in radians. + +:param x: A numeric value in radians. +:return: The cosine of x, in the range [-1, 1]. +`; + +(Math.exp)[prosperon.DOC] = `Return e^x, where e is Euler's number (approximately 2.71828). + +:param x: A numeric exponent. +:return: The value of e raised to x. +`; + +(Math.log)[prosperon.DOC] = `Return the natural logarithm (base e) of x. If x is <= 0, the result is NaN. + +:param x: A positive numeric value. +:return: The natural logarithm of x. +`; + +(Math.pow)[prosperon.DOC] = `Return base raised to the power exponent, i.e. base^exponent. If base is +negative and exponent is not an integer, result is NaN. + +:param base: The base number. +:param exponent: The exponent number. +:return: base raised to exponent. +`; + +(Math.sin)[prosperon.DOC] = `Return the sine of x, where x is in radians. + +:param x: A numeric value in radians. +:return: The sine of x, in the range [-1, 1]. +`; + +(Math.tan)[prosperon.DOC] = `Return the tangent of x, where x is in radians. If x is (π/2 + nπ), the +result is ±Infinity or NaN. + +:param x: A numeric value in radians. +:return: The tangent of x. +`; + +(Math.trunc)[prosperon.DOC] = `Return the integer part of x by removing any fractional digits. Does not +round, just truncates. + +:param x: A numeric value. +:return: x truncated toward zero. +`; + +(Math.sign)[prosperon.DOC] = `Return the sign of x, indicating whether x is positive, negative, or zero. +Returns 1 if x > 0, -1 if x < 0, 0 if x is 0, and NaN if x is NaN. + +:param x: A numeric value. +:return: 1, -1, 0, -0, or NaN, depending on x. +`; + +(Math.cosh)[prosperon.DOC] = `Return the hyperbolic cosine of x, (e^x + e^-x) / 2. + +:param x: A numeric value. +:return: The hyperbolic cosine of x. +`; + +(Math.sinh)[prosperon.DOC] = `Return the hyperbolic sine of x, (e^x - e^-x) / 2. + +:param x: A numeric value. +:return: The hyperbolic sine of x. +`; + +(Math.tanh)[prosperon.DOC] = `Return the hyperbolic tangent of x, (e^x - e^-x) / (e^x + e^-x). + +:param x: A numeric value. +:return: The hyperbolic tangent of x. +`; + +(Math.acosh)[prosperon.DOC] = `Return the inverse hyperbolic cosine of x, defined as ln(x + sqrt(x^2 - 1)). +If x < 1, the result is NaN. + +:param x: A numeric value >= 1. +:return: The inverse hyperbolic cosine of x. +`; + +(Math.asinh)[prosperon.DOC] = `Return the inverse hyperbolic sine of x, defined as ln(x + sqrt(x^2 + 1)). + +:param x: A numeric value. +:return: The inverse hyperbolic sine of x. +`; + +(Math.atanh)[prosperon.DOC] = `Return the inverse hyperbolic tangent of x, defined as 1/2 * ln((1 + x) / (1 - x)). +If |x| >= 1, the result is NaN. + +:param x: A numeric value in the range (-1, 1). +:return: The inverse hyperbolic tangent of x. +`; + +(Math.expm1)[prosperon.DOC] = `Return e^x - 1, for small values of x this provides higher precision than +Math.exp(x) - 1. + +:param x: A numeric exponent. +:return: e^x - 1. +`; + +(Math.log1p)[prosperon.DOC] = `Return the natural logarithm of (1 + x). More accurate than Math.log(1 + x) +for small x. + +:param x: A numeric value > -1. +:return: ln(1 + x). +`; + +(Math.log2)[prosperon.DOC] = `Return the base-2 logarithm of x. If x <= 0, the result is NaN. + +:param x: A positive numeric value. +:return: The base-2 logarithm of x. +`; + +(Math.log10)[prosperon.DOC] = `Return the base-10 logarithm of x. If x <= 0, the result is NaN. + +:param x: A positive numeric value. +:return: The base-10 logarithm of x. +`; + +(Math.cbrt)[prosperon.DOC] = `Return the cube root of x, including negative values. + +:param x: A numeric value (can be negative). +:return: The cube root of x. +`; + +(Math.hypot)[prosperon.DOC] = `Return the square root of the sum of squares of its arguments, i.e. +sqrt(x1^2 + x2^2 + ...). If any value is ±Infinity, returns Infinity. If +any value is NaN, returns NaN. + +:param values: One or more numeric values. +:return: The square root of the sum of squares of the arguments. +`; + +(Math.random)[prosperon.DOC] = `Return a pseudo-random floating-point number in the range [0, 1). +The result is usually seeded by an engine-defined source of randomness. + +:return: A number >= 0 and < 1. +`; + +(Math.fround)[prosperon.DOC] = `Return the nearest 32-bit single-precision float representation of x. + +:param x: A numeric value. +:return: The 32-bit float representation of x. +`; + +(Math.imul)[prosperon.DOC] = `Return the result of a 32-bit integer multiplication of two values. +Effectively (a * b) | 0 in many implementations. + +:param a: A numeric value. +:param b: A numeric value. +:return: The 32-bit integer result of multiplying a by b. +`; + +(Math.clz32)[prosperon.DOC] = `Return the number of leading zero bits in the 32-bit binary representation +of x. If x is 0, returns 32. + +:param x: A numeric value, treated as a 32-bit unsigned integer. +:return: The count of leading zero bits, in the range [0, 32]. +`; + +(Number.parseInt)[prosperon.DOC] = `Parse a string argument and return an integer of the specified radix (base). +If the string does not start with a valid integer, return NaN. Leading +whitespace is ignored. + +:param string: The string to parse as an integer. +:param radix: An integer between 2 and 36 indicating the base of the number in the string. +:return: The parsed integer, or NaN if the input is not a valid integer. +`; + +(Number.parseFloat)[prosperon.DOC] = `Parse a string argument and return a floating-point number. If the string does not represent a valid number, return NaN. Leading whitespace is ignored, and the string can include a decimal point or exponent. + +:param string: The string to parse as a floating-point number. +:return: The parsed number, or NaN if invalid. +`; + +(Number.isNaN)[prosperon.DOC] = `Determine if a value is the special numeric value NaN, without converting the argument. Unlike the global isNaN(), this returns false for non-numeric values. + +:param value: The value to test. +:return: True if the value is NaN, otherwise false. +`; + +(Number.isFinite)[prosperon.DOC] = `Determine if a value is a finite number. Unlike the global isFinite(), this returns false for non-numeric values without attempting to convert them. + +:param value: The value to test. +:return: True if the value is a finite number, otherwise false. +`; + +(Number.isInteger)[prosperon.DOC] = `Check if the given value is a finite number and also an integer (no fractional part). Returns false for non-numeric values or NaN. + +:param value: The value to test. +:return: True if value is an integer, otherwise false. +`; + +(Number.isSafeInteger)[prosperon.DOC] = `Check if the given value is a safe integer. A safe integer is one that can be exactly represented as an IEEE-754 double-precision number (i.e., between -9007199254740991 and 9007199254740991 inclusive). + +:param value: The value to test. +:return: True if value is an integer within the safe range, otherwise false. +`; + +(Array.isArray)[prosperon.DOC] = `Determine if the given value is an Array. Returns true if the argument is an array, otherwise false. + +:param value: The value to be checked. +:return: True if 'value' is an array, otherwise false. +`; + +(Array.from)[prosperon.DOC] = `Create a new array from an array-like or iterable object. An optional map function can be invoked on each element before it is added to the new array. + +:param arrayLike: An array-like or iterable object to convert. +:param mapFn: Optional. A function to call on every element of the new array. +:param thisArg: Optional. A value to use as 'this' within the map function. +:return: A new array populated with elements processed from arrayLike. +`; + +(Array.of)[prosperon.DOC] = `Create a new array with a variable number of arguments, regardless of the number or type of the arguments. Unlike the Array constructor, there is no special treatment for a single numeric argument. + +:param elements: A variable number of arguments which become array elements. +:return: A new array containing the provided arguments. +`; + +(Symbol.for)[prosperon.DOC] = `Search the global symbol registry for a symbol with the given key. If found, return that symbol; otherwise, create a new symbol with that key and add it to the registry, then return the new symbol. + +:param key: A string key used to identify the symbol in the global registry. +:return: A symbol associated with the given key in the global registry. +`; + +(Symbol.keyFor)[prosperon.DOC] = `Retrieve a shared symbol’s key from the global symbol registry. If the symbol is not in the global registry, return undefined. + +:param sym: The symbol to find the key for. +:return: The string key if 'sym' is a global symbol, otherwise undefined. +`; + +// ------------------------------------------ +// MAP +// ------------------------------------------ +Map.prototype[prosperon.DOC] = {} +Map.prototype[prosperon.DOC][prosperon.DOC] = `A Map object holds key-value pairs, where any value (both objects and primitive values) may be used as either a key or a value. Insertion order is remembered, which allows iteration in that order.`; + +Map.prototype[prosperon.DOC].size = `A read-only property returning the number of key-value pairs in the Map. + +:return: The number of entries in the Map. +`; + +(Map.prototype.set)[prosperon.DOC] = `Add or update an entry in the Map with the specified key and value. + +:param key: The key of the element to add or update. +:param value: The value associated with the key. +:return: The Map object (for chaining). +`; + +(Map.prototype.get)[prosperon.DOC] = `Return the value associated with the specified key, or undefined if no +such key exists. + +:param key: The key of the element to retrieve. +:return: The value associated with the key, or undefined if not found. +`; + +(Map.prototype.has)[prosperon.DOC] = `Return a boolean indicating whether the Map contains an element with the +specified key. + +:param key: The key to test for presence in the Map. +:return: True if the key is found, otherwise false. +`; + +(Map.prototype.delete)[prosperon.DOC] = `Remove the specified key and its associated value from the Map, if it exists. + +:param key: The key to remove. +:return: True if an element was removed, otherwise false. +`; + +(Map.prototype.clear)[prosperon.DOC] = `Remove all entries from the Map, leaving it empty. + +:return: None +`; + +(Map.prototype.forEach)[prosperon.DOC] = `Execute a provided callback function once per each key-value pair in the Map, +in insertion order. + +:param callbackFn: A function(value, key, map) to execute on each entry. +:param thisArg: Optional. A value to use as 'this' when executing callbackFn. +:return: None +`; + +(Map.prototype.values)[prosperon.DOC] = `Return a new Iterator object that contains the values for each element +in the Map, in insertion order. + +:return: An iterator of the Map's values. +`; + +(Map.prototype.keys)[prosperon.DOC] = `Return a new Iterator object that contains the keys for each element in +the Map, in insertion order. + +:return: An iterator of the Map's keys. +`; + +(Map.prototype.entries)[prosperon.DOC] = `Return a new Iterator object that contains the [key, value] pairs for +each element in the Map, in insertion order. + +:return: An iterator of [key, value] pairs. +`; + + +// ------------------------------------------ +// SET +// ------------------------------------------ +Set.prototype[prosperon.DOC] = {} +Set.prototype[prosperon.DOC][prosperon.DOC] = `A Set object lets you store unique values of any type, whether primitive values or object references. It remembers insertion order for iteration.`; + +Set.prototype[prosperon.DOC].size = `A read-only property returning the number of elements in the Set. + +:return: The number of unique values in the Set. +`; + +(Set.prototype.add)[prosperon.DOC] = `Add a new element with the given value to the Set, if it’s not already present. + +:param value: The value to add. +:return: The Set object (for chaining). +`; + +(Set.prototype.has)[prosperon.DOC] = `Return a boolean indicating whether the Set contains the specified value. + +:param value: The value to check for presence in the Set. +:return: True if the value is found, otherwise false. +`; + +(Set.prototype.delete)[prosperon.DOC] = `Remove the specified value from the Set if it exists. + +:param value: The value to remove. +:return: True if the value was present and removed, otherwise false. +`; + +(Set.prototype.clear)[prosperon.DOC] = `Remove all elements from the Set, leaving it empty. + +:return: None +`; + +(Set.prototype.forEach)[prosperon.DOC] = `Execute a provided callback function once for each value in the Set, +in insertion order. + +:param callbackFn: A function(value, valueAgain, set) to execute on each element. +:param thisArg: Optional. A value to use as 'this' when executing callbackFn. +:return: None +`; + +(Set.prototype.values)[prosperon.DOC] = `Return a new Iterator object containing all the values in the Set, +in insertion order. + +:return: An iterator of the Set's values. +`; + +(Set.prototype.keys)[prosperon.DOC] = `Alias for values() in a Set. Return a new Iterator object containing all +the values (as keys) in the Set, in insertion order. + +:return: An iterator of the Set's values. +`; + +(Set.prototype.entries)[prosperon.DOC] = `Return a new Iterator object containing [value, value] pairs for each value +in the Set, in insertion order. This maintains API consistency with Map objects. + +:return: An iterator of [value, value] pairs. +`; + + +// ------------------------------------------ +// WEAKMAP +// ------------------------------------------ +WeakMap.prototype[prosperon.DOC] = `A WeakMap object is a collection of key/value pairs in which keys must be +objects. References to key objects in a WeakMap are held weakly, meaning +they do not prevent garbage collection if there are no other references +to the object. WeakMap keys are not iterable.`; + +(WeakMap.prototype.set)[prosperon.DOC] = `Set the value for the specified key in the WeakMap. The key must be an object. + +:param key: The object key. +:param value: The value associated with the key. +:return: The WeakMap object (for chaining). +`; + +(WeakMap.prototype.get)[prosperon.DOC] = `Return the value associated with 'key' in the WeakMap, or undefined if +no such key exists. The key must be an object. + +:param key: The object key. +:return: The value associated with the key, or undefined if not present. +`; + +(WeakMap.prototype.has)[prosperon.DOC] = `Return a boolean indicating whether an element with the specified key +exists in the WeakMap. The key must be an object. + +:param key: The object key to check. +:return: True if the key is found, otherwise false. +`; + +(WeakMap.prototype.delete)[prosperon.DOC] = `Remove the specified key and its associated value from the WeakMap, +if it exists. + +:param key: The object key to remove. +:return: True if an element was removed, otherwise false. +`; + + +// ------------------------------------------ +// WEAKSET +// ------------------------------------------ +WeakSet.prototype[prosperon.DOC] = `A WeakSet object is a collection of unique objects (no primitive values). +References to objects in a WeakSet are held weakly, so they do not prevent +garbage collection if there are no other references to the object. WeakSet +elements are not iterable.`; + +(WeakSet.prototype.add)[prosperon.DOC] = `Add a new object to the WeakSet if it is not already present. The value +must be an object. + +:param value: The object to add. +:return: The WeakSet object (for chaining). +`; + +(WeakSet.prototype.has)[prosperon.DOC] = `Return a boolean indicating whether an object is present in the WeakSet. + +:param value: The object to check. +:return: True if the object is in the WeakSet, otherwise false. +`; + +(WeakSet.prototype.delete)[prosperon.DOC] = `Remove the specified object from the WeakSet, if it exists. + +:param value: The object to remove. +:return: True if the object was present and removed, otherwise false. +`; diff --git a/scripts/core/engine.js b/scripts/core/engine.js index f83f4538..63bb6008 100644 --- a/scripts/core/engine.js +++ b/scripts/core/engine.js @@ -1,10 +1,6 @@ (function engine() { prosperon.DOC = Symbol('+documentation+') // Symbol for documentation references -var pd = Object.getOwnPropertyDescriptor(prosperon, 'c_types') -pd.enumerable = false -Object.defineProperty(prosperon,'c_types', pd) - // // sprite // @@ -1656,7 +1652,8 @@ prosperon[prosperon.DOC] = { DOC: `Symbol used to store documentation references on objects.`, on: `Register a callback function for a given event type. Returns a function to remove the callback.`, dispatch: `Dispatch an event of the given type, calling all registered callbacks with the provided data.`, - PATH: `Array of directory paths that Prosperon will search to find scripts or modules.` + PATH: `Array of directory paths that Prosperon will search to find scripts or modules.`, + c_types: `Prototype objects for all present defined c-types (like sprite, transform, etc)` } // Document the actor object/prototype diff --git a/scripts/modules/doc.js b/scripts/modules/doc.js index c675c05b..6cae61b9 100644 --- a/scripts/modules/doc.js +++ b/scripts/modules/doc.js @@ -1,19 +1,19 @@ +// doc.js function docOf(obj, prop) { - // Grab the top-level doc block on the object. var block = obj[prosperon.DOC]; if (!block) return ''; - // 1) If `block` is directly a string, that’s the entire doc for the object. - // If a sub-property was requested, we have nowhere to look that up → return ''. + // 1) If `block` is a string, that's the entire doc for `obj`. + // If a sub-property is requested, we have nowhere to look → return ''. if (typeof block === 'string') { return prop ? '' : block; } - // 2) Otherwise, `block` is (hopefully) an object. We handle two scenarios: - // (a) No `prop` asked for → return block.doc or block[prosperon.DOC]. - // (b) If a `prop` is asked for → check if block[prop] is a string or object with its own doc. + // 2) Otherwise, if `block` is an object: + // (a) With no `prop`, return block.doc or block[prosperon.DOC]. + // (b) If `prop` is given, look for doc specifically for that property (just one level). if (typeof block === 'object') { - // 2a) If no property was requested, return block.doc or block[prosperon.DOC], if either is a string. + // 2a) No property → top-level doc if (!prop) { if (typeof block.doc === 'string') { return block.doc; @@ -24,16 +24,12 @@ function docOf(obj, prop) { return ''; } - // 2b) If a property is requested, see if there's a doc for that property inside the block. + // 2b) If a prop is requested → see if there's a doc string or object for that property var subBlock = block[prop]; if (!subBlock) return ''; - - // If subBlock is a string → return it as the doc if (typeof subBlock === 'string') { return subBlock; } - - // If subBlock is an object, see if it has .doc or [prosperon.DOC] if (typeof subBlock === 'object') { if (typeof subBlock.doc === 'string') { return subBlock.doc; @@ -49,7 +45,6 @@ function docOf(obj, prop) { return ''; } - function parseDocStr(docStr) { if (!docStr) return []; @@ -57,15 +52,14 @@ function parseDocStr(docStr) { var paramRe = /^:param\s+([A-Za-z0-9_]+)\s*:\s*(.*)$/; var returnRe = /^:return:\s*(.*)$/; - // We'll collect three categories of lines, then reassemble: - var descLines = []; // For plain description lines - var paramLines = []; // For :param: lines - var returnLines = []; // For :return: lines + var descLines = []; + var paramLines = []; + var returnLines = []; for (var i = 0; i < lines.length; i++) { var line = lines[i].trim(); if (!line) { - // Keep empty lines with the "desc" section to maintain spacing + // Keep empty lines in the desc section descLines.push(''); continue; } @@ -74,26 +68,21 @@ function parseDocStr(docStr) { var rm = returnRe.exec(line); if (pm) { - // param line → store in paramLines paramLines.push('**' + pm[1] + '**: ' + pm[2]); paramLines.push(''); } else if (rm) { - // return line → store in returnLines returnLines.push('**Returns**: ' + rm[1]); returnLines.push(''); } else { - // Otherwise, it's a general description line descLines.push(line); } } - // Now reassemble in the fixed order: - // 1) description lines, 2) param lines, 3) returns lines var final = []; + // Reassemble: description → params → returns if (descLines.length) { final.push.apply(final, descLines); - // Insert blank line if needed if (paramLines.length || returnLines.length) { final.push(''); } @@ -114,40 +103,32 @@ function parseDocStr(docStr) { return final; } - function writeDocFile(obj, title) { var lines = []; var docTitle = title || "Documentation"; lines.push('# ' + docTitle + '\n'); - walkObject(obj, lines, 1, docTitle); return lines.join('\n'); // If you had I/O, you'd write to file here - // io.slurpwrite(outputPath, finalStr) } +/** + * Documents the top-level object and each of its immediate properties, + * but does NOT recurse deeper than that. + */ function walkObject(obj, lines, level, name) { - // See what doc string (if any) this object has + // Print top-level doc or fallback heading var topDocStr = docOf(obj); - - // If there's an actual docstring for the object, don't output another heading if (topDocStr) { - // parseDocStr is your existing function that handles :param etc. var docOut = parseDocStr(topDocStr); if (docOut.length > 0) { lines.push(docOut.join('\n') + '\n'); } - } - // Otherwise, if there's no docstring, insert an auto-generated heading - else { - var heading = '#'.repeat(level + 1) + ' ' + name; - lines.push(heading + '\n'); } - // Now enumerate this object's direct properties - var propNames = Object.keys(obj); + var propNames = Object.getOwnPropertyNames(obj); for (var i = 0; i < propNames.length; i++) { var prop = propNames[i]; if (prop === 'constructor') continue; @@ -155,40 +136,60 @@ function walkObject(obj, lines, level, name) { var desc = Object.getOwnPropertyDescriptor(obj, prop); if (!desc) continue; - // Check if this is an accessor property (getter/setter) + // Check if accessor property (getter/setter) var hasGetter = typeof desc.get === 'function'; var hasSetter = typeof desc.set === 'function'; if (hasGetter || hasSetter) { - // We handle them as a single "property" entry, - // not separate get/set headings. writeProperty(lines, obj, prop, desc, level); continue; } - // Otherwise, if there's a "value" (could be a function or an object) + // If it's a normal data property if ('value' in desc) { var val = desc.value; + + // If it's a function, treat it like a method if (typeof val === 'function') { writeMethod(lines, obj, prop, val, level); - } else if (val && typeof val === 'object') { - // Possibly a nested object; check if it or its children have doc - if (hasAnyDoc(val)) { - walkObject(val, lines, level + 1, prop); - } + } + // If it's an object, just print doc for that object (no deep recursion) + else if (val && typeof val === 'object') { + writeSubObject(lines, obj, prop, val, level); + } + // Otherwise, it's a primitive or something else + else { + writeDataProperty(lines, obj, prop, val, level); } } } } /** - * Writes out a single property entry for an accessor (getter/setter). - * - If only a getter, adds "(read only)" just below the property name. - * - If only a setter, adds "(set only)" just below the property name. - * - If both, no extra text is added (but we do a single heading). + * Write out a heading and doc for an object property + * (but do NOT recurse into that object's subproperties). */ +function writeSubObject(lines, parentObj, prop, val, level) { + // E.g. "## someObject object" + var heading = '#'.repeat(level + 2) + ' ' + prop + ' object'; + lines.push(heading + '\n'); + + // 1) If there's doc assigned specifically to the parent's doc block for `prop` + var docStr = docOf(parentObj, prop); + // 2) If no doc there, see if the object itself has top-level doc + if (!docStr) { + docStr = docOf(val); + } + + var docOut = parseDocStr(docStr); + if (docOut.length > 0) { + lines.push(docOut.join('\n') + '\n'); + } +} + function writeProperty(lines, parentObj, prop, desc, level) { - var heading = '#'.repeat(level + 2) + ' ' + prop; + // E.g. "## myProp accessor" + var heading = '#'.repeat(level + 2) + ' ' + prop + ' accessor'; lines.push(heading + '\n'); var hasGetter = typeof desc.get === 'function'; @@ -199,10 +200,8 @@ function writeProperty(lines, parentObj, prop, desc, level) { } else if (!hasGetter && hasSetter) { lines.push('(set only)\n'); } - // If both, we do nothing extra - // Collect doc from the property-level doc block - // If that's empty, see if either accessor function has doc + // Look up doc in parent's doc block first, or in the accessor functions var docStr = docOf(parentObj, prop); if (!docStr && hasGetter) { docStr = docOf(desc.get) || docStr; @@ -217,38 +216,12 @@ function writeProperty(lines, parentObj, prop, desc, level) { } } -function hasAnyDoc(o) { - if (!o) return false; - // If the object itself has a docOf - if (docOf(o)) return true; - - // Or if any property is a function that has doc - var names = Object.getOwnPropertyNames(o); - for (var i = 0; i < names.length; i++) { - var desc = Object.getOwnPropertyDescriptor(o, names[i]); - if (!desc) continue; - - // check if accessor doc - if (typeof desc.get === 'function' && docOf(desc.get)) return true; - if (typeof desc.set === 'function' && docOf(desc.set)) return true; - - // check function doc - if (desc.value && typeof desc.value === 'function') { - if (docOf(desc.value) || docOf(o, names[i])) return true; - } - // or check nested object - if (desc.value && typeof desc.value === 'object') { - if (hasAnyDoc(desc.value)) return true; - } - } - return false; -} - function writeMethod(lines, parentObj, prop, fn, level) { + // Pull doc from the function or from the parent's doc block var docStr = fn[prosperon.DOC] || docOf(parentObj, prop) || ''; - // parse :param lines var paramNames = []; + // Try to extract param names from the doc if (docStr) { var docLines = docStr.split('\n'); var paramRe = /^:param\s+([A-Za-z0-9_]+)\s*:\s*(.*)$/; @@ -258,27 +231,50 @@ function writeMethod(lines, parentObj, prop, fn, level) { } } + // E.g. "## myFunction(param1, param2) function" var heading = '#'.repeat(level + 2) + ' ' + prop; - // if we found param names in the doc, show them in the heading + if (paramNames.length > 0) { heading += '(' + paramNames.join(', ') + ')'; } else { - // fallback: parse the function signature + // As a fallback, parse function signature var m = fn.toString().match(/\(([^)]*)\)/); if (m && m[1].trim()) { heading += '(' + m[1].trim() + ')'; + } else { + // If no params at all (or we cannot detect them), still add () + heading += '()'; } } + + heading += ' function'; lines.push(heading + '\n'); - // parse doc lines var docOut = parseDocStr(docStr); if (docOut.length > 0) { lines.push(docOut.join('\n') + '\n'); } } -writeDocFile[prosperon.DOC] = `Return a markdown string for a given obj, with optional title.`; +/** + * Write out a heading and doc for a primitive (string, number, boolean, etc). + */ +function writeDataProperty(lines, parentObj, prop, val, level) { + // E.g. "## someString string" + var typeStr = typeof val; + var heading = '#'.repeat(level + 2) + ' ' + prop + ' ' + typeStr + ''; + lines.push(heading + '\n'); + + // Look up doc in parent's doc block + var docStr = docOf(parentObj, prop); + var docOut = parseDocStr(docStr); + if (docOut.length > 0) { + lines.push(docOut.join('\n') + '\n'); + } +} + +// Provide a doc string for writeDocFile +writeDocFile[prosperon.DOC] = `Return a markdown string for a given obj, with an optional title.`; return { writeDocFile: writeDocFile