added "!for VAR in ITERABLE { BLOCK }" possibility.

git-svn-id: https://svn.code.sf.net/p/acme-crossass/code-0/trunk@306 4df02467-bbd4-4a76-a152-e7ce94205b78

docs/AllPOs.txt

@@ -457,11 +457,17 @@ Examples:	; this was taken from <6502/std.a>:
 
 
 Call:		!for SYMBOL, START, END { BLOCK }
+or:		!for SYMBOL in ITERABLE { BLOCK }
 Purpose:	Looping assembly. The block of statements will be
 		parsed a fixed number of times, as specified by the
-		values of START and END. For more flexible
-		possibilities, have a look at "!do" and "!while"
-		below.
+		arguments:
+		When using the first syntax, SYMBOL will simply count
+		from START to END.
+		When using the second syntax, SYMBOL will iterate over
+		the contents of the ITERABLE, which must be a string
+		or a list.
+		For more flexible loop constructs, have a look at
+		"!do" and "!while" below.
 Parameters:	SYMBOL: Any valid symbol name.
 		START: Any formula the value parser accepts, but it
 		must be solvable even in the first pass. SYMBOL will 
@@ -469,6 +475,15 @@ Parameters:	SYMBOL: Any valid symbol name.
 		END: Any formula the value parser accepts, but it must
 		be solvable even in the first pass. SYMBOL will have
 		this value during the last loop cycle.
+		ITERABLE: This must be a string or a list, but its
+		length must be defined even in the first pass (and of
+		course it should stay the same during all subsequent
+		passes).
+			If ITERABLE is a list, its _items_ are allowed
+			to be undefined.
+			If ITERABLE is a string, SYMBOL will be set to
+			each of its character codes in turn, using the
+			currently chosen conversion table.
 		BLOCK: A block of assembler statements.
 		If START or END are floats, they will be converted to
 		integers (never use floats for loop counters). If
@@ -508,8 +523,25 @@ Examples:
 			sta $0400 + i
 		}
 
-Miscellaneous:	The old syntax ("!for SYMBOL, END { BLOCK }" where
-		START was always implied to be 1) is still fully
+	split_table_lo ; generate two tables from one list
+		!for h in my_handler_list {
+			!by <h
+		}
+	split_table_hi
+		!for h in my_handler_list {
+			!by >h
+		}
+
+	hidden_string ; "encrypt" a string by XORing with address
+		!ct scr {	; use screen codes
+			!for c in "very secret message" {
+				!by c XOR <*
+			}
+		}
+
+Miscellaneous:	The old syntax
+			!for SYMBOL, END { BLOCK }
+		where START was always implied to be 1 is still fully
 		supported, but gives a warning to get people to change
 		to the new syntax.
 		You can disable this warning using the "--dialect" or
@@ -778,6 +810,11 @@ or type (call-by-value vs. call-by-reference). So
 		!macro process_bytes b1, b2, ~b3 {...whatever...}
 can *all* be used at the same time without any name clash.
 
+Since release 0.97, lists are supported. This is useful for macros if
+you want an arbitrary number of arguments: Just define the macro with
+a single argument, then pass a list and have the macro iterate over
+its contents.
+
 
 ----------------------------------------------------------------------
 Section:   Segment assembly

docs/Errors.txt

@@ -264,6 +264,12 @@ File name quotes not found ("" or <>).
     File names have to be given in quotes. Either "" quoting for files
     located in the current directory or <> quoting for library files.
 
+Force bits can only be given to counters, not when iterating over string/list contents.
+    You used a force bit with a "!for" loop counter, but then used the
+    "iterate over string/list contents" syntax. This does not work,
+    because lists could contain other lists, and then a force bit does
+    not make any sense.
+
 Force bits can only be given to numbers.
     You tried to give a force bit to a symbol and then assign a string
     or list to it.
@@ -276,6 +282,10 @@ Garbage data at end of statement (unexpected 'CHAR').
     There are still arguments when there should not be any more. The
     given character is the one where end-of-line was expected.
 
+Given object is not iterable.
+    You used "!for VAR in ITERABLE", but the iterable was neither a
+    string nor a list (likely a number).
+
 Hex digits are not given in pairs.
     The two digits of a hex byte are separated by another character,
     or there is an odd number of digits.
@@ -289,6 +299,12 @@ Index is undefined.
 Index out of range.
     The value for an indexing operation wasn't in the allowed range.
 
+Loop var must be followed by either "in" keyword or comma.
+    You made a syntax error when using "!for": After the loop counter
+    symbol there can either be a comma (for a simple counting loop) or
+    the "in" keyword (when iterating over string or list contents).
+    Anything else will give this error.
+
 Macro already defined.
     Macros can only be defined once. If you define a macro twice, ACME
     will help you find the definitions by giving a warning for the
@@ -554,6 +570,9 @@ IllegalImmediateMode
 IllegalInputSource
     Input is taken neither from a file nor from a RAM block.
 
+IllegalLoopAlgo
+    The "!for" function was told to use an unknown algorithm.
+
 IllegalNumberTypeX
     A number was neither INT nor FLOAT nor UNDEFINED.