File Header documentation

Introductions

When working with individual files, you will need to understand file "headers", the idea is the header is an object based off a file that can be used to read its data or push new data into it with the risk of direct file interaction. Changes made to a header don't instantly change the file being represented, and reading will only capture the contents of the file when the header was "opened".

In NEET file headers are the only builtin way to interact with files themselves, however the rest of the file system is accesses via its perspective API, and the file system API is also where headers are created

For reference its good practice to "close" the header because as it's only a puppet of the real file, it's using up as much ram and some as the file does file pace! "closing" the header will make it inoperable but its good practice for mitigating memory leaks and playing nice with the game server.

Note for people who know lua: although a header is an object, call its functions directly [header.seek()] instead of normal lua object notation [header:seek()], because unlike normal lua objects headers contain no table data, just pre-programed functions

Lookup table

read(format = 'l')

Starts reading data from the reading cursor to an endpoint determined by the Format parameter, the cursor will then be moved to that point

The "l"(lowercase L) and "L" formats will read to the next line, if "L" format then the newline character will be returned as well

The "a" format will read until the end of the file

read(amount)

Starts reading data from the read cursor for 'amount' characters, then moved the read cursor past the last character read

write(bytes)

Writes the data provided to the file header (if supplied as a int the number will be treated like a byte) to the file (some file modes will wipe the file before writing, to append information to the end of a existing file use append (a) file modes)

seek(whence = 'cur', offset = 0)

Repositions the read cursor, starting from a position specified by whence, to the offset

"set" whence moves the cursor to 'offset' position away from the start of the file, setting its location

"cur" whence moves the cursor by 'offset' amount away from the cursors current position, accepts negative numbers

"end" whence moves the cursor 'offset' away from the end of the file, must be negative

A neat trick is because by default seek parameters move zero units away from current pos, and returns the cursors position, calling seek with no arguments will fetch the cursors position!

flush()

Pushes the current state of the file header onto the file, I.E. saves its content

close()

Flushes the file (saves it) before relocating its resources, making the file inoperable (every function called after will error)