Hello there!

Welcome to my brainfuck-VM, here are the basics of using my said Brainfuck-VM + how to customise and embed. The extensions my program use are strictly '.bf' and '.bfc' files, all other files will be rejected.

If you have any errors, please bring it up on the Github and explain what you've done to cause it.
And state whether it is a modified VM.

How does this BF model work?

This BF model uses a specialised VM, it converts source code BF into its own unique set of instructions
like ASM, and puts it into a bytecoded format, you are able to initialise and run source code, or the specialised bytecode it uses.

---

USING THE CLI

If you didn't get an .exe/.out file or you're a stereotypical Gentoo user

You need to compile the 'main.c' file in the src folder (src/main.c). By doing so, you can finally use my Brainfuck-VM.

There are 3 commands for my CLI, here are all the listed commands:

Paranthesis () = Flag/Optional Brackets [] = Required

---

compile

using 'compile' is to turn '.bf' into '.bfc' which is the bytecoded format of '.bf'.
If the final file output does exist, then you will need to confirm it, or use the flag

It has one flag which is -f (force).
This is if you're too lazy to type Y when it asks if you want to overwrite a file.

heres how to run it:

[brainfuck-cli] compile (-f) [bf-file-to-compile] [bfc-output-destination]

NOTE: compile automatically adds '.bfc' to the end, so do not put .bfc at the end unless you want a
'.bfc.bfc' file ANOTHER NOTE: It will reject all files that aren't .bf, so make sure it has that extension!

---

run

using 'run' works for both '.bf' and '.bfc' files, it works by setting up a VM and deleting it once
done, it's a quick way of running a '.bf'/'.bfc' file.

It has one flag which is -s (string).
It is used if you want to run a code in the terminal itself, it will always expect a valid string.

heres how to run it: (did you see what i did there?)

[brainfuck-cli] run (-s) [bf-file/bfc-file/bf-string]

NOTE: It will reject all files that aren't .bf/.bfc, so make sure it has that extension!

---

man (currently removed, but will be reintroduced)

using 'man' is to bring up and read what certain commands do (and their flags).
It does not have any flags and to pull up the entire manual, you run it without a command.

heres how to run man:

[brainfuck-cli] man (command)

---

CUSTOMISING AND COMPILING YOUR OWN VM

In order to do this, you require the source files and make sure you compile main.c for everything to fall into place.
To edit the configs of the VM, you can go into src/core/BRAINFUCKconfig.h, from there, you can manipulate the variables/macros to be for your flavour.
Please do know you bare full responsibility if the VM fails, and it has been modified.

---

EMBEDDING

In order to embed (for C/C++), you need to link your project with the file in src/BRAINFUCKapi.h, this will expose the API needed to set up a VM
and to save/load BF Objects.

After your done with your project, you need to compile it alongside the main BRAINFUCK file, you have to link src/core/BRAINFUCK.c (or a compiled version) to your file and it should run as expected.

Example (for C):

gcc -c .../src/core/BRAINFUCK.c -o BRAINFUCK.o
gcc -c yourprogram.c -o yourprogram.o
gcc yourprogram.o BRAINFUCK.o -o yourprogram

Example (for C++):

gcc -c .../src/core/BRAINFUCK.c -o BRAINFUCK.o
g++ -c yourprogram.cpp -o yourprogram.o
g++ yourprogram.o BRAINFUCK.o -o yourprogram

---

APIs

bool BF_set_underline_error_char(char character);
Set the look of how the underline error char looks like

BF_OBJECT* init_BF_OBJECT_with_str(const char* string_code, const bool fail_silently);
Initialise a BF_OBJECT with a string

BF_OBJECT* init_BF_OBJECT_with_source(const char* filedir, bool fail_silently);
Initialise a BF_OBJECT with a source file (not compiled)

BF_OBJECT* init_BF_OBJECT_with_bytecode(const char* filedir, bool fail_silently);
Initialise a BF_OBJECT with a bytecoded file (compiled)

bool del_BF_OBJECT(BF_OBJECT** BF_object);
Safely delete a BF_Object once done with use

BF_VM* init_BF_VM(BF_OBJECT* BF_object, FILE* stdout_file, FILE* stdin_file, FILE* stderr_file, const size_t cell_list_size);
Initialise a Brainfuck-VM

int run_BF_VM(BF_VM* VM);
Run a Brainfuck-VM, it returns the exit code once done

VM-Exit codes and their meanings:

-1  -  Yet to start<br>
 0  -  Successful<br>
 1  -  Error<br>
 2  -  Panic<br>

int BF_VM_state(BF_VM* VM) Returns the exit code the VM exited in

bool del_BF_VM(BF_VM** VM, bool delete_BF_OBJECT);
Safely delete a Brainfuck-VM once done with use