Merge pull request #222 from boriel/doc

Doc

Author: boriel

doc/docs

@@ -0,0 +1 @@
+../docs

doc/process_wiki.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+from bs4 import BeautifulSoup as BS
+import sys
+import re
+import os
+
+RE_CODE = re.compile('<zxbasic>|</zxbasic>|<freebasic>|</freebasic>|<qbasic>|</qbasic>')
+RE_INTERNAL_LINK = re.compile(r'\[\[([^]|]+)(\|[^]]+)?\]\]')
+RE_EXTERNAL_LINK = re.compile(r'\[(http://[^ ]+) ([^]]+)\]')
+
+
+def get_file_names(path):
+    result = set()
+    for root, dir, files in os.walk(path):
+        result.update([os.path.basename(x) for x in files])
+
+    return result
+
+
+def link_to_fname(link):
+    if link.startswith('ZX_BASIC:'):
+        link = link[9:]
+
+    link = link.replace(' ', '_').lower() + '.md'
+    link = link.replace('released_programs_-_', 'released_programs/')
+    return link
+
+
+def write_page(title, text, sha1, already_done):
+    fname = title.replace(' ', '_').lower().replace('released_programs_-_', 'released_programs/') + '.md'
+    if fname in already_done:
+        return
+
+    print('Processing {}'.format(fname))
+
+    with open(fname, 'wt', encoding='utf-8') as fout:
+        fout.write('#{}\n\n'.format(title))
+        started = False
+        verbatim = False
+
+        for line in text.split('\n'):
+            if line == sha1:
+                continue
+
+            started = started or line == 'text/x-wiki'
+            if not started or line == 'text/x-wiki':
+                continue
+
+            prefix = ''
+            if line.startswith(' ') or verbatim:
+                if not verbatim:
+                    fout.write('```\n')
+                    verbatim = True
+                elif line and not line.startswith(' '):
+                    fout.write('\n```')
+                    verbatim = False
+
+            if not verbatim:
+                while line and line[0] == line[-1] == '=':
+                    line = line[1:-1]
+                    prefix = prefix + '#'
+
+                line = line.replace("'''", '**')
+                line = line.replace("''", '_')
+                line = RE_CODE.sub(repl='\n```\n', string=line)
+                line = line.replace('<tt>', '_').replace('</tt>', '_')
+
+                while True:
+                    match = RE_INTERNAL_LINK.search(line)
+                    if not match:
+                        break
+                    lline = list(line)
+                    a, b = match.span()
+                    fname, txt = match.groups()
+                    txt = (txt or fname).lstrip('|')
+                    lline[a: b] = list('[{}]({})'.format(txt, link_to_fname(fname)))
+                    line = ''.join(lline)
+
+                while True:
+                    match = RE_EXTERNAL_LINK.search(line)
+                    if not match:
+                        break
+                    lline = list(line)
+                    a, b = match.span()
+                    link, txt = match.groups()
+                    txt = (txt or link).strip()
+                    lline[a: b] = list('[{}]({})'.format(txt, link))
+                    line = ''.join(lline)
+
+                line = line.replace('&gt;', '>').replace('&lt;', '<').replace('&amp;', '&')
+                if line.startswith('*') and line[:2] not in ('* ', '**'):
+                    line = '* {}'.format(line[1:])
+
+            fout.write(prefix + line + '\n')
+
+
+# given your html as the variable 'html'
+with open(sys.argv[1], 'rt') as f:
+    soup = BS(f.read(), "xml")
+
+already_done = get_file_names('./docs')
+
+pages = soup.find_all('page')
+for page in pages:
+    title = page.title.text
+    if not title.startswith('ZX BASIC:'):
+        continue
+    title = title[9:]
+    write_page(title, page.text, page.sha1.text, already_done)

docs/about.md

