Update for new features/version

git-svn-id: svn://svn.cc65.org/cc65/trunk@138 b7a2c559-68d2-44c3-8de9-860c34a00d81

doc/ca65.txt

@@ -4,7 +4,7 @@
 
 	   A Macro Crossassembler for the 6502/65C02/65816 CPUs
 
-	      (C) Copyright 1998-1999 Ullrich von Bassewitz
+	      (C) Copyright 1998-2000 Ullrich von Bassewitz
 			    (uz@musoftware.de)
 
 
@@ -95,12 +95,6 @@ development:
     this decision, but I've written several multipass assemblers, and it
     started to get boring. A one pass assembler needs much more elaborated
     data structures, and because of that it's much more fun:-)
-    There is one drawback with this point: It is nearly impossible to
-    generate a listing when reading the source file only once without
-    storing the source file in memory. Consequently, the assembler is not
-    able to produce a listing. This could be added by reading the source
-    file a second time if a listing was requested, but I didn't see an
-    urgent need for a listing, so this was not a disadvantage for me.
 
   * Non-GPLed code that may be used in any project without restrictions or
     fear of "GPL infecting" other code.
@@ -112,81 +106,162 @@ development:
 
 The assembler accepts the following options:
 
-   	-g		Generate debug info
+---------------------------------------------------------------------------
-   	-i		Ignore case of symbols
+Usage: ca65 [options] file
-        -l              Create a listing if assembly was ok
+Short options:
-   	-o name		Name the output file
+  -g			Add debug info to object file
-   	-s		Enable smart mode
+  -h			Help (this text)
-   	-v		Increase verbosity
+  -i			Ignore case of symbols
-	-D name[=value]	Define a symbol
+  -l			Create a listing if assembly was ok
-	-U		Mark unresolved symbols as import
+  -o name		Name the output file
-	-V		Print the assembler version
+  -s			Enable smart mode
-	-W n		Set warning level n
+  -v			Increase verbosity
-        --cpu type      Set cpu type
+  -D name[=value]	Define a symbol
-	--pagelength n	Set the page length for the listing
+  -I dir		Set an include directory search path
-        --smart         Enable smart mode
+  -U			Mark unresolved symbols as import
+  -V			Print the assembler version
+  -W n			Set warning level n
 
-When the -g option (or the equivalent control command .DEBUGINFO) is used,
+Long options:
-the assembler will add a section to the object file that contains all
+  --auto-import		Mark unresolved symbols as import
-symbols (including local ones) together with the symbol values and source
+  --cpu type		Set cpu type
-file positions. The linker will put these additional symbols into the
+  --debug-info		Add debug info to object file
-VICE label file, so even local symbols can be seen in the VICE monitor.
+  --help      		Help (this text)
+  --ignore-case		Ignore case of symbols
+  --include-dir dir	Set an include directory search path
+  --listing  		Create a listing if assembly was ok
+  --pagelength n	Set the page length for the listing
+  --smart    		Enable smart mode
+  --verbose  		Increase verbosity
+  --version   		Print the assembler version
+---------------------------------------------------------------------------
 
-The option -i makes the assembler case insensitive on identifiers and
+Here is a description of all the command line options:
-labels. This option will override the default, but may itself be overriden
-by the .CASE control command (see section 6).
 
-The default output name is the name of the input file with the extension
-replaced by ".o". If you don't like that, you may give another name with
-the -o option. The output file will be placed in the same directory as the
-source file, or, if -o is given, the full path in this name is used.
 
-In smart mode (enabled by -s or the .SMART pseudo instruction) the
+  --cpu type
-assembler will track usage of the REP and SEP instructions in 65816 mode
-and update the operand sizes accordingly. If the operand of such an
-instruction cannot be evaluated by the assembler (for example, because the
-operand is an imported symbol), a warning is issued. Beware: Since the
-assembler cannot trace the execution flow this may lead to false results
-in some cases. If in doubt, use the .ixx and .axx instructions to tell the
-assembler about the current settings. Smart mode is off by default.
 
--v does increase the assembler verbosity and is usually only needed for
+  Set the default for the CPU type. The option takes a parameter, which
-debugging purposes. You may use this option more than one time for even
+  may be one of
-more verbose output.
 
--D allows you to predefine symbols on the command line. Without a value,
+ 	6502, 65C02, 65816 and sunplus
-the symbol is defined with the value zero. When giving a value, you may
-use the '$' prefix for hexadecimal symbols. Please note that for some
-operating systems, '$' has a special meaning, so you may have to quote
-the expression.
 
