kspalaiologos / asmbf

                                                      .oooo.    .o8        .o88o. 
                                                    .dP""Y88b  "888        888 `" 
                .oooo.    .oooo.o ooo. .oo.  .oo.         ]8P'  888oooo.  o888oo  
               `P  )88b  d88(  "8 `888P"Y88bP"Y88b      .d8P'   d88' `88b  888    
                .oP"888  `"Y88b.   888   888   888    .dP'      888   888  888    
               d8(  888  o.  )88b  888   888   888  .oP     .o  888   888  888    
               `Y888""8o 8""888P' o888o o888o o888o 8888888888  `Y8bod8P' o888o   
                                                                                  
                                                                                  
                                                                                  
The only true brainfuck assembler. Produces small and efficient brainfuck code based on instruction choice.
With Lua preprocessor, labels, precise floating point, effective adresses, conditional branching, signed arithmetics,
dynamic memory allocation and all the features you'd expect from a normal assembly, it's ready for use.
Lastest changes include stack-based offsets and move semantics. Why not check it out?

etc/asmbf.pdf                    - WIP, UP TO DATE ASM2BF MANUAL AND DOCUMENTATION.

https://esolangs.org/wiki/Asm2bf - a brief showcase of select asm2bf's capabilities.

examples/                        - who doesn't love learning by examples?
test/                            - unit tests for the entire toolchain.

a functional programming language interpreter in 150 lines of asm2bf:
https://github.com/kspalaiologos/asmbf/blob/master/examples/sk.asm

asm2bf was used to create a JSON formatter webservice:
https://github.com/kspalaiologos/JSONFormatter/blob/master/jsonformatter.asm

also, a subleq interpreter approach has been taken:
https://github.com/kspalaiologos/SqEMU/blob/master/dev-sqemu.s

an optimized 8ball:
https://github.com/kspalaiologos/asmbf/blob/master/examples/8ball.asm

----------------------------------------- What can asm2bf do? ------------------------------------------

First and foremost, asm2bf is a language which is very portable. It can compile to special asm2bf
bytecode (which can be retargetted to virtually any platform in a few hours). It also outputs _pure_
brainfuck, which is executable by any brainfuck interpreter, which means, that asm2bf is able to benefit
from countless brainfuck-to-any compilers.

Secondly, asm2bf is a both a fairly low level language and a high level language. It abstracts the
concepts of effective adresses, powerful preprocessors, advanced control flow, floating point numbers,
signed arithmetic, etc..., into a robust toolkit for developing brainfuck, and, subsequently, any language
which can be a target of compilation from brainfuck or asm2bf bytecode.

Third, asm2bf in itself can be made to produce really small programs (check 8ball.asm in examples),
but it can also be used to create very complicated programs (check sk.asm). Because it provides an acceptable
level of abstraction to the programmer, it's feasible to write your proofs of concepts in asm2bf and
later optimize them to be as fast as possible using existing resources and community-created guides,
or by reading the code and experimenting yourself.

asm2bf is still, after multiple years, work in progress. It gains new features rather often. So far,
asm2bf has around 160 instructions that you can use in your programs and around 300 lines of Lua
code providing essential batteries for metaprogramming in asm2bf. It's a hobby project of mine, to which
a few people decided to contribute, but I'll try to maintain it for as long as possible.

asm2bf is capable of being the foundation of any more or less complex program. It has been used to create
an operating system (which boots and operates mainly thanks to pure brainfuck! This is possible because the
brainfuck code can directly access the memory and set up a custom interrupt handler, which executes
provided assembled machine code when the timer intterupt fires, which later modifies the interpreter
to add special instructions to it). asm2bf has also been used to create a small (~150 line) functional
programming language interpreter, which compiles to only around 20 kilobytes of brainfuck. It was also
used to create tiny brainfuck programs, as well as proofs of concepts for web development in brainfuck.

Finally, I, the author, am working on an exhaustive manual on _all_ of asm2bf, for which the progress
you can see in etc/asmbf.pdf

------------------------------------------ Get a taste of it! ------------------------------------------

; Sierpinski triangle fractal viewer

@loop1
    mov r2, 0
    
    @loop2
        mov r3, r1
        band r3, r2
        cge r3, 1
        mov r3, .*
        cmov r3, 32
        out r3
        clt r2, 63
        cadd r2, 1
        cjn %loop2
    
    out 10
    
    clt r1, 63
    cadd r1, 1
    cjn %loop1

--------------------------------------- Installation Instruction ---------------------------------------

1. Pull the repository from github: `git clone https://github.com/kspalaiologos/asmbf'
2. Run the configure script and build asm2bf:
    `./configure --with-target=release && make all && sudo make install`

-------------------------------------- State-of-art Documentation --------------------------------------

There is the esolang wiki article which you can check out. Feel free to join the discord server for
asm2bf, where you can discuss the project or ask me about learning asm2bf: https://discord.gg/m4Wcenn.

You can also check out the manual (etc/asmbf.pdf); although up to date, it's not complete.

---------------------------------------------- Dependencies ---------------------------------------------

Term::ReadKey, File::Basename, Term::ANSIColor               @ cpan
gcc, bison, flex, make, autotools, ncurses

--------------------------------------------- Windows Build ---------------------------------------------

To _configure_ this project on Windows, you need either Cygwin or MinGW (msys). The build should look
exactly the same like the Linux one.

Note that building the project on Windows and targets other than `release' and `auto' is unsupported.