CudaText files formats: what changed
Revision 2 to 3. Removed lines have a minus sign; added lines have a plus sign.
| Old | New | Line | |
|---|---|---|---|
| 1 | - | ||
| 1 | + | ## Format of auto-completion acp file | |
| 2 | 2 | ||
| 3 | - | ||
| 4 | - | ||
| 5 | - | ||
| 6 | - | ||
| 7 | - | ||
| 8 | - | ||
| 9 | - | ||
| 10 | - | ||
| 11 | - | ||
| 12 | - | ||
| 3 | + | Common auto-completion file format is ANSI text file, it contains list of lines in forms: | |
| 13 | 4 | ||
| 14 | - | ||
| 5 | + | `Type Id |Hint`\ | |
| 6 | + | `Type Id (Param1; Param2; ...) |Hint`\ | |
| 7 | + | `Type Id (Param1; Param2; ...): ResultType |Hint` | |
| 15 | 8 | ||
| 16 | - | ||
| 17 | - | ||
| 18 | - | ||
| 19 | - | ||
| 20 | - | ||
| 21 | - | ||
| 9 | + | - 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. | |
| 10 | + | - Both ";" and "," chars can be params delimiters. "\|Hint" part is optional. | |
| 11 | + | - If "\\" char is present in hint part, then it must be escaped: "\\\\". | |
| 12 | + | - If space is needed in id part, it must be written as "%20" (it's allowed for any char in range 0x20..0x2F). | |
| 22 | 13 | ||
| 23 | - | ||
| 24 | - | ||
| 25 | - | ||
| 26 | - | ||
| 14 | + | 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: | |
| 27 | 15 | ||
| 28 | - | ||
| 29 | - | ||
| 30 | - | ||
| 31 | - | ||
| 16 | + | `#chars .-#` | |
| 32 | 17 | ||
| 33 | 18 | ## Format of install.inf files | |
| 34 | 19 | ||
| 35 | - | ||
| 20 | + | 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. | |
| 36 | 21 | ||
| 37 | - | ||
| 38 | - | ||
| 39 | - | ||
| 40 | - | ||
| 41 | - | ||
| 42 | - | ||
| 43 | - | ||
| 22 | + | - "title" field (required) | |
| 23 | + | - "desc" field, long text for install prompt dialog | |
| 24 | + | - "type" field (required) must be one of: | |
| 25 | + | - cudatext-plugin: to install plugin to subdir of "py" dir | |
| 26 | + | - cudatext-data: to copy any files into subdir of "data" dir | |
| 27 | + | - lexer: to install lexers (zip must be made by SynWrite's ExLexer addon) | |
| 28 | + | - lexer-lite: to install lite lexer | |
| 44 | 29 | ||
| 45 | - | ||
| 46 | - | ||
| 47 | - | ||
| 48 | - | ||
| 49 | - | ||
| 50 | - | ||
| 30 | + | - "subdir" field (required) | |
| 31 | + | - for plugins it should begin with prefix "cuda_" | |
| 32 | + | - for lexers it should be "-" | |
| 33 | + | - "homepage" field, source code repository URL (usually on GitHub) | |
| 34 | + | - "api" field, optional, minimal required API version (3 numbers dot-separated) | |
| 35 | + | - "os" field, optional, comma-separated list of supported platforms, described below | |
| 51 | 36 | ||
| 52 | 37 | ### Install.inf supported "os" values | |
| 53 | 38 | ||
| 54 | - | ||
| 39 | + | 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. | |
| 55 | 40 | ||
| 56 | - | ||
| 41 | + | OS names are: | |
| 57 | 42 | ||
| 58 | - | ||
| 59 | - | ||
| 60 | - | ||
| 61 | - | ||
| 62 | - | ||
| 63 | - | ||
| 64 | - | ||
| 65 | - | ||
| 66 | - | ||
| 43 | + | - win | |
| 44 | + | - linux | |
| 45 | + | - macos | |
| 46 | + | - freebsd | |
| 47 | + | - openbsd | |
| 48 | + | - netbsd | |
| 49 | + | - dragonfly | |
| 50 | + | - solaris | |
| 51 | + | - haiku | |
| 67 | 52 | ||
| 68 | - | ||
| 53 | + | CPU families are: | |
| 69 | 54 | ||
| 70 | - | ||
| 71 | - | ||
| 72 | - | ||
| 73 | - | ||
| 74 | - | ||
| 75 | - | ||
| 76 | - | ||
| 77 | - | ||
| 55 | + | - i386 | |
| 56 | + | - x86_64 | |
| 57 | + | - arm | |
| 58 | + | - aarch64 | |
| 59 | + | - sparc | |
| 60 | + | - ppc | |
| 61 | + | - ppc64 | |
| 62 | + | - mips | |
| 78 | 63 | ||
| 79 | - | ||
| 64 | + | So for example Windows x86 platform values are "win" and "win-i386", Linux AMD64 platform values are "linux" and "linux-x86_64". | |
| 80 | 65 | ||
| 81 | 66 | ### Install.inf for plugins | |
| 82 | 67 | ||
| 83 | - | ||
| 84 | - | ||
| 68 | + | Example of install.inf for plugin (plugin adds 2 menu items with menu separator between): | |
| 69 | + | ||
| 70 | + | ``` ini | |
| 85 | 71 | [info] | |
| 86 | - | ||
| 87 | - | ||
| 88 | - | ||
| 89 | - | ||
| 90 | - | ||
| 91 | - | ||
| 92 | - | ||
| 93 | - | ||
| 94 | - | ||
| 95 | - | ||
| 96 | - | ||
| 97 | - | ||
| 98 | - | ||
| 99 | - | ||
| 100 | - | ||
| 101 | - | ||
| 102 | - | ||
| 103 | - | ||
| 104 | - | ||
| 105 | - | ||
| 106 | - | ||
| 107 | - | ||
| 108 | - | ||
| 109 | - | ||
| 72 | + | title=MyName | |
| 73 | + | desc=Plugin allows smth | |
| 74 | + | type=cudatext-plugin | |
| 75 | + | subdir=cuda_test | |
| 76 | + | homepage=http://github.com/some/name/ | |
| 77 | + | api=1.0.200 | |
| 78 | + | ||
| 79 | + | [item1] | |
| 80 | + | section=commands | |
| 81 | + | caption=MyPlugin\Cmd one | |
| 82 | + | method=run | |
| 83 | + | lexers=CSS,HTML | |
| 84 | + | hotkey=Alt+F | |
| 85 | + | ||
| 86 | + | [item2] | |
| 87 | + | section=commands | |
| 88 | + | caption=MyPlugin\- | |
| 89 | + | method=nnnn | |
| 90 | + | ||
| 91 | + | [item3] | |
| 92 | + | section=commands | |
| 93 | + | caption=MyPlugin\Cmd other | |
| 94 | + | method=run_more | |
| 95 | + | menu=0 | |
| 110 | 96 | ``` | |
| 111 | 97 | ||
| 112 | - | ||
| 98 | + | Section names: "item" followed by any string (e.g. "item1"). Fields in sections: | |
| 113 | 99 | ||
| 114 | - | ||
| 115 | - | ||
| 116 | - | ||
| 117 | - | ||
| 118 | - | ||
| 119 | - | ||
| 120 | - | ||
| 121 | - | ||
| 122 | - | ||
| 123 | - | ||
| 124 | - | ||
| 125 | - | ||
| 100 | + | - "section": possible values are "commands", "events". | |
| 101 | + | - "caption": caption of menu item in Plugins menu. "\\" separates menu levels. "&" makes accelerator hotkey. "-" as final level name, makes separator menu item. | |
| 102 | + | - "method": Python method name in Command class. | |
| 103 | + | - "lexers": comma-separated lexer names, means that command can be run only when such lexer(s) active. | |
| 104 | + | - "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"). | |
| 105 | + | - If "lexers=" param missed, then hotkey saves to file "keys.json" for all lexers. | |
| 106 | + | - If "lexers=" param present, then hotkey saves to "keys lexer NNNN.json" for each mentioned lexer. | |
| 107 | + | - "menu": optional. Possible values: | |
| 108 | + | - "" (empty, default): menu item will be put to "Plugins". | |
| 109 | + | - "0": hide menu item. | |
| 110 | + | - "o": menu item will be put to "Options / Settings-plugins". | |
| 111 | + | - "op": menu item will be put both to "Plugins" and "Options / Settings-plugins". | |
| 126 | 112 | ||
| 127 | - | ||
| 113 | + | Only for "section=events": | |
| 128 | 114 | ||
| 129 | - | ||
| 130 | - | ||
| 131 | - | ||
| 132 | - | ||
| 115 | + | - "events": comma-separated list of events to handle in plugin, e.g. "events=on_change,on_caret". | |
| 116 | + | - "keys": supported only for several events: | |
| 117 | + | - 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). | |
| 118 | + | - for "on_open" / "on_open_pre": comma-separated list of lower-case file extensions, without leading dot, to handle in event. | |
| 133 | 119 | ||
| 134 | 120 | #### Install.inf sidebar buttons | |
| 135 | 121 | ||
| 136 | - | ||
| 122 | + | 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: | |
| 137 | 123 | ||
| 138 | - | ||
| 139 | - | ||
| 140 | - | ||
| 124 | + | - "hint": Tooltip of button, must be the same as used by plugin to create its button. | |
| 125 | + | - "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. | |
| 126 | + | - "method": Python method name to show plugin panel. This command should create side panel for this button. | |
| 141 | 127 | ||
| 142 | - | ||
| 128 | + | 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. | |
| 143 | 129 | ||
| 144 | 130 | #### Install.inf lexer lists | |
| 145 | 131 | ||
| 146 | - | ||
| 147 | - | ||
| 132 | + | 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: | |
| 133 | + | ||
| 134 | + | ``` ini | |
| 148 | 135 | [info] | |
| 149 | - | ||
| 136 | + | $var=Name1,Name2,Name3 | |
| 150 | 137 | ``` | |
| 151 | 138 | ||
| 152 | - | ||
| 153 | - | ||
| 139 | + | In \[itemN\] sections set lexers like this: | |
| 140 | + | ||
| 141 | + | ``` ini | |
| 154 | 142 | [itemN] | |
| 155 | - | ||
| 143 | + | lexers=$var | |
| 156 | 144 | ``` | |
| 157 | 145 | ||
| 158 | - | ||
| 159 | - | ||
| 146 | + | 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: | |
| 147 | + | ||
| 148 | + | ``` ini | |
| 160 | 149 | [info] | |
| 161 | - | ||
| 150 | + | $var=regex:.*SQL.* | |
| 162 | 151 | ``` | |
| 163 | 152 | ||
| 164 | 153 | ### Install.inf for data files | |
| 165 | 154 | ||
| 166 | - | ||
| 167 | - | ||
| 155 | + | Example of install.inf for data files, to be copied into subdir of "data" dir. Name of subdir can be any, for example "themes". | |
| 156 | + | ||
| 157 | + | ``` ini | |
| 168 | 158 | [info] | |
| 169 | - | ||
| 170 | - | ||
| 171 | - | ||
| 172 | - | ||
| 159 | + | title=NiceDarkTheme | |
| 160 | + | desc=Nice Dark theme (by AuthorName) | |
| 161 | + | type=cudatext-data | |
| 162 | + | subdir=themes | |
| 173 | 163 | ``` | |
| 174 | 164 | ||
| 175 | 165 | ### Install.inf for lexers | |
| 176 | 166 | ||
| 177 | - | ||
| 178 | - | ||
| 167 | + | 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. | |
| 168 | + | ||
| 169 | + | ``` ini | |
| 179 | 170 | [info] | |
| 180 | - | ||
| 181 | - | ||
| 182 | - | ||
| 183 | - | ||
| 184 | - | ||
| 185 | - | ||
| 186 | - | ||
| 187 | - | ||
| 188 | - | ||
| 189 | - | ||
| 190 | - | ||
| 191 | - | ||
| 192 | - | ||
| 193 | - | ||
| 194 | - | ||
| 195 | - | ||
| 171 | + | title=HTML Smarty | |
| 172 | + | type=lexer | |
| 173 | + | subdir=- | |
| 174 | + | ||
| 175 | + | [lexer1] | |
| 176 | + | file=HTML Smarty internal | |
| 177 | + | [lexer2] | |
| 178 | + | file=HTML Smarty | |
| 179 | + | link1=CSS | |
| 180 | + | link2=VBScript | |
| 181 | + | link3=JavaScript | |
| 182 | + | link4=JavaScript | |
| 183 | + | link5=VBScript | |
| 184 | + | link6=PHP | |
| 185 | + | link7=PHP | |
| 186 | + | link8=HTML Smarty internal | |
| 196 | 187 | ``` | |
| 197 | 188 | ||
| 198 | 189 | ### Install.inf for lite lexers | |
| 199 | 190 | ||
| 200 | - | ||
| 201 | - | ||
| 191 | + | Example of install.inf for lite lexer. Note that "^" suffix not needed here. | |
| 192 | + | ||
| 193 | + | ``` ini | |
| 202 | 194 | [info] | |
| 203 | - | ||
| 204 | - | ||
| 205 | - | ||
| 195 | + | title=MyLexer | |
| 196 | + | type=lexer-lite | |
| 197 | + | subdir=- | |
| 206 | 198 | ``` | |
| 207 | 199 | ||
| 208 | 200 | ## Format of .cuda-lexops files | |
| 209 | 201 | ||
| 210 | - | ||
| 202 | + | Files keep lexer styles, which user changed in the "Lexer Properties" dialog. JSON format. | |
| 211 | 203 | ||
| 212 | - | ||
| 204 | + | Root keys: | |
| 213 | 205 | ||
| 214 | - | ||
| 215 | - | ||
| 216 | - | ||
| 217 | - | ||
| 218 | - | ||
| 219 | - | ||
| 220 | - | ||
| 206 | + | - "files": str: space-separated list of file masks for lexer. Each mask can be "nnn" for extension .nnn, or "/mmm" for full filename mmm. | |
| 207 | + | - "style_NN" for each lexer style name "NN", which user have changed. Subkeys are: | |
| 208 | + | - "font_color": str: color of font, in Pascal format. | |
| 209 | + | - "font_style": str: several chars: "i" for italic, "b" for bold, "s" for strikeout. | |
| 210 | + | - "back": str: color of background, in Pascal format. | |
| 211 | + | - "brd_c_l", "brd_c_r", "brd_c_t", "brd_c_b": str: color of border (left, right, top, bottom), in Pascal format. | |
| 212 | + | - "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. | |
| 221 | 213 | ||
| 222 | - | ||
| 214 | + | 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> | |
| 223 | 215 | ||
| 224 | 216 | --- | |
| 225 | - | ||
| 217 | + | *From the Free Pascal wiki, page "CudaText files formats", as it stood on 2022-08-16 after a change by Alextp, out of the wiki's dump of 2024-05-26. 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).* | |
| 218 | + | Category: CudaText |