watch file syntax

# a watch file is a normal text (*.txt) file containing names, types, and addresses of watches.
# like this document, which happens to be a valid watch file.
# each line in the file can have one watch entry.
# the '#' character starts a line comment (like this one).
# comments are just plain text that gets ignored when importing watches from a watch file.
# watches look like this:

"this is a watch" u16 0x80001234  # oh, comments can also appear at the end of a watch line

# the name of the watch goes first, contained in double quotes.
# after it comes the data type. valid data types are:
# u8,  s8,  x8  : one-byte value (signed format, unsigned format, hex format)
# u16, s16, x16 : two-byte value (ditto)
# u32, s32, x32 : four-byte value (ditto)
# f32           : four-byte value, 32-bit ieee 754 single-precision floating-point format

# finally comes the address. in the example above, the address is just a simple hexadecimal number.
# numbers can start with '0x' for hexadeciaml, '0b' for binary, '0' for octal,
# or any digit other than zero for decimal.
# but the address can also be a more complex expression, with arithmetic and indirection.
# the available arithmetic operators are:
# * / % : multiplication, division, and remainder
# + -   : addition and subtraction
# here's an example address with arithmetic operations:

"complex address with arithmetic" f32 5 * (3 + 4)

# the address in this example becomes the result of the arithmetic expression, which is equal to:
# 5 * (3 + 4) = 5 * (7) = 35
# obviously this isn't very useful, since you could have just written '35' as the address
# (and also 35 isn't even a valid address). that's where indirection comes in.

# indirection is the act of replacing part of an expression with the value at the address given by that expression.
# this is done by enclosing the sub-expression in [square brackets].
# if we do this with the address in the first example we get:

"this is also a watch" u16 [0x80001234]

# this expression no longer means "the address i want is 0x80001234", but instead means
# "the address i want is the value located at 0x80001234 in memory".
# so whatever 32-bit value happens to be at 0x80001234 when this watch is imported,
# that's going to be the address of the new watch.
# this is useful for computing the address of dynamically loaded things, such as most actors.
# the value given by the indirection doesn't need to be an actual address though.
# it can be a smaller part that is needed to compute the address of a bigger expression.
# the result of an indirection can be used in arithmetic just like any number. there can also be nested indirection:
# [[0x80001234 + 0x20] + [0x80003210] * 0x31]
# the expression above means: "add 0x20 to 0x80001234, then get the value at the resulting address.
# multiply the value at 0x80003210 by 0x31. take these two values and add them together.
# then, since the whole thing is enclosed in square brackets, get the value at the address resulting
# from the last summation and use that as the new watch address."

# in all of the above uses of indirection, the type of the value to get is implicitly a 32-bit integer.
# but, other types can be used as well by explicitly preceding the square brackets with a mode indicator.
# the following modes are available:
# b.[0x80001234]  : one-byte value, sign-extended to 32 bits.
# bz.[0x80001234] : ditto, zero-extended to 32 bits.
# h.[0x80001234]  : two-byte (16-bit halfword) value, sign-extended to 32 bits.
# hz.[0x80001234] : ditto, zero-extended to 32 bits.
# w.[0x80001234]  : four-byte value (32-bit word, the default mode when no mode is explicitly specified)

# finally, there are a few builtin symbols that can be used in address expressions.
# whenever one of these are encountered, they are replaced by the address represented by that symbol.

"link x" f32 link + 0x24

# the above expression results in whatever address the link actor is loaded at, plus 0x24.
# this happens to be the address of link's x-coordinate.
# these symbols exist:
# link  : gets replaced by the starting address of the link actor
# ctxt  : gets replaced by the address of the global context
# file  : gets replaced by the address of the current zelda file data