--U marks symbols that are not defined in the sources as imported symbols.
+  (the latter is not available in the freeware version).
-This should be used with care since it delays error messages about typos
-and such until the linker is run. The compiler uses the equivalent of
-this switch (.AUTOIMPORT, see control command section below) to enable
-auto imported symbols for the runtime library. However, the compiler is
-supposed to generate code that runs through the assembler without
-problems, something which is not always true for assembler programmers.
 
--V prints the version number of the assembler. If you send any suggestions
-or bugfixes, please include your version number.
 
--Wn sets the warning level for the assembler. Using -W2 the assembler will
+  -g
-even warn about such things like unused imported symbols. The default
+  --debug-info
-warning level is 1, and it would probably be silly to set it to something
-lower.
 
---cpu sets the default for the CPU type. The option takes a parameter,
+  When this option (or the equivalent control command .DEBUGINFO) is used,
-which may be one of
+  the assembler will add a section to the object file that contains all
+  symbols (including local ones) together with the symbol values and
+  source file positions. The linker will put these additional symbols into
+  the VICE label file, so even local symbols can be seen in the VICE
+  monitor.
 
-	6502, 65C02, 65816 and sunplus
 
-(the latter is not available in the freeware version).
+  -h
+  --help
 
---pagelength sets the length of a listing page in lines. See the
+  Print the short option summary shown above.
-.PAGELENGTH directive for more information.
 
---smart is identical to -s - see there.
+
+  -i
+  --ignore-case
+
+  This option makes the assembler case insensitive on identifiers and
+  labels. This option will override the default, but may itself be
+  overriden by the .CASE control command (see section 6).
+
+
+  -l
+  --listing
+
+  Generate an assembler listing. The listing file will always have the
+  name of the main input file with the extension replaced by ".lst". This
+  may change in future versions.
+
+
+  -o name
+
+  The default output name is the name of the input file with the extension
+  replaced by ".o". If you don't like that, you may give another name with
+  the -o option. The output file will be placed in the same directory as
+  the source file, or, if -o is given, the full path in this name is used.
+
+
+  --pagelength n
+
+  sets the length of a listing page in lines. See the .PAGELENGTH
+  directive for more information.
+
+
+  -s
+  --smart-mode
+
+  In smart mode (enabled by -s or the .SMART pseudo instruction) the
+  assembler will track usage of the REP and SEP instructions in 65816 mode
+  and update the operand sizes accordingly. If the operand of such an
+  instruction cannot be evaluated by the assembler (for example, because
+  the operand is an imported symbol), a warning is issued.
+
+  Beware: Since the assembler cannot trace the execution flow this may
+  lead to false results in some cases. If in doubt, use the .ixx and .axx
+  instructions to tell the assembler about the current settings. Smart
+  mode is off by default.
+
+
+  -v
+  -verbose
+
+  Increase the assembler verbosity. Usually only needed for debugging
+  purposes. You may use this option more than one time for even more
+  verbose output.
+
+
+  -D
+
+  This option allows you to define symbols on the command line. Without a
+  value, the symbol is defined with the value zero. When giving a value,
+  you may use the '$' prefix for hexadecimal symbols. Please note that for
+  some operating systems, '$' has a special meaning, so you may have to
+  quote the expression.
+
+
+  -I dir
+  --include-dir dir
+
+  Name a directory which is searched for include files. The option may be
+  used more than once to specify more than one directory to search. The
+  current directory is always searched first before considering any
+  additional directores.
+
+
+  -U
+  --auto-import
+
+  Mark symbols that are not defined in the sources as imported symbols.
+  This should be used with care since it delays error messages about typos
+  and such until the linker is run. The compiler uses the equivalent of
+  this switch (.AUTOIMPORT, see control command section below) to enable
+  auto imported symbols for the runtime library. However, the compiler is
+  supposed to generate code that runs through the assembler without
+  problems, something which is not always true for assembler programmers.
+
+
+  -V
+  --version
+
+  Print the version number of the assembler. If you send any suggestions
+  or bugfixes, please include the version number.
+
+
+  -Wn
+
+  Set the warning level for the assembler. Using -W2 the assembler will
+  even warn about such things like unused imported symbols. The default
+  warning level is 1, and it would probably be silly to set it to
+  something lower.
 
 
 
@@ -308,10 +383,13 @@ Available operators sorted by precedence:
     .CONST	Builtin function	     		1
     .CPU	Builtin pseudo variable (r/o)		1
     .DEFINED	Builtin function	     		1
