feat: Add Rotational Cipher (resolves #152) (#171)

config.json

@@ -207,6 +207,14 @@
         "prerequisites": [],
         "difficulty": 3,
         "topics": []
+      },
+      {
+        "slug": "rotational-cipher",
+        "name": "Rotational Cipher",
+        "uuid": "6442b4e8-9520-41a1-a7dd-0245e686a4c5",
+        "practices": [],
+        "prerequisites": [],
+        "difficulty": 4
       }
     ]
   },

exercises/practice/rotational-cipher/.docs/instructions.md

@@ -0,0 +1,29 @@
+# Instructions
+
+Create an implementation of the rotational cipher, also sometimes called the Caesar cipher.
+
+The Caesar cipher is a simple shift cipher that relies on transposing all the letters in the alphabet using an integer key between `0` and `26`.
+Using a key of `0` or `26` will always yield the same output due to modular arithmetic.
+The letter is shifted for as many values as the value of the key.
+
+The general notation for rotational ciphers is `ROT + <key>`.
+The most commonly used rotational cipher is `ROT13`.
+
+A `ROT13` on the Latin alphabet would be as follows:
+
+```text
+Plain:  abcdefghijklmnopqrstuvwxyz
+Cipher: nopqrstuvwxyzabcdefghijklm
+```
+
+It is stronger than the Atbash cipher because it has 27 possible keys, and 25 usable keys.
+
+Ciphertext is written out in the same formatting as the input including spaces and punctuation.
+
+## Examples
+
+- ROT5  `omg` gives `trl`
+- ROT0  `c` gives `c`
+- ROT26 `Cool` gives `Cool`
+- ROT13 `The quick brown fox jumps over the lazy dog.` gives `Gur dhvpx oebja sbk whzcf bire gur ynml qbt.`
+- ROT13 `Gur dhvpx oebja sbk whzcf bire gur ynml qbt.` gives `The quick brown fox jumps over the lazy dog.`

exercises/practice/rotational-cipher/.meta/config.json

@@ -0,0 +1,19 @@
+{
+  "authors": [
+    "keiravillekode"
+  ],
+  "files": {
+    "solution": [
+      "impl.mips"
+    ],
+    "test": [
+      "runner.mips"
+    ],
+    "example": [
+      ".meta/example.mips"
+    ]
+  },
+  "blurb": "Create an implementation of the rotational cipher, also sometimes called the Caesar cipher.",
+  "source": "Wikipedia",
+  "source_url": "https://en.wikipedia.org/wiki/Caesar_cipher"
+}

exercises/practice/rotational-cipher/.meta/example.mips

@@ -0,0 +1,47 @@
+# Perform Rotational Cipher encryption.
+#
+# $a0 - input text, pointer to null-terminated string
+# $a1 - input shift key
+# $a2 - output pointer
+# $t0 - 26, 'z' - 'a' + 1
+# $t1 - 32, 'a' - 'A'
+# $t2 - 97, 'a'
+# $t3 - ~32 (bitwise inverse)
+# $t4 - pointer into input text
+# $t5 - pointer into output text
+# $t6 - current character
+# $t7 - current letter as number, 0..25
+
+.globl rotate
+
+.text
+
+rotate:
+        li      $t0, 26
+        li      $t1, 32
+        li      $t2, 97
+        nor     $t3, $t1, $zero
+        move    $t4, $a0                # pointer into input text
+        move    $t5, $a2                # pointer into output text
+
+loop:
+        lb      $t6, 0($t4)             # Load byte
+        move    $t7, $t6
+        or      $t7, $t7, $t1           # Convert to lower case
+        blt     $t7, $t2, write         # Jump if below alphabet
+        sub     $t7, $t7, $t2           # Convert from letter to number
+        bge     $t7, $t0, write         # Jump if above alphabet
+        add     $t7, $t7, $a1           # Shift by shift key
+        div     $t7, $t0
+        mfhi    $t7
+        add     $t7, $t7, $t2           # Convert from number to letter
+
+        nor     $t6, $t6, $t3           # Determine if letter was uppercase
+        xor     $t6, $t7, $t6           # Convert to original case
+
+write:
+        sb      $t6, 0($t5)
+        addi    $t4, $t4, 1
+        addi    $t5, $t5, 1
+        bne     $t6, $zero, loop
+        jr      $ra

exercises/practice/rotational-cipher/.meta/tests.toml

@@ -0,0 +1,40 @@
+# This is an auto-generated file.
+#
+# Regenerating this file via `configlet sync` will:
+# - Recreate every `description` key/value pair
+# - Recreate every `reimplements` key/value pair, where they exist in problem-specifications
+# - Remove any `include = true` key/value pair (an omitted `include` key implies inclusion)
+# - Preserve any other key/value pair
+#
+# As user-added comments (using the # character) will be removed when this file
+# is regenerated, comments can be added via a `comment` key.
+
+[74e58a38-e484-43f1-9466-877a7515e10f]
+description = "rotate a by 0, same output as input"
+
+[7ee352c6-e6b0-4930-b903-d09943ecb8f5]
+description = "rotate a by 1"
+
+[edf0a733-4231-4594-a5ee-46a4009ad764]
+description = "rotate a by 26, same output as input"
+
+[e3e82cb9-2a5b-403f-9931-e43213879300]
+description = "rotate m by 13"
+
+[19f9eb78-e2ad-4da4-8fe3-9291d47c1709]
+description = "rotate n by 13 with wrap around alphabet"
+
+[a116aef4-225b-4da9-884f-e8023ca6408a]
+description = "rotate capital letters"
+
+[71b541bb-819c-4dc6-a9c3-132ef9bb737b]
+description = "rotate spaces"
+
+[ef32601d-e9ef-4b29-b2b5-8971392282e6]
+description = "rotate numbers"
+
+[32dd74f6-db2b-41a6-b02c-82eb4f93e549]
+description = "rotate punctuation"
+
+[9fb93fe6-42b0-46e6-9ec1-0bf0a062d8c9]
+description = "rotate all letters"

