log.txt

#
# Author: 		James Anthony Ortiz
# Project name: 	CTextEditor
# Project began: 	12/21/2019
# Current update: 	01/02/2020 
# Project Version: 	1.3
# File name: 		log.txt


# Project Description: A full implementation of a text-editor
# and text-processor written in C99 (1999)
# for Linux distributions. 

==================================================
PHASE 1:

CREATING THE INITIAL PROGRAM
==================================================

#Date: 12/21/2019
- Created file called kilo.c
- Used kilo.c with echo to test output
- Did not need to install GCC as this comes with the 
linux distribution. 
- Created initial makefile for program


makefile commands:
- $(CC) is a variable that make expands to cc by default.
-Wall stands for “all Warnings”, and gets the compiler to 
warn you when it sees code in your program that might not technically be wrong, but 
is considered bad or questionable usage of the C language, like using variables before initializing them.

-Wextra and -pedantic turn on even more warnings. 
For each step in this log, if the program compiles, it shouldn’t produce 
any warnings except for “unused variable” warnings in some cases. 
If you get any other warnings, check to make sure your code 
exactly matches the code in that step.

-std=c99 specifies the exact version of the C language standard we’re using,
which is C99. C99 allows us to declare variables anywhere within a function, 
whereas ANSI C requires all variables to be declared at the top of a function or block.


First, attempt to read key processes from user:

-------------------------------------------
#include <unistd.h>
int main()
{
	char c;
	while(read(STDIN_FILENO, &c, 1) == 1);
	return 0;
}//end main

--------------------------------------------

*** read() & STDIN_FILENO 
Both are from: <unistd.h>
Whats occurring: We are asking read() to read 1 byte from the standard input into the variable c,
and to keep doing it until there are no more bytes to read. read() returns the
number of bytes that it read, and will return 0 when it reaches the end of a file.

What happens when running this program:
When running ./kilo, the terminal gets hooked up to standard input
and the keyboard input gets read into the c variable.

How to exit the above program:
Use Ctrl-D to tell read() that it has reached the end of the file.
Or, alternatively you can also press Ctrl-c.

=================================================
Phase 1 : Part 2

ADDING A COMMAND TO QUIT ('q')
=================================================


Now we want to demonstrate how canonical mode functions, 
we are able to do this by having the program itself exit when it reads 
'q' as input from the user.

-------------------------------------------------------
#include <unistd.h>

int main()
{
	char c;
	while(read(STDIN_FILENO, &c, 1) == 1 && c != 'q');
	return 0;
}

-------------------------------------------------------


How to quit:
To quit the program you will need to type a line of text that 
includes a q in it, and then press enter. The program will quickly read the 
line of text one character at a time until it reads the 'q' 
as a single character. This will halt the while loop from continuing.

===============================================
Phase 1 : Part 3

TURN OFF ECHOING
===============================================

The user is able to set a teriminal's attributes by 
- Useing tcgetattr() to read current attributes into a struct
- Modifying the struct by hand
- Passing the struct to tcsetattr() to write 
the terminal attributes back out.

-----------------------------------------------------------
#include <termios.h>
#include <unistd.h>

void enableRawMode()
{
	struct termios raw;
	
	tcgetattr(STDIN_FILENO, &raw);
	
	raw.c_lflag &= ~(ECHO);
	
	tcsetattr(STDIN_FILENO, TCSAFLUSH, &raw);

} // end enableRawMode()



int main()
{
	enableRawMode();
	
	char c;
	while(read(STDIN_FILENO, &c, 1) == 1 && c != 'q');
	return 0;
}//end MAIN

------------------------------------------------------------

Functions:
From <termios.h>
stuct termios, tcgetattr(), tcsetattr(), ECHO, TCSAFLUSH



The ECHO feature causes each key you type to be
printed to the terminal, so you can see what 
you’re typing. This is useful in canonical mode, 
but really gets in the way when we are trying to 
carefully render a user 
interface in raw mode. So we turn it off.

This program does the same thing as the one in the
previous step, the only difference is that it is
not printing out the characters as you are typing.

This is similar to what occurs when you are entering
a value wile using "sudo".

