fam 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e38f107dfcb9efdeb43affd220b7ef40b662ddf35f21b070753fecc6bf953d25
-  data.tar.gz: 596acf48da4a1c333ad15b1ab8b4032f75ed02d8709d69dfca4a5f679807277f
+  metadata.gz: a4dfcc52fdeefad0727862860ec59ad2ff5d4609d82d998383e0f46e25bef721
+  data.tar.gz: ce91c0ca5e16a70c65c68054f4993ac5a9e2fee57d3c928a7d6f441b06cb1678
 SHA512:
-  metadata.gz: dfcc9df73fe1d1dbd3c4d5871392da853801db10bef0fd4972a0ea2a48224c36c7f16d755509df56bfcc38b15b9b12060af80798d6d945220cd7544180ab3165
-  data.tar.gz: 820eedd878734ceaca7bdc7e994f7649c18c09f2c62f5e6fc1365e9a50bf0605fc05675f1a0122eeb82d4876efaa83173a595ef8550588cfa5f2de2b5d6041ac
+  metadata.gz: 1a001bae8abf643e6c14d53e9346609d89ebfae9c6b8acd5361bbae4b6c33002c8aae60c7bd647cf82938ddb138257f7b3ec4722202b111d3770c807bf2b1a7d
+  data.tar.gz: 1442bf6cb3a042383ce68ee66cb681f6efce1a6db6b56601f5966c098420c1531f8562131361624f2d21ac8d93c30574686de52ae2d121c05a1b841260601d53

data/DOC.md

@@ -0,0 +1,109 @@
+# Documentation
+> Documentation, quite incomplete
+
+## Basic Syntax
+The syntax is extremely simplistic.
+
+The language consists mostly of labels, opcodes and operands.
+
+### Identifiers
+Identifiers are just names for things, such as variables, labels, etc.
+
+They may consist of any number of underscores (`_`) anywhere in the name and any number of Latin alphabet letters. Numbers may only exist in identifiers only if preceded by one or more letters or underscores.
+
+Identifiers have the following regular expression:
+
+`[A-Za-z_]([A-Za-z0-9_]+)?`
+
+### Labels
+A label is defined by an identifier (a name) immediately followed by a colon, e.g.
+```nasm
+LABEL_NAME:
+    !! Code goes here.
+    !! ...
+```
+A label if not jumped to by a `GOTO`, will be entered automatically, when that happens the special `_BACK` ident will be set to that label.
+
+Labels are defined as: `[a-zA-Z_]([a-zA-Z0-9_]+)?:`
+
+### Comments
+Single-line comments must start with an `!` (although it looks neater using a double exclamation-mark: `!!`), and are ended, naturally, by a new line.
+
+e.g.
+```nasm
+    SUB   4 : &ACC  !! Hi, I'm a comment
+    MOD 265 : &ACC
+```
+
+Multi-line comments start by a `{{` and are ended by a `}}`.
+
+e.g.
+```nasm
+  DATA x : -0xff
+  {{ I can be one line }}
+
+  {{
+      Here, multiple lines
+      are commented out.
+  }}
+```
+
+### Numerics
+Numerics must always start with either a number, or a sign (`+`/`-`). Hexadecimal and duodecimal (binary) support also exists; this is achieved by prepending a `0x` (hexadecimal) or `0b` (binary) prefix to the number.
+
+Normal base-10 numbers can have an `e` (scientific notation for 10 to the power of some number).
+
+Numbers can be defined through the regular expression:
+```
+(\-|\+)??((?=0x|0b)([0-9A-Za-z]+)|([0-9]+((e(\-|\+)?[0-9]+)?)))
+```
+
+Some examples of numbers:
+```
+!! Scientific notation
+12e1      !! becomes 120
+12e+1     !! becomes 120
+-23e+3    !! becomes -23000
+5000e-3   !! becomes 5
+
+!! Hexadecimal
+0xff4a    !! becomes 65354
+-0xff4a   !! becomes -65354
+
+!! Binary
+0b010110 !! becomes 184615184
+-0b101    !! becomes -5
+```
+
+### Registers
+Registers in the language, are names for the registers in the CPU. Registers must start with an `&` followed by any combination of lower and uppercase Latin letters, and digits.
+
+Regular expression: `&[a-zA-Z0-9]+`
+
+### Addresses
+Addresses address locations in memory, these address numbers range from `0` to your chosen allocated amount, minus one.
+
+Regular expression: `@[0-9]+`
+
+### Opcodes
+#### `:HALT`
+#### `:ALIAS`
+  **Not implemented.**
+#### `:DATA`
+#### `:STORE`
+#### `:LOAD`
+#### `:GOTO`
+#### `:DATA`
+#### `:EQUAL`
+#### `:MORE`
+#### `:LESS`
+#### `:ADD`
+#### `:SUB`
+#### `:MUL`
+#### `:DIV`
+#### `:MOD`
+#### `:SLEEP`
+  **Not implemented.**
+#### `:IN`
+#### `:OUT`
+#### `:ASCII`