exercises/practice/rotational-cipher/runner.mips

@@ -0,0 +1,143 @@
+#
+# Test rotate with some examples
+#
+# a0 - input string, for callee
+# a1 - shift key, for callee
+# a2 - pointer to output string, for callee
+# s0 - num of tests left to run
+# s1 - address of input string
+# s2 - address of shift key
+# s3 - address of expected output string
+# s4 - char byte of expected output
+# s5 - char byte of actual output
+# s6 - copy of output location
+# s7 - copy of address of expected output
+#
+# rotate must:
+# - be named rotate and declared as global
+# - read input string from a0
+# - read shift key from a1
+# - follow the convention of using the t0-9 registers for temporary storage
+# - (if it uses s0-7 then it is responsible for pushing existing values to the stack then popping them back off before returning)
+# - write a zero-terminated string representing the return value to address given in a2
+
+.data
+
+# number of test cases
+n: .word 10
+# input values and expected output values (all null terminated)
+texts: .asciiz "a", "a", "a", "m", "n", "OMG", "O M G", "Testing 1 2 3 testing", "Let's eat, Grandma!", "The quick brown fox jumps over the lazy dog."
+shift_keys: .word 0, 1, 26, 13, 13, 5, 5, 4, 21, 13
+outs: .asciiz "a", "b", "a", "z", "a", "TRL", "T R L", "Xiwxmrk 1 2 3 xiwxmrk", "Gzo'n zvo, Bmviyhv!", "Gur dhvpx oebja sbk whzcf bire gur ynml qbt."
+
+failmsg: .asciiz "failed for test input: "
+shiftkeymsg: .asciiz " with shift key "
+expectedmsg: .asciiz ". expected "
+tobemsg: .asciiz " to be "
+okmsg: .asciiz "all tests passed"
+
+.text
+
+runner:
+        lw      $s0, n
+        la      $s1, texts
+        la      $s2, shift_keys
+        la      $s3, outs
+
+        li      $v0, 9                  # code for allocating heap memory
+        li      $a0, 48                 # specify 48 bytes - length of longest expected output
+        syscall
+
+        move    $a2, $v0                # location of allocated memory is where callee writes result
+        move    $s6, $v0                # also keep a copy for ourselves
+
+run_test:
+        jal     clear_output            # zero out output location
+        move    $a0, $s1                # load input address into a0
+        lw      $a1, 0($s2)             # load shift key into a1
+        move    $a2, $s6                # load output address into a2
+        jal     rotate                  # call subroutine under test
+        move    $a2, $s6                # restore output address
+        move    $s7, $s3                # copy expected output
+
+scan:
+        lb      $s4, 0($s3)             # load one byte of the expectation
+        lb      $s5, 0($a2)             # load one byte of the actual
+        bne     $s4, $s5, exit_fail     # if the two differ, the test has failed
+        addi    $s3, $s3, 1             # point to next expectation byte
+        addi    $a2, $a2, 1             # point to next actual byte
+        bne     $s4, $zero, scan        # if one char (and therefore the other) was not null, loop
+
+input_scan:
+        addi    $s1, $s1, 1
+        lb      $s4, 0($s1)
+        bne     $s4, $zero, input_scan
+
+done_scan:
+        addi    $s1, $s1, 1             # point to next input word
+        addi    $s2, $s2, 4             # point to next shift key
+        sub     $s0, $s0, 1             # decrement num of tests left to run
+        bgt     $s0, $zero, run_test    # if more than zero tests to run, jump to run_test
+
+exit_ok:
+        la      $a0, okmsg              # put address of okmsg into a0
+        li      $v0, 4                  # 4 is print string
+        syscall
+
+        li      $v0, 10                 # 10 is exit with zero status (clean exit)
+        syscall
+
+exit_fail:
+        la      $a0, failmsg            # put address of failmsg into a0
+        li      $v0, 4                  # 4 is print string
+        syscall
+
+        move    $a0, $s1                # print input that failed on
+        li      $v0, 4
+        syscall
+
+        la      $a0, shiftkeymsg
+        li      $v0, 4
+        syscall
+
+        lb      $a0, 0($s2)             # print shift key that failed on
+        li      $v0, 1                  # 1 is print integer
+        syscall
+
+        la      $a0, expectedmsg
+        li      $v0, 4
+        syscall
+
+        move    $a0, $s6                # print actual that failed on
+        li      $v0, 4
+        syscall
+
+        la      $a0, tobemsg
+        li      $v0, 4
+        syscall
+
+        move    $a0, $s7                # print expected value that failed on
+        li      $v0, 4
+        syscall
+
+        li      $a0, 1                  # set error code to 1
+        li      $v0, 17                 # 17 is exit with error
+        syscall
+
+clear_output:
+        sw      $zero, 0($s6)           # zero out output by storing 12 words (48 bytes) of zeros
+        sw      $zero, 4($s6)
+        sw      $zero, 8($s6)
+        sw      $zero, 12($s6)
+        sw      $zero, 16($s6)
+        sw      $zero, 20($s6)
+        sw      $zero, 24($s6)
+        sw      $zero, 28($s6)
+        sw      $zero, 32($s6)
+        sw      $zero, 36($s6)
+        sw      $zero, 40($s6)
+        sw      $zero, 44($s6)
+        jr      $ra
+
+# # Include your implementation here if you wish to run this from the MARS GUI.
+# .include "impl.mips"