builtins: documentation

diff --git a/DOC/BUILTINS.txt b/DOC/BUILTINS.txt
new file mode 100644 (file)
index 0000000..6e73c51
--- /dev/null
+++ b/DOC/BUILTINS.txt
@@ -0,0 +1,42 @@
+Builtin commands
+--------------------
+
+Basic
+--------------------
+
+cd [dir]
+   Change directory to dir, relative to the current working directory.
+   Omission of dir will change directory to $HOME.
+
+Math
+--------------------
+General math functions. They all take any number of arguments and
+perform the operation on all arguments (or relative to the first,
+with subtraction/division)
+
+If an optional single-character prefix is specified (x, X, o) before
+the operator the output will take the form of lowercase hexadecimal,
+uppercase hexadecimal or octal.
+
+Prefixes are interpreted in the input, so the value 0xDEADBEEF will
+be treated as hexadecimal.
+
+[xXo]+ ...
+   Add the arguments provided together and print the result.
+
+[xXo]- ...
+   Subtract in order starting from the first argument and print the
+   result.
+
+[xXo]* ...
+   Multiply the arguments provided together and print the result.
+
+[xXo]/ ...
+   Perform integer division in order with the first argument as the
+   dividend, with subsequent results becoming the divident and print the
+   result.
+
+[xXo]% ...
+   Calculate the modulo (integer remainder) in order with the first
+   argument as the dividend, with subsequent results becoming the
+   divident and print the result.

diff --git a/builtin/math.c b/builtin/math.c
index 5274ef97ff1135d9d5211e933ef10ed837a2612c..07ed260a39ae98a01ec56df26444f0a092fcfe96 100644 (file)
--- a/builtin/math.c
+++ b/builtin/math.c
@@ -1,4 +1,11 @@
-// Future home of 'math' builtins.
+// Do note that these builtin commands, implementation-wise, accept more than
+// two arguments; make sure to carefully consider inputs, since for example:
+//   / 10 2 2
+// is equivalent to 10 / 2 / 2.
+// This is similar to scheme/lisp dialects.
+// Additionally, these will parse octal (0) and hexadecimal (0x) when
+// provided; this is desirable behavior to me but it may not be to you.
+// Make sure you don't have leading zeroes, or strip them beforehand.
 
 #include <stdio.h>
 #include <stdlib.h>