data/README.md

@@ -1,2 +1,101 @@
 # FAM
-A very Fake Assembly(ish-language) Machine thingy...
+> A very **<u>F</u>ake** **<u>A</u>ssembly**(_-ish_ language) **<u>M</u>achine**, parser and _interpreter_.
+
+## Installation
+```shell
+gem install fam
+```
+## Documentation
+See this repository's `DOC.md` file.
+
+## Examples
+Examples can be found in scarce supply, in the `example` folder in this repository.
+
+Some examples:
+```nasm
+    STORE 55 : @0
+    DATA dyn : 0b01101  !! Dynamic memory allocation,
+    LOAD -0xf : &DAT    !! finds available memory location.
+    LOAD &DAT : &ACC
+
+LOOP:
+    ADD 1 : &ACC
+    OUT &ACC
+    STORE &ACC : dyn
+
+    EQUAL &ACC : 30
+        | GOTO END
+        | GOTO LOOP
+
+END: HALT 0
+```
+```nasm
+    GOTO INCR
+    OUT &ACC
+    HALT 0
+
+INCR:
+    ADD 1 : &ACC
+    GOTO _BACK
+
+{{  _BACK works by jumping to just after the last GOTO
+    statement, or jumping to the last label that was passed
+    without GOTOing to it.  }}
+```
+
+## Usage
+Current terminal usage is very simplistic.
+Simply, write `fam` and the file name _ensuring_ the file name ends in `.fam`.
+
+e.g.
+```shell
+fam some_file.fam
+```
+by default, the program is extremely verbose.
+To make any changes it is recommended you write a Ruby script to deal with it yourself.
+
+e.g.
+```ruby
+program = <<EOF
+  IN  &DAT
+  ADD 10 : &DAT
+  OUT &DAT
+
+  HALT 0
+EOF
+
+# PROGRAM STRING, ALLOC, CLOCK, VERBOSE?
+# All except the `program string' are optional,
+#   block is not required either.
+FAM.run program, '200B', 6, true do |ram, pc, regs|
+  puts "RAM:\n#{ram.to_a}"
+  puts "REGISTERS:"
+  regs.each { |name, value| puts "#{name} => #{value}" }
+
+  puts "PROGRAM COUNTER: #{pc}"
+end
+```
+in a more verbose manner:
+```ruby
+require 'fam'
+
+$VERBOSE = true
+$CLOCK = $VERBOSE ? 20 : Float::INFINITY
+
+file_names = ARGV.select { |file| file.include? '.fam'}
+lexed = FAM::Syntax::Lexer.lex File.read file_names[-1]
+
+parsed = FAM::Syntax::Parser.parse lexed.tokens
+AST = parsed.ast
+
+MEM = FAM::Machine::RAM.new '100B'  # Alloc 100 bytes
+CPU = FAM::Machine::CPU.new MEM
+
+CPU.run AST do |pc|
+  # Do something every `clock-cycle'
+  puts "Program counter: #{pc}"
+end
+```
+A `#step(syntax_tree)` method is also available for the CPU class.
+
+for auto-generated documentation, see: [rubydoc.info/gems/fam/](http://www.rubydoc.info/gems/fam/FAM/Machine/CPU)

data/lib/fam.rb

@@ -5,10 +5,10 @@ class Object
 end
 
 module FAM
-  VERSIONS = { :major => 0, :minor => 1, :tiny => 0 }
+  VERSIONS = { :major => 0, :minor => 1, :tiny => 1 }
 
   def self.version *args
-    VERSIONS.flatten.select.with_index { |val, i| i.odd? }.join '.'
+    VERSIONS.values.join '.'
   end
 end
 

data/lib/fam/syntax/tokens.rb

@@ -67,7 +67,7 @@ module FAM::Syntax
     TYPES = [
       :OPCODE,
       :OPERAND,
-      :NUMERTIC,
+      :NUMERIC,
       :REGISTER,
       :ADDRESS,
       :LABEL,

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fam
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Demonstrandum
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-04-04 00:00:00.000000000 Z
+date: 2018-08-27 00:00:00.000000000 Z
 dependencies: []
 description: A very watered down language ment to look like an assembly language.
 email: knutsen@jetspace.co
@@ -41,7 +41,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.0.0
+      version: 2.5.1
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -49,7 +49,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.7.4
+rubygems_version: 2.7.3
 signing_key: 
 specification_version: 4
 summary: Fake Assembly(ish) Machine