C# API For EZCode

C# API For EZCode
- Example Project
EZCodeLanguage.EZCode
EZCodeLanguage.Debug
- Debug.Breakpoint
EZCodeLanguage.Interpreter
EZCodeLanguage.Parser
EZCodeLanguage.PackageClass
EZCodeLanguage.Package
EZCodeLanguage.PackageClass
EZCodeLanguage.Projects
EZCodeLanguage.EZHelp

The API for EZCode is supposed to be as straightforward as possible and easy to incorporate into your project. You'll need to add the nuget package to your project, or clone the repository and add it as a dependency to your project.

dotnet add package EZCode

To include it in the file, use, using EZCodeLanguage.

Example Project

using EZCodeLanguage;

public class Program
{
    public static void Main(string[] args)
    {
        var code = """
            include main

            int x new : 50
            int y new : 100

            print '(x * y)'
            """;
        EZCode.RunCode(code);
        // outputs 5000
    }
}

EZCodeLanguage.EZCode

This class is the easiest way to add EZCode to your project.

// Run and execute EZCode file  
EZCode.RunFile("path/to/file.ezcode")

// Run EZCode file with the 'main' package automatically included 
EZCode.RunFileWithMain("path/to/file.ezcode")

// Debug an EZCode file by adding breakpoints with: Debug.Breakpoint[] 
// new Parser.Line("line_content", NUMBER, "file");
// var line = parser.TokenWithLines[1]; // assuming 'parser' is instance of Parser
EZCode.DebugFile([new Breakpoint(line)], "path/to/file.ezcode")

// Run code without a file
// 'path' is optional parameter
EZCode.RunCode("code")
EZCode.RunCode("code", path:"Running from inside program")

// Run code with the 'main' package automatically included 
// 'path' is optional parameter
EZCode.RunCodeWithMain("code")
EZCode.RunCodeWithMain("code", path:"Running from inside program")

// Debug an EZCode code by adding breakpoints with: Debug.Breakpoint[] 
// new Parser.Line("line_content", NUMBER, "file");
// var line = parser.TokenWithLines[1]; // assuming 'parser' is instance of Parser
// 'path' is optional parameter
EZCode.DebugCode([new Breakpoint(line)], "path/to/file.ezcode", path:"Running from inside program")

// Run and execute a Project
// input path and directory into function
// You can use: EZCode.RunProject(path, Path.GetDirectoryName(path));
EZCode.RunProject("directory/project.json", "directory/")

// Debug an EZCode Project by adding breakpoints with: Debug.Breakpoint[] 
// input breakpoints, path, and directory into function
// You can use: EZCode.DebugProject(breakpoints, path, Path.GetDirectoryName(path));
EZCode.DebugProject(breakpoints, "path/to/file.ezcode", path:"Running from inside program")

EZCodeLanguage.Debug

Static class used for debugging in the interpreter

var interpreter = /*Interpreter Class*/;
var line = interpreter.CurrentLine;
var breakpoints = [
    new Breakpoint(line)
];

// Check if Breakpoint is hit.
// Returns boolean depending on if hit or not
IsHit(line, breakpoints, interpreter)

Debug.Breakpoint

public class Breakpoint
{
    // Required:
    public Line Line { get; set; }
    // Optional:
    public bool Enabled { get; set; }
    public bool DisableWhenHit { get; set; }
    public string? EZCodeConditionToHit { get; set; }
    public string? EZCodeActionWhenHit { get; set; }
    public Breakpoint? EnabledWhenBreakpointIsHit { get; set; }
    public bool Hit { get; set; }
    // Constructor:
    public Breakpoint(Line line, bool enabled = true, bool disableWhenHit = false,
        string? ezcodeConditionToHit = null, string? ezcodeActionWhenHit = null, 
        Breakpoint? enabledWhenBreakpointIsHit = null)
    {
        Line = line;
        Enabled = enabled;
        DisableWhenHit = disableWhenHit;
        EZCodeConditionToHit = ezcodeConditionToHit;
        EZCodeActionWhenHit = ezcodeActionWhenHit;
        EnabledWhenBreakpointIsHit = enabledWhenBreakpointIsHit;
    }
}

EZCodeLanguage.Interpreter

This class is used to interpret parsed EZCode.

new Interpreter(parser, /*optional for debugging:*/ breakpoints)

Setting it up

var parser = /*set up parser*/;
var interpreter = new Interpreter(parser);
/* Set up Input Type (Optional):
 * interpreter.InputType = EZInputType.Console; // default
 * //                    = EZInputType.InputMethod; // needs SetInput()
 * // SetInput("input") // Input for 'input' method 
 */
