Updating readme

README.md

@@ -1,43 +1,88 @@
-# assembler6502 0.3
+# Assembler6502 0.4
 
 An NES assembler for the 6502 microprocessor written in Ruby
 
  Usage: ./assembler\_6502.rb <infile.asm> -o outfile.nes
 
-  This is a pretty straightfoward assembler, that is currently set up
-  to produce iNES ROM formatted binaries from simple assembly listings.
+  This is a pretty straightfoward assembler, which is currently set up
+  to produce iNES formatted ROM binaries from 6502 assembly language files.
+
+  Inside An NES cartridge there are basically some number of ROM chips
+  which contain banks of either program code or character (graphics) 
+  data.  A PROG ROM bank is generally 16KB, and a CHAR ROM bank is generally
+  8KB.  At least one PROG ROM bank is required, and the NES can address
+  2 PROG ROM banks and 1 CHAR ROM bank without the use of a mapper.
+
+  This assembler works on the idea of defining these banks, and allowing
+  you to specify their contents.  When you then assemble your output ROM
+  this assembler translates the assmebly code in your your PROG banks 
+  into executable binary segments, and also lets you organize and address
+  data in your CHAR banks.  In the end it jams all these banks together
+  one after another, PROG first, then CHAR, and slaps an iNES header
+  on the front of it.
+
   It is good at knowing which addressing modes are and are not allowed for 
   each instruction, and contains some examples of correct syntax.
 
-  This assembler does not understand banks or mappers yet, and so having
-  more than one PROG section does not quite work yet.  That is next
-  in line to be fixed.
-  
-  It handles labels, and does a two pass assembly, first assembling
-  the byte codes, and then going back and filling in the proper addresses
-  where labels were used.
+  I believe this assembler can now handle bankswitching if you set a 
+  valid mapper in the header, write more than 2 PROG banks, and then 
+  and write whatever bankswitching code is nessessary for the mapper
+  you've chosen.  I have not tried this yet, but I will be testing it
+  out soon.
+
+  This assembler supports symbolic labels which can be scoped.  When 
+  writing assembly it can be easy to run out of effective names for 
+  labels when they are scoped globally.  I have seen other assemblers
+  using anonymous labels to get around this but I decided I didn't like
+  that syntax very much.  Instead I opted to allow opening a new scope
+  where you can reuse symbol names.  You can give scopes names or allow
+  them to be anonymous.  If you choose to name a symbol scope you can
+  use a dot syntax to address any symbols that are outside your current
+  scope.  I should put some example code up here showing this.
+
+  I hoped to make writing NES libraries more effective since you can basically
+  namespace your symbols into your own file and not mess with anyone 
+  else's code.  I also have a feeling that this will have some use in
+  creating in memory data structures similar to a C struct in the future.
+
+  The assembler does two passes over your code, any symbols that are used
+  which it hasn't seen the definition for yet return a "promise", that 
+  are stored for the second pass.  A "promise" is a fancy name for a 
+  lambda/closure which promises to come up with a value later, while
+  your code continues on.  It then evaluates all these "promises" during
+  the assembler's second pass, which fills in the missing addresses etc.
 
   I have used this to compile some code for the NES, and it ran correctly
   on FCEUX, got it to make some sounds, load tiles, sprites, and scrolling.
 
+  There is an example file included (shown below) that is a modified port of
+  the NES101 tutorial by Michael Martin.
+
   ![Scrolling NES Demo](assembler_demo.png)
 
   Some Todos:
-  - Understand how to deal with various mappers
-  - Understand how to create multiple banks
   - Get an NSF file playing
-  - More unit tests for each instruction
   - I may make this into a Rubygem
   - Maybe I can put some better error messages.
   - I would like to add some Macros to generate settings for
     the PPU and APU, (values for locations like $2000 and $2001,
-    the $4000s, etc.)
+    the $4000s, etc.)  Put into a library.
   - Support binary literals ie %10101010
-  - Anonymous Label support, (maybe, not sure if I like the idea)
   - Give this project a better name.
   - Create an interactive read eval compile loop?
+  - Add scoping directives
+  - Add struct directive
+  - Add macro/symbol define directive, name memory
+  - Make an interactive mode
 
  Some new additions:
+  - Split the Parser into its own class
+  - New MemorySpace class
+  - Rewrote the Assembler class
+  - Rewrote the Instruction class 
+  - Rewrote all directive's classes
+  - Split the assembler from the commandline front-end 
+  - Scoped Symbol Table
   - Lower case mnemonics and hex digits
   - Ported NES101 tutor to this assembler.
   - Added msb and lsb byte selectors on address labels
@@ -46,19 +91,10 @@ An NES assembler for the 6502 microprocessor written in Ruby
   - added .bytes directive
   - added .incbin directive
   - added .ascii directive
+  - added .segment directive
   - Invented my own iNES header directive that is JSON
   - Split the project up into separate files per class
   - Wrote some more unit tests
   - Added OptionParser for commandline opts
   - Tested a ROM with Sound output
   - Tested a ROM that changes background color
-
-I decided that during the first pass of assembly, I should just initialize
-an entire 65535 byte virtual memory images, and write the instructions to
-their correct places, and then after resolving symbols during the second pass,
-I just clip out the Cartridge ROM area and iNES header at the end, works great 
-so far.  Now that I know I will need to support various mappers, I still may 
-use this method, but will need to create multiple 65535 memory segments and use
-banking to distinguish them before finally writing out the resulting ROM in
-the correct order.
-