add super funny readme as i got nothing else to show for rn

This commit is contained in:
Qrakhen 2025-11-07 17:23:00 +01:00
parent 47dcc24e1e
commit 6d66473999
4 changed files with 125 additions and 2 deletions

1
.gitignore vendored
View File

@ -1,5 +1,6 @@
Debug/
Release/
Build/
bin/
obj/
log/

View File

@ -2,7 +2,18 @@
namespace Qrakhen.Qamp.Core.Collections;
public abstract class Expander<T> : IEnumerable<T>, IGetSet<long, T>, IAdd<long, T>
/// <summary>
/// Expanding Collection based on doubling capacity allocations when adding elements.
/// </summary>
/// <remarks>
/// Not implementing <see cref="IList{T}"/> because it expects <see cref="Add"> to return void,
/// and we don't need that here in Q&.
/// </remarks>
/// <typeparam name="T"></typeparam>
public abstract class Expander<T> :
IEnumerable<T>,
IGetSet<long, T>,
IAdd<long, T>
{
protected T[] Data;

View File

@ -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
*/
/// <summary>

110
Qrakhen.Qamp.Core/README.md Normal file
View File

@ -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 <filepath> [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 <dirpath>` - 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.