xhartae/xhartae.c

/*
Copyright (c) 2023 : Ognjen 'xolatile' Milan Robovic

Xhartae is free software! You will redistribute it or modify it under the terms of the GNU General Public License by Free Software Foundation.
And when you do redistribute it or modify it, it will use either version 3 of the License, or (at yours truly opinion) any later version.
It is distributed in the hope that it will be useful or harmful, it really depends... But no warranty what so ever, seriously. See GNU/GPLv3.
*/

#ifdef STATIC_SOURCE
	#include "chapter/chapter_0.c"
	#include "chapter/chapter_1.c"
	#include "chapter/chapter_2.c"
	#include "chapter/chapter_3.c"
	#include "chapter/chapter_4.c"
#else
	#include "chapter/chapter_0.h"
	#include "chapter/chapter_1.h"
	#include "chapter/chapter_2.h"
	#include "chapter/chapter_3.h"
	#include "chapter/chapter_4.h"
#endif

/*
About this "book":

This is the ultimate C programming language guide, brought to you by Ognjen 'xolatile' Milan Robovic. I'm not a native English speaker nor a real programmer, only a hobbyist, so
this "book" will be full of grammatical mistakes, but not compiler warnings. Please be patient, C is a small language, even for the time when it was made, so if you ignore my
rambling and focus on what's written outside of the comments, you'll easily learn it. Good luck and have fun...

With that being said, I'll tell you the honest truth. No amount of books or source code you read (that's written in C or any other language) will make you good in programming (in
C or any other language). You get good in programming by writing the programs. Knowing what some statement, expression or library function will do is just a small advantage that's
saving you the time in order not to read (read yet again...) some documentation or specification. Sure, you can write literal machine code for some CPU instruction set, but you
still need to know what instructions are supported and how they translate to machine code. The sad thing about programming is that you need very small subset of information to
achieve creating almost anything, and yet, you need huge set of informations to do it in more concise way. That's the tradeoff.

Either learn very small subset of "building materials" and "architecture", then proceed building sewers, roads, houses, malls, factories, skyscrapers and in the end create a town,
or learn huge set of "pre-made houses, pre-made factories, pre-made road blocks", and create a same-looking town. If you use any kind of library functions, even the ones we'll
use in some parts of this program, you'll end up as a "interior designer" rather than an "architect". C programming language is the minimal kind of tool that's widely supported
and lets you write "quick assembly", we'll have entire chapter about assembly and machine code, so you can make your own language.

We're dealing with a low-level functional (and procedural) programming language called C. So, disengage all safety protocols, think twice, write once, enter the Great C and learn
to sail on it after some practice. This will never be a book. It has no readers. It's not even printed. It's pages are files. It's cover is a folder. This will never be a book. I,
for the most part, am having fun writing this, same as I have fun while programming. You won't get a job after reading this "book", only some knowledge.

How to read this book?

- First of all, read the "README.md" file in base directory. Run scripts there in the order they're listed.
- Now, make a copy of 'xhartae' folder somewhere, and run '$ xhartae' from there, or just read the source.
- Feel free to modify (edit) that copy, if you can't fix some error, just replace it with the original one.

When you read some book about a programming language, you can't modify it and recompile it. You can do it with this book, so it's not really a "book", but at the same time it is.
If you fuck up something and don't know how to fix it, you'll easily replace that folder with the working one, which you can also download from my GitLain repository. If you're,
for example, learning about switch statement, you can just write it inside this book, recompile it and run it. If compiler spits out warnings or error that you can't fix, just
delete that part of the code, and go on with your life...

Why should you learn or use C programming language in 2023?

- C was inspiration for many newer programming languages for good reasons.
- C can interface with huge variety of other distinct programming languages.
- C can be a lot more readable, faster and easier if used well.

Goal of this so-called book?

- You'll be able to write your own compiler or interpretter, for your own language after reading this, and many more programs.
- You might learn something new. My target audience is people who don't know C languages, but maybe there's something new for you.
- You won't (hopefully) buy into big ideas and paradigms about programming, you'll just create programs, and have fun doing so.

Before we get into it, there are some requirements that this book is based on. Thou shalt use GNU/systemd/Linux operating system, commonly and wrongly refered to as Linux OS or
just simply distro (distribution). They come in many flavours, so if you're new to this, you could just install BunsenLabs, LXLE or Mint on some old laptop, if you don't want to
switch totally from spyware known as Windows (niche OS made for games). You'll revive your old laptop that was useless, and you support free software by doing so, making you a
part of the revolution. Beside that, you'll need a C compiler such as TCC, GCC (which is preinstalled on most distros) or Clang, and lastly Valgrind and Splint, to verify the
quality of your C source code. Text editor or IDE is a trivial thing at the begining, but it'll shape your coding style in the long run. Lets talk about them.

GNU/Linux operating systems:

- LXLE: Entire distro based on motto "Revive your old PC", so you understand everything. It's based on (L)Ubuntu and uses LX desktop environment. It comes preinstalled with a lot
of useful software, so you can work with it as soon as the installation is finished. If your old machine was struggling with XP, it'll fly with this.
- Mint: You can consider it as a noob Linux distro, but all that aside, it's good introduction to freedom, as it looks very similar to Windows, except nicer. I prefer to suggest
over Ubuntu for new users (revolutionists). You can also use it out of the box, since it comes with a lot of good software.
- BunsenLabs: Easy to use distribution, and I personal use it. I like to call it "hybrid distro", because it doesn't buy into big ideas like universal window manager, desktop
environment, or anything else. It just literally works, and you're free to modify it however you want, nothing breaks and it's friendly with older hardware.

C compiler and other tools (and other compilers...):

- TCC: Tiny C compiler, imagine that you just want to compile some huge program that's taking forever to compile (and it's not written in Pust "programming" language). Then just
compile it with TCC, it'll be around 10 times faster than GCC or Clang, but it'll do less optimizations and less error checking.
- GCC: GNU compiler collection (formerly known as GNU C compiler) is beast of a compiler, with decent optimizations and error checking, but it's very old and sometimes produces
errors that cause SIGILL (Illegal instruction) on Linux (on Intel's x86-64 CPUs). Also, it was rewritten in C++, so no wonder...
- Clang: LLVM C compiler, I personally dislike it, but don't mind my opinion too much. It has good warning messages, so sometimes I use it with flag '-Weverything' in order to see
that my code is absolutely correct. It also has quite good optimizations, but I couldn't care less about that honestly.
- Valgrind: Heavy metal program for checking memory leaks (when using heap memory / dynamic memory management), I absolutely love it and use it to test all my C programs. I use it
with '-g' flag passed to the compiler I'm using to use debug symbols in generated object files. Every single C programmer needs to use it.
- Splint: Careful with using this one, it's old and outdated C linter. It basically prints warnings about your C source code, without compiling it, it's called static code
analysis. In order to use it efficiently, you'll need to learn some flags, and we'll cover that in future chapters.
+ GNAT: GNU toolchain made for Ada programming language. We'll briefly talk about other older and newer programming languages in this book, Ada, Fortran, flat assembly mostly
positively, and C++, Rust, Java, mostly negatively. You don't need this, it's just an extra, in case that (Gott forbid) you want to learn more.
+ fasm: flat assembler, not a compiler, close to interpretter, but not quite, is the most unique piece of software I've ever seen. It's implemented in itself, which is something
you can do with C too, write your own C compiler, compile it with TCC, and then recompile it in itself. You will need assembly knowledge.

Text editors or IDEs (integrated development environments):

- ed: It's the STANDARD text editor for UNIX-based operating systems. Nothing else can be said, it's literally the best tool I've ever seen, and I use it sometimes.
- kilo: Terminal text editor, written in C language, less than 1000 lines of code. It's nice, simple and usable, and you can extend it once you learn C.
- nano: Also terminal text editor, very simple to use, but some prefer micro over it. You gotta admit, people are very creative when naming their software...
- Vim: Beast of an editor, once you learn how to exit it, you'll be like a Gott to other non-Vim users. I won't tell you how to exit it. I don't know.
- Emacs: Yet another beast of an editor, your pinky finger will be twice stronger because of it. It has many extensions and all PROs use it.
- Mousepad: State of the art text editor, it works same as Notepad, but it's more based. You really don't need anything more complex than this for editing a text file.
- Geany: I use it most of the time, but I switch to nano, Emacs, my own text editor whenever I feel like it, in order not to limit myself to just one tool.

Jokes aside, don't obesess over any distro (as long as it's some kind of Linux, BSD is cucked), any kind of compiler and any kind of text editor! You only want to edit text file,
insert and delete few lines of code, nothing more. You don't need some IDE (bloated text editor) that uses 2 GiB or RAM, opens up after 10s of blank window, and work slow overall.
Just don't use any of the following for reasons you'll understand once your grow up: Windows, MSVC, VS Code, Visual Studio, Atom, Helix, Kakoune, Eclipse, Sublime.

One sane C program should have the following structure (please keep in mind that this is a book, not a sane program, thanks...):

0) Optional file, author or license information in comment.
1) Header guards and implementation definitions.
2) System header files then project header files.
3) Macro definitions (please avoid them).
4) Internal function then variable declarations.
5) External function then variable declarations.
6) Internal function then variable definition.
7) External function then variable definition.
8) Main function.
*/

int main (int argc, char * * argv) {
	(void) argc;
	(void) argv;

	curses_configure ();

	// We could simply write a while loop, but I prefer to be consistent with using for loops, and not to rely on default comparison to zero.
	// while (curses_active) { ...
	for (; curses_active != 0; ) {
		curses_render_background   ('.', COLOUR_GREY, EFFECT_BOLD);
		curses_render_character    ('@', COLOUR_RED, EFFECT_BOLD, 1, 1);
		curses_render_string       ("Heyo world!", COLOUR_GREEN, EFFECT_ITALIC, 2, 2);
		curses_render_number_limit (-420, 6, COLOUR_YELLOW, EFFECT_UNDERLINE, 0, 3);

		curses_synchronize ();
	}

	preview_c_file ("program/hello_world.c", curses_screen_width, curses_screen_height, 0, 0);

	return (EXIT_SUCCESS);
}