aboutsummaryrefslogtreecommitdiff
path: root/README.org
diff options
context:
space:
mode:
Diffstat (limited to 'README.org')
-rw-r--r--README.org89
1 files changed, 89 insertions, 0 deletions
diff --git a/README.org b/README.org
new file mode 100644
index 0000000..087440d
--- /dev/null
+++ b/README.org
@@ -0,0 +1,89 @@
+#+TITLE: QiuYu
+#+AUTHOR: David Moc (no. 243)
+#+DESCRIPTION: A project for de/encoding QiuYu, a cypher from the amazing artists *No.006* <3
+
+* What is QiuYu?
+It's a cypher that's mainly used in the titles of *No.006*'s songs and on their site [[https://no006.org/][no006.org]].
+It's a neat thing that really sparked my curiosity in implementing a tool that could do this for universally any language.
+
+It works by representing tones via =[1..4]=:
+- =u1ch.ing2m.ao4y.en4ch.ao3z= in normal pinyin would be =chu1 ming2 yao4 chen4 zao3=.
+
+The same can be applied to other languages, e.g. English:
+- =Hello world= -> =ello@h.orld@w=
+- Side note: the numbers in pinyin function as a delimiter. Because there are no tones nor diacritics in English, =@= is used as one.
+
+In both cases the first letter (or initial) of a word moves to the back, behind the delimiter, and words are separated by =.= instead of a space.
+
+These two are already working systems on their site, but I'd like to extend it a bit.
+
+* Supported languages
+- Chinese (pinyin)
+- English
+
+* Usage
+#+begin_src sh
+./qiuyu [-e | -d] [-l <language>] <text>
+#+end_src
+
+- =-e= encrypt (default)
+- =-d= decrypt
+- =-l= language, the name of a file in =langs/= without the extension (default: =english=)
+
+#+begin_src sh
+./qiuyu -l english -e "Hello world" # ello@h.orld@w
+./qiuyu -l english -d "ello@h.orld@w" # Hello world
+./qiuyu -l pinyin -e "chu1 ming2 yao4" # u1ch.ing2m.ao4y
+#+end_src
+
+Run it from the project root, since =langs/= is looked up relative to the working directory.
+
+* Building
+QiuYu needs [[https://git.cdatgoose.org/ccdjit][CCDJIT]] (the language files are compiled at runtime), built beforehand with =./build.sh release=.
+
+#+begin_src sh
+make CCDJIT=/path/to/ccdjit
+make check # loads every langs/*.c once to catch compile errors
+#+end_src
+
+* How languages work
+Every file in =langs/= is a language. They are not part of the program: =qiuyu= compiles =langs/<name>.c= with CCDJIT when =-l <name>= is given, so adding a language needs no rebuild.
+
+A language file includes =lang.h= and defines two functions. Both return a =malloc='d string, or =NULL= on failure:
+
+#+begin_src c
+char *lang_encrypt(const char *input);
+char *lang_decrypt(const char *input);
+#+end_src
+
+Do not define =main= in a language file, it is added automatically.
+
+=lang.h= also provides a small toolkit, since every language boils down to finding a delimiter and reordering the pieces:
+- =SB=: a growable string buffer (=sb_init=, =sb_append=, =sb_push=, =sb_take=, =sb_free=)
+- =Span=: a view into a string, so pieces can be moved around without copying
+- =split_spans= / =sb_join_spans=: split on a delimiter and join back
+
+* Tests
+=make check= runs every sample in =samples.txt= through the matching language file.
+Each sample is encrypted, compared with the expected ciphertext (if one is given), decrypted again, and compared with the original.
+
+A line is =language|plaintext= with an optional third field =|ciphertext=:
+
+#+begin_src
+english|Hello world|ello@h.orld@w
+pinyin|ni3 hao3|i3n.ao3h
+#+end_src
+
+- Blank lines and lines starting with =#= are ignored.
+- The language is the file name in =langs/= without the extension.
+- With a ciphertext the exact output is checked too. Without one, only the round trip is.
+- A language file with no samples gets a warning.
+- Use about 10 samples per language, and cover its edge cases: digraphs, syllables or words that pass through unchanged, single letters.
+- English plaintext must start with a capital and contain no other capitals, because decrypt capitalizes the first letter of the output.
+
+
+* Adding a language
+1. Create =langs/<name>.c=. The name may only contain =a-z=, =0-9= and =_=.
+2. Write up the rules.
+3. Add about 10 samples to =samples.txt= and run =make check=.
+4. Add it to the list of supported languages.