CudaText files formats: what changed
Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.
| Old | New | Line | |
|---|---|---|---|
| 1 | - | ||
| 1 | + | ## Contents | |
| 2 | 2 | ||
| 3 | - | ||
| 3 | + | * 1 Format of auto-completion acp file | |
| 4 | + | * 2 Format of install.inf files | |
| 5 | + | * 2.1 Install.inf supported "os" values | |
| 6 | + | * 2.2 Install.inf for plugins | |
| 7 | + | * 2.2.1 Install.inf sidebar buttons | |
| 8 | + | * 2.2.2 Install.inf lexer lists | |
| 9 | + | * 2.3 Install.inf for data files | |
| 10 | + | * 2.4 Install.inf for lexers | |
| 11 | + | * 2.5 Install.inf for lite lexers | |
| 12 | + | * 3 Format of .cuda-lexops files | |
| 4 | 13 | ||
| 5 | - | ||
| 6 | - | ||
| 7 | - | ||
| 14 | + | ## Format of auto-completion acp file | |
| 8 | 15 | ||
| 9 | - | ||
| 10 | - | ||
| 11 | - | ||
| 12 | - | ||
| 16 | + | Common auto-completion file format is ANSI text file, it contains list of lines in forms: | |
| 17 | + | ``` | |
| 18 | + | Type Id |Hint | |
| 19 | + | Type Id (Param1; Param2; ...) |Hint | |
| 20 | + | Type Id (Param1; Param2; ...): ResultType |Hint | |
| 21 | + | ``` | |
| 13 | 22 | ||
| 14 | - | ||
| 23 | + | * Strings "Type", "Id", "Params", "Hint" are shown in separate columns of completion listbox, with separate colors. "Id" is the text which is inserted for a line. | |
| 24 | + | * Both ";" and "," chars can be params delimiters. "|Hint" part is optional. | |
| 25 | + | * If "\" char is present in hint part, then it must be escaped: "\\\". | |
| 26 | + | * If space is needed in id part, it must be written as "%20" (it's allowed for any char in range 0x20..0x2F). | |
| 15 | 27 | ||
| 16 | - | ||
| 28 | + | First line in the file can be the "control" line: it specifies what chars are "word chars" for the used syntax. For example, if word chars are minus, dot, and # sign, the control line should be: | |
| 29 | + | ``` | |
| 30 | + | #chars .-# | |
| 31 | + | ``` | |
| 17 | 32 | ||
| 18 | 33 | ## Format of install.inf files | |
| 19 | 34 | ||
| 20 | - | ||
| 35 | + | User can open addons in zip files (using "File-Open") and install them. To make such zip file, pack into zip also "install.inf" with meta-info. | |
| 21 | 36 | ||
| 22 | - | ||
| 23 | - | ||
| 24 | - | ||
| 25 | - | ||
| 26 | - | ||
| 27 | - | ||
| 28 | - | ||
| 37 | + | * "title" field (required) | |
| 38 | + | * "desc" field, long text for install prompt dialog | |
| 39 | + | * "type" field (required) must be one of: | |
| 40 | + | * cudatext-plugin: to install plugin to subdir of "py" dir | |
| 41 | + | * cudatext-data: to copy any files into subdir of "data" dir | |
| 42 | + | * lexer: to install lexers (zip must be made by SynWrite's ExLexer addon) | |
| 43 | + | * lexer-lite: to install lite lexer | |
| 29 | 44 | ||
| 30 | - | ||
| 31 | - | ||
| 32 | - | ||
| 33 | - | ||
| 34 | - | ||
| 35 | - | ||
| 45 | + | * "subdir" field (required) | |
| 46 | + | * for plugins it should begin with prefix "cuda_" | |
| 47 | + | * for lexers it should be "-" | |
| 48 | + | * "homepage" field, source code repository URL (usually on GitHub) | |
| 49 | + | * "api" field, optional, minimal required API version (3 numbers dot-separated) | |
| 50 | + | * "os" field, optional, comma-separated list of supported platforms, described below | |
| 36 | 51 | ||
| 37 | 52 | ### Install.inf supported "os" values | |
| 38 | 53 | ||
| 39 | - | ||
| 54 | + | Value of "os" field is comma-separated list of platforms (no spaces around commas). Each platform is supported OS name, with optional trailing "-" and CPU family name. | |
| 40 | 55 | ||
| 41 | - | ||
| 56 | + | OS names are: | |
| 42 | 57 | ||
| 43 | - | ||
| 44 | - | ||
| 45 | - | ||
| 46 | - | ||
| 47 | - | ||
| 48 | - | ||
| 49 | - | ||
| 50 | - | ||
| 51 | - | ||
| 58 | + | * win | |
| 59 | + | * linux | |
| 60 | + | * macos | |
| 61 | + | * freebsd | |
| 62 | + | * openbsd | |
| 63 | + | * netbsd | |
| 64 | + | * dragonfly | |
| 65 | + | * solaris | |
| 66 | + | * haiku | |
| 52 | 67 | ||
| 53 | - | ||
| 68 | + | CPU families are: | |
| 54 | 69 | ||
| 55 | - | ||
| 56 | - | ||
| 57 | - | ||
| 58 | - | ||
| 59 | - | ||
| 60 | - | ||
| 61 | - | ||
| 62 | - | ||
| 70 | + | * i386 | |
| 71 | + | * x86_64 | |
| 72 | + | * arm | |
| 73 | + | * aarch64 | |
| 74 | + | * sparc | |
| 75 | + | * ppc | |
| 76 | + | * ppc64 | |
| 77 | + | * mips | |
| 63 | 78 | ||
| 64 | - | ||
| 79 | + | So for example Windows x86 platform values are "win" and "win-i386", Linux AMD64 platform values are "linux" and "linux-x86_64". | |
| 65 | 80 | ||
| 66 | 81 | ### Install.inf for plugins | |
| 67 | 82 | ||
| 68 | - | ||
| 69 | - | ||
| 70 | - | ||
| 83 | + | Example of install.inf for plugin (plugin adds 2 menu items with menu separator between): | |
| 84 | + | ``` | |
| 71 | 85 | [info] | |
| 72 | - | ||
| 73 | - | ||
| 74 | - | ||
| 75 | - | ||
| 76 | - | ||
| 77 | - | ||
| 78 | - | ||
| 79 | - | ||
| 80 | - | ||
| 81 | - | ||
| 82 | - | ||
| 83 | - | ||
| 84 | - | ||
| 85 | - | ||
| 86 | - | ||
| 87 | - | ||
| 88 | - | ||
| 89 | - | ||
| 90 | - | ||
| 91 | - | ||
| 92 | - | ||
| 93 | - | ||
| 94 | - | ||
| 95 | - | ||
| 86 | + | title=MyName | |
| 87 | + | desc=Plugin allows smth | |
| 88 | + | type=cudatext-plugin | |
| 89 | + | subdir=cuda_test | |
| 90 | + | homepage=http://github.com/some/name/ | |
| 91 | + | api=1.0.200 | |
| 92 | + | ||
| 93 | + | [item1] | |
| 94 | + | section=commands | |
| 95 | + | caption=MyPlugin\Cmd one | |
| 96 | + | method=run | |
| 97 | + | lexers=CSS,HTML | |
| 98 | + | hotkey=Alt+F | |
| 99 | + | ||
| 100 | + | [item2] | |
| 101 | + | section=commands | |
| 102 | + | caption=MyPlugin\- | |
| 103 | + | method=nnnn | |
| 104 | + | ||
| 105 | + | [item3] | |
| 106 | + | section=commands | |
| 107 | + | caption=MyPlugin\Cmd other | |
| 108 | + | method=run_more | |
| 109 | + | menu=0 | |
| 96 | 110 | ``` | |
| 97 | 111 | ||
| 98 | - | ||
| 112 | + | Section names: "item" followed by any string (e.g. "item1"). Fields in sections: | |
| 99 | 113 | ||
| 100 | - | ||
| 101 | - | ||
| 102 | - | ||
| 103 | - | ||
| 104 | - | ||
| 105 | - | ||
| 106 | - | ||
| 107 | - | ||
| 108 | - | ||
| 109 | - | ||
| 110 | - | ||
| 111 | - | ||
| 114 | + | * "section": possible values are "commands", "events". | |
| 115 | + | * "caption": caption of menu item in Plugins menu. "\" separates menu levels. "&" makes accelerator hotkey. "-" as final level name, makes separator menu item. | |
| 116 | + | * "method": Python method name in Command class. | |
| 117 | + | * "lexers": comma-separated lexer names, means that command can be run only when such lexer(s) active. | |
| 118 | + | * "hotkey": value must be simple hotkey string (e.g. "Alt+F", "Ctrl+Shift+F1") or key combo separated by "|" (e.g. "Alt+F|F|G"). | |
| 119 | + | * If "lexers=" param missed, then hotkey saves to file "keys.json" for all lexers. | |
| 120 | + | * If "lexers=" param present, then hotkey saves to "keys lexer NNNN.json" for each mentioned lexer. | |
| 121 | + | * "menu": optional. Possible values: | |
| 122 | + | * "" (empty, default): menu item will be put to "Plugins". | |
| 123 | + | * "0": hide menu item. | |
| 124 | + | * "o": menu item will be put to "Options / Settings-plugins". | |
| 125 | + | * "op": menu item will be put both to "Plugins" and "Options / Settings-plugins". | |
| 112 | 126 | ||
| 113 | - | ||
| 127 | + | Only for "section=events": | |
| 114 | 128 | ||
| 115 | - | ||
| 116 | - | ||
| 117 | - | ||
| 118 | - | ||
| 129 | + | * "events": comma-separated list of events to handle in plugin, e.g. "events=on_change,on_caret". | |
| 130 | + | * "keys": supported only for several events: | |
| 131 | + | * for "on_key": comma-separated list of int key codes to handle in event, e.g. "keys=9" means that event is only called for key code 9 (Tab char). | |
| 132 | + | * for "on_open" / "on_open_pre": comma-separated list of lower-case file extensions, without leading dot, to handle in event. | |
| 119 | 133 | ||
| 120 | 134 | #### Install.inf sidebar buttons | |
| 121 | 135 | ||
| 122 | - | ||
| 136 | + | CudaText can show plugin's sidebar buttons even without running the plugin in "on_start" event. Plugin should add sections "sidebar*" ("*" means any substring), with the keys: | |
| 123 | 137 | ||
| 124 | - | ||
| 125 | - | ||
| 126 | - | ||
| 138 | + | * "hint": Tooltip of button, must be the same as used by plugin to create its button. | |
| 139 | + | * "icon": Filename of PNG icon. If path is missed, CudaText uses file from its "data" folder. To specify filename in plugin folder, write value as "{dir}/subdir/filename.png" - with macro {dir}, with forward slashes. | |
| 140 | + | * "method": Python method name to show plugin panel. This command should create side panel for this button. | |
| 127 | 141 | ||
| 128 | - | ||
| 142 | + | Plugin should add sections "bottombar*" ("*" means any substring) to perform the same, but for the bottom part of sidebar, where buttons "Console" and "Output" are placed. | |
| 129 | 143 | ||
| 130 | 144 | #### Install.inf lexer lists | |
| 131 | 145 | ||
| 132 | - | ||
| 133 | - | ||
| 134 | - | ||
| 146 | + | If plugin has many [itemN] sections, it is possible to set list of lexers using variable (not to write each time "lexers=name,name2,name3"). Declare list of lexers in [info] section like this, any variable name: | |
| 147 | + | ``` | |
| 135 | 148 | [info] | |
| 136 | - | ||
| 149 | + | $var=Name1,Name2,Name3 | |
| 137 | 150 | ``` | |
| 138 | 151 | ||
| 139 | - | ||
| 140 | - | ||
| 141 | - | ||
| 152 | + | In [itemN] sections set lexers like this: | |
| 153 | + | ``` | |
| 142 | 154 | [itemN] | |
| 143 | - | ||
| 155 | + | lexers=$var | |
| 144 | 156 | ``` | |
| 145 | 157 | ||
| 146 | - | ||
| 147 | - | ||
| 148 | - | ||
| 158 | + | You can set lexers by reg-ex, e.g. reg-ex ".*SQL.*" means all names with substring "SQL". To do it, write variable with prefix: | |
| 159 | + | ``` | |
| 149 | 160 | [info] | |
| 150 | - | ||
| 161 | + | $var=regex:.*SQL.* | |
| 151 | 162 | ``` | |
| 152 | 163 | ||
| 153 | 164 | ### Install.inf for data files | |
| 154 | 165 | ||
| 155 | - | ||
| 156 | - | ||
| 157 | - | ||
| 166 | + | Example of install.inf for data files, to be copied into subdir of "data" dir. Name of subdir can be any, for example "themes". | |
| 167 | + | ``` | |
| 158 | 168 | [info] | |
| 159 | - | ||
| 160 | - | ||
| 161 | - | ||
| 162 | - | ||
| 169 | + | title=NiceDarkTheme | |
| 170 | + | desc=Nice Dark theme (by AuthorName) | |
| 171 | + | type=cudatext-data | |
| 172 | + | subdir=themes | |
| 163 | 173 | ``` | |
| 164 | 174 | ||
| 165 | 175 | ### Install.inf for lexers | |
| 166 | 176 | ||
| 167 | - | ||
| 168 | - | ||
| 169 | - | ||
| 177 | + | To see example of install.inf for lexers, download any lexer. To see complex example, download lexer zip for "HTML Smarty" which has 2 lexers inside, one lexer is linked to another. | |
| 178 | + | ``` | |
| 170 | 179 | [info] | |
| 171 | - | ||
| 172 | - | ||
| 173 | - | ||
| 174 | - | ||
| 175 | - | ||
| 176 | - | ||
| 177 | - | ||
| 178 | - | ||
| 179 | - | ||
| 180 | - | ||
| 181 | - | ||
| 182 | - | ||
| 183 | - | ||
| 184 | - | ||
| 185 | - | ||
| 186 | - | ||
| 180 | + | title=HTML Smarty | |
| 181 | + | type=lexer | |
| 182 | + | subdir=- | |
| 183 | + | ||
| 184 | + | [lexer1] | |
| 185 | + | file=HTML Smarty internal | |
| 186 | + | [lexer2] | |
| 187 | + | file=HTML Smarty | |
| 188 | + | link1=CSS | |
| 189 | + | link2=VBScript | |
| 190 | + | link3=JavaScript | |
| 191 | + | link4=JavaScript | |
| 192 | + | link5=VBScript | |
| 193 | + | link6=PHP | |
| 194 | + | link7=PHP | |
| 195 | + | link8=HTML Smarty internal | |
| 187 | 196 | ``` | |
| 188 | 197 | ||
| 189 | 198 | ### Install.inf for lite lexers | |
| 190 | 199 | ||
| 191 | - | ||
| 192 | - | ||
| 193 | - | ||
| 200 | + | Example of install.inf for lite lexer. Note that "^" suffix not needed here. | |
| 201 | + | ``` | |
| 194 | 202 | [info] | |
| 195 | - | ||
| 196 | - | ||
| 197 | - | ||
| 203 | + | title=MyLexer | |
| 204 | + | type=lexer-lite | |
| 205 | + | subdir=- | |
| 198 | 206 | ``` | |
| 199 | 207 | ||
| 200 | 208 | ## Format of .cuda-lexops files | |
| 201 | 209 | ||
| 202 | - | ||
| 210 | + | Files keep lexer styles, which user changed in the "Lexer Properties" dialog. JSON format. | |
| 203 | 211 | ||
| 204 | - | ||
| 212 | + | Root keys: | |
| 205 | 213 | ||
| 206 | - | ||
| 207 | - | ||
| 208 | - | ||
| 209 | - | ||
| 210 | - | ||
| 211 | - | ||
| 212 | - | ||
| 214 | + | * "files": str: space-separated list of file masks for lexer. Each mask can be "nnn" for extension .nnn, or "/mmm" for full filename mmm. | |
| 215 | + | * "style_NN" for each lexer style name "NN", which user have changed. Subkeys are: | |
| 216 | + | * "font_color": str: color of font, in Pascal format. | |
| 217 | + | * "font_style": str: several chars: "i" for italic, "b" for bold, "s" for strikeout. | |
| 218 | + | * "back": str: color of background, in Pascal format. | |
| 219 | + | * "brd_c_l", "brd_c_r", "brd_c_t", "brd_c_b": str: color of border (left, right, top, bottom), in Pascal format. | |
| 220 | + | * "brd_t_l", "brd_t_r", "brd_t_t", "brd_t_b": int: type of border (left, right, top, bottom). Values 0..9: None, Solid, Dash, Dot, DashDot, DashDotDot, Solid2, Solid3, WavyLine, Double. | |
| 213 | 221 | ||
| 214 | - | ||
| 222 | + | Color in Pascal format: hex number (6..8 digits) with "$" prefix, or constants. See possible constants (with hex values) in Lazarus file Graphics.pp, where string 'clBlack' is defined. <https://gitlab.com/freepascal.org/lazarus/lazarus/-/blob/main/lcl/graphics.pp> | |
| 215 | 223 | ||
| 216 | 224 | --- | |
| 217 | - | ||
| 218 | - | ||
| 225 | + | *From the Free Pascal wiki, page "CudaText files formats", as the Internet Archive kept it on 2023-12-03. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).* |