implement missing libraries

.fvmrc

@@ -1,3 +1,3 @@
 {
-  "flutter": "3.29.3"
+  "flutter": "3.32.8"
 }

.github/workflows/docs.yaml

@@ -0,0 +1,38 @@
+name: Update Docs
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  update_docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: 📚 Checkout code
+        uses: actions/checkout@v3
+
+      - name: 🐦 Set up Dart
+        uses: dart-lang/setup-dart@v1
+        with:
+          sdk: stable
+
+      - name: 📦 Install dependencies
+        run: dart pub get
+
+
+      - name: 📖 Generate documentation
+        run: dart bin/doc.dart
+
+      - uses: fregante/setup-git-user@v2
+      - name: 📤 Commit and push changes
+        run: | 
+            if [ -z "$(git status --porcelain)" ]; then
+              echo "No changes to commit."
+              exit 0
+            fi
+            git commit -am "docs: update documentation [skip ci]"
+            git push
+
+
+

.github/workflows/report.yaml

@@ -1,4 +1,5 @@
-
+name: Report Test Results
+
 on:
   workflow_run:
     workflows: ["Unit Tests"]
@@ -22,8 +23,6 @@ jobs:
             name: 🧪 Unit Tests
             path: test-results.json
             reporter: dart-json
-            fail-on-empty: true
-            fail-on-error: true
             max-annotations: 50
 
 

.github/workflows/tests.yaml

@@ -37,7 +37,7 @@ jobs:
 
       - name: 📝 Check Test Results
         run: |
-          if grep -q '"result":"failure"' test-results.json; then
+          if grep -q '"result":"error"' test-results.json; then
             echo "❌ Tests failed"
             exit 1
           fi

.gitignore

@@ -11,3 +11,4 @@
 *.interp
 *.tokens
 coverage/
+custom_lint.log

.versionrc

@@ -22,5 +22,14 @@
     ],
     "packageFiles": [
         "pubspec.yaml"
-    ]
+    ],
+    "parserOpts": {
+        "noteKeywords": [
+            "BREAKING CHANGE",
+            "BREAKING CHANGES",
+            "BREAKING",
+            "BREAKING-CHANGE",
+            "BREAKING-CHANGES"
+        ]
+    }
 }

.vscode/settings.json

