1 files changed, 150 insertions, 0 deletions
diff --git a/awk/rawk/README.md b/awk/rawk/README.md
new file mode 100644
index 0000000..d68217a
--- /dev/null
+++ b/awk/rawk/README.md
@@ -0,0 +1,150 @@
+# rawk
+## Make awk rawk.
+
+Rawk helps to bring some modern developer comforts to awk while maintaining awk's portability and inbuilt goodness.
+
+## Create a rawk file (`example.rawk`):
+```rawk
+BEGIN {
+    print "Hello from rawk!"
+}
+
+RAWK {
+    $greet = (name) -> {
+        return "Hello, " name "!";
+    };
+    
+    $add = (x, y) -> {
+        return x + y;
+    };
+}
+
+{
+    print greet("World");
+    print "2 + 3 =", add(2, 3);
+    exit 0;
+}
+```
+
+A `.awk` file should, generally, be a totally valid `.rawk` file. Just like any valid JavaScript is valid TypeScript, likewise with awk and rawk. 
+
+Rawk introduces a new semantic block to awk, so that you can write special forms within the `RAWK {...}` block. 
+
+## Compile and run:
+```bash
+# Compile to awk
+awk -f rawk.awk example.rawk > example.awk
+
+# Run the compiled program
+echo "test" | awk -f example.awk
+
+# Or compile and run in one line
+echo "test" | awk -f rawk.awk example.rawk | awk -f -
+```
+
+## How to run the example:
+```bash
+# Compile the example file
+awk -f rawk.awk example.rawk > example_output.awk
+
+# Run with sample log data
+awk -f example_output.awk sample.log
+
+# Or run with just a few lines
+head -10 sample.log | awk -f example_output.awk
+
+# Or compile and run without outputting an awk file to disk
+awk -f rawk.awk example.rawk | awk -f - sample.log
+```
+
+## Syntax
+
+### Function Definitions
+All functions go inside an `RAWK { ... }` block. 
+
+```rawk
+RAWK {
+    $function_name = (param1, param2) -> {
+        return param1 + param2;
+    };
+}
+```
+
+### Function Calls
+Call rawk functions from anywhere in the code,
+
+```rawk
+{
+    result = add(5, 3);
+    print result;
+}
+```
+
+### Mixed Code
+Mix and match awk and rawk code, 
+
+```rawk
+BEGIN { FS = "," }
+
+RAWK {
+    $process = (field) -> {
+        return "Processed: " field;
+    };
+}
+
+{
+    if ($1 != "") {
+        print process($1);
+    }
+}
+```
+
+## Standard Library
+Rawk boasts a rather large standard library.
+
+### Testing
+```rawk
+expect_equal(add(2, 3), 5, "Addition should work");
+expect_true(is_positive(5), "5 should be positive");
+```
+
+### Type Checking Predicates
+```rawk
+if (is_number(value)) { ... }
+if (is_string(value)) { ... }
+```
+
+### Varuius Validation Predicates
+```rawk
+if (is_email(email)) { ... }
+if (is_url(url)) { ... }
+```
+
+### Functional Programming Patterns
+```rawk
+# Transform array elements
+count = map("double", numbers, doubled);
+
+# Filter array elements  
+count = filter("is_positive", numbers, positive);
+
+# Reduce array to single value
+sum = reduce("add", numbers);
+```
+
+## Testing
+
+Run the test suite, 
+
+```bash
+cd tests && ./test_runner.sh
+```
+
+## Requirements
+
+- Any awk implementation (gawk, mawk, nawk, etc.)
+- No additional dependencies, strives to work with any POSIX awk
+
+## License
+
+Public Domain
\ No newline at end of file