@@ -0,0 +1,20 @@
+#About
+
+
+##About the ZX BASIC Project
+
+ZX BASIC is a [BASIC](http://en.wikipedia.org/wiki/BASIC) ''cross compiler''.
+It will compile BASIC programs (in your PC) for your [ZX Spectrum](http://en.wikipedia.org/wiki/Sinclair_ZX_Spectrum).
+ZX BASIC is an <abbr title="Software Development Kit">SDK</abbr> entirely written in [python](http://www.python.org).
+The SDK is implemented using the [PLY](http://www.dabeaz.com/ply/) (Python Lex/Yacc) compiler tool.
+It translates BASIC to Z80 assembler code, so it is easily portable to other Z80 platforms (Amstrad, MSX).
+Other non Z80 targets could also be available in the future.
+
+ZX BASIC syntax tries to maintain compatibility as much as possible with
+[Sinclair BASIC](http://en.wikipedia.org/wiki/Sinclair_BASIC), it also have many new features, mostly taken from
+[FreeBASIC](http://www.freebasic.net/wiki) dialect.
+
+###Platform Availability
+Since it is written in python, it is available for many platforms, like Windows, Linux and Mac.
+You only need to have python installed on these. For windows, there also is an installable (.MSI) _compiled_
+version, which does not need python previously installed.

docs/abs.md

@@ -0,0 +1,30 @@
+#ABS
+
+##Syntax
+
+
+```
+ABS(numericExpression)
+```
+
+
+##Description
+
+Returns the absolute value of the given argument.
+Argument must be a numeric expression. Returned value has the same type as the input argument.
+
+##Examples
+
+
+```
+REM Absolute value
+LET a = -1
+PRINT "Absolute value of a is "; ABS(a)
+REM 'Will print 1
+```
+
+
+##Remarks
+
+* This function is 100% Sinclair BASIC Compatible
+

docs/acs.md

@@ -0,0 +1,32 @@
+#ACS
+
+##Syntax
+
+```
+ACS(numericExpression)
+```
+ 
+
+##Description
+
+Returns the arc cosine value of the given argument.
+Argument must be a numeric expression. Returned value type is [Float](types#float.md).
+
+##Examples
+
+```
+REM Arc cosine value
+PRINT "Arc Cosine value of a is "; ACS(a)
+```
+ 
+
+##Remarks
+
+* This function is 100% Sinclair BASIC Compatible
+* If the given argument type is not float, it will be [converted](cast.md) to float before operating with it.
+
+##See also
+
+* [SIN](sin.md) and [ASN](asn.md)
+* [TAN](tan.md) and [ATN](atn.md)
+* [COS](cos.md)

docs/architectures/6502.py.md

@@ -0,0 +1,171 @@
+#6502.py
+
+```
+  #!/usr/bin/python
+  # -*- coding: utf-8 -*-
+  # vim:ts=4:et:
+  #- important: this code is not acurated yet - needs fixes
+  class Opcode(object):
+    ''' Describes opcodes and other info.
+    '''
+    def __init__(self, asm, time, size, opcode):
+      self.asm = asm
+      self.T = time
+      self.size = size
+      self.opcode = opcode
+  6502SET = {
+    "BRK": Opcode("BRK", 1, 1, "00"),
+    "ORA (x,X)": Opcode("ORA (x,X)", 1, 1, "01 XX XX"),
+    "ORA x": Opcode("ORA x", 1, 1, "05 XX"),
+    "ASL x": Opcode("ASL x", 1, 1, "06 XX"),
+    "PHP": Opcode("PHP", 1, 1, "08"),
+    "ORA #x": Opcode("ORA #x", 1, 1, "09 XX"),
+    "ASL": Opcode("ASL", 1, 1, "0a"),
+    "ORA ?": Opcode("ORA ?", 1, 1, "0d XX XX"),
+    "ASL ?": Opcode("ASL ?", 1, 1, "0e XX XX"),
+    "BPL x": Opcode("BPL x", 1, 1, "10 XX"),
+    "ORA (x),Y": Opcode("ORA (x),Y", 1, 1, "11 XX"),
+    "ORA x,X": Opcode("ORA x,X", 1, 1, "15 XX"),
+    "ASL x,X": Opcode("ASL x,X", 1, 1, "16 XX"),
+    "CLC": Opcode("CLC", 1, 1, "18"),
+    "ORA ?,Y": Opcode("ORA ?,Y", 1, 1, "19 XX XX"),
+    "ORA ?,X": Opcode("ORA ?,X", 1, 1, "1d XX XX"),
+    "ASL ?,X": Opcode("ASL ?,X", 1, 1, "1e XX XX"),
+    "JSR ?": Opcode("JSR ?", 1, 1, "20 XX XX"),
+    "AND (x,X)": Opcode("AND (x,X)", 1, 1, "21 XX"),
+    "BIT x": Opcode("BIT x", 1, 1, "24 XX"),
+    "AND x": Opcode("AND x", 1, 1, "25 XX"),
+    "ROL x": Opcode("ROL x", 1, 1, "26 XX"),
+    "PLP": Opcode("PLP", 1, 1, "28"),
+    "AND #x": Opcode("AND #x", 1, 1, "29 XX"),
+    "ROL A": Opcode("ROL A", 1, 1, "2a"),
+    "BIT ?": Opcode("BIT ?", 1, 1, "2c XX XX"),
+    "AND ?": Opcode("AND ?", 1, 1, "2d XX XX"),
+    "ROL ?": Opcode("ROL ?", 1, 1, "2e XX XX"),
+    "BMI x": Opcode("BMI x", 1, 1, "30 XX"),
+    "AND (x),Y": Opcode("AND (x),Y", 1, 1, "31 XX"),
+    "AND x,X": Opcode("AND x,X", 1, 1, "35 XX"),
+    "ROL x,X": Opcode("ROL x,X", 1, 1, "36 XX"),
+    "SEC": Opcode("SEC", 1, 1, "38"),
+    "AND ?,Y": Opcode("AND ?,Y", 1, 1, "39 XX XX"),
+    "AND ?,X": Opcode("AND ?,X", 1, 1, "3d XX XX"),
+    "ROL ?,X": Opcode("ROL ?,X", 1, 1, "3e XX XX"),
+    "RTI": Opcode("RTI", 1, 1, "40"),
+    "EOR (x,X)": Opcode("EOR (x,X)", 1, 1, "41 XX"),
+    "EOR x": Opcode("EOR x", 1, 1, "45 XX"),
+    "LSR x": Opcode("LSR x", 1, 1, "46 XX"),
+    "PHA": Opcode("PHA", 1, 1, "48"),
+    "EOR #x": Opcode("EOR #x", 1, 1, "49 XX"),
+    "LSR A": Opcode("LSR A", 1, 1, "4a"),
+    "JMP ?": Opcode("JMP ?", 1, 1, "4c XX XX"),
+    "EOR ?": Opcode("EOR ?", 1, 1, "4d XX XX"),
+    "LSR ?": Opcode("LSR ?", 1, 1, "4e XX XX"),
+    "BVC x": Opcode("BVC x", 1, 1, "50 XX"),
+    "EOR (x),Y": Opcode("EOR (x),Y", 1, 1, "51 XX"),
+    "EOR x,X": Opcode("EOR x,X", 1, 1, "55 XX"),
+    "LSR x,X": Opcode("LSR x,X", 1, 1, "56 XX"),
+    "CLI": Opcode("CLI", 1, 1, "58"),
+    "EOR ?,Y": Opcode("EOR ?,Y", 1, 1, "59 XX XX"),
+    "EOR ?,X": Opcode("EOR ?,X", 1, 1, "5d XX XX"),
+    "LSR ?,X": Opcode("LSR ?,X", 1, 1, "5e XX XX"),
+    "RTS": Opcode("RTS", 1, 1, "60"),
+    "ADC (x,X)": Opcode("ADC (x,X)", 1, 1, "61 XX"),
+    "ADC x": Opcode("ADC x", 1, 1, "65 XX"),
+    "ROR x": Opcode("ROR x", 1, 1, "66 XX"),
+    "PLA": Opcode("PLA", 1, 1, "68"),
+    "ADC #x": Opcode("ADC #x", 1, 1, "69 XX"),
+    "ROR A": Opcode("ROR A", 1, 1, "6a"),
+    "JMP (?)": Opcode("JMP (?)", 1, 1, "6c XX XX"),
+    "ADC ?": Opcode("ADC ?", 1, 1, "6d XX XX"),
+    "ROR ?": Opcode("ROR ?", 1, 1, "6e XX XX"),
+    "BVS x": Opcode("BVS x", 1, 1, "70 XX"),
+    "ADC (x),Y": Opcode("ADC (x),Y", 1, 1, "71 XX"),
+    "ADC x,X": Opcode("ADC x,X", 1, 1, "75 XX"),
+    "ROR x,X": Opcode("ROR x,X", 1, 1, "76 XX"),
+    "SEI": Opcode("SEI", 1, 1, "78"),
+    "ADC ?,Y": Opcode("ADC ?,Y", 1, 1, "79 XX XX"),
+    "ADC ?,X": Opcode("ADC ?,X", 1, 1, "7d XX XX"),
+    "ROR ?,X": Opcode("ROR ?,X", 1, 1, "7e XX XX"),
+    "STA (x,X)": Opcode("STA (x,X)", 1, 1, "81 XX"),
+    "STY x": Opcode("STY x", 1, 1, "84 XX"),
+    "STA x": Opcode("STA x", 1, 1, "85 XX"),
+    "STX x": Opcode("STX x", 1, 1, "86 XX"),
+    "DEY": Opcode("DEY", 1, 1, "88"),
+    "TXA": Opcode("TXA", 1, 1, "8a"),
+    "STY ?": Opcode("STY ?", 1, 1, "8c XX XX"),
+    "STA ?": Opcode("STA ?", 1, 1, "8d XX XX"),
+    "STX ?": Opcode("STX ?", 1, 1, "8e XX XX"),
+    "BCC x": Opcode("BCC x", 1, 1, "90 XX"),
+    "STA (x),Y": Opcode("STA (x),Y", 1, 1, "91 XX"),
+    "STY x,X": Opcode("STY x,X", 1, 1, "94 XX"),
+    "STA x,X": Opcode("STA x,X", 1, 1, "95 XX"),
+    "STX x,Y": Opcode("STX x,Y", 1, 1, "96 XX"),
+    "TYA": Opcode("TYA", 1, 1, "98"),
+    "STA ?,Y": Opcode("STA ?,Y", 1, 1, "99 XX XX"),
+    "TXS": Opcode("TXS", 1, 1, "9a"),
+    "STA ?,X": Opcode("STA ?,X", 1, 1, "9d XX XX"),
+    "LDY #x": Opcode("LDY #x", 1, 1, "a0 XX"),
+    "LDA (x,X)": Opcode("LDA (x,X)", 1, 1, "a1 XX"),
+    "LDX #x": Opcode("LDX #x", 1, 1, "a2 XX"),
+    "LDY x": Opcode("LDY x", 1, 1, "a4 XX"),
+    "LDA x": Opcode("LDA x", 1, 1, "a5 XX"),
+    "LDX x": Opcode("LDX x", 1, 1, "a6 XX"),
+    "TAY": Opcode("TAY", 1, 1, "a8"),
+    "LDA #x": Opcode("LDA #x", 1, 1, "a9 XX"),
+    "TAX": Opcode("TAX", 1, 1, "aa"),
+    "LDY ?": Opcode("LDY ?", 1, 1, "ac XX XX"),
+    "LDA ?": Opcode("LDA ?", 1, 1, "ad XX XX"),
+    "LDX ?": Opcode("LDX ?", 1, 1, "ae XX XX"),
+    "BCS x": Opcode("BCS x", 1, 1, "b0 XX"),
+    "LDA (x),Y": Opcode("LDA (x),Y", 1, 1, "b1"),
+    "LDY x,X": Opcode("LDY x,X", 1, 1, "b4"),
+    "LDA x,X": Opcode("LDA x,X", 1, 1, "b5"),
+    "LDX x,Y": Opcode("LDX x,Y", 1, 1, "b6"),
+    "CLV": Opcode("CLV", 1, 1, "b8"),
+    "LDA ?,Y": Opcode("LDA ?,Y", 1, 1, "b9"),
+    "TSX": Opcode("TSX", 1, 1, "ba"),
+    "LDY ?,X": Opcode("LDY ?,X", 1, 1, "bc"),
+    "LDA ?,X": Opcode("LDA ?,X", 1, 1, "bd"),
+    "LDX ?,Y": Opcode("LDX ?,Y", 1, 1, "be"),
+    "CPY #x": Opcode("CPY #x", 1, 1, "c0 XX"),
+    "CMP (x,X)": Opcode("CMP (x,X)", 1, 1, "c1 XX"),
+    "CPY x": Opcode("CPY x", 1, 1, "c4 XX"),
+    "CMP x": Opcode("CMP x", 1, 1, "c5 XX"),
+    "DEC x": Opcode("DEC x", 1, 1, "c6 XX"),
+    "INY": Opcode("INY", 1, 1, "c8"),
+    "CMP #x": Opcode("CMP #x", 1, 1, "c9 XX"),
+    "DEX": Opcode("DEX", 1, 1, "ca"),
+    "CPY ?": Opcode("CPY ?", 1, 1, "cc XX XX"),
+    "CMP ?": Opcode("CMP ?", 1, 1, "cd XX XX"),
+    "DEC ?": Opcode("DEC ?", 1, 1, "ce XX XX"),
+    "BNE x": Opcode("BNE x", 1, 1, "d0 XX"),
+    "CMP (x),Y": Opcode("CMP (x),Y", 1, 1, "d1 XX"),
+    "CMP x,X": Opcode("CMP x,X", 1, 1, "d5 XX"),
+    "DEC x,X": Opcode("DEC x,X", 1, 1, "d6 XX"),
+    "CLD": Opcode("CLD", 1, 1, "d8"),
+    "CMP ?,Y": Opcode("CMP ?,Y", 1, 1, "d9"),
+    "CMP ?,X": Opcode("CMP ?,X", 1, 1, "dd"),
+    "DEC ?,X": Opcode("DEC ?,X", 1, 1, "de"),
+    "CPX #x": Opcode("CPX #x", 1, 1, "e0 XX"),
+    "SBC (x,X)": Opcode("SBC (x,X)", 1, 1, "e1 XX"),
+    "CPX x": Opcode("CPX x", 1, 1, "e4 XX"),
+    "SBC x": Opcode("SBC x", 1, 1, "e5 XX"),
+    "INC x": Opcode("INC x", 1, 1, "e6 XX"),
+    "INX": Opcode("INX", 1, 1, "e8"),
+    "SBC #x": Opcode("SBC #x", 1, 1, "e9 XX"),
+    "NOP": Opcode("NOP", 1, 1, "ea"),
+    "CPX ?": Opcode("CPX ?", 1, 1, "ec XX XX"),
+    "SBC ?": Opcode("SBC ?", 1, 1, "ed XX XX"),
+    "INC ?": Opcode("INC ?", 1, 1, "ee XX XX"),
+    "BEQ x": Opcode("BEQ x", 1, 1, "f0 XX"),
+    "SBC (x),Y": Opcode("SBC (x),Y", 1, 1, "f1 XX"),
+    "SBC x,X": Opcode("SBC x,X", 1, 1, "f5 XX"),
+    "INC x,X": Opcode("INC x,X", 1, 1, "f6 XX"),
+    "SED": Opcode("SED", 1, 1, "f8"),
+    "SBC ?,Y": Opcode("SBC ?,Y", 1, 1, "f9 XX XX"),
+    "SBC ?,X": Opcode("SBC ?,X", 1, 1, "fd XX XX"),
+    "INC ?,X": Opcode("INC ?,X", 1, 1, "fe XX XX"),
+  
+  }
+
+