Merge pull request #3 from BoGoEngine/new-api

Refactor bogo.py. New API.

Author: lewtds

README.md

@@ -18,73 +18,34 @@ Usage
 ('cán', 'casn')
 ```
 
-`process_key()` is intended to be called iteratively on each keystroke 
-generated by the user with the following arguments:
+`process_key()` is intended to be called successively on each keystroke with
+the following arguments.
 
-- `string`: the previously processed Vietnamese string, or ""
-- `key`: the keystroke
-- `fallback_sequence`: the previous key strokes, or ""
-- an optional `config`: a dictionary-like object (see below)
+- `string`: The previously processed string or "".
+- `key`: The keystroke.
+- `fallback_sequence`: The previous keystrokes.
+- `input_method_definition` (optional): A dictionary listing
+  transformation rules. Defaults to the value returned by `get_telex_definition()`.
+- `skip_non_vietnamese` (optional): Whether to skip results that
+  doesn't seem like Vietnamese. Defaults to True.
 
-This function returns a tuple, the first item of which is the processed
-Vietnamese string, the second item is the next fallback sequence. The two
-items are to be fed back into the next call of `process_key()` as `string`
-and `fallback_sequence`.
+It returns a tuple. The first item of which is the processed
+Vietnamese string, the second item is the next fallback sequence.
+The two items are to be fed back into the next call of process_key()
+as `string` and `fallback_sequence`. If `skip_non_vietnamese` is
+True and the resulting string doesn't look like Vietnamese,
+both items contain the `fallback_sequence`.
 
-`process_key()`'s behavior is controlled by the `config` argument, which takes
-the value of `bogo.get_default_config()` if none is specified:
+Note that when a key is an undo key, it won't get appended to
+`fallback_sequence`.
 
 ```python
-{
-    "input-method": "telex",
-    "skip-non-vietnamese": True,
-    "default-input-methods": {
-        "simple-telex": {
-            "a": "a^",
-            "o": "o^",
-            "e": "e^",
-            "w": ["u*", "o*", "a+"],
-            "d": "d-",
-            "f": "\\",
-            "s": "/",
-            "r": "?",
-            "x": "~",
-            "j": "."
-        },
-        "telex": {
-            "a": "a^",
-            "o": "o^",
-            "e": "e^",
-            "w": ["u*", "o*", "a+", "<ư"],
-            "d": "d-",
-            "f": "\\",
-            "s": "/",
-            "r": "?",
-            "x": "~",
-            "j": ".",
-            "]": "<ư",
-            "[": "<ơ",
-            "}": "<Ư",
-            "{": "<Ơ"
-        },
-        "vni": {
-            "6": ["a^", "o^", "e^"],
-            "7": ["u*", "o*"],
-            "8": "a+",
-            "9": "d-",
-            "2": "\\",
-            "1": "/",
-            "3": "?",
-            "4": "~",
-            "5": "."
-        }
-    }
-}
-
+>>> process_key('â', 'a', 'aa')
+(aa, aa)
 ```
 
-`input-method` is one of the `default-input-methods`, each of which is a
-dictionary of keystrokes and their effects.
+`input_method_definition` is a dictionary that maps keystrokes to
+their effect string. The effects can be one of the following:
 
 - 'a^': a with circumflex (â), only affect an existing 'a family'
 - 'a+': a with breve (ă), only affect an existing 'a family'
@@ -100,8 +61,13 @@ dictionary of keystrokes and their effects.
 - '<ư': append ư
 - '<ơ': append ơ
 
-If `skip-non-vietnamese` is True and `process_key()` deems a key sequence to
-yield non-Vietnamese result then it will return the `fallback_sequence`.
+A keystroke entry can have multiple effects, in which case the
+dictionary entry's value should be a list of the possible
+effect strings. Although you should try to avoid this if
+you are defining a custom input method rule.
+
+We have already defined input method definitions for TELEX and VNI with the
+`get_telex_definition()` and `get_vni_definition()` functions.
 
 More help is available as docstring for each module and function.
 

bogo/__init__.py

@@ -1 +1 @@
-from bogo.bogo import process_key, get_default_config
+from bogo.bogo import process_key