interpreter.Interperate();

Properties

// Instance of EZCode used with EZHelp
public static Interpreter Instance { get; private set; }

public string[] Output; // Console output from execution

public enum EZInputType { Console, InputMethod } // Type of input
public EZInputType InputType { get; set; } = EZInputType.Console; // Input type, sets default to Console

// For debugging. Used to continue when a break point is hit. Set it to true for that
public bool ContinuedForBreakpoint = false;

// The Parser used in the interpreting
public Parser parser { get; private set; }

public EZHelp EZHelp { get; private set; } // The EZHelp instance

// Don't mess with.
// Used for including EZCode Packages that have custom dll
public CustomAssemblyLoadContext[] LoadedAssemblies = [];

public Stack<string> StackTrace { get; private set; } // Stacktrace

public Exception[] Errors { get; private set; } = []; // Errors that have occured in the script

public Var[] Vars { get; set; } = []; // Array of variables that are in the scope of the current line in the interpreter

public Method[] Methods { get; set; } = []; // Array of methods that are in the scope of the current line in the interpreter

public Class[] Classes { get; set; } = []; // Array of classes that are in the scope of the current line in the interpreter

public Debug.Breakpoint[]? Breakpoints { get; set; } // Debug Breakpoints for the interpreter

public Line CurrentLine { get; private set; } // current line being executed in the interpreter

Methods and Functions

// This would be used if the environment that EZCode is running on does not have a console.
// This could be used in a method that gets called when a user types the input somewhere and clicks send
// It would call this method with the input like this:
/* public Send_Clicked() 
 * {
 *     SetInput(InputTextBox.Text);
 * }
 */
// Used for the EZCode method 'input' in the main package
public void SetInput(string input, EZInputType inputType = EZInputType.InputMethod)

// Start Interpreting  
public void Interperate()

// Start Interpreting with custom LineWithToken array and not the parser.LinesWithTokens
public void Interperate(LineWithTokens[] LineTokens)

// InvokeMethod is a function that invokes a method from the 'methodPath' and 'parameters'
// var methodPath = "System.Console.WriteLine";
// var parameters = ["Hello World"];
// Interpreter.InvokeMethod(methodPath, parameters, new EZHelp(), out _)
public static object? InvokeMethod(string methodPath, object[] parameters, EZHelp e, out CustomAssemblyLoadContext? assemblyContext)

Events

// This event gets called when the output is wrote to with the Output property
public event EventHandler OutputWrote;

// This event gets called when the output is cleared
public event EventHandler OutputCleared;

Interpreter.CustomAssemblyLoadContext

Empty class used for EZCode Packages that include custom dll's

public class CustomAssemblyLoadContext: AssemblyLoadContext
{
    public CustomAssemblyLoadContext() : base(isCollectible: true) { }
    protected override Assembly Load(AssemblyName assemblyName) => null;
}

EZCodeLanguage.Parser

This class is used to Parse from string EZCode to LineWithToken[]

new Parser(code, filePath)

Setting it up

With a FileInfo Instance

// create FileInfo
var file = "C:/file.ezcode";
var fileInfo = new FileInfo(file);

// set up parser
var parser = new Parser(fileInfo);

With code and filepath

// set up path and code
var path = "C:/file.ezcode";
var code = "print Hello World";

// set up parser
var parser = new Parser(code, path);

Properties

// seperating chars that seperate tokens
public static char[] Delimeters = [' ', '{', '}', '@', ':', ',', '?', '!'];

// the code property that gets parsed
public string Code { get; private set; }

// the filepath property that goes with the Lines
public string FilePath { get; set; }

// the list of classes found in the code property
public List<Class> Classes = [];

// the list of methods found in the code property
public List<Method> Methods = [];

// the list of line with tokens found in the code property
public List<LineWithTokens> LinesWithTokens = [];

Enum

The Enum for Token Types that are all the available types

public enum TokenType
{
    None, Null, Comment, Comma, QuestionMark, Colon, Arrow, DataType,
    OpenCurlyBracket, CloseCurlyBracket, New, If, Else, Elif, Loop, Try, Fail,
    Argument, Identifier, Undefined, Class, Explicit, Alias, Watch, Params,
    TypeOf, NoCol, Method, Match, Break, Yield, Return, Get, And, Not, Or, Make,
    RunExec, EZCodeDataType, Include, Exclude, Global, True, False, Throw, Dispose, 
}

Classes

Token

The class for tokens

