Release 3.0.0

.github/workflows/ci.yml

@@ -16,7 +16,12 @@ jobs:
 
     - uses: actions/setup-dotnet@v3
       with:
-        dotnet-version: '5.0.x'
+        dotnet-version: |
+          5.0.x
+          6.0.x
+          7.0.x
+          8.0.x
+          9.0.x
 
     - name: Build
       run: ./build.sh
@@ -29,7 +34,12 @@ jobs:
 
     - uses: actions/setup-dotnet@v3
       with:
-        dotnet-version: '5.0.x'
+        dotnet-version: |
+          5.0.x
+          6.0.x
+          7.0.x
+          8.0.x
+          9.0.x
 
     - name: Build
       run: |

CHANGELOG.md

@@ -1,3 +1,23 @@
+# 3.0.0
+
+- Fixed potential misinterpretation of fractions in hex numbers (#128)
+- Fixed usage of capital `X` or `B` for hex or binary representations
+- Fixed bug in JSON representation using trailing comma
+- Fixed arithmetic overflow detection for number edge cases (#125) by @josefblaha
+- Improved GC allocations (#81)
+- Added wrapping of `Task` in `Future` (#64)
+- Added octal representation (e.g., `0o123`) for numbers
+- Added insertion points (`_`) to function calls (#129)
+- Added JSX syntax (#120)
+- Added default `jsx` and `html` function (#120)
+- Added events to `Engine` to handle uncaught errors (#121)
+- Added object metadata retrievable via `type` (#49)
+- Added a `randi` function to generate random integers (#124) by @GhostVaibhav
+
+# 2.0.3
+
+- Include checksum in chocolatey package
+
 # 2.0.2
 
 - Fixed vulnerability using outdated version of `System.Drawing.Common` for plugins

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2016-2024 Florian Rappl
+Copyright (c) 2016 - 2025 Florian Rappl
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,30 +1,76 @@
-![MAGES Logo](https://raw.githubusercontent.com/FlorianRappl/Mages/main/logo.png)
+![MAGES Logo](./logo.png)
 
 # MAGES
 
-[![GitHub CI](https://github.com/FlorianRappl/Mages/actions/workflows/ci.yml/badge.svg)](https://github.com/FlorianRappl/Mages/actions/workflows/ci.yml)
-[![NuGet](https://img.shields.io/nuget/v/MAGES.svg?style=flat-square)](https://www.nuget.org/packages/Mages/)
-[![Issues](https://img.shields.io/github/issues/FlorianRappl/MAGES.svg?style=flat-square)](https://github.com/FlorianRappl/Mages/issues)
+[![GitHub CI](https://github.com/FlorianRappl/Mages/actions/workflows/ci.yml/badge.svg)](https://github.com/FlorianRappl/Mages/actions/workflows/ci.yml) [![NuGet](https://img.shields.io/nuget/v/MAGES.svg?style=flat-square)](https://www.nuget.org/packages/Mages/) [![Issues](https://img.shields.io/github/issues/FlorianRappl/MAGES.svg?style=flat-square)](https://github.com/FlorianRappl/Mages/issues)
 
 ## Mages: Another Generalized Expression Simplifier
 
 MAGES is the official successor to [YAMP](https://github.com/FlorianRappl/YAMP). It is a very simple, yet powerful, expression parser and interpreter. You can use MAGES to include a sophisticated, easy to customize, and lightweight scripting engine to your application.
 
-Among other applications, MAGES is used in [Microsoft's PowerToys](https://github.com/microsoft/PowerToys).
+Among other applications, MAGES has been used in [Microsoft's PowerToys](https://github.com/microsoft/PowerToys).
 
 ### Current Status
 
-MAGES was just updated (v2.0.0) with support for complex numbers. Also, the build target and runtime has been updated to make use of modern possibilities.
+**2024**:
+
+MAGES was just updated (v3.0.0) with object metadata, direct list support, and JSX syntax.
+
+JSX as you know it - stringified via `html`:
+
+```plain
+<div class={"hello" + "," + "there"}><h1>Hi</h1><p>World.</p></div> | html
+// result: <div class="hello,there"><h1>Hi</h1><p>World.</p></div>
+```
+
+Object metadata reflected via `type`:
+
+```plain
+new { a: "foo", b: 42 } | type | json
+// {
+//   "name": "Object",
+//   "create": "[Function]",
+//   "keys": {
+//     "0": "a",
+//     "1": "b"
+//   }
+// }
+
+((x, y, z) => x + y + z) | type | json
+// {
+//   "name": "Function",
+//   "create": "[Function]",
+//   "parameters": {
+//     "0": "x",
+//     "1": "y",
+//     "2": "z"
+//   }
+// }
+```
+
+Placeholders for calling functions / specifying what should be curry'ed:
+
+```plain
+var f = (x, y, z) => x + 2 * y + 3 * z;
+5 | f(1, _, 2)
+// 17, by computing 1 + 2 * 5 + 3 * 2
+```
 
 ### Previous Status
 
+**2023**:
+
+MAGES was updated (v2.0.0) with support for complex numbers. Also, the build target and runtime has been updated to make use of modern possibilities.
+
+**2018**:
+
 The first stable version has been released. The current version 1.6.0 contains an improved REPL. The library contains everything to perform lightweight scripting operations in C#. A [CodeProject article](http://www.codeproject.com/Articles/1108939/MAGES-Ultimate-Scripting-for-NET) about the library (also containing some background and performance comparisons) is also available.
 
 ### Installation
 
 MAGES itself does not have any dependencies, however, the tests are dependent on NUnit and the benchmarks use BenchmarkDotNet. Usually, MAGES should be installed via the NuGet package source. If this does not work for you, then clone the source and build MAGES yourself. Make sure that all unit tests pass.
 
-The whole library was designed to be consumed from .NET 3.5 (or higher) applications. This means it is (amongst others) compatible with Unity / Mono 2.6. The NuGet package is available via [the official package feed](https://www.nuget.org/packages/MAGES).
+The whole library was designed to be consumed from .NET Core 3.0 (or higher) / .NET 5.0 (or higher) applications. This means it is (amongst others) compatible with Unity 2021.2 or Mono 6.4. The NuGet package is available via [the official package feed](https://www.nuget.org/packages/MAGES).
 
 ### Get Me Started!
 
@@ -100,12 +146,4 @@ Thanks for all the support and trust in the project!
 
 ## License
 
-The MIT License (MIT)
-
-Copyright (c) 2016-2024 Florian Rappl
-
-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.
+This code is released using the MIT license. For more information see the [LICENSE file](./LICENSE).

build.cake

@@ -36,9 +36,9 @@ if (isRunningOnGitHubActions)
     }
 }
 
-var buildDir = Directory("./src/Mages.Core/bin") + Directory(configuration) + Directory("netstandard2.0");
-var replDir = Directory("./src/Mages.Repl/bin") + Directory(configuration) + Directory("netcoreapp3.1");
-var installerDir = Directory("./src/Mages.Repl.Installer/bin") + Directory(configuration) + Directory("net45");
+var buildDir = Directory("./src/Mages.Core/bin") + Directory(configuration) + Directory("netstandard2.1");
+var replDir = Directory("./src/Mages.Repl/bin") + Directory(configuration) + Directory("net60");
+var installerDir = Directory("./src/Mages.Repl.Installer/bin") + Directory(configuration) + Directory("net50");
 var buildResultDir = Directory("./bin") + Directory(version);
 var nugetRoot = buildResultDir + Directory("nuget");
 var chocolateyRoot = buildResultDir + Directory("chocolatey");
@@ -71,7 +71,10 @@ Task("Restore-Packages")
     .IsDependentOn("Clean")
     .Does(() =>
     {
-        NuGetRestore("./src/Mages.sln");
+        NuGetRestore("./src/Mages.sln", new NuGetRestoreSettings
+        {
+            DisableParallelProcessing = isRunningOnUnix && isRunningOnGitHubActions,
+        });
     });
 
 Task("Update-Assembly-Version")
@@ -123,7 +126,7 @@ Task("Copy-Files")
     .IsDependentOn("Build")
     .Does(() =>
     {
-        var nugetBin = nugetRoot + Directory("lib") + Directory("netstandard2.0");
+        var nugetBin = nugetRoot + Directory("lib") + Directory("netstandard2.1");
         CreateDirectory(nugetBin);
         CreateDirectory(squirrelBin);
         CreateDirectory(releaseDir);
@@ -204,10 +207,11 @@ Task("Create-Squirrel-Package")
     });
 
 Task("Create-Chocolatey-Package")
-    .IsDependentOn("Copy-Files")
+    .IsDependentOn("Create-Squirrel-Package")
     .WithCriteria(() => isRunningOnWindows)
     .Does(() => {
-        var content = String.Format("$packageName = 'Mages'{1}$installerType = 'exe'{1}$url32 = 'https://github.com/FlorianRappl/Mages/releases/download/v{0}/Mages.exe'{1}$silentArgs = ''{1}{1}Install-ChocolateyPackage \"$packageName\" \"$installerType\" \"$silentArgs\" \"$url32\"", version, Environment.NewLine);
+        var checksum = CalculateFileHash(releaseDir.Path.FullPath + "/MagesSetup.exe", HashAlgorithm.SHA256).ToHex();
+        var content = String.Format("$packageName = 'Mages'{1}$installerType = 'exe'{1}$url32 = 'https://github.com/FlorianRappl/Mages/releases/download/v{0}/MagesSetup.exe'{1}$silentArgs = ''{1}$checksum32 = '{2}'{1}{1}Install-ChocolateyPackage -PackageName \"$packageName\" -FileType \"$installerType\" -SilentArgs \"$silentArgs\" -Url \"$url32\" -Checksum \"$checksum32\" -ChecksumType \"sha256\"", version, Environment.NewLine, checksum);
         var nuspec = chocolateyRoot + File("Mages.nuspec");
         var toolsDirectory = chocolateyRoot + Directory("tools");
         var scriptFile = toolsDirectory + File("chocolateyInstall.ps1");
@@ -267,7 +271,7 @@ Task("Publish-GitHub-Release")
             TargetCommitish = isPublish ? "main" : "devel"
         }).Result;
 
-        var target = nugetRoot + Directory("lib") + Directory("netstandard2.0");
+        var target = nugetRoot + Directory("lib") + Directory("netstandard2.1");
         var libPath = target + File("Mages.Core.dll");
         var releaseFiles = GetFiles(releaseDir.Path.FullPath + "/*");
 
@@ -280,11 +284,6 @@ Task("Publish-GitHub-Release")
         {
             var name = System.IO.Path.GetFileName(file.FullPath);
 
-            if (name.Equals("Setup.exe"))
-            {
-                name = "Mages.exe";
-            }
-
             using (var fileStream = System.IO.File.OpenRead(file.FullPath))
             {
                 newRelease.UploadAsset(release, new ReleaseAssetUpload(name, "application/x-msdownload", fileStream, null)).Wait();

doc/functions.md

@@ -261,6 +261,14 @@ Works without any arguments.
 x = rand() // any number between 0 and 1
 ```
 
+### Generate Single Random Integer
+
+Works with one argument.
+
+```
+x = randi(5) // any integer between 0 and 5
+```
+
 ### Generate Random Vector
 
 Works with one argument.
@@ -284,9 +292,9 @@ M = rand(3, 2) // a 3x2 matrix with numbers between 0 and 1
 Works with one argument, which could be anything.
 
 ```
-x = type(true) // "Boolean"
-x = type([1, 2, 3]) // "Matrix"
-x = type("foo") // "String"
+x = type(true).name // "Boolean"
+x = type([1, 2, 3]).name // "Matrix"
+x = type("foo").name // "String"
 ```
 
 ### Checking Types
@@ -397,4 +405,23 @@ Shuffles the arguments of a given function (last argument) by the order of the g
 fab = (a, b) => a * b - b;
 fba = shuffle("b", "a", fab);
 fab(1, 2) - fba(1, 2) // -1
-```
+```
+
+## Stringification
+
+### JSON
+
+Transforms the value into a valid JSON string. Does not stringify functions.
+
+```
+json(new { a: 42, b: "foo" }) // { "a": 42, "b": "foo" }
+```
+
+### HTML
+
+Transforms the value into a valid JSON string. Does only stringify valid JSX objects, numbers, and strings. Strings are automatically HTML-encoded.
+
+```
+"foo<b>ho</b>" | html // foo&lt;b&gt;ho&lt;/b&gt;
+<div class={"foo" + "bar"}>Hi</div> | html // <div class="foobar">Hi</div>
+```

doc/introduction.md

@@ -100,7 +100,7 @@ On starting the REPL we see the following:
           \/         \/        \/        \/        \/
 
   (c) Florian Rappl, 2024
-  Version 2.0.2
+  Version 2.0.3
   Running on Microsoft Windows NT 6.2.9200.0
 
   For help type 'help()'.

doc/language.md

@@ -270,4 +270,44 @@ cos(2.5) == cos()()(2.5)
 
 are therefore equal. In the previous example two calls without any arguments result in the function itself, such that the last call is operating on `cos` itself. Auto currying is applied to any standard function, custom created function (lambda expression), and wrapped .NET function.
 
-Auto currying allows to use functions to create functions without much ceremony and plays great together with the pipe operator, which expects functions requiring only a single argument on the right side.
+Auto currying allows to use functions to create functions without much ceremony and plays great together with the pipe operator, which expects functions requiring only a single argument on the right side.
+
+### Placeholders
+
+Calling a function with parameters supplied as `_` will result in a new function taking the number of used placeholders as arguments.
+
+Example:
+
+```
+var f = (x, y, z) => x + 2 * y + 3 * z
+```
+
+Classically, this could be called like `f(x, y, z)` or with auto-currying like `f(x, y)` or even `f(x)`. But what if we would like to have a function `g(y) = f(x, y, z)`? We would need to define this alias quite explicitly:
+
+```
+var g = (y) => f(1, y, 3)
+```
+
+With the placeholder parameter it can be written such as:
+
+```
+var g = f(1, _, 3)
+```
+
+The big advantage of this is that we get a simple way to pipe things:
+
+```
+4 | f(1, _, 3)
+```
+
+## JSX
+
+XML-like syntax is an integrated part of MAGES. Expressions such as
+
+```
+<div><p style="font-style:italic">hello</p><p>there<br/>said Obi.</p></div>
+```
+
+can just be used and will call the JSX-factory function `jsx`, which (by default, i.e., if not specified otherwise) will result in JSX-objects. These are just ordinary objects, but with a defined set of keys such as `props` and `children`.
+
+You can either use the JSX output to work on the JSX-objects, or you can pass it to a helper function such as `html`. This works well with JSX-objects and transforms it into a valid HTML string - also taking care of things such as HTML escaping.

doc/syntax.md

@@ -28,10 +28,12 @@ A number is the usual suspect:
 ```
 binary_character ::= '0' | '1'
 hex_character ::= digit | [a - f] | [A - F]
+octal_character ::= [0 - 7]
 binary ::= '0' ('b' | 'B') binary_character+
 hex ::= '0' ('x' | 'X') hex_character+
+octal ::= '0' ('o' | 'O') octal_character+
 float ::= digit+ (. digit* (('e' | 'E') sign? digit+)?)?
-number ::= float | binary | hex
+number ::= float | binary | hex | octal
 ```
 
 Boolean primitive values are given by keywords:

src/Directory.Build.props

@@ -3,7 +3,7 @@
     <Product>Mages</Product>
     <Authors>Florian Rappl</Authors>
     <Company>smapiot</Company>
-    <Version>2.0.2</Version>
+    <Version>3.0.0</Version>
     <Copyright>Copyright (c) 2024, Florian Rappl</Copyright>
     <PackageLicenseUrl>https://github.com/FlorianRappl/MAGES/blob/main/LICENSE</PackageLicenseUrl>
     <PackageProjectUrl>https://github.com/FlorianRappl/MAGES/</PackageProjectUrl>

src/Mages.Chocolatey.nuspec

@@ -7,10 +7,11 @@
     <authors>Florian Rappl</authors>
     <owners>FlorianRappl</owners>
     <licenseUrl>https://github.com/FlorianRappl/Mages/blob/main/LICENSE</licenseUrl>
-    <projectUrl>https://github.com/FlorianRappl/Mages</projectUrl>
+    <projectUrl>https://github.com/FlorianRappl/Mages/blob/main/README.md</projectUrl>
     <iconUrl>https://raw.github.com/FlorianRappl/Mages/main/logo.png</iconUrl>
     <releaseNotes>https://github.com/FlorianRappl/Mages/blob/main/CHANGELOG.md</releaseNotes>
     <projectSourceUrl>https://github.com/FlorianRappl/Mages</projectSourceUrl>
+    <packageSourceUrl>https://github.com/FlorianRappl/Mages</packageSourceUrl>
     <docsUrl>https://github.com/FlorianRappl/Mages/tree/main/doc</docsUrl>
     <bugTrackerUrl>https://github.com/FlorianRappl/Mages/issues</bugTrackerUrl>
     <requireLicenseAcceptance>false</requireLicenseAcceptance>