From eae7c8d16411507a8e7ff6e98c029b16c948339d Mon Sep 17 00:00:00 2001
From: sejo <sejo@texto-plano.xyz>
Date: Thu, 2 Sep 2021 16:20:04 -0500
Subject: [PATCH] created readme

---
 README.md | 202 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 202 insertions(+)

diff --git a/README.md b/README.md
index e69de29..27a1d3a 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,202 @@
+# turingsim
+
+a quick and dirty turing machine simulator, written in C89.
+
+[turingsim in compudanzas](https://compudanzas.net/turingsim.html)
+
+# build and run
+
+to build:
+
+```
+make build
+```
+
+or
+
+```
+cc -std=c89 -Wall turingsim.c -o turingsim
+```
+
+to run with an input file:
+
+```
+./turingsim machines/parentesis.txt | less
+```
+
+# input file fields
+
+the line-based fields are:
+
+* initial state
+* inital tape
+* initial position of head on tape (starting at 0)
+* number of rules
+* list of rules, in the form: state, symbol, new state, new symbol, direction (even is right, odd is left)
+* maximum number of simulation steps
+
+# example input file
+
+this input file corresponds to the "comprobador de paréntesis" machine described in [máquinas de turing](https://compudanzas.net/máquinas_de_turing.html)
+
+```
+a
+A(()())A
+1
+11
+a)bX1
+a(a(0
+aAcA1
+aXaX0
+b)b)1
+b(aX0
+bAH00
+bXbX1
+c(H00
+cAH10
+cXcX1
+80
+```
+
+## example output
+
+the output for this example file looks as follows:
+
+```
+parentesis.txt
+initial state: a
+initial tape: A(()())A
+initial position of head: 1
+number of rules: 11
+rule number 0: a)bX1
+rule number 1: a(a(0
+rule number 2: aAcA1
+rule number 3: aXaX0
+rule number 4: b)b)1
+rule number 5: b(aX0
+rule number 6: bAH00
+rule number 7: bXbX1
+rule number 8: c(H00
+rule number 9: cAH10
+rule number 10: cXcX1
+max number of simulation steps: 80
+
+step 0
+ a
+A(()())A
+
+step 1
+  a
+A(()())A
+
+step 2
+   a
+A(()())A
+
+step 3
+  b
+A((X())A
+
+step 4
+   a
+A(XX())A
+
+step 5
+    a
+A(XX())A
+
+step 6
+     a
+A(XX())A
+
+step 7
+    b
+A(XX(X)A
+
+step 8
+     a
+A(XXXX)A
+
+step 9
+      a
+A(XXXX)A
+
+step 10
+     b
+A(XXXXXA
+
+step 11
+    b
+A(XXXXXA
+
+step 12
+   b
+A(XXXXXA
+
+step 13
+  b
+A(XXXXXA
+
+step 14
+ b
+A(XXXXXA
+
+step 15
+  a
+AXXXXXXA
+
+step 16
+   a
+AXXXXXXA
+
+step 17
+    a
+AXXXXXXA
+
+step 18
+     a
+AXXXXXXA
+
+step 19
+      a
+AXXXXXXA
+
+step 20
+       a
+AXXXXXXA
+
+step 21
+      c
+AXXXXXXA
+
+step 22
+     c
+AXXXXXXA
+
+step 23
+    c
+AXXXXXXA
+
+step 24
+   c
+AXXXXXXA
+
+step 25
+  c
+AXXXXXXA
+
+step 26
+ c
+AXXXXXXA
+
+step 27
+c
+AXXXXXXA
+
+step 28
+ H
+1XXXXXXA
+halted
+```
+
+the 1 written at the end indicates that the parenthesis sequence was well-formed. if there was a parenthesis without its pair, the machine would have written 0 instead.