@acristoffers/tree-sitter-matlab 1.2.4

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2023 Álan Crístoffer
+
+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,97 @@
+# MATLAB grammar for tree-sitter.
+
+There are screenshots at the end of this README :)
+
+This parser has the objective of generating a tree that is as correct as
+possible (but sometimes just convenient) with what MATLAB itself executes. It
+is not intended only for syntax highlight, but also to be used by scripts to
+whatever it may be needed. In fact, I wrote it because I'm a Neovim/Doom Emacs
+user and love having text-objects, and was really missing a text object for
+matrices rows/cells.
+
+Being as correct as possible means that some things are done correctly, for
+example:
+
+- Commands are parsed the same way MATLAB does it, by treating arguments as
+literals, grouping them correctly and only starting comments when allowed. It
+should perfectly match what MATLAB does.
+
+- Assignment has its own token, and multiple-variable assignment is NOT an
+assignment to a matrix (and returning an error is the correct thing to do, as
+it allows the user to see that something is off with the highlight, meaning
+something is probably off with the code):
+
+```matlab
+% (assignment (multioutput_variable (identifier) (identifier)) (identifier))
+[a,b] = d
+
+% this is WRONG:
+[a;b] = d
+```
+
+- Inside a matrix, `1 + 1` and `1 +1` are different things:
+
+```matlab
+a = 1 + 1 % 2
+a = 1 +1 %2
+[1 + 1] == [2]
+[1 +1]  == [1 1]
+```
+
+Being convenient means that sometimes the difference between what is acceptable
+and what is not acceptable lives in the semantics, so we can't know. In such
+cases I just accept semantically wrong but syntax correct things and group them
+in the same token (first example). I do the same when the overhead of
+generating a specific token would not really pay off (second example).
+
+- Function calls and Matrix Indexing are the same in MATLAB: `A(1)` can be any
+of them and you cannot tell them apart unless you know for sure what `A` is
+referring to. So for convenience I just generate a `function_call` for them and
+also for cell indexing `A{1}`. The "problem" with that is that this is a valid
+indexing but an invalid function call: `A(:)`. However I don't distinguish at
+all and say that all of them are `function_call`.
+
+- Function definitions, when inside a class, accepts a special syntax for the
+name of the function, allowing it to be preceded by either `get.` or `set.`,
+like `function get.name()`. I could have a `method_definition` that would allow
+that to only be valid in the class context, but I doubt that would be worth it.
+So any function anywhere can have those and be recognize as correct still.
+Given the existence of external method definition, maybe that is even the
+correct thing to do, since we don't know if the current file is inside a
+special class folder.
+
+# Known problems
+
+Newlines, just like whitespaces, are mostly ignored. In the case of spaces, it
+allows `abs( a )` and `abs(a)` to be described by the same, simple rule. In the
+case of newlines, it allows many multiline constructs (like, `if`, `while`,
+`function`) to be expressed the same way.
+
+This creates the undesired side-effect that some constructs, which are not
+accepted by MATLAB, are correctly parsed, like:
+
+```matlab
+function (
+  a
+)
+end
+```
+
+This, however, is hard to fix. The assumption that newlines are ignored by
+default is all over the grammar and changing it requires making changes to too
+many rules, which also make them all more complex and fragile. Therefore, this
+change won't be made.
+
+# Installation
+
+This parser is now the default for the following editors:
+
+- Emacs: Through the `tree-sitter-langs` package.
+- Helix: Builtin, now in master and will be available in the next release (whatever comes after 23.05).
+- Neovim: Through the `nvim-treesitter` plugin.
+
+# Screenshots
+
+![First Screenshot](https://raw.githubusercontent.com/acristoffers/tree-sitter-matlab/screenshots/s1.png)
+![Second Screenshot](https://raw.githubusercontent.com/acristoffers/tree-sitter-matlab/screenshots/s2.png)
+![Third Screenshot](https://raw.githubusercontent.com/acristoffers/tree-sitter-matlab/screenshots/s3.png)

package/binding.gyp

@@ -0,0 +1,35 @@
+{
+  "targets": [
+    {
+      "target_name": "tree_sitter_matlab_binding",
+      "dependencies": [
+        "<!(node -p \"require('node-addon-api').targets\"):node_addon_api_except",
+      ],
+      "include_dirs": [
+        "src",
+      ],
+      "sources": [
+        "bindings/node/binding.cc",
+        "src/parser.c",
+      ],
+      "variables": {
+        "has_scanner": "<!(node -p \"fs.existsSync('src/scanner.c')\")"
+      },
+      "conditions": [
+        ["has_scanner=='true'", {
+          "sources+": ["src/scanner.c"],
+        }],
+        ["OS!='win'", {
+          "cflags_c": [
+            "-std=c11",
+          ],
+        }, { # OS == "win"
+          "cflags_c": [
+            "/std:c11",
+            "/utf-8",
+          ],
+        }],
+      ],
+    }
+  ]
+}

package/bindings/node/binding.cc

@@ -0,0 +1,19 @@
+#include <napi.h>
+
+typedef struct TSLanguage TSLanguage;
+
+extern "C" TSLanguage *tree_sitter_matlab();
+
+// "tree-sitter", "language" hashed with BLAKE2
+const napi_type_tag LANGUAGE_TYPE_TAG = {
+    0x8AF2E5212AD58ABF, 0xD5006CAD83ABBA16
+};
+
+Napi::Object Init(Napi::Env env, Napi::Object exports) {
+    auto language = Napi::External<TSLanguage>::New(env, tree_sitter_matlab());
+    language.TypeTag(&LANGUAGE_TYPE_TAG);
+    exports["language"] = language;
+    return exports;
+}
+
+NODE_API_MODULE(tree_sitter_matlab_binding, Init)

package/bindings/node/binding_test.js

@@ -0,0 +1,9 @@
+const assert = require("node:assert");
+const { test } = require("node:test");
+
+const Parser = require("tree-sitter");
+
+test("can load grammar", () => {
+  const parser = new Parser();
+  assert.doesNotThrow(() => parser.setLanguage(require(".")));
+});

package/bindings/node/index.d.ts

@@ -0,0 +1,27 @@
+type BaseNode = {
+  type: string;
+  named: boolean;
+};
+
+type ChildNode = {
+  multiple: boolean;
+  required: boolean;
+  types: BaseNode[];
+};
+
+type NodeInfo =
+  | (BaseNode & {
+      subtypes: BaseNode[];
+    })
+  | (BaseNode & {
+      fields: { [name: string]: ChildNode };
+      children: ChildNode[];
+    });
+
+type Language = {
+  language: unknown;
+  nodeTypeInfo: NodeInfo[];
+};
+
+declare const language: Language;
+export = language;

package/bindings/node/index.js

@@ -0,0 +1,11 @@
+const root = require("path").join(__dirname, "..", "..");
+
+module.exports =
+  typeof process.versions.bun === "string"
+    // Support `bun build --compile` by being statically analyzable enough to find the .node file at build-time
+    ? require(`../../prebuilds/${process.platform}-${process.arch}/tree-sitter-matlab.node`)
+    : require("node-gyp-build")(root);
+
+try {
+  module.exports.nodeTypeInfo = require("../../src/node-types.json");
+} catch (_) {}