public class Token
{
    public TokenType Type { get; set; }
    public object Value { get; set; }
    public string StringValue { get; set; }
    public Token(TokenType type, object value, string stringValue)
    {
        Type = type;
        Value = value;
        StringValue = stringValue;
    }
}

Line

The class for lines

public class Line
{
    public string Value { get; set; }
    public int CodeLine { get; set; }
    public string FilePath { get; set; }
    public Line(string value, int codeLine, string file)
    {
        FilePath = file;
        Value = value;
        CodeLine = codeLine;
    }
}

There are many others, they can be found in EZCode/Parser.cs

Here is a list,

LineWithTokens
Argument
Statement
DataType
ExplicitWatch
ExplicitParams
RunMethod
GetValueMethod
Class
Var
CSharpMethod
CSharpDataType

EZCodeLanguage.PackageClass

This is the equivelent for the JSON package

public class PackageClass
{
    public string Name { get; set; }
    public string[] Files { get; set; }
    public Config? Configuration { get; set; }
    public class Config
    {
        public string? LibraryDirectory { get; set; }
        public string[]? GlobalPackages { get; set; }
    }
}

EZCodeLanguage.Package

This is a static class for Packages

// Where the Package Directory is located:
// C:\Users\%USER%\EZCodeLanguage\Packages\
public static string PackagesDirectory;

// This adds an EZCode Package into the Execution directory (used for importing dll into program). 
public static void AddPackageToExecutionDirectory(PackageClass project, string executionDirectory)

// This removes an EZCode Package from the Execution directory (used for removing imported dll from program). 
public static void RemovePackageFromExecutionDirectory(PackageClass project, string executionDirectory)

// This removes all EZCode Package from the Execution directory (used for removing imported dll from program). 
public static void RemoveAllPackagesFromExecutionDirectory(string executionDirectory)

// Gets package directory from a package name
public static string GetPackageDirectory(string package_name)

// Gets package file from a package name
public static string GetPackageFile(string package_name)

// Gets package from package name
public static PackageClass GetPackageAsProject(string package_name)

// Gets parser from package name
public static Parser GetPackageAsParser(string package_name)

// Returns a parser with packages:
// parser = /*Parser Instance*/;
// parser = Parser.ReturnParserWithPackages(parser, ["main", "time"])
public static Parser ReturnParserWithPackages(Parser parser, string[] package_names)

// Removes a parser from a parser
public static Parser RemovePackageFromParser(Parser main_parser, Parser remove)

// Combines parsers into a single parser
public static Parser CombineParsers(Parser[] parsers)

// Combines parsers into a single parser
public static Parser CombineParsers(Parser parser, Parser p2)

EZCodeLanguage.PackageClass

This is the equivelent for the JSON Project

public class ProjectClass
{
    public string Name { get; set; }
    public string[] Files { get; set; }
    public string[]? GlobalPackages { get; set; }
}

EZCodeLanguage.Projects

This is a static class for Projects

// Returns a project from a file
public static ProjectClass GetProjectFromPath(string path)

// Returns a parser from a project
public static Parser GetParserFromProject(ProjectClass project, string directory)

// Returns a parser that includes a the global packages in the project
public static Parser IncludeGlobalPackages(Parser parser, ProjectClass project)

// Runs and executes the EZCode Project
public static void Run(ProjectClass project, string directory)

EZCodeLanguage.EZHelp

The Api for making a package is in the package docs

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

API.md

API.md

C# API For EZCode

Example Project

EZCodeLanguage.EZCode

EZCodeLanguage.Debug

Debug.Breakpoint

EZCodeLanguage.Interpreter

Setting it up

Properties

Methods and Functions

Events

Interpreter.CustomAssemblyLoadContext

EZCodeLanguage.Parser

Setting it up

Properties

Enum

Classes

EZCodeLanguage.PackageClass

EZCodeLanguage.Package

EZCodeLanguage.PackageClass

EZCodeLanguage.Projects

EZCodeLanguage.EZHelp

Files

API.md

Latest commit

History

API.md

File metadata and controls

C# API For EZCode

Example Project

EZCodeLanguage.EZCode

EZCodeLanguage.Debug

Debug.Breakpoint

EZCodeLanguage.Interpreter

Setting it up

Properties

Methods and Functions

Events

Interpreter.CustomAssemblyLoadContext

EZCodeLanguage.Parser

Setting it up

Properties

Enum

Classes

EZCodeLanguage.PackageClass

EZCodeLanguage.Package

EZCodeLanguage.PackageClass

EZCodeLanguage.Projects

EZCodeLanguage.EZHelp