Terminal attributes are read by termios struct and 
tcgetattr(). After getting this value it is then later set
by tcsetattr() and applied to the terminal program.

The TCSAFLUSH argument specifies when to apply the actual change.
In this case, it waits for all pending output to be written to 
the terminal.

The c_lflag field is for "local flags" (miscellaneous flags)
Other flag fields include:
- c_iflag: input flags
- c_oflag: output flags 
- c_cflag: control flags

Echo
Echo is a bitflag.
In this case, it is defined as:
00000000000000000000000000001000
 
Useing the NOT bitwise operator on the value above we get:
11111111111111111111111111110111

We then use bitwise AND and this value forces the 4th bit
in the flags field to become 0.

==================================================
PHASE 1 : PART 4

DISABLE RAW MODE AT EXIT (To be continued....)
==================================================

In this section, we will restore the terminal's original
attributes when the program exits.

---------------------------------------------------
#include <stdlib.h>
#include <termios.h>
#include <unistd.h>

struct termios orig_termios;

void disableRawMode()
{
	tcsetattr(STDIN_FILENO, TCSAFLUSH, $orig_termios);

}//end disableRawMode()

void enableRawMode()
{
	tcgetattr(STDIN_FILENO, $orig_termios);
	atexit(disableRawMode);
	
	struct termios raw = orig_termios;
	raw.c_lflag &= ~(ECHO);
	
	tcsetattr(STDIN_FILENO, TCSAFLUSH, &raw);

}//end enableRawMode()

int main()  {...}
-----------------------------------------------------

