io.jou

# IO = Input and Output: reading/writing files, printing to terminal,
# reading keyboard input.

# Printing to terminal (stdout)
#
# You can usually ignore the return values of these functions.
# If you are paranoid about error handling, you can use them to
# check whether printing failed.
#
# See also printf() manual page: https://linux.die.net/man/3/printf
declare putchar(a_byte: int) -> int  # Print a byte (parameter type is "int" for historical reasons)
declare puts(string: byte*) -> int  # Print a string followed by "\n"
declare printf(pattern: byte*, ...) -> int  # Example: printf("%s %d\n", "hi", 123)

# Keyboard input
# TODO: add EOF and errno, explain here how to use them
# TODO: add stdin and explain how to use fgets(..., stdin)
declare getchar() -> int

# Parsing input. For example, this expects the user to type two
# numbers separated by a comma:
#
#    x: int
#    y: int
#    printf("Enter coordinates: ")
#    scanf("%d,%d\n", &x, &y)
#
# Return value indicates how many elements were matched. In the
# example above, return value 2 means success.
#
# See also scanf() manual page: https://linux.die.net/man/3/scanf
declare scanf(pattern: byte*, ...) -> int  # Parse keyboard input (stdin)

class FILE:
    # The members that are actually inside this class are
    # platform-specific. Use the functions below instead of trying
    # to accessing the members directly.
    _dummy: int

# Special files for terminal input and output.
declare global stdin: FILE*
declare global stdout: FILE*
declare global stderr: FILE*

# Open/close a file for reading or writing. Mode can be e.g. "r", "w",
# "a", "rb", "wb" or "ab". The meanings of these modes are as in many
# other languages, such as Python.
#
# The "b" at the end of the mode makes a difference only on Windows.
# Text files on Windows typically use two bytes "\r\n" for newlines,
# even though Jou code typically uses "\n". Without "b", the file will
# convert between "\n" and "\r\n" automatically.
declare fopen(path: byte*, mode: byte*) -> FILE*
declare fclose(file: FILE*) -> int  # Call this when done with the file. Return value is not meaningful.

# Similar to other functions, but these read/write a file.
declare fputc(a_byte: int, file: FILE*) -> int  # see putchar()
declare fputs(string: byte*, file: FILE*) -> int  # does NOT add '\n' like puts() does
declare fprintf(file: FILE *, pattern: byte*, ...) -> int
declare fgetc(file: FILE*) -> int  # see getchar()
declare fscanf(file: FILE*, pattern: byte*, ...) -> int

# Reads at most n items of data, each of size "itemsize". Returns number of items read.
# Usually this is used with itemsize 1, so return value is number of bytes.
declare fread(destination: byte*, itemsize: long, n: long, file: FILE*) -> long

# Ensure that output is actually written. It may remain buffered
# if this function isn't called.
declare fflush(file: FILE*) -> int

# Read a line of text from file into a string starting at the given
# pointer. Reading stops at newline character, end of file, on error,
# or when the resulting string (including the '\0') wouldn't fit
# within n bytes.
#
# Return value: NULL on error, same as destination on success.
declare fgets(destination: byte*, n: int, file: FILE*) -> byte*

# TODO: document
declare feof(file: FILE*) -> int
declare ferror(file: FILE*) -> int

# Move back to beginning of file.
declare rewind(file: FILE*) -> None