aboutsummaryrefslogtreecommitdiff
path: root/README.org
blob: 087440db0fbc5a12714a4617f719a2f600c79ea9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
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.