From 6d664739996203fe91bc92d426a5e8702c699a01 Mon Sep 17 00:00:00 2001 From: Qrakhen Date: Fri, 7 Nov 2025 17:23:00 +0100 Subject: [PATCH] add super funny readme as i got nothing else to show for rn --- .gitignore | 1 + Qrakhen.Qamp.Core/Collections/Expander.cs | 13 ++- Qrakhen.Qamp.Core/Execution/Runner.cs | 3 +- Qrakhen.Qamp.Core/README.md | 110 ++++++++++++++++++++++ 4 files changed, 125 insertions(+), 2 deletions(-) create mode 100644 Qrakhen.Qamp.Core/README.md diff --git a/.gitignore b/.gitignore index 2b848cb..05f6a5a 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ Debug/ Release/ +Build/ bin/ obj/ log/ diff --git a/Qrakhen.Qamp.Core/Collections/Expander.cs b/Qrakhen.Qamp.Core/Collections/Expander.cs index 5519184..db0029d 100644 --- a/Qrakhen.Qamp.Core/Collections/Expander.cs +++ b/Qrakhen.Qamp.Core/Collections/Expander.cs @@ -2,7 +2,18 @@ namespace Qrakhen.Qamp.Core.Collections; -public abstract class Expander : IEnumerable, IGetSet, IAdd +/// +/// Expanding Collection based on doubling capacity allocations when adding elements. +/// +/// +/// Not implementing because it expects to return void, +/// and we don't need that here in Q&. +/// +/// +public abstract class Expander : + IEnumerable, + IGetSet, + IAdd { protected T[] Data; diff --git a/Qrakhen.Qamp.Core/Execution/Runner.cs b/Qrakhen.Qamp.Core/Execution/Runner.cs index 580c786..08d9aae 100644 --- a/Qrakhen.Qamp.Core/Execution/Runner.cs +++ b/Qrakhen.Qamp.Core/Execution/Runner.cs @@ -22,7 +22,8 @@ using Op = OpCode; * - make variable operations faster with optimized inline lambda expressions * - better debugging for the instruction set * - Add classic sqript dialect - * - Fix console "IDE" + * - Fix console "IDE" + * - Split Runner, Digester and Core into separate projects */ /// diff --git a/Qrakhen.Qamp.Core/README.md b/Qrakhen.Qamp.Core/README.md new file mode 100644 index 0000000..9965296 --- /dev/null +++ b/Qrakhen.Qamp.Core/README.md @@ -0,0 +1,110 @@ +# Q& +###### ~by Qrakhen + +## About + +A single-pass byte code interpreter with the ability to pre-compile executables +into a format that can be efficiently executed by the runtime. +It serves many features, which are listed a bit further down below. + +This would have officially been the fourth iteration of my language (sqript4), +but I thought I'd stop with the numbers as people would ask what happened to the +previous three languages. + +Q& (or Qamp for Q Ampersand) was originally made for my contributions to the +Advent Of Code 2025, but I thought it's a nice and stable enough concept to be +sharing it to the public anyway. + +## Usage + +To build Q&, you need nothing more than a C# compiler that supports .NET10. +There are .NET8 compatible versions available, but they are not recommended, +as Q& utilizes all of the performance optimizations .NET10 has to offer. + +After cloning, a simple `dotnet build ./` in the root directory will suffice. + +You can execute pre-compiled .sqi files using `qamp.runtime.exe [parameters]`, +or the REPL/CLI using `qamp.cli.exe [parameters]`. +If you want to build your own source into pre-compiled instruction files, +use `qamp.digest.exe ` - the digester will look for an `Init()` function +declared in any of the files, and build the instructions from there. + +## Language & Syntax + +You are free to choose between the classic sqript-style dialect `*~ q <~ 0xf;` or +the standard dialect, which is strongly inspired by the C# standard: `var q = 0xf;`. + +All of the following examples are written in the classic dialect `--dialect=sqr` or `-d=q`. + +### Syntax + +Most basic Usage: +``` +# This is a comment. +*~ q <~ 12; +*~ f <~ (n) <: n < 2 ? n : f(n-1) + f(n-2); +``` + +### Assignments + +Q& has two distinct ways to assign a value to a variable: By reference `<&` or by value `<=`. +Using the auto-assignment operator `<~` will choose the correct assignment based on what +type the right-hand expression consists of. +Primitive types will be assigned by value, any object values will be assigned by reference. +This is strongly inspired by the behaviour that most interpeters implement. + +#### What happens if... +##### I assign an object by value? +The entire object will be deep-copied and transfered to the new location. +See it as a free clone method on basically anything that is considered an object. +##### I assign a primitive by reference? +So, assuming that `x` is a primitive (value type), given the instruction `*~ y <& x;`, +`y` will be assigned as a reference value _pointing_ to the location of `x` - somewhat like a +pointer in C, but a little smarter. +##### I do not praise the god emperor of mankind? +You will be duly punished. + +#### Variable Declaration + +``` +*~ q <~ 0xf; +``` + +#### Variable Declaration + +## Customization & Extras + +Some more information about extending and customizing Q& to your needs. + +### Implementing external Libraries + +Implementation is easy. +Q& is written in C#, and supports basically anything you can wrap in C#. +All you have to do in order to implement a library is referencing the SDK dll +which should be located within your `./Build/` folder after building as described above. + +Here's a quick example of how you would implement virtually any library: +```cs +using Qrakhen.Qamp.Core; +using System.Linq; + +Value Sqrt(Value number) +{ + Assert.IsNumber(number); + + if (number.IsDecimal) + return Math.Sqrt(number.AsDecimal); + if (number.IsSigned) + return Math.Sqrt(number.AsSigned); + if (number.IsUnsigned) + return Math.Sqrt(number.Unsigned); + throw new Qrakhen.Qamp.Core.QampException($"Unsupported value type {value}"); +} + +Injector injector = new(); +injector.Register(scope: Scope.Global, name: "sqrt", params: [ ("number", ValueType.Number) ], returns: ValueType.Number); +injector.Export("desiredPath.sqi"); +``` +That's it - although this being a very simple example, more is possible. +I will add a few basic implementations of very common libraries in a separate repository soon. +