@@ -1,10 +1,11 @@
 {
-  "dart.flutterSdkPath": ".fvm/versions/3.29.3",
+  "dart.flutterSdkPath": ".fvm/versions/3.32.8",
   "conventionalCommits.scopes": [
     "analyzer",
     "compiler",
     "runtime",
-    "vm"
+    "vm",
+    "stdlib"
   ],
   "conventionalCommits.autoCommit": false,
   "conventionalCommits.gitmoji": false,

README.md

@@ -6,36 +6,15 @@ A lightweight [Domain-Specific Language (DSL)](https://en.wikipedia.org/wiki/Dom
 
 ---
 
-## Getting Started
-
-Define a script:
-
-```dscript
-author "You";
-version 0.1.0;
-name "Example";
+## Motivation
 
-description "demo";
+For many applications I've built, I wished it was possible for users to extend the app with custom code, such as plugins or scripts. However, during my research I found out that dart does not support dynamic code execution like C# or Java using DLLs or JARs. A different approach would be to have plugins exist as seperate executables and communicate with the main app via grpc, but this would expose the app to severe security risks, as the plugin could do anything it wants once the executable is running.
 
-contract Demo {
-  impl greet(string who) -> void {
-    log::info("Hello " + who);
-  }
-}
-```
+So I looked at [lua_dardo](https://pub.dev/packages/lua_dardo) and [dart_eval](https://pub.dev/packages/dart_eval) to see if I could use them to run scripts, but they were not suitable for my use case as lua lacked the strong permission system I wanted, and dart_eval seemed to have too much boilerplate for my taste. After long consideration and hesitation, I decided to create my own DSL that would be easy to use, have a strong permission system, and with strong interop with Dart code (it was also a good opportunity to learn about writing parsers and interpreters).
 
-Register the contract in your host app:
-
-```dart
-final demo = contract('Demo')
-  .impl('greet', returnType: PrimitiveType.VOID)
-  .param('who', PrimitiveType.STRING)
-  .describe("Greets someone")
-  .end()
-  .build();
-```
+## Getting Started
 
-For full documentation see the [docs](https://mcquenji.github.io/dscript).
+The documentation can be found [here](https://mcquenji.github.io/dscript).
 
 ## Contributing
 

analysis_options.yaml

@@ -28,6 +28,8 @@ linter:
 analyzer:
   exclude:
     - lib/src/gen/antlr/**
+  plugins:
+    - custom_lint
 # For more information about the core and recommended set of lints, see
 # https://dart.dev/go/core-lints
 

bin/doc.dart

@@ -0,0 +1,162 @@
+import 'dart:io';
+import 'package:dscript_dart/dscript_dart.dart';
+
+void main() async {
+  final sb = StringBuffer();
+
+  sb.writeln('# Standard Library');
+  sb.writeln();
+  // Generate Table of Contents
+  sb.writeln();
+  final libraries = LibraryBinding.stdLib();
+  for (final lib in libraries) {
+    final anchor = _toAnchor(lib.name);
+    sb.writeln('- [${lib.name}](#$anchor)');
+  }
+  sb.writeln('---');
+
+  sb.writeln();
+  sb.writeln('## Globals');
+  sb.writeln();
+  sb.writeln(
+    'The following globals are available in the dscript runtime. They are not part of any library.',
+  );
+  sb.writeln();
+  sb.writeln();
+
+  sb.writeln('| Name | Type | Value |');
+  sb.writeln('| --- | --- | --- |');
+
+  for (final glob in TypeScope.globals.entries) {
+    sb.writeln('| ${glob.key} | `${glob.value.$2}` | ${glob.value.$1} |');
+  }
+
+  sb.writeln();
+
+  sb.writeln('## Structs');
+
+  for (final struct in Struct.defaults) {
+    sb.writeln();
+    sb.writeln('### ${struct.name}');
+    sb.writeln();
+    sb.writeln(struct.description?.docstring);
+    sb.writeln();
+
+    if (struct.fields.isNotEmpty) {
+      sb.writeln('| Field | Type |');
+      sb.writeln('| --- | --- |');
+      for (final field in struct.fields.entries) {
+        sb.writeln('| ${field.key} | `${field.value}` |');
+      }
+    } else {
+      sb.writeln('This struct has no fields.');
+    }
+  }
+
+  sb.writeln();
+  sb.writeln();
+
+  // Document each library
+  for (final lib in libraries) {
+    sb.writeln();
+    sb.writeln('---');
+    sb.writeln();
+    sb.writeln(_documentLibrary(lib));
+  }
+
+  final output = sb.toString();
+  final file = File('docs/language/standard-library.md');
+  await file.writeAsString(output);
+}
+
+String _toAnchor(String text) {
+  return text
+      .trim()
+      .toLowerCase()
+      .replaceAll(RegExp(r'[^a-z0-9\s-]'), '')
+      .replaceAll(RegExp(r'\s+'), '-');
+}
+
+String _documentLibrary(LibraryBinding lib) {
+  final sb = StringBuffer();
+
+  sb.writeln('## ${lib.name}');
+  sb.writeln();
+  sb.writeln(lib.description.docstring);
+  sb.writeln();
+
+  for (final binding in lib.bindings) {
+    sb.writeln(_documentBinding(binding));
+    sb.writeln();
+  }
+
+  return sb.toString();
+}
+
+String _documentBinding(RuntimeBinding binding) {
+  final sb = StringBuffer();
+
+  // Binding Header with anchor
+  sb.writeln('### ${binding.name} → `${binding.returnType}`');
+
+  // Combine positional and named params in one table
+  final params = <Map<String, dynamic>>[];
+  for (var i = 0; i < binding.positionalParams.length; i++) {
+    final p = binding.positionalParams.entries.elementAt(i);
+    params.add(
+      {'name': p.key, 'type': p.value, 'kind': 'Positional (${i + 1})'},
+    );
+  }
+  for (final entry in binding.namedParams.entries) {
+    final name = entry.key
+        .toString()
+        .substring('Symbol("'.length, entry.key.toString().length - 2);
+    params.add({
+      'name': name,
+      'kind': 'Named',
+      'type': entry.value.toString(),
+    });
+  }
+
+  if (params.isNotEmpty) {
+    sb.writeln();
+    sb.writeln('| Name | Type | Kind |');
+    sb.writeln('| --- | --- | --- |');
+    for (final p in params) {
+      sb.writeln('| ${p['name']} | `${p['type']}` | ${p['kind']} |');
+    }
+  }
+
+  if (binding.description != null && binding.description!.isNotEmpty) {
+    final description = binding.description!.docstring;
+
+    if (description.contains('\n')) {
+      final summary = description.split('\n').first;
+      final details = description.substring(summary.length).trim();
+      sb.writeln('<details>');
+      sb.writeln('<summary><em>$summary</em></summary>');
+      sb.writeln('<em>$details</em>');
+      sb.writeln('</details>');
+      sb.writeln('<br>');
+    } else {
+      sb.writeln();
+      sb.writeln('<em>$description</em>');
+    }
+  }
+
+  if (binding.permissions.isNotEmpty) {
+    sb.writeln();
+    sb.writeln('#### Permissions');
+    sb.writeln();
+    sb.writeln(binding.permissions.map((p) => '`$p`').join(', '));
+  }
+
+  return sb.toString();
+}
+
+extension on String {
+  String get docstring => trim().replaceAllMapped(
+        RegExp(r'\[([^\]]+)\]'),
+        (m) => '<code>${m.group(1)}</code>',
+      );
+}