library.md

Embedding h4x in your own projects

First you need to put the h4x folder in your project folder. idk how to install it system wide maybe ill upload it to pip someday

After that you need to import h4x

import h4x

Then you need to create scopes, thats a just list of dictionaries with all the variables.

scopes = h4x.create_scopes()

Import the standard library with the basic functions (if, +, define). If you want you can use your own if you want to limit access to certain functions. the h4x.import_module function takes a list scopes (dictionaries) and imports the second argument into it. h4x.import_module(scopes[0], "my.modules") TODO i need to update this with the new module import system

h4x.import_stdlib(scopes)

Then you parse whatever program you want to run. (technically it does the tokenizing and the parsing see parsing)

parsed_program = h4x.parse(program)

After you can just evaluate that tree

h4x.eval(parsed_program, scopes)

If theres an error while evaluating/parsing/tokenizing it will raise a h4x.error.H4xError, I reccomend putting that in a try/except block to not have ugly python error msg

Notes

parsing

If you want more control you can call the h4x.tokenize on your program, then call h4x.tokens_to_tree on the tokens returned by tokenize. Also you can validate a token list by calling h4x.parse.is_valid_program(tokens)

modules/importing

Modules are just python files with an exports dictionary which will be merged with the top scope. Each key is the name of the variable and its value is an instance of the classes in h4x.datatypes.

Mecause it uses python importing it doesnt work if you try to import say numpy or sys

creating a module 101

Let's make a module called foo with a function foo:bar which prints baz. Create a file "foo.py" and put it in the same folder as the file that runs h4x.eval

import h4x

exports = {}
def func_bar(args, scopes):
	print("baz")
	return h4x.datatypes.String("baz")

exports["foo:bar"] = h4x.datatypes.PyExec(func_bar, 0)

So first you import h4x to get access to the datatypes and stuff. Then you create and exports variable which is where you put all your functions/data which will be accessed by h4x.

All the functions called by h4x take 2 arguments. The args that are passed to it, and all the scopes. it returns a h4x.datatypes.String because thats how the evaluator knows its a string and can do stuffs with it. Thats the same for h4x.dataytypes.PyExec is a function that can be called from h4x, the constructor takes to arguments. 1: the function, 2: the amount of arguments it needs. If you want a variable amount of arguments/more overall control, for now the best way its to read the code and look into h4x.datatypes.SpecialExec cause im kinda tired of writing docs about this rn sorry

if you want more examples check out h4x/stdlib/ all of these are modules