@bscotch/gml-parser 1.14.2

package/LICENSE.md

@@ -0,0 +1,29 @@
+# License for the Stitch Monorepo
+
+License information for the content of this git repository. The various packages in this repo are developed by [Butterscotch Shenanigans](https://www.bscotch.net) ("Bscotch").
+
+## License files
+
+Whenever a `LICENSE` file is found in a folder, or a license is specified by a `package.json` or similar manifest file, that license takes precedence for all files in that folder and its subfolders.
+
+This is the root-most `LICENSE` file, and therefore dictates the default licensing in this repository.
+
+## Stitch name and logo
+
+![Stitch Logo](https://img.bscotch.net/fit-in/256x256/logos/stitch.png "The Stitch Logo, copyright and trademark Butterscotch Shenanigans, all rights reserved.")
+
+Stitch™ and its logo are trademarks of Bscotch. Bscotch reserves all rights to Stitch and its logo.
+
+Stitch Logo ©2022 by Bscotch. All rights reserved.
+
+## Other code and content
+
+Everything found in this project, except for the Stitch name and logo as described above or unless otherwise specified by a more proximal LICENSE file, falls under the MIT license (https://opensource.org/license/mit/):
+
+Copyright 2023 Butterscotch Shenanigans
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,151 @@
+# GameMaker Language (GML) Parser (`gml-parser`)
+
+A parser, project model, and meta-programming tool for [GameMaker](https://gamemaker.io/) projects, which provides the core project-management features provided by [Stitch for VSCode](https://marketplace.visualstudio.com/items?itemName=bscotch.bscotch-stitch-vscode).
+
+This package can also be used independently of Stitch for VSCode to create automations and pipelines for working with GameMaker projects.
+
+**⚠️💀 Use at your own risk, and use source control! This is a meta-programming tool, so it _will_ make changes to and _might_ completely break your project! 💀⚠️**
+
+Stitch is developed by [Butterscotch Shenanigans](https://www.bscotch.net) ("Bscotch"). Support this project by buying [our games](https://www.bscotch.net), [reporting issues](https://github.com/bscotch/stitch/issues), and [contributing](https://github.com/bscotch/stitch/tree/develop/packages/parser).
+
+## Overview
+
+This package was developed to replaced our [Stitch CLI](https://github.com/bscotch/stitch/tree/develop/packages/core), so that we could support newer versions of GameMaker and provide underlying features for using VSCode as an alternate GameMaker IDE via [Stitch for VSCode](https://marketplace.visualstudio.com/items?itemName=bscotch.bscotch-stitch-vscode).
+
+Unlike the Stitch CLI, which is focused on high-level project management, this parser fully models an entire project, including reference and resource tracking.
+
+## Requirements
+
+- [Node.js](https://nodejs.org) v20+
+- Windows. Might partially work on other operating systems, but it is developed and tested only on Windows.
+
+⚠️ This project supports a narrow set of GameMaker versions. It does not try to be backwards-compatible with every version of GameMaker, and may not properly handle changes in the most recent versions either. It may break your project if your GameMaker version isn't fully compatible.
+
+## Installation
+
+This package does not provide a CLI, but it can be imported into Node.js projects to make your own pipelines and automations for GameMaker projects.
+
+If you have Node installed, you can use this package by:
+
+1. Opening a terminal
+2. Changing the working directory to wherever your scripts live
+3. Adding a `package.json` file if you don't already have one (by running `npm init`)
+4. Installing this package via `npm install @bscotch/gml-parser` (or the equivalent with another package manager)
+
+Then you can import things from this package (ESM-style):
+
+```js
+import { Project } from '@bscotch/gml-parser';
+
+const project = await Project.initialize('path/to/your/project.yyp');
+```
+
+## Usage
+
+This package provides a lot of features, which are mostly exposed via instances of the `Project` class. Some examples are provided here, but these docs are incomplete. You can use Typescript's inference/autocomplete and [peruse this package's source code](https://github.com/bscotch/stitch/tree/develop/packages/parser) to discover more parts of the API.
+
+### (Re)load a project
+
+When the parser loads a project it has to discover every asset and parse every line of code, so it can take a while for large projects!
+
+However, once it's been loaded it'll stay up to date whenever you manipulate your project using the Project instance's methods. So you only have to load things once, unless you manipulate your project externally to the Project instance's methods.
+
+```ts
+import { Project } from '@bscotch/gml-parser';
+
+// Load a project into memory, which will parse all of the code,
+// discover all assets,
+// and create a model of the project you can then interact with.
+const project = await Project.initialize('path/to/your/project.yyp');
+
+// If you've changed something in the project's files *externally*
+// to the Project model, you can do a full reload of the project
+// to make sure you're up to date.
+await project.reload();
+```
+
+### View/Manage Project metadata
+
+```ts
+// Get the project's directory
+project.dir;
+
+// Get the config (see https://github.com/bscotch/stitch/tree/develop/packages/config)
+project.stitchConfig;
+
+// Get the names of each GameMaker config
+project.configs;
+
+// List the included files
+project.datafiles;
+
+// List the folders defined in the resource tree in the IDE as POSIX paths.
+project.folders;
+```
+
+### Programmatically manage assets
+
+A `Project` instance provides methods for adding and removing assets, which you can use to build pipelines and other programmatic tools.
+
+```ts
+// Get a GML file in its parsed state. Returns a Code instance,
+// which includes various methods for querying/modifying them.
+const code = project.getGmlFile(
+  '/path/to/my/project/scripts/some_script/some_script.gml',
+);
+
+// Find an asset. Assets are represented by Asset instances,
+// which include a variety of methods to query and manipulate them.
+const asset = project.getAssetByName('a_room_or_sprite_or_whatever_name');
+
+// List the assets found in a given asset-tree folder
+await project.listAssetsInFolder('some/folder', { recursive: true });
+
+// Rename an asset-tree folder (equivalent to "moving" it)
+await project.renameFolder('old/folder/path', 'new/folder/path');
+
+// Create an asset-tree folder
+await project.createFolder('new/folder/path');
+
+// Rename an asset, including all of its references in code and by other asset definitions.
+await project.renameAsset('old_name', 'new_name');
+
+// Delete an asset from the project. This does not remove code
+// references, but does try to clean up other kinds of references.
+// E.g. removing a sprite will also remove references to that sprite
+// in Object definitions, and removing an object asset will remove
+// its references as a parent to any of its children.
+await project.removeAssetByName('unwanted_asset_name');
+
+// Create a sound asset from an audio file
+await project.createSound(
+  'folder/subfolder/my_new_sound',
+  '/path/to/source/file.wav',
+);
+
+// Create a sprite asset from an image
+await project.createSprite(
+  'folder/subfolder/sp_my_sprite',
+  '/path/to/source/file.png',
+);
+
+// And so on and so on. You can create new objects, rooms, etc.
+// Each asset is modeled by an Asset instance, which will allow
+// you to do further queries and manipulations (like adding a sprite
+// to a room, or adding a new object event, or setting the code
+// for a script, or adding a sprite to an object, or setting an
+// object's parent, etc)
+
+// Import assets from another project into this one
+await project.import(someOtherProject, {
+  /* import options */
+});
+
+// Sync the project's Included Files with the files found on disk
+await project.syncIncludedFiles();
+
+// Ensure that a discovered asset's yy file is represented
+// by an entry in the project's yyp file. Useful for recovering
+// orphaned assets!
+await project.addAssetToYyp('paty/to/orphaned/resource.yy');
+```