[codegen] make it possible to escape $ using $$, [doc] complete doc o…

…f codegen

doc/fcitx-example.fxaddon

@@ -80,7 +80,7 @@
 #         from this generated file.
 
 ##
-# Note on Types:
+# Notes on Types:
 #     Many of the entries define types related to the functions. The value
 #     of these entries are just the type name as what you put before a
 #     variable's name in a c-declaration, e.g. int, const char*, struct s1,
@@ -227,7 +227,7 @@ Name=my-function0
 
 # Return Entry:
 #     This is the type of the return value. The size of this type should NOT
-#     be larger than that of a pointer. (See "Note on Type" section above).
+#     be larger than that of a pointer. (See "Notes on Types" section above).
 Return=my_return_type1
 
 # ErrorReturn Entry:
@@ -262,15 +262,110 @@ CacheResult=True
 #     using those functions.) (See fcitx-x11 @ src/module/x11 for a real
 #     example).
 EnableWrapper=@ENABLE_EXAMPLE@
-Arg0=
-Arg1=
-Arg1.Deref=
-Arg1.DerefType=
+
+# Arg* Entries:
+#     (Array)
+#     These entries are loaded in the same way as macro's and function's
+#     entries in the [FcitxAddon] group (although leaving empty entries will
+#     not help a lot here).
+#
+#     The value of these entries are type names of the arguments. See the Notes
+#     on Types section above for more detail including the size limit.
+Arg0=type_of_arg0
+Arg1=int
+Arg2=boolean
+
+##
+# Entries for add-functions headers only:
+#     All following fields are used only to generate the add-functions headers.
+#     They provide information for `fcitx-scanner` to run code/call functions
+#     in each of the api functions.
+
+##
+# Notes on Expressions (and statements):
+#     Some of the following entries' value are simple expressions or statements.
+#     You can refer to some special variables in these expressions using
+#     sh-style argument subsitution (e.g. $0). The pharse of these expressions
+#     are really simple so quoting "$" will NOT work. Whenever you need a
+#     literal $ in your expression, use $$ to escape it. (although it should
+#     be really rare..)
+
+##
+# Dereference expressions (.Deref=) and Dereference Types (.DerefType=)
+#     A dereference expression is either a integer not less than -1 (in which
+#     case the corresponding .DerefType= entry cannot be omitted, empty or
+#     void) or a expression as described in Notes on Expressions
+#     (and statements) section, and a Dereference Type is the return type
+#     of the expression (except for Res.Deref, where Return is the return type
+#     of Res.Deref and Res.DerefType is the type before Deref)
+#     (can be omitted, empty or void). If the dereference expression is an
+#     integer n >= 0, the Deref result is taking the value this variable point
+#     to n times (i.e. a `.Deref=2` on a `int**` will result in a `int`),
+#     For n = -1, the result is the address of the variable.
+#
+#     NOTE: returning the address of a local variable can obviously causes
+#     problems. `fcitx-scanner` will NOT check for these although the compiler
+#     should give you a WARNING if you really do so.
+#
+#     NOTE: if you really need a literal integer in a .Deref expression use
+#     parentheses e.g. (-1).
+
+##
+# Stages in a generated private api wrapper function:
+#     Each generated private wrapper function can be separated into several
+#     stages:
+#     1. Cast arguments from pointers:
+#         In this stage, the self pointer and all arguments are cast from
+#         void* to the correct types, using `Self.Type=` entry in the
+#         [FcitxAddon] group and the `Arg*=` entries.
+#     2. Dereference of arguments:
+#         `Self.Deref=` and `Arg*.Deref=` entries (and corresponding .DerefType
+#         entries) are used in this stage. You can use `$<` to refer to the self
+#         pointer and `$n` (where n is a positive number) for the n'th argument
+#         (all of the are values before any deref.)
+#     3. Inline Code:
+#         The value of the Inline.Code entry will be inserted in the function
+#         with a semi-colon appended at the end. `$<` and `$n`'s can be used
+#         to refer to the self pointer and arguments after Deref (if any).
+#     4. Calculating Result:
+#         One and ONLY one of `Res.Exp=` an `Res.WrapFunc=` MUST be provided
+#         for each function in order to generate a add-functions header.
+#         The type of this result should be `Res.DerefType=` (if `Res.Deref=`
+#         is provided), or `Return=` (if not).
+#         For `Res.Exp=`:
+#             This is a general expression just like those in `Inline.Code=`
+#             and `.Deref=`. `$<` and `$n`'s can be used in the same way as in
+#             `Inline.Code=`.
+#         For `Res.WrapFunc=`:
+#             This is the name of the function (or function-like macro) to be
+#             wrapped in this api function. None of the arguments' type can be
+#             void after Deref in this case.
+#             If `Static=` (see below) is true, the function is called with
+#             all the arguments after .Deref, and if not, the self pointer
+#             will be inserted as the first argument.
+#     5. Dereference of Result:
+#         This is the final stage you can insert code, in which you can preform
+#         the last simple operation on the result. This is controled by
+#         `Res.Deref=` and `Res.DerefType=` with the meaning of
+#         `Res.DerefType=` slightly modified as described above. In addition
+#         to all substitution available in `Inline.Code=` and `Res.Exp=`,
+#         `$@` can be used in this expression to refer to the result
+#         before Deref.
+#     6. Cast Result to pointer and return:
+#         The final result is cast to `void*` (with the size limit keeping in
+#         mind) and return. If the return type of the api is void, `NULL` will
+#         be returned.
+Arg2.Deref=
+Arg2.DerefType=
 Self.Deref=
 Self.DerefType=
 Res.WrapFunc=
 Res.Deref=
 Res.DerefType=
 Res.Exp=$<->rules
+
+# Static Entry:
+#     Similar to any boolean value entries above, "On", "True", "Yes", and "1"
+#     will be treated as true and otherwise false.
 Static=1
 Inline.Code=if ($0) *$0 = $<->primary.len

tools/dev/fcitx-scanner.c

@@ -341,6 +341,11 @@ fxscanner_write_translate(FILE *ofp, const char *str,
         str += len;
         if (!*str)
             return true;
+        if (str[0] == str[1]) {
+            _write_len(ofp, str, 1);
+            str += 2;
+            continue;
+        }
         str++;
         len = translator(ofp, str, data);
         if (len < 0)