From db2d954c0dd2582877d70774a66d500a9ba9338d Mon Sep 17 00:00:00 2001 From: Lukas Krickl Date: Tue, 29 Oct 2024 18:00:23 +0100 Subject: [PATCH] Added syntax reference manpage --- makefile | 1 + man/ulas.1 | 52 +------------------ man/ulas.5 | 149 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 152 insertions(+), 50 deletions(-) create mode 100644 man/ulas.5 diff --git a/makefile b/makefile index 37a51a4..0590c92 100644 --- a/makefile +++ b/makefile @@ -45,6 +45,7 @@ clean: install: cp ./$(NAME) $(INSTALL_DIR)/bin cp ./man/$(NAME).1 $(INSTALL_DIR)/man + cp ./man/$(NAME).5 $(INSTALL_DIR)/man .PHONY: tags tags: diff --git a/man/ulas.1 b/man/ulas.1 index 92e322d..e5abd56 100644 --- a/man/ulas.1 +++ b/man/ulas.1 @@ -52,61 +52,13 @@ -w=warning Toggle warnings: a=all, o=overflow -.SH PREPROCESSOR - -The preprocessor is a text based way of modifying the input before -the assembly step. Stray tokens after a directive are ignored! - -Preprocessor directives start with a # and have to be the first non-space character in a line. -All lines that are not a preprocessor directive, or are not part of a preprocessor block (macro, or if) -will be output as-is. If a line contains the name of a preprocessot define or macro -,surrounded by token any character that is not alphanumeric or an underscore, -the define or macro will be expanded. - -Withing preprocessor macros -- $0 will expand to the literal argument string -- $1 to $9 will expand to the comma separated arguments of the macro -- $$ will insert a unique numeric literal - -Macros: - -#macro my_macro -label$$: - adc $1, $2 -#endmacro - -my_macro a, b - -Define: - -#define name value -name ; will be replaced with 'value' -#undefine name - -.SH ASSEMBLY SYNTAX - - - -.SH EXPRESSION SYNTAX - -Expressions are written in Reverse Polish Notation style and evaluated based on their expected data type. -For example when an expression expects an int type the expression will assume all values that are pushed to it -are integers. - -.SH ASSEMBLY DIRECTIVES - -During assembly sometimes it is required to set certain parameters of the assembler such as the base address (represented by the $@ symbol in expressions). - -Valid directives: - - \.org - Sets the base address - .SH EXAMPLES ulas -o example.gb ./src/main.s .SH SEE ALSO + ulas(5) for a syntax reference. + The documentation for make(1) for compilation instructions. A compiler documentation such as cc(1) gcc(1) or clang(1). diff --git a/man/ulas.5 b/man/ulas.5 new file mode 100644 index 0000000..785395d --- /dev/null +++ b/man/ulas.5 @@ -0,0 +1,149 @@ +.\" Manpage for ulas. +.\" Contact lukas@krickl.dev to correct errors or typos. + +.TH man 1 "29 October 2024" "0.0.1" "ulas language reference" + +.SH PREPROCESSOR + +The preprocessor is a text based way of modifying the input before +the assembly step. Stray tokens after a directive are ignored! + +Preprocessor directives start with a # and have to be the first non-space character in a line. +All lines that are not a preprocessor directive, or are not part of a preprocessor block (macro, or if) +will be output as-is. If a line contains the name of a preprocessot define or macro +,surrounded by token any character that is not alphanumeric or an underscore, +the define or macro will be expanded. + +.SH Macros: + +Within preprocessor macros +- $0 will expand to the literal argument string +- $1 to $9 will expand to the comma separated arguments of the macro +- $$ will insert a unique numeric literal + +#macro my_macro +.br +label$$: +.br + adc $1, $2 +.br +#endmacro + +my_macro a, b + +.SH Define: + +#define name value +name ; will be replaced with 'value' + +.SH Undefine: + +#undefine name +name will be undefined + +.SH ifdef: + +#ifdef [defined value] +.br + +.br +#endif + +If the symbol is defined everything inside of ifdef will be assembled. +If it is undefined it will be skipped. + +.SH ifndef: + +#ifndef [defined value] +.br + +.br +#endif + +The inverse of ifdef. + +.SH include: + +#include "path/to/file.s" + +This will include the literal file into the assembly input. + +.SH ASSEMBLY SYNTAX + +.SH ASSEMBLY DIRECTIVES + +During assembly sometimes it is required to set certain parameters of the assembler such as the base address (represented by the $@ symbol in expressions). +The special value $ will evaluate to the current address. + +.SH org: + + \.org + Sets the base address + +.SH set + \.set variable = + Sets a previously defined expression + +.SH db + \.db value[, value...] + Defines a sequence of bytes. + +.SH str + \.str "String" + Defines a literal string + +.SH fill + \.fill , + \.fill , $ - n + Fills the rom for n bytest. + +.SH incbin + \.incbin "path/to/file.bin" + Includes a literal binary file. + +.SH def + \.def int int_val = 1 + \.def str str_vale = "hello" + Defines a variable + +.SH chksm + \.chksm + Inserts a checksum into the rom. + Can be used for header. + +.SH adv + \.adv + Advances address by n bytest but does not emit data. + +.SH se + \.se + Sets a global enumerator value. + +.SH .de + \.de , + Defines a name for the current se value and advances se by len. + +.SH scc + \.scc 'a' = 'b' + Re-defines the ascii value for one character to another value. + Can be used for custom encodings. + +.SH .chr + \.chr 01233213 + Outputs a byte as a 2bpp sprite. + Must have exactly 8 values ranging from 0-3 + +.SH rep + \.rep , , , + Repeats the instruction n times advancing from 0 by step each iteration. + The first parameter is a counter value that allows the instruction to access the + current iterator value. +.SH SEE ALSO + + ulas(1) for a rference on how to use ulas. + +.SH AUTHOR + Lukas Krickl (lukas@krickl.dev) + +.SH COPYRIGHT + Copyright 2024 Lukas Krickl (lukas@krickl.dev) -- 2.30.2