+    .LEFT	Builtin function			1
     .MATCH	Builtin function			1
+    .MID	Builtin function			1
     .XMATCH	Builtin function			1
     .PARAMCOUNT Builtin pseudo variable	(r/o)		1
     .REFERENCED Builtin function			1
+    .RIGHT	Builtin function			1
     .STRING	Builtin function			1
     :: 	    	Global namespace override		1
     +  	    	Unary plus			   	1
@@ -331,7 +409,7 @@ Available operators sorted by precedence:
     << 	    	Shift left operator			2
     .SHL	Shift left operator			2
     >> 	    	Shift right operator			2
-    .SHR	Shift right operator			2
+    .SHR	Shift right operator 			2
 
     +  	    	Binary plus		   		3
     -  	    	Binary minus				3
@@ -1159,6 +1237,36 @@ Here's a list of all control commands and a description, what they do:
    	.include	"subs.inc"
 
 
+.LEFT
+
+  Builtin function. Extracts the left part of a given token list.
+
+  Syntax:
+
+       	.LEFT (<int expr>, <token list>)
+
+  The first integer expression gives the number of tokens to extract from
+  the token list. The second argument is the token list itself.
+
+  Example:
+
+    To check in a macro if the given argument has a '#' as first token
+    (immidiate addressing mode), use something like this:
+
+    	.macro	ldax	arg
+    		...
+    		.if (.match (.left (1, arg), #))
+
+    		; ldax called with immidiate operand
+    		...
+
+    		.endif
+    		...
+       	.endmacro
+
+  See also the .MID and .RIGHT builtin functions.
+
+
 .LINECONT
 
   Switch on or off line continuations using the backslash character
@@ -1325,6 +1433,39 @@ Here's a list of all control commands and a description, what they do:
     be the reserved keyword "A".
 
 
+.MID
+
+  Builtin function. Takes a starting index, a count and a token list as
+  arguments. Will return part of the token list.
+
+  Syntax:
+
+	.MID (<int expr>, <int expr>, <token list>)
+
+  The first integer expression gives the starting token in the list (the
+  first token has index 0). The second integer expression gives the number
+  of tokens to extract from the token list. The third argument is the
+  token list itself.
+
+  Example:
+
+    To check in a macro if the given argument has a '#' as first token
+    (immidiate addressing mode), use something like this:
+
+    	.macro	ldax	arg
+    		...
+    		.if (.match (.mid (0, 1, arg), #))
+
+    		; ldax called with immidiate operand
+    		...
+
+    		.endif
+    		...
+       	.endmacro
+
+  See also the .LEFT and .RIGHT builtin functions.
+
+
 .ORG
 
   Start a section of absolute code. The command is followed by a constant
@@ -1456,7 +1597,7 @@ Here's a list of all control commands and a description, what they do:
   storage should be defined. The second, optional expression must by a
   constant byte value that will be used as value of the data. If there
   is no fill value given, the linker will use the value defined in the
-  linker configuration file (default: zero).
+  linker configuration file (default: zero).	
 
   Example:
 
@@ -1464,6 +1605,20 @@ Here's a list of all control commands and a description, what they do:
   	.res	12, $AA
 
 
+.RIGHT
+
+  Builtin function. Extracts the right part of a given token list.
+
+  Syntax:
+
+       	.RIGHT (<int expr>, <token list>)
+
+  The first integer expression gives the number of tokens to extract from
+  the token list. The second argument is the token list itself.
+
+  See also the .LEFT and .MID builtin functions.
+
+
 .RODATA
 
   Switch to the RODATA segment. The name of the RODATA segment is always
@@ -1821,7 +1976,7 @@ Macros with parameters may also be useful:
       	.define DEBUG(message)	.out	message
 
       	DEBUG	"Assembling include file #3"
-
+			       
 Note that, while formal parameters have to be placed in braces, this is
 not true for the actual parameters. Beware: Since the assembler cannot
 detect the end of one parameter, only the first token is used. If you
@@ -1896,9 +2051,9 @@ hear from you. Feel free to contact me by email (uz@musoftware.de).
 10. Copyright
 -------------
 
-ca65 (and all cc65 binutils) are (C) Copyright 1998 Ullrich von Bassewitz.
+ca65 (and all cc65 binutils) are (C) Copyright 1998-2000 Ullrich von
-For usage of the binaries and/or sources the following conditions do
+Bassewitz. For usage of the binaries and/or sources the following
-apply:
+conditions do apply:
 
 This software is provided 'as-is', without any expressed or implied
 warranty.  In no event will the authors be held liable for any damages