atexit() comes from <stdlib.h>
We use this to register disableRawMode() to be 
called automatically upon exiting the program (or exit()
function.

orig_termios
We then stor the original terminal attributes in a 
global variable, orig_termios. We then assign 
the orig_termios struct to be the raw struct, so that
a raw copy can be made before making changes.

Notice that in this implementation, input is no longer
fed into the shell when after the program ends.

This is because TCSAFLUSH is being passed to tcsetattr()
when the program exits. This discards any unread input 
before applying the changes to the terminal.

=============================================================
PHASE 1: PART 5


TURNING OFF CANONICAL MODE
=============================================================

ICANON Flag
- There is an ICANON flag that allows us to turn off 
canonical mode . This will alows the users to read input 
byte by byte, instead of line-by-line.

--------------------------------------------------------------
#include <stdlib.h>
#include <termios.h>
#include <unistd.h>

struct termios orig_termios;

void disableRawMode() { .... }

void enableRawMode() 
{
	tcgetattr(STDIN_FILENO, &orig_termios);
	atexit(disableRawMode);
	
	struct termios raw = orig_termios;
	raw.c_lflag &= ~(ECHO | ICANON);
	
	tcsetattr(STDIN_FILENO, TCSAFLUSH, &raw);
}

int main() { ... }
--------------------------------------------------------------


ICANON comes from <termios.h>.
Input flags (the ones in the c_iflags field will generally
start with I like ICANON does. However, ICANON is not 
an input flag, but actually a "local" flag in the c_lflag 
field. 

Now we have the program set in a way that allows us to quit as soon
as we press 'q' on the keyboard.




===============================================================
PHASE 1 : PART 6


DISPLAY KEYPRESSES
===============================================================

In order to get a better idea how input in raw mode works, 
lets print out each byte that we read with read(). We will 
print each character's numeric ASCII value, as well as the 
character that it represents if it is a printable character.


--------------------------------------------------------------
#include <ctype.h>
#include <stdio.h>
#include <stdlib.h>
#include <termios.h>
#include <unistd.h>

struct termios orig_termios;

void disableRawMode() 	{...}
void enableRawMode() 	{...}

int main()
{
	enableRawMode();
	char c;
	while(read(STDIN_FILENO, &c, 1) == 1 && c != 'q')
	{
		if(iscntrl(c)) //tests whether if ctrl char:
		{
			printf("%d\n", c);
		}
		else //if not, disp. actual char and ASCII#
		{
			printf("%d ('%c')\n", c, c);
		}
	}
	
	return 0;
}//end MAIN 

--------------------------------------------------------------

iscntrl()	 comes from <ctype.h>
printf()	 comes from <stdio.h>

*** iscntrl()
iscntrl() tests whether a character is a control character.
Control characters are non-printable characters that we don't want to 
print to the screen. ASCII codes 0-31 are all control
characters, and 127 is also a control character. All ASCII 
codes 32-126 are all printable.

*** printf()
printf() can print multiple representations of a byte. 
%d tells that a format of a byte is a decimal number 
(it's ascii code) and %c tells it to write the byte directly,
as a character. 

While useing this useful program you may notice a 
few interesting features:
Arrow keys, Page Up, Page Down, Home, and End all input 
3 or 4 bytes to the terminal: 27, '[', and then one or two 
other characters. This is known as an escape sequence. 
All escape sequences start with a 27 byte. Pressing Escape sends a 
single 27 byte as input.
Backspace is byte 127. Delete is a 4-byte escape sequence.
Enter is byte 10, which is a newline 
character, also known as '\n'.
Ctrl-A is 1, Ctrl-B is 2, Ctrl-C is… oh, that terminates the 
program, right. But the Ctrl key combinations that do work 
seem to map the letters A–Z to the codes 1–26.

Below is an example of s small trial:
72 ('H')
101 ('e')
108 ('l')
108 ('l')
111 ('o')
32 (' ')
87 ('W')
111 ('o')
114 ('r')
108 ('l')
100 ('d')
115 ('s')
27
91 ('[')
65 ('A')
27
91 ('[')
68 ('D')
27
91 ('[')
67 ('C')
32 (' ')
97 ('a')
115 ('s')
100 ('d')
65 ('A')
73 ('I')
32 (' ')
97 ('a')
109 ('m')
32 (' ')
97 ('a')
32 (' ')
83 ('S')
111 ('o')
102 ('f')
116 ('t')
119 ('w')
97 ('a')
114 ('r')
101 ('e')
32 (' ')
68 ('D')
101 ('e')
118 ('v')
101 ('e')
108 ('l')
111 ('o')
112 ('p')
101 ('e')
114 ('r')


===========================================================================

PHASE 1 : PART 7

TURNING OFF Ctrl-c and ctrl-z SIGNALS

===========================================================================
Ctrl-c sends a SIGINT signal to the curreent process which causes 
it to terminate, and Ctrl-Z sends a SIGSTP signal to the current prcess 
which causes it to suspend. 
-------------------------------------------------------
#include <ctype.h>
#include <stdio.h>
#include <stdlib.h>
#include <termios.h>
#include <unistd.h>

struct termios orig_termios;

void disableRawMode() {...}

void enableRawMode()
{
	tcgetattr(STDIN_FILENO, &orig_termios);
	atexit(disableRawMode);
	
	struct termios raw = orig_termios;
	
	raw.c_lflag &= ~(ECHO | ICANON | ISIG);
	
	tcsetattr(STDIN_FILENO, TCSAFLUSH, &raw);
	
	
}

int main() {...}
--------------------------------------------------------
ISIG comes from <termios.h>, like ICANON does, the only
small difference between the two is that it isnt an 
input flag.

Now, Ctrl-c can read as a 3 byte and Ctrl-z can read as a 26 byte.


==========================================================

PHASE 1: PART 8

DISABLE CTRL-S and CTRL-Q

==========================================================

Ctrl-s and Ctrl-q are mainly used for software flow control.
Ctrl-s: helps stop data from being transmitted to the
terminal until pressing Ctrl-q. The idea comes from 
older development periods where engineers wanted to
pause the transmission of data, to let external devices
take control.

---------------------------------------------------------
#include <ctype.h>
#include <stdio.h>
#include <stdlib.h>
#include <termios.h>
#include <unistd.h>

struct termios orig_termios;

void disableRawMode() { ... }

void enableRawMode() {
  tcgetattr(STDIN_FILENO, &orig_termios);
  atexit(disableRawMode);
  struct termios raw = orig_termios;
  raw.c_iflag &= ~(IXON);
  raw.c_lflag &= ~(ECHO | ICANON | ISIG);
  tcsetattr(STDIN_FILENO, TCSAFLUSH, &raw);
}

int main() { ... }
---------------------------------------------------------

IXON comes from <termios.h>. I stands for input flag
and XON comes from the names of the two control 
characters that Ctrl-s and Ctrl-Q produce. XOFF
to pause transmission and XON to resume transmission
of data.

Now, Ctrl-s can read as 19 bytes whereas Ctrl-q can reads
as 17 bytes.


===========================================================
PHASE 1: PART 9

DISABLE CTRL-V

==========================================================

On some operating systems, when you type Ctrl-V the
terminal waits for you to type another character value, 
sending that character as a literal value. We can turn 
off this feature with the IEXTEN flag.

---------------------------------------------------------
#include <ctype.h>
#include <stdio.h>
#include <stdlib.h>
#include <termios.h>
#include <unistd.h>
struct termios orig_termios;
void disableRawMode() { ... }
void enableRawMode() {
  tcgetattr(STDIN_FILENO, &orig_termios);
  atexit(disableRawMode);
  struct termios raw = orig_termios;
  raw.c_iflag &= ~(IXON);
  raw.c_lflag &= ~(ECHO | ICANON | IEXTEN | ISIG);
  tcsetattr(STDIN_FILENO, TCSAFLUSH, &raw);
}
int main() {...}
---------------------------------------------------------

IEXTEN comes from <termios.h>. This is another
flags that begins with I but belongs in the c_lflag field.


=========================================================

PHASE 1: PART 10

FIX CTRL-M

=========================================================

Running the program now and going through the alphabet
while holding ctrl, you should now notice that we
have every letter, except for m.Ctrl-M is weird: it’s being read as 10, when we expect it to be read as 13, 
since it is the 13th letter of the alphabet, and Ctrl-J 
already produces a 10. What else produces 10? The Enter 
key does.

It turns out that the terminal is helpfully 
translating any carriage returns (13, '\r') 
inputted by the user into newlines (10, '\n').
 Let’s turn off this feature.
 
 ------------------------------------------------------
#include <ctype.h>
#include <stdio.h>
#include <stdlib.h>
#include <termios.h>
#include <unistd.h>
struct termios orig_termios;
void disableRawMode() { ...}
void enableRawMode() {
  tcgetattr(STDIN_FILENO, &orig_termios);
  atexit(disableRawMode);
  struct termios raw = orig_termios;
  raw.c_iflag &= ~(ICRNL | IXON);
  raw.c_lflag &= ~(ECHO | ICANON | IEXTEN | ISIG);
  tcsetattr(STDIN_FILENO, TCSAFLUSH, &raw);
}
int main() { ... }
-------------------------------------------------------

ICRNL comes from <termios.h>. The I stands for "input
flag", CR stands for "carriage retrun" and NL for 
"New Line"

Now, Ctrl-M will be read as 13, and the Enter key 
will aslpo be read as 13.

=======================================================

Phase 1 : Part 11

TURN OFF ALL OUTPUT PROCESSING

=======================================================

We can see that the terminal does a similar translation
on the output side. It translates each newline ("\n") we print into a 
carriage return followed by a newline ("\r\n"). The terminal requires 
both of these characters in order to start a new line of text. The 
carriage return moves the cursor back to the beginning of the
 current line, and the newline moves the cursor down a line, 
 scrolling the screen if necessary. (These two distinct 
 operations originated in the days of typewriters and teletypes.)


We will turn off all output processing features by turning off 
the OPOST flag. In practice, the "\n" to "\r\n" translation is likely the only output 
processing feature turned on by default.

-------------------------------------------------------
#include <ctype.h>
#include <stdio.h>
#include <stdlib.h>
#include <termios.h>
#include <unistd.h>
struct termios orig_termios;
void disableRawMode() { ... }
void enableRawMode() {
  tcgetattr(STDIN_FILENO, &orig_termios);
  atexit(disableRawMode);
  struct termios raw = orig_termios;
  raw.c_iflag &= ~(ICRNL | IXON);
  raw.c_oflag &= ~(OPOST);
  raw.c_lflag &= ~(ECHO | ICANON | IEXTEN | ISIG);
  tcsetattr(STDIN_FILENO, TCSAFLUSH, &raw);
}

int main() {...}


-------------------------------------------------------

OPOST belongs to <termios.h>. O means that it is an 
output flag, and POST represents "post-processing
of output".

If you try running the program now, you will notice
that the newline characters we're printing are only
moving the cursor down, and to the left side of the screen
.To fix that, we will then add a couple of carriage
returns to the printf() statements.

-------------------------------------------------------

#include <ctype.h>
#include <stdio.h>
#include <stdlib.h>
#include <termios.h>
#include <unistd.h>
struct termios orig_termios;
void disableRawMode() { ... }
void enableRawMode() { ... }
int main() {
  enableRawMode();
  char c;
  while (read(STDIN_FILENO, &c, 1) == 1 && c != 'q') {
    if (iscntrl(c)) {
      printf("%d\r\n", c);
    } else {
      printf("%d ('%c')\r\n", c, c);
    }
  }
  return 0;
}


-------------------------------------------------------

From now on we will have to write out the full "\r\n" 
when we start a new line.

=======================================================

PHASE 1: Part 12
MISCELLANEOUS FLAGS

=======================================================

Turning off a few more flags:

-------------------------------------------------------
#include <ctype.h>
#include <stdio.h>
#include <stdlib.h>
#include <termios.h>
#include <unistd.h>
struct termios orig_termios;
void disableRawMode() { ... }
void enableRawMode() {
  tcgetattr(STDIN_FILENO, &orig_termios);
  atexit(disableRawMode);
  struct termios raw = orig_termios;
  raw.c_iflag &= ~(BRKINT | ICRNL | INPCK | ISTRIP | IXON);
  raw.c_oflag &= ~(OPOST);
  raw.c_cflag |= (CS8);
  raw.c_lflag &= ~(ECHO | ICANON | IEXTEN | ISIG);
  tcsetattr(STDIN_FILENO, TCSAFLUSH, &raw);
}
int main() { ... }
-------------------------------------------------------

BRKINT, INPCK, ISTRIP, and CS8 all come from <termios.h>

At one point switiching off these flags was considered
be a step for enabling "raw mode".

Descriptions of flags:
BRKINT - when turned on, enables a break condition
that will cause a SIGINT signal to be sent to the 
program, like pressing Ctrl-C.
INPCK - enables parity checking, which doesnt 
apply to modern terminals.
ISTRIP - Causes the 8th bit of each input byte 
to be stripped, meaning it will be set to 0.
CS8 - Not a flag, but a bitmask with multiple 
bits, which are then set to bitwise-OR(|)
operator unlike all of the flags we are turning off.
This sets the character size to become 8 bits per byte.
On Linux however, it is already set that way.

=======================================================

PHASE 1 : PART 13

A TIMEOUT FOR READ()

=======================================================

Currently, read() will wait indefinitely for input from
the keyboard before it returns. However what if we want
to animate something on the screen while waiting for user 
input?

It is possible to set a timeout, that way read() returns 
if it doesn't get any input for a certain amount of time.

--------------------------------------------------------
#include <ctype.h>
#include <stdio.h>
#include <stdlib.h>
#include <termios.h>
#include <unistd.h>
struct termios orig_termios;
void disableRawMode() {...}
void enableRawMode() {
  tcgetattr(STDIN_FILENO, &orig_termios);
  atexit(disableRawMode);
  struct termios raw = orig_termios;
  raw.c_iflag &= ~(BRKINT | ICRNL | INPCK | ISTRIP | IXON);
  raw.c_oflag &= ~(OPOST);
  raw.c_cflag |= (CS8);
  raw.c_lflag &= ~(ECHO | ICANON | IEXTEN | ISIG);
  raw.c_cc[VMIN] = 0;
  raw.c_cc[VTIME] = 1;
  tcsetattr(STDIN_FILENO, TCSAFLUSH, &raw);
}
int main() {
  enableRawMode();
  while (1) {
    char c = '\0';
    read(STDIN_FILENO, &c, 1);
    if (iscntrl(c)) {
      printf("%d\r\n", c);
    } else {
      printf("%d ('%c')\r\n", c, c);
    }
    if (c == 'q') break;
  }
  return 0;
}

--------------------------------------------------------

VMIN & VTIME come from <termios.h>
These are both indexes for the c_cc field (control
characters)

VMIN - Sets the minimum number of bytes needed
before reach() can return.
VTIME - Sets the maximum amount of ttime to wait before 
read() returns.

If read times out, it will return 0, which makes sense
since it is the usual return value (number of bytes read).

While running the program you can see how often read()
tends to time out. If you dont supply input on time,
it will keep returning and and displaying 0.

=========================================================

PHASE 1 : Part 14
ERROR HANDLING 

=========================================================

Now that we have that set up, enableRawMode() will now
have use all set up to be completely into "raw mode".

Now we will add some error handling. First we will include
a die() funtion to the soruce code that prints and 
displays an error message and then exits the program.

---------------------------------------------------------

#include <ctype.h>
#include <stdio.h>
#include <stdlib.h>
#include <termios.h>
#include <unistd.h>
struct termios orig_termios;
void die(const char *s) {
  perror(s);
  exit(1);
}
void disableRawMode() {...}
void enableRawMode() {...}
int main() {...}
---------------------------------------------------------

perror() is a function that comes from <stdio.h>
exit() comes from <stdlib.h>

Most C library functions that fail, set the global errno
variable to indicate what the error was. perror() looks
for the global errno variable and then prints a 
descriptive error message for it. It also displays the 
string given before it prints the error, which provide 
information about which part of the code caused the error.


Lets now check library calls and then call die if they 
fail to work.

---------------------------------------------------------

#include <ctype.h>
#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
#include <termios.h>
#include <unistd.h>
struct termios orig_termios;
void die(const char *s) {...}
void disableRawMode() {
  if (tcsetattr(STDIN_FILENO, TCSAFLUSH, &orig_termios) == -1)
    die("tcsetattr");
}
void enableRawMode() {
  if (tcgetattr(STDIN_FILENO, &orig_termios) == -1) die("tcgetattr");
  atexit(disableRawMode);
  struct termios raw = orig_termios;
  raw.c_iflag &= ~(BRKINT | ICRNL | INPCK | ISTRIP | IXON);
  raw.c_oflag &= ~(OPOST);
  raw.c_cflag |= (CS8);
  raw.c_lflag &= ~(ECHO | ICANON | IEXTEN | ISIG);
  raw.c_cc[VMIN] = 0;
  raw.c_cc[VTIME] = 1;
  if (tcsetattr(STDIN_FILENO, TCSAFLUSH, &raw) == -1) die("tcsetattr");
}
int main() {
  enableRawMode();
  while (1) {
    char c = '\0';
    if (read(STDIN_FILENO, &c, 1) == -1 && errno != EAGAIN) die("read");
    if (iscntrl(c)) {
      printf("%d\r\n", c);
    } else {
      printf("%d ('%c')\r\n", c, c);
    }
    if (c == 'q') break;
  }
  return 0;
}

---------------------------------------------------------

errno and EAGAIN come from <errno.h>

tcsetattr(), tcgetattr() and read() will all return -1
on failure, and set the errno value in order to inicate
the error.

An easy way to make tcgetattr() fail is to give the
program a text file or a pipe as standard input
instead of your terminal. To give it a pipe, run
echo test | ./kilo . Both will yield the same error
from tcgetattr().

=========================================================

PHASE 1 : PART 15 
SLIPTTING CODE INTO SECTIONS

=========================================================

This concludes phase 1 on entering raw mode. Now, we will
split the code into sections. 

---------------------------------------------------------
/*** includes ***/

#include <ctype.h>
#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
#include <termios.h>
#include <unistd.h>

/*** data ***/
struct termios orig_termios;
/*** terminal ***/
void die(const char *s) {...}
void disableRawMode() {...}
void enableRawMode() {...}

/*** init ***/

int main() {...}

----------------------------------------------------------

=========================================================

PHASE 2 : LOW-LEVEL TERMINAL INPUT / OUTPUT HANDLING
Started: 01/02/2020

=========================================================