1== Comments == 2 3You can add/remove code comments, via "Comments" plugin. Plugin is preinstalled in CudaText. It gives about 6 commands in menu "Plugins / Comments". Plugin supports only adding/removing of comments, not syntax highlighting for them (highlighting is lexer's work). 4 5* '''Line comments''': from some position to the nearest end-of-line. E.g. in C lexer: "//text here", in Python lexer: "# text here". 6* '''Comments for range''' ('''Stream comments'''): from some text position to some bigger text position, often in the different line. E.g. in C lexer: "/* text here */". 7* '''Comments for full lines''': from newline to another newline, ie comment for several whole lines. Rarely used, e.g. used in PowerShell. 8 9For example, Python lexer supports only line comment, and don't support stream comments. PowerShell lexer supports comments for full lines, while don't support comments for any range. 10 11Comment chars are editable in SynWrite editor, in dialog "Lexer properties" (after you install the same lexer to SynWrite). In dialog tab "Commenting" you'll see input fields. 12 13Command "Toggle stream comment" in plugin adds/removes comments of last 2 types: for range, for full lines (plugin chooses needed kind). 14 15Comment chars are saved: 16 17* Line comments: in lexer file data/lexlib/nnn.lcf. 18* Range comments: in files data/lexlib/nnn.cuda-lexmap. 19 20== Macros == 21 22Macro is a sequence of CudaText actions, which can be saved to a file and invoked later by some command. 23To use macros, you must install plugin "Macros" from Addon Manager. It adds "Macros" menu to CudaText main menu bar. This menu gives items: 24 25* Macros... 26* Start record 27* Stop record 28* Cancel record 29* Export... 30* Import... 31* (items for saved macros) 32 33To record a macro: 34 35* call menu item "Macros / Start record", or use dialog "Macros / Macros..." which gives "Start record" button too 36* pefrorm some action(s) in CudaText: 37** built-in commands, plugin commands (invoked by hotkey, by menu, by Command Palette) 38** some mouse actions (clicks/selections, they save/playback relative to caret position) 39** calling of Find/Replace dialog, "Go to" dialog 40** actions in Find/Replace dialog 41* call menu item "Macros / Stop record" to save your macro, plugin will ask for macro name 42 43Macro saves action(s) performed inside its original editor tab (not other tabs). And it doesn't save actions inside plugin dialogs (e.g. FindInFiles). 44 45To playback macro: 46 47* call menu item "Macros / (macro name)", the end of this menu lists all available/saved macros 48* or call dialog "Macros / Macros..." which allows to run available macros: it can be simple running, running N times, or running in loop ([x] While text changes, [x] Until caret on last line) 49 50== Project Manager == 51 52This plugin is preinstalled in CudaText. It shows panel "Project" in the sidebar (to show this panel, call plugin by any command, or set plugin's option "Load on program start" and restart, CudaText sidebar will have Project button). On the project panel, on its tree-view, you can add several "root nodes", each node must be existing file or folder. For folder nodes, plugin auto shows all nested folders. You cannot add nodes on other levels (like SynWrite editor does). 53 54Plugin has context menu on its panel, with items: 55 56* Project file 57** New project 58** Open project 59** Recent projects 60** Save project as... 61** Go to file... - this shows menu with all project files, and then tree-view selection jumps on selected file 62** Project properties... - this shows dialog with current project's options 63** Config... - this shows dialog with global Project Manager options 64* Root nodes - commands for nodes on the project's root level 65** Add folder... 66** Add file... 67** Clear project 68** Remove node 69* Selected file - it's shown only for files 70* Selected directory - it's shown only for folders 71* Refresh - it re-reads state of files/folders from disk 72 73Any project can have "main file", you can choose it in the context menu: "Selected file / Set as main file". Main file's path is used by plugin External Tools, when some tool is configured with macro {ProjMainFile}. This allows tools to run compilation of the main file. 74 75=== Project Manager options dialog === 76 77* "Ignore files": ";"-separated shell wildcards, which are [https://docs.python.org/3/library/fnmatch.html documented here]. If file name (without path) matches any of these wildcards, it will not be listed in the treeview. 78* "Ignore folders": ";"-separated shell wildcards. If folder name matches any of these wildcards, it will not be listed in the treeview. 79* "Ignore all hidden files/folders": Additionally don't list all hidden items. On Unix, hidden mean "beginning with dot". On Windows, hidden means having file-system "hidden" attribute. 80* "Open file after "Go to file" command": If turned on, command "Project Manager: Go to file" will not only jump to chosen file in the treeview, but also open that file in editor. 81* "Use "preview tab" on item clicking": If option is on, single click on treeview file item, will open file in "preview tab". Preview tab is single such tab, it's shared by all files, it has italic+underlined tab title. If option is off, clicking file item will open normal tab, separate normal tabs per each file. 82* "Open files by double-click": If turned on, only double-click in the treeview will open file for editing, but not the single click. 83* "On opening file in Git/SVN repo...": On opening any file, Project Manager will check if this file is in the Git/SVN repository (by presence of folder ".git" or ".svn" near the file, or in upper level folders). If yes, Project Manager will create the project from that repository and open it. This gives some slowdown of course. 84 85And options for icons: 86 87* "File type icons": Set of file/folder icons for treeview. You can install additional themes from Addons Manager, see category "filetypeicons" there. Example of such theme: "VSCode Material 24x24". This option shows themes, which are present in the folder "data/filetypeicons". 88* "Toolbar icons": Set of icons for Project Manager toolbar buttons. You can install additional themes from Addon Manager, see the category "projtoolbaricons" there. This option shows themes, which are present in the folder "data/projtoolbaricons". 89 90=== Preview tab === 91 92To see the "preview tab", call "File / Open folder" and choose a folder with some files. Folder will be opened in the side panel "Project". Make single click on a file in this project, it will open in the "preview tab". Single "preview tab" is shared by all clicked (in the project) files. It has italic font style of the caption (font style is customizable). When you begin to edit file in the "preview tab", tab becomes "normal" and looses its special status. 93 94"Preview tab" is always '''created in the first tab-group''', even if the focused editor is located in different tab-group. 95It was made on purpose, to avoid the situation when "preview tab" jumps from one tab-group to another. 96 97Again, if you click different items in the Project Manager, and files are opened '''in the first tab-group''', it's not a bug. 98If you need to open clicked files in different tab-groups, you can do it - by unchecking the option "Use preview tab on item clicking" in the Project Manager options. 99 100"Preview tab" can be dragged to another tab-group, it should work there too. 101 102=== Switch between projects === 103 1041) To switch to different project, Plugin Manager gives the context menu: "Project File / Recent projects / name.cuda-proj". 105 1062) Another way is using the plugin "Favorites". It gives the dialog (can be called by a hotkey), with 2 tabs: "Files" and "Projects", so you can choose one of your favorite projects from a listbox. 107 1083) There is also a way to quickly switch between projects: 109 110* Install plugins: "Config Toolbar", "External Tools" and "Session Manager". Restart CudaText. 111* Set CudaText option "ui_one_instance": true. 112* In "External Tools" make a tool which starts CudaText (yes, from within CudaText) with parameter: full path of a project. The command line can look like: "c:\Apps\cudatext.exe "c:\Apps\some_project.cuda-proj"". You can add here additional parameter: full path of a session file, *.cuda-session / *.json. So this external tool will open given project (and maybe a session too). It will open it inside the same CudaText instance (because "ui_one_instance":true). 113* Add more such tools in the "External Tools", for different projects (and maybe sessions). 114 115[[File:cudatext-tools-and-projects.png]] 116 117* In the plugin "Config Toolbar", add the toolbar drop-down menu, with menu-items referring to different tools. Or add the individual menu-items for separate tools. 118 119[[File:cudatext-tools-and-projects-config.png]] 120 1214) There is a method for CudaText 1.145.1 or newer. 122 123* Install plugin "Config Toolbar" (only 1 plugin here, comparing to the previous method). 124* CudaText option "ui_one_instance" can be any. 125* In the plugin "Config Toolbar", add the toolbar button which will switch the project and/or session. The properties of this button are tricky. In the "Command" property of the button, you must enter "exec=path_of_project_file path_of_session file". You cannot type this directly to the dialog field, but you should press the "Enter command line..." button in the dialog and enter the command line contents (full path of .cuda-proj file and/or full path of .cuda-session file). "Config Toolbar" will store your command line with the "exec=" prefix. 126* CudaText will use the new command-line which you entered after "exec=". 127 128== Snippets == 129 130To use snippets you need: 131 132* plugin "Snippets" (install from Addon Manager) 133* snippet package for needed lexer (install from Addon Manager) 134 135Each snippet has a name (shown in the dialog when Snippets plugin is called) and short id (letters, digits, '_', dot). You can type id in editor and press Tab key: snippet for this id will be inserted into text. You can insert snippets also by choosing in dialog: call menu item "Plugins / Snippets". 136 137Only those snippets are enabled, which are suitable for the current lexer. For example, a snippet may be for lexers "C,C++,Objective C" - it is enabled only when these lexers are active. If a snippet has no lexer property, it is always enabled. 138 139Dialog of Snippets plugin: 140 141[[File:cudatext_snippets_menu.png]] 142 143Texts of snippets usually have tab-stop(s), e.g. ${1:some_text}. Plugin Snippets finds tab-stops and places "markers" for them. After markers are placed, Tab-key works special in editor, it jumps to next marker. See detailed information in the [[CudaText#Markers]]. 144 145=== Snippets from VSCode === 146Since recent versions, Snippets plugin supports snippets from VSCode editor. It gives menu items in "Plugins / Snippets": 147 148* "Install VSCode snippets..." - this suggests to install packages with snippets (packages usually contain more functionality, and CudaText plugin will install only snippets). 149 150[[File:cudatext-snippets-add-vscode.png]] 151 152* "Remove VSCode snippets" 153* "Visit homepage of VSCode snippets..." 154* "Convert snippets package from old format" - this takes snippets in old .cuda-snippet format (if you have some old ones) and converts them to VSCode JSON format. 155 156Plugin also gives the fully featured snippet editor dialog, in menu item "Add/edit snippets...". 157 158[[File:cudatext-snippets-editor.png]] 159 160Currently most of VSCode/TextMate "macros" are supported in snippets body, but not all. Refer to readme file of the plugin. 161 162=== Snippets for HTML tags === 163 164CudaText has preinstalled 120+ snippets for HTML tags. (You still need to install Snippets plugin.) They are enabled with HTML lexer. Just type tag name without a bracket, press Tab, and snippet is inserted. E.g. "a"<Tab> will insert: 165 166 <a href="http" title="Title" target="_blank"></a> 167 168These snippets have markers, so Tab key jumps to the next marker. Last marker is usually placed after the entire tag, ie after ">" bracket. 169 170===Format of snippet files=== 171 172====Snippets tab-stops==== 173 174Specify tab-stops in the snippet text like this: 175 176* ${NN} 177* ${NN:default text} 178 179This places markers (AKA tab-stops) in the editor, marker index NN should be from 0 to 40. 180After snippet insertion, tab-key goes to next marker(s) and deletes it. 181 182* Markers can be listed in any order (e.g. marker 4 can be between 1 and 2). 183* Tab-key first goes to marker 1, 2, 3... and marker 0 is always the last. 184* Markers with the same indexes will place multi-carets. 185* Nested markers (with default text) are allowed, but only with one nesting level, e.g. ${2:text is {$3:here}}. 186* Marker with default text ${NN:...} can specify multi-line default text (character "}" is on another line of snippet). 187 188====Snippets macros==== 189Special macros are handled by Snippets plugin in snippet text: 190 191* ${sel} - Text selected before snippet insertion (if snippet called with Tab key, it's empty string) 192* ${cp} - Current clipboard contents 193 194* ${cmt_start} - Current lexer's "block comment" start symbols (or empty string) 195* ${cmt_end} - Current lexer's "block comment" end symbols (or empty string) 196* ${cmt_line} - Current lexer's "line comment" symbols (or empty string) 197 198* ${fname} - File name only, without path 199* ${fpath} - Full file name, with path 200* ${fdir} - Directory of file 201* ${fext} - Extension of file 202* ${psep} - OS path separator: backslash on Windows, slash on Unix 203 204* ${date:nnnn} - Current date/time formatted by string "nnnn"; see [http://strftime.org/ Python docs] 205* ${env:nnnn} - Value of OS environment variable "nnnn" 206 207The following macros from Sublime Text editor are supported. They can be written as $NAME or as ${NAME}. 208 209* $TM_SELECTED_TEXT - The currently selected text or the empty string 210* $TM_CURRENT_LINE - The contents of the current line 211* $TM_CURRENT_WORD - The contents of the word under cursor or the empty string 212* $TM_LINE_INDEX - The zero-based line number 213* $TM_LINE_NUMBER - The one-based line number 214* $TM_FILEPATH - The full file path of the current document 215* $TM_DIRECTORY - The directory of the current document 216* $TM_FILENAME - The filename of the current document 217* $TM_FILENAME_BASE - The filename of the current document without its extensions 218* $CLIPBOARD - The contents of your clipboard 219* $WORKSPACE_NAME - The name of the opened workspace or folder 220 221* $BLOCK_COMMENT_START - Current lexer's "block comment" start symbols (or empty string) 222* $BLOCK_COMMENT_END - Current lexer's "block comment" end symbols (or empty string) 223* $LINE_COMMENT - Current lexer's "line comment" symbols (or empty string) 224 225For inserting the current date and time: 226* $CURRENT_YEAR - The current year 227* $CURRENT_YEAR_SHORT - The current year's last two digits 228* $CURRENT_MONTH - The month as two digits (e.g. '02') 229* $CURRENT_MONTH_NAME - The full name of the month (e.g. 'July') 230* $CURRENT_MONTH_NAME_SHORT - The short name of the month (e.g. 'Jul') 231* $CURRENT_DATE - The day of the month 232* $CURRENT_DAY_NAME - The name of day (e.g. 'Monday') 233* $CURRENT_DAY_NAME_SHORT - The short name of the day (e.g. 'Mon') 234* $CURRENT_HOUR - The current hour in 24-hour clock format 235* $CURRENT_MINUTE - The current minute 236* $CURRENT_SECOND - The current second 237* $CURRENT_SECONDS_UNIX - The number of seconds since the Unix epoch 238 239====Snippets file names==== 240 241Snippets are stored in separate files with extensions: 242 243* .cuda-snippet or .synw-snippet: main format. 244* .cuda-snips: compact format for collections of tiny snippets. 245 246Encoding is UTF-8, no BOM. Files can be placed in any subfolder of "data/snippets" folder, file/folder names have no meaning, but it's recommended to name subfolders like AuthorName.SyntaxName, so users can easily find newly installed snippets. 247 248====Format of .cuda-snippet==== 249 250First lines have format "key=value" (no spaces around "="), where "key" is one of strings: 251 252* "name": snippet full name, shown in dialog. 253* "id": snippet short alias for Tab-key (latin letters, digits, "_.$"), line is optional. 254* "lex": lexers list, comma-separated, for which snippet is active, line is optional, empty means snippet always active. 255 256Then follows the line "text=" without value, and all next lines - are snippet contents. 257 258* Trailing blank lines are discarded. 259* Use tab-chars in text indents, they are auto replaced to spaces if current editor configured so. 260 261====Format of .cuda-snips==== 262 263File contains one or several lines, one snippet per line. Empty lines, lines starting with "#" or space, are ignored. Format of lines: 264 265* id text 266* /N=name text 267* id /N=name text 268* id /L=lexers text 269* id /L=lexers /N=name text 270* id /L="lexers" /N="name" text 271 272Here "id" is short alias for Tab-key, "name" (if not set, it's the same as "id") is full name for dialog, "lexers" is comma-separated lexer list, "text" is snippet contents. Contents can have escaped special chars: "\n", "\r", "\t" (tab-char), "\\" (backslash). 273 274== Snippet Panel == 275 276Plugin "Snippet Panel" is preinstalled in CudaText. It gives an alternative way to use short text fragments (only simple ones) in editor. It adds button to sidebar, and command "Plugins / Snippet Panel". When called, plugin shows panel in the sidebar, with a drop-down list of folders, which contain several "snippets". You can double-click snippets to insert them into text (multi-carets are supported). 277 278Preinstalled folders: 279 280* Arrows 281* Currency symbols 282* Greek alphabet (lower) 283* Greek alphabet (upper) 284* HTML - Arrows 285* HTML - Color names 286* HTML - Color names+values 287* HTML - Letters 288* HTML - Math symbols 289* HTML - Special characters 290* Math symbols 291* Quote selection 292* Special characters 293 294Plugin looks for its folders in two places: 295 296* Folder "clips" in the plugin folder. 297* Folder CudaText/data/clips, which is absent by default, for custom user folders. 298 299Each snippet folder can contain one or more .txt files, in UTF-8 (no BOM) or UTF-16 (with BOM) encoding. Files have snippet per line, in the form "name=value" or simply "name" (if value missed, it equals to name). Each snippet can be simple short string, or string with ${sel} macro to replace selected text. This allows to quote currently selected text by calling snippets from "Quote selection" folder. 300 301== CudaLint == 302 303CudaLint plugin allows to check correctness of documents in many syntaxes. 304It was initially ported from SublimeLinter 2.x plugin for Sublime Text. 305Each lexer must be supported with additionally installed linter, for example: 306 307* JavaScript is supported with linter based on JSLint tool, 308* HTML is supported with linter based on HTML Tidy tool, 309* CSS is supported with linter based on CSSLint tool, 310* etc 311 312You will find all linters in the Addon Manager: "Plugins / Addon Manager / Install". 313Linters are installable like other plugins but they don't add commands, they only add folders 314"[CudaText]/py/cuda_lint_*", which are automatically used by CudaLint. 315After you install a linter, see readme in its folder, maybe how-to-use info is written there. 316 317=== Linters - usage === 318 319To run linting, use menu item "Plugins / CudaLint / Lint", or set hotkey to this command 320(in CudaText Command Palette, press F9). You will see statusbar message, which tells how many errors 321linter found. For each found error, you'll see yellow/red bookmark (you can use usual commands 322for these bookmarks). Plugin also shows list of errors in the "Validate" panel 323(to show Validate panel, click V icon on the CudaText sidebar). 324 325Linting can also be run by events: 326 327* after opening file 328* on saving file 329* after text is changed + pause passed 330 331Events aren't used by default (to not slowdown usual work). To use events, you must enable them in config. 332Call config by menu item in "Options / Settings-plugins". 333 334=== Linters - Node.js === 335 336Some linters require Node.js, so for those linters, you must install Node first. 337Those linters are sometimes shipped with Node modules preinstalled (in plugin folder) 338and sometimes you need to install Node modules via NPM. 339See linter's readme file for details. 340 341* Windows: "node.exe" must be in PATH, command "node -v" must work in console. 342* Linux: "nodejs" package must be installed, command "nodejs -v" must work in terminal. 343 344=== Linters - authoring === 345 346To support more lexers, it's a good idea to port linter from SublimeLinter. To port a linter, most you need is: 347 348* Fix "imports" to use "cuda_lint" module, instead of SublimeLinter modules. cuda_lint gives almost the same classes which SublimeLinter gives. Except Node.js linter class - it's not supported yet. Usual Linter and PythonLinter classes are supported. 349* Change syntax name (for Sublime Text) to CudaText lexer name, names are often different. If no such lexer for CudaText exists yet, ask for it. 350* Remove in linter usage of Sublime Text API to read settings (often used in linters). You can add usage of settings via CudaText API ini_read, or via json module. 351* If linter was using Node.js, take some code to run Node, from cuda_lint_csslint linter. 352 353=== Linters - per project === 354 355How to configure linters per project? In your project (Project Manager plugin), right-click root node of project treeview, call menu item "Project file / Project properties...". In this dialog, in the "Variablies" field, enter variable(s) like this: 356 357 linter_css=csslint 358 359Variable prefix "linter_" required, after goes lower-case lexer name (CSS). Value of variable must be name of linter's folder (in "py" folder) without "cuda_lint_". So if linter's folder is py/cuda_lint_aaa, specify value "aaa". 360 361In this example, CudaLint plugin allows, for mentioned lexer CSS, only linter "csslint", even if another CSS linter (e.g. "csstree") is installed and found first. 362 363== CudaFormatter == 364CudaFormatter is plugin which uses 2nd-level plugins, "formatters", to change the source code. Each "formatter" supports one or more lexers, and provides one or more actions. For example, the Addon Manager contains two formatters for XML: XML IndentX and XML Pretty Print. 365 366For example, how to format code in XML? 367 368* Use "Plugins / Addon Manager / Install" to install the CudaFormatter, and formatter(s) for XML. Restart CudaText. 369* Open XML file. 370* Use "Plugins / CudaFormatter / Formatter (menu)". This will show the menu of actions from appropriate formatter(s) for current file. 371 372Formatters may change entire file text or only selected text. If selection is made, formatter changes only the selection, otherwise the entire text. 373 374===CudaFormatter commands=== 375 376* Formatter (menu): Runs formatter for current editor file. If several formatters are found, menu dialog will suggest to choose one of them. 377 378* Formatter A...D: Runs formatter for current editor file, which has label (A, B, C, D) set. Labels are configurable by another command. 379 380* Configure on_save: Chooses which formatters are active on file saving. The first formatter, which is suitable for current lexer, and has the flag "on_save", will be used to format text on file saving. 381 382* Configure labels: Allows to assign labels (A, B, C, D) to formatters. Labels allow to use commands "Formatter A"..."Formatter D", e.g. via hotkeys. So you can use command "Formatter A" via some hotkey, and be sure that for all lexers "Formatter A" will use desired formatters. 383 384* Configure formatter: For those formatters which support config file, command will suggest to open global config file (in the folder "settings" of CudaText). 385 386* Configure formatter (local): For those formatters which suppots config file, command will suggest to open "local" config (in the folder of current editor file). If local config not exists, plugin will suggest to create it from global config. 387 388== External Tools == 389 390=== Introduction to External Tools === 391 392Plugin "External Tools" (ExtTools) can be installed from Addon Manager. It allows to run external programs, catch their output, and then it can: 393 394* Display this output in the Output or Console panel of CudaText. 395* Replace current editor selection with the output. 396* Copy this output to a new document. 397* Copy this output to Clipboard. 398* And more. 399 400Plugin adds "Tools" top menu (near "Plugins"), which has menu item "Config" to configure all tools (in the single dialog), and menu items to run all individual tools. 401 402[[File:cudatext-tools-menuitem.png]] 403 404Some external tools configs are shown in the Wiki topics below. Enter these strings in the "Tool properties" dialog. 405 406[[File:cudatext-tools-props.png]] 407 408Plugin allows to customize hotkeys for all individual tools, or to use the single hotkey for different tools. The single hotkey is the hotkey of the plugin's command "Tools / Run main lexer tool". What is the "main lexer tool"? For example, you have 2 tools for lexer C++, and 3 tools for lexer HTML. You open the "Tool properties" dialog for some C++ tool, and press "Set main" button to mark that tool as "main" for C++. Then you open properties of some HTML tool, press "Set main" button to mark that tool as "main" for HTML. So now the "Tools / Run main lexer tool" can determine what is the main tool for C++ and HTML. 409 410[[File:cudatext-tools-mainlexertool.png]] 411 412Notes: 413 414* The disadvantage of the plugin: it cannot show tool output lines immediately when they appear, it waits until tool is terminated. Use the [[#Runner]] plugin which supports that feature. 415* If you see that running of tools makes the Output panel visible, you need to fix the "Capture output" option of those tools, set it to "Ignore". 416 417=== Tool to compile by GCC === 418 419You can test how this tool works on any Linux, because GCC is preinstalled. Test the tool on C++ example, which is created from CudaText by menu "File / New from template / C++". 420 421Properties: 422 423* Name: C - compile 424* File name: gcc 425* Shell command: unchecked 426* Parameters: "{FileNameOnly}" -o "{FileNameNoExt}" 427* Initial folder: {FileDir} 428* Lexers: C,C++ 429* Capture output: Output panel 430* Encoding: utf_8 431 432Optionally, configure "Pattern", so double click in the Output panel will put caret to the source code. Example of GCC error line in the Output panel, it will be handled by double click: "new.cpp:10:3: error: 'zz' was not declared in this scope". 433 434* Pattern: (?P<file>[^:]+):(?P<line>\d+):(?P<col>\d+): .+ 435 436=== Tool to run C program === 437 438Tool is for Linux, so "File name" don't have an extension. For Windows, change "File name" field to "{FileNameNoExt}.exe". 439 440Tool will catch the program output in the Output panel, program text input will not work. 441 442* Name: C - run 443* File name: "./{FileNameNoExt}" 444* Shell command: checked 445* Parameters: (empty) 446* Initial folder: {FileDir} 447* Lexers: C,C++ 448* Capture output: Output panel 449* Encoding: utf_8 450* Pattern: (empty) 451 452=== Tool to run C program, on Windows, with input in terminal === 453 454Tool is for Windows, it allows to run compiled C/C++ program in new console window. Text input will work in this console. 455 456Example C++ program: 457 458<syntaxhighlight lang="C++"> 459#include <stdio.h> 460int main () 461{ 462 int c; 463 puts ("Enter text. Include a dot ('.') in a sentence to exit:"); 464 do { 465 c=getchar(); 466 putchar (c); 467 } while (c != '.'); 468 return 0; 469} 470</syntaxhighlight> 471 472Tool props: 473* Name: C - run 474* File name: cmd 475* Shell command: unchecked 476* Parameters: /K "{FileNameNoExt}.exe" 477** Alternative value: /C "{FileNameNoExt}.exe" && pause 478* Initial folder: {FileDir} 479* Lexers: C,C++ 480* Capture output: Ignore 481* Encoding: utf_8 482* Pattern: (empty) 483 484=== Tool to run C program, on Linux, with input in terminal === 485 486Tool is for Linux, it allows to run compiled C/C++ program in new terminal window. Text input will work in this terminal window. 487 488Example C++ program: 489 490<syntaxhighlight lang="C++"> 491#include <stdio.h> 492int main () 493{ 494 int c; 495 puts ("Enter text. Include a dot ('.') in a sentence to exit:"); 496 do { 497 c=getchar(); 498 putchar (c); 499 } while (c != '.'); 500 return 0; 501} 502</syntaxhighlight> 503 504Tool props: 505* Name: C - run 506* Variant for xterm: 507** File name: xterm 508** Parameters: -hold -e "./{FileNameNoExt}" 509* Variant for gnome-terminal: 510** File name: gnome-terminal 511** Parameters: -- bash -c "./{FileNameNoExt}; read -s -n1 -r -p 'Press any key... '; echo" 512* Shell command: unchecked 513* Initial folder: {FileDir} 514* Lexers: C,C++ 515* Capture output: Ignore 516* Encoding: utf_8 517* Pattern: (empty) 518 519=== Tool to compile+run C program === 520 521In the External Tools dialog, press Join button, to join 2 tools created in above steps. Properties of joined tool: 522 523* Name: C - make+run 524* Series: C - compile; C - run 525* Lexers: C,C++ 526 527=== Tool to run current Batch file === 528 529Tool properties: 530 531* Name: Run batch file 532* File name: cmd.exe 533* Shell command: unchecked 534* Parameters: /c "{FileName}" 535* Initial folder: {FileDir} 536* Lexers: Batch files 537* Capture output: Output panel 538* Encoding: the same as file's encoding: e.g. utf_8 or cp1251 (cp1251 is Russian ANSI codepage) 539 540=== Tool to compile by Free Pascal === 541 542This tool is for Free Pascal 3.x on Linux x64. 543 544Properties: 545 546* Name: FPC - compile 547* File name: 548** for FPC installed system-wide: fpc 549** for FPC installed via fpcupdeluxe: /home/user/fpcupdeluxe/fpcupdeluxe/fpc/bin/x86_64-linux/fpc.sh 550* Shell command: unchecked 551* Parameters: {FileNameOnly} 552* Initial folder: {FileDir} 553* Lexers: Pascal 554* Capture output: Output panel 555* Encoding: utf_8 556 557Optionally, configure "Pattern", so double click in the Output panel will put caret to the source code. In the "Tool properties" dialog, press "Set" button near the "Pattern" and choose there ready preset for Free Pascal. 558 559=== Tool to call file-compare utility === 560 561Tools, which call file-compare utility, to compare 2 files: active files in group-1 and group-2. 562 563==== WinMerge, KDiff, Kompare==== 564 565* Name: Compare files in G1, G2 566* File name: (full name of executable file) 567* Shell command: unchecked 568* Parameters: "{FileName_g1}" "{FileName_g2}" 569* Initial folder: (empty) 570* Capture output: Ignore 571 572==== Meld ==== 573 574* Name: Compare files in G1, G2 575* File name: (full name of executable file) 576* Shell command: unchecked 577* Parameters: --newtab "{FileName_g1}" "{FileName_g2}" 578* Initial folder: (empty) 579* Capture output: Ignore 580 581==== diff ==== 582 583* Name: Compare files in G1, G2 584* File name: diff 585* Shell command: unchecked 586* Parameters: -Nau "{FileName_g1}" "{FileName_g2}" 587* Initial folder: (empty) 588* Capture output: Copy to new document 589 590=== Tool to run Python scripts === 591 592* Name: Python3 593* File name: 594** on Windows: full path to "python.exe" 595** on Unix: python3 596* Shell command: 597** on Windows: checked 598** on Unix: unchecked 599* Parameters: "{FileNameOnly}" 600* Initial folder: {FileDir} 601* Lexers: Python 602* Capture output: Output panel 603* Encoding: utf_8 604* Pattern: \s*File "(?P<file>.+)", line (?P<line>\d+) 605 606=== Tool to preview HTML file in Chrome === 607 608* Name: Preview in Chrome 609* File name: 610** on Windows: C:\Program Files\Google\Chrome\Application\chrome.exe 611* Shell command: 612** on Windows: unchecked 613* Parameters: "{FileName}" 614* Initial folder: (empty) 615* Lexers: HTML 616* Capture output: Ignore 617 618=== Tool to open PHP documentation with given topic === 619 620Tool to open PHP documentation, in .chm format, for the word under editor's caret. For Windows only. You need to install KeyHH from http://keyworks.helpmvp.com/ , it is stable tool mentioned on several sites. Program "keyhh.exe" will be in your system PATH. 621 622Before making the tool, add "$" char to word chars for PHP lexer. To do it, call "Plugins / Options Editor", in the Options Editor dialog find option "word_chars" and set it to "$". You must save option to PHP lexer-specific config, so in the dialog you must check flag "For [x] Lexer", and choose lexer "PHP", and then write option value "$" and press Enter. 623 624Download PHP documentation in .chm format from PHP.net, google for "php_manual_en chm", it is 16M file. 625 626Tool properties: 627 628* Name: PHP Help 629* File name: keyhh.exe 630* Shell command: unchecked 631* Parameters: -MyHelp -#klink {CurrentWord} "C:\Work\php_manual_en.chm" 632* Initial folder: (empty) 633* Lexers: PHP 634* Save before: Nothing 635* Capture output: Ignore 636 637=== Tool to open AutoIt documentation with given topic === 638 639Tool to open AutoIt documentation, in .chm format, for the word under editor's caret. For Windows only. You need to install KeyHH from http://keyworks.helpmvp.com/ , it is stable tool mentioned on several sites. Program "keyhh.exe" will be in your system PATH. 640 641With AutoIt installed, you also have .chm documentation, its path is usually "C:\Program Files (x86)\AutoIt3\AutoIt.chm". 642 643Tool properties: 644 645* Name: AutoIt Help 646* File name: keyhh.exe 647* Shell command: unchecked 648* Parameters: -MyHelp -#klink {CurrentWord} "C:\Program Files (x86)\AutoIt3\AutoIt.chm" 649* Initial folder: (empty) 650* Lexers: AutoIt 651* Save before: Nothing 652* Capture output: Ignore 653 654=== Tool to open .chm documentation for all lexers === 655 656See above example about tool for PHP documentation. Create the similar tool 657 658* File name: keyhh.exe 659* Shell command: unchecked 660* Parameters: -MyHelp -#klink "{CurrentWord}" "{AppDir}\..\Docs\{Lexer}.chm" 661* Lexers: (empty) 662 663This tool needs renamed .chm files: for lexer AutoIt it needs "AutoIt.chm" and so on. It needs .chm files in a single folder relative to CudaText folder. 664 665=== URL for Google search === 666 667This is URL, not tool. In the External Tools dialog, press URL button, then press Add to add a new URL. 668 669* Name: Google find 670* URL: 671 672<syntaxhighlight lang="text"> 673http://google.com/search?q={SelectedText|q} 674</syntaxhighlight> 675 676=== Tool to open folder of current file in Windows Explorer === 677 678Tool properties: 679 680* Name: Open cur dir in Explorer 681* File name: explorer.exe 682* Shell command: unchecked 683* Parameters: {FileDir} 684* Initial folder: {FileDir} 685 686=== Tool to go to current file in FreeCommander === 687 688* Name: Go to file in FreeCommander 689* File name: path\to\FreeCommander.exe 690* Shell command: unchecked 691* Parameters: "/L={FileName}" /C 692* Initial folder: {FileDir} 693 694=Runner= 695Plugin Runner was written as an alternative to External Tools. 696 697* Runner is more light weight. 698* Runner supports Sublime Text 3 build-systems. 699* Runner displays tool output immediately line-by-line as it appears (External Tools can only show the entire ready output). 700 701Many build-systems from Sublime Text 3 were packaged and put to add-on collection, search for add-on "Many Build Systems". 702Only few build-systems were packaged into own separate packages because they have big EXE/Binary files. 703Some ST3 plugins have build-systems paired with some Python code - they are not supported. 704 705See the [https://github.com/halfbrained/cuda_runner/blob/main/readme/readme.txt Runner documentation on GitHub]. 706 707Here is the GIF animation which shows reaction of Runner to PHP script running: 708<syntaxhighlight lang="php"> 709<?php 710for($i=0; $i<10; $i++) { 711 sleep(1); 712 echo "$i is here\n"; 713} 714?> 715</syntaxhighlight> 716 717[[File:cudatext-runner-thread.gif]] 718 719==Example C++ tool== 720Install the add-on "build-system: C++ using G++". 721It supports C++ lexer using GNU C++ compiler. 722It works on Linux/macOS out-of-the-box, on Windows you need the command "g++" to be in the system PATH. 723 724This build-system has 2 commands: 725* compile, then run the compiled binary (default command) 726* only run the compiled binary (it should be called from "Plugins / Runner / Build with..."). 727 728Example C++ file: 729<syntaxhighlight lang="cpp"> 730#include <iostream> 731 732int main() { 733 std::cout << "Hello World!"; 734 return 0; 735} 736</syntaxhighlight> 737 738Example output in the CudaText Output panel (Linux): 739<pre> 740-- [16:41:55] Building: C++: new.cpp 741-- Command: g++ -std=c++11 -Wall "/home/user/new.cpp" -o "/home/user/new" && "/home/user/new" 742-- Working dir: /home/user 743Hello World! 744-- Done (0.8s), return code: 0 745</pre> 746 747==Example PHP tool== 748How to debug for example PHP file, with Runner. 749Create file "[CudaText]/data/buildsystems/php.sublime-build" with such text: 750<syntaxhighlight lang="json"> 751{ 752 "file_patterns": ["*.php"], 753 "linux": { 754 "cmd": ["php", "$file"] 755 }, 756 "windows": { 757 "cmd": ["C:\\PHP_folder\\php-win.exe", "$file"] 758 } 759} 760</syntaxhighlight> 761 762Restart CudaText. 763 764After opening a PHP file, call Runner main command "Build", that's it. It must show script output (in the Output panel) line-by-line, as it appears. 765 766Example script to test: 767<syntaxhighlight lang="php"> 768<?php 769for($i=0; $i<10; $i++) { 770 sleep(1); 771 echo "$i is here\n"; 772} 773?> 774</syntaxhighlight> 775 776==Example Python tool== 777How to debug for example Python file, with Runner. 778Create file "[CudaText]/data/buildsystems/py.sublime-build" with such text: 779<syntaxhighlight lang="json"> 780{ 781 "file_patterns": ["*.py"], 782 "linux": { 783 "cmd": ["python3", "$file"], 784 }, 785 "windows": { 786 "cmd": ["pythonw.exe", "$file"] 787 } 788} 789</syntaxhighlight> 790 791Restart CudaText. 792 793After opening a Python file, call Runner main command "Build", that's it. It must show script output (in the Output panel) line-by-line, as it appears. 794 795Example script to test: 796<syntaxhighlight lang="python"> 797import sys 798import time 799 800def ForTest(): 801 for i in range(5): 802 time.sleep(1) 803 print(str(i) + " is here", flush=True) 804 805if __name__ == '__main__': 806 ForTest() 807</syntaxhighlight> 808 809==Example Free Pascal tool== 810How to compile and run Free Pascal files. 811Create file "[CudaText]/data/buildsystems/Free Pascal.sublime-build" with such text: 812<syntaxhighlight lang="json"> 813{ 814 "file_patterns": ["*.pp", "*.pas"], 815 "file_regex": "(.+?)\\((\\d+),(\\d+)\\)\\s(.+)$", 816 "working_dir": "$file_path", 817 "name": "Compile", 818 "cmd": ["/home/user/fpcupdeluxe/fpcupdeluxe32/fpc/bin/x86_64-linux/fpc.sh", "$file_name"], 819 "variants": [ 820 { 821 "name": "Run", 822 "cmd": ["./$file_base_name"] 823 } 824 ] 825} 826</syntaxhighlight> 827 828Restart CudaText. 829 830Here we use full path to FPC, when it is installed by FPCUPdeluxe tool on Linux x64. We use path of "fpc.sh" which is created by FPC installation. 831 832After opening a Pascal file, call Runner main command "Build", that's it. 833The "Build" command example output: 834 835<pre> 836-- [20:07:55] Building: Free Pascal: new.pas 837-- Command: ['/home/user/fpcupdeluxe/fpcupdeluxe32/fpc/bin/x86_64-linux/fpc.sh', 'new.pas'] 838-- Working dir: /home/user 839Free Pascal Compiler version 3.2.3-425-gebc55c0f4e-dirty [2021/09/09] for x86_64 840Copyright (c) 1993-2021 by Florian Klaempfl and others 841Target OS: Linux for x86-64 842Compiling new.pas 843Linking new 8443 lines compiled, 0.1 sec 845-- Done (0.2s), return code: 0 846</pre> 847 848The config above also gives the "Run" command for the compiled binary - in the menu of "Plugins / Runner / Build with...". The "Run" command example output: 849 850<pre> 851-- [20:09:09] Building: Free Pascal: new.pas 852-- Command: ['./new'] 853-- Working dir: /home/user 854Hello world. 855-- Done (-0.0s), return code: 0 856</pre> 857 858=FindInFiles= 859This plugin implements searching in many files, starting from custom folder. CudaText doesn't have the built-in feature to search in many files, and seems it will not have it in future, because FindInFiles is so powerful, it even has the Configuration dialog with dozens of options. 860 861Project Manager plugin allows to call FindInFiles functionality. Focus a folder in Project Manager, call context menu, and then "Selected directory / Find in directory..." menu item. 862 863==FiF3 and FiF4: comparison and future== 864CudaText has two plugins to search in files/tabs: 865 866* FindInFiles v3 (FiF3) 867* FindInFiles v4 (FiF4) 868 869Important: FiF3 is almost frozen. Only serious bugs will be fixed. No plans to hide/delete FiF3. FiF4 supersedes FiF3. 870 871Detailed comparison. 872 873Common features: 874 875* Speed of search. Speed of FiF3 is stable. FiF4 can search faster or slower depending on the settings. In the "slow" mode FiF4 gives more complex Results or uses more complex filters. 876* Encoding detection. FiF4 allows to set more flexible plan (see submenu "=/Encoding plan"). 877* Presets. Both versions allow to define and restore named set of search parameters. FiF4 allows to run dialog and start '''immediate search''' with parameters from a preset (see main menu command "Find by preset..."). FiF4 allows to restore [pre]previous parameters (runtime '''auto saving'''). 878* Results/Source. FiF3 allows to put Results in old/new tab or in dialog editor control. FiF4 allows to put Results only in dialog editor control and has a command to copy Results to new tab. Both allow to open the source file for specified fragment in new tab. FiF3 can place Results and Source vertically or horizontally. FiF4 has only one way. 879* FiF3 has commands to '''count fragments''' and to show only filenames. FiF4 skips such commands as unnecessary. 880* FiF3 can save '''dialog layouts'''. FiF4 saves layout as part of preset. 881* Like FiF3, FiF4 has the "Replace" functionality. 882* Like FiF3, FiF4 can search '''in project''' folder(s). 883 884Main new features: 885 886* FiF4 can report the found fragment with its '''around lines''' (see "-?+?" button). 887* FiF4 can search '''multi-line fragments''' (see "+" button). 888* FiF4 can search in '''many start folders'''. 889* FiF4 allows to use '''lexer data''' to filter and report fragments (in/out string/comment, lexer path). 890* FiF4 allows to show lines in the Results with its '''lexer colors''' from source files. 891* FiF4 allows to use '''macro-variables''' (OS environments, properties of current file/tab and free-set names) in any editable fields . 892* FiF4 has '''statusbar''' to show statistics of the last search: folders/files/fragments/timing. 893* FiF4 allows to '''reformat Results''' (change tree type and more) without new search. 894* FiF4 allows to show '''modification time''' of files in the Results. 895 896=Configure Menu= 897 898Plugin "Configure Menu" (in Addon Manager) allows to change top menu and context menu. Plugin can create file (settings/menu.json) with default menu configuration, which you edit to customize all menus. File has items like: 899 900 ,{"cap":"&Save", "cmd":"cmd_FileSave"} 901 902How to add here built-in commands? See identifiers of CudaText commands in the file "py/cudatext_cmd.py", they have prefixes "cCommand_" (low level commands) and "cmd_" (high level commands). For example, "cmd_FileSave" is the command to save current file. 903 904How to add here plugin commands? For example, you have plugin "Comments", it is in the folder "py/cuda_comments". See plugin's file install.inf, and find there needed Python methods. Then add in the "settings/menu.json" item like this: 905 906 ,{"cap":"Toggle line comment", "cmd":"module=cuda_comments;cmd=cmt_toggle_line_body;"} 907 908Here "cuda_comments" is plugin folder name, and "cmt_toggle_line_body" is Python method from install.inf. 909 910You can add items to the CudaText top-menu and/or context-menu, it is different sections in "menu.json". 911Example screenshot shows how "menu.json" will look with new items for context-menu: 912 913[[File:cudatext-editing-context-menu.png]] 914 915=Intext Bookmarks= 916 917Plugin allows to place special marks, and to show Goto dialog for its special marks. 918These are not usual CudaText bookmarks, but text lines, which are recognized only by this plugin. 919 920Plugin adds menu items in "Plugins / In-text Bookmarks": 921 922* List for current tab -- show all marks in the current document 923* List for all tabs -- show all marks in all opened UI-tabs 924* Go to next 925* Go to previous 926* Add -- add a new mark at caret position 927 928"Special" lines are supported even for files without lexer, and files with lexer if lexer doesn't support comments. For such poor files, plugin will add special lines like "//NOTE: comment_text". 929 930You can customize that special lines, using plugin configuration dialog: menu item "Options / Settings-plugins / In-text Bookmarks". Dialog gives such options: 931 932* Bookmark signs: NOTE: NB! TODO: todo: todo. FIX: 933* Comment sign: // 934 935That configuration means that for "poor" files (without lexer, or with lexer without line comments), plugin uses lines beginning with "//NOTE:" or "//NB!" or "//TODO:" etc. 936For files with rich lexers, plugin uses lexer's line-comment prefix. 937 938=Color Text= 939 940Plugin "Color Text" gives several commands (in the Plugins menu) to add coloring to text ranges. 941Plugin uses the selected text, without selection it uses word under first caret. 942On applying the coloring, plugin marks file as "modified". 943Plugin is suitable for files with any lexer, it adds its colors over the lexer highlight. 944 945[[File:cudatext-color-text.png]] 946 947The data of coloring is saved to additional 'helper file' with extension .cuda-colortext, in the folder of the original file. After you delete this 'helper file', plugin will not load its data on next start. 948 949Not only background color can be changed, but also border color, and font styles (bold, italic, stikeout). 950To specify colors/styles, you have to edit the plugin config file. 951To edit the config file, call menu item "Options / Settings-plugins / Color Text". 952Config file has sections for colors/styles, and usual options: 953 954* "all_words": Colorize all occurrences of fragment. 955* "case_sensitive": Case sensitive search for other occurrences. 956* "whole_words": Colorize only those occurrences, which are whole words. 957* "show_on_map": Show added colored marks also on micro-map. 958 959=Insert Pics= 960CudaText gives the plugin API to show pictures between the text lines. 961These spaces between lines are called "gaps". 962Plugin "Insert Pics" exists to show picture files in gaps. 963It saves pictures in the helper files (using Base64 encoding), with extension .cuda-pic, 964near the original text file. Files with pictures look like this: 965 966[[File:cudatext-insert-pics.png]] 967 968* You can use any lexer for files with pictures. 969* You can add the unlimited number of pictures. But only one picture per "gap". 970* You can add/delete pictures later, using plugin's commands in menu "Plugins / Insert Pics". 971* When you delete the "helper file" (located in the same folder), all pictures will be lost for plugin. 972 973=Complete From Text= 974Plugin allows to show auto-completion listbox with words from the current file (or all opened UI-tabs, by option). 975E.g. if you typed "op" and press Ctrl+Space (default auto-completion hotkey), it may suggest previously mentioned words "operations", "opinion", "option" etc. 976Plugin is not smart like "LSP Client" plugin, so expect lot of 'false positives' in its listbox. 977 978[[File:cudatext-complete-from-text.png]] 979 980In the picture above, one word was taken from C lexer's C.acp file (this is a feature). 981 982Plugin is preconfigured to work with small set of lexers: none-lexer, Ini files, Markdown, reStructuredText, Properties. Here is how to use it for let's say "C" lexer: 983 984* Install the plugin 985* Call menu item "Options / Settings-plugins / Complete From Text" 986* This opens the "plugins.ini" file 987* Find section "[complete_from_text]", add ",c" (without quotes) to the line "lexers=" 988* Restart CudaText 989 990Plugin has more options in that "plugins.ini" file: 991 992* 'lexers': comma-separated lexer names, ie for which lexers to work; specify none-lexer as '-'. 993* 'min_len': minimal word length, words of smaller length will be ignored. 994* 'max_lines': if document has bigger count of lines, ignore this document. 995* 'case_sens': case-sensitive; words starting with 'A' will be ignored when you typed 'a'. 996* 'no_comments': ignore words inside "syntax comments" (lexer specific). 997* 'no_strings': ignore words inside "syntax strings" (lexer specific). 998* 'what_editors': which documents (ie UI tabs) to read to get words. Values: 999** 0: only current document. 1000** 1: all opened documents. 1001** 2: all opened documents with the same lexer. 1002* 'use_acp': add suggestions from autocomplete files in 'data/autocomplete' 1003* 'case_split': expands suggestions, autocompletion for 'AB' will include 'AzzBzz', so to get 'ValueError' just typing 'VE' (or 'VaE', 'VErr', 'ValErr' etc.) and calling on autocompletion will suggest it. 1004* 'underscore_split': expands suggestions, autocompletion for 'AB' will include 'AZZ_BZZ', so to get 'supports_bytes_environ' just typing 'sb' (or 'sbe', 'supbyenv' etc.) and calling on autocompletion will suggest it. 1005 1006Plugin supports CudaText option "nonword_chars", so for example words with '$' char are also added to completions, if CudaText option is configured so. 1007 1008=Embedded Editor= 1009 1010Plugin "Embedded Editor" shows "included" file in embedded editor - additional editor UI control is 1011shown between the text lines. 1012For example, you can open included CSS / JS files while editing the HTML file. 1013 1014[[File:cudatext-embedded-editor.png]] 1015 1016It adds menu item to show/hide embedded editor in the current document, for the 1017current caret position: "Plugins / Embedded Editor / Toggle". 1018 1019By default, plugin searches for the included filename inside double-quotes, 1020surrounding the caret position. This works OK for HTML and many other documents. 1021 1022For example, when you have opened file "/folder/file.html", and placed caret 1023inside first double-quotes: 1024<syntaxhighlight lang="html"> 1025 <link href="css/style.css" rel="stylesheet" type="text/css"/> 1026</syntaxhighlight> 1027then embedded editor will be opened for file "/folder/css/style.css". 1028 1029The search can be configured, though. For example, plugin can be used in Pascal 1030files for include-directives: 1031<syntaxhighlight lang="pascal"> 1032 {$I path/filename.inc} 1033</syntaxhighlight> 1034 1035Plugin has 2 config files, you will see 2 menu items in the 1036"Options / Settings-plugins / Embedded Editor". 1037Read more about config files in the readme.txt of plugin. 1038 1039=Breadcrumbs= 1040 1041Plugin "Breadcrumbs" shows the toolbar widget (modern name is breadcrumb bar) below or on top of the editor for quick 1042file-system navigation. For example, when you have active editor with filename 1043"/home/user/mydir/myfile.ext", widget shows buttons: 1044<pre> 1045[ home / user / mydir / myfile.ext ] 1046</pre> 1047It can also show the "~" button for the home directory (by option): 1048<pre> 1049[ ~ / mydir / myfile.ext ] 1050</pre> 1051 1052[[File:cudatext-breadcrumbs.png]] 1053 1054Clicking on each button shows the popup with file-system listing, showing the 1055folder containing the clicked item. This popup supports basic tree-view navigation, 1056you can click files there to open them in CudaText. 1057 1058Plugin can also show buttons for Code-Tree nodes. This must be enabled first 1059in the config file - turn on the option "code_navigation". 1060Clicking the buttons from the code-tree shows the same tree-popup but with 1061a different content - with symbols of the documents. Clicking the nodes 1062in the tree-popup scrolls the document to different symbols. 1063 1064=LSP Client= 1065 1066Plugin "LSP Client" allows to use Microsoft LSP protocol in CudaText with servers for many languages. 1067It requires that CudaText uses Python 3.6 or newer (otherwise you will see the error messagebox). 1068 1069LSP Client gives several commands in the "Plugins / LSP Client", and all these commands work only if server supports them. 1070Some of LSP commands are: 1071 1072* Auto-completion: integrated with CudaText command "Auto-completion menu" (in the Command Palette). 1073* Go to definition: integrated with CudaText command "Go to definition" (in the Command Palette, and in the editor context menu). 1074* Function signature help: integrated with CudaText command "Show function hint" (in the Command Palette). 1075* Hover: shows the tooltip when you hover mouse above identifiers. You need the Ctrl key pressed while you hover. 1076 1077[[File:cudatext-lsp-hover_.png]] 1078 1079* Find references: finds all locations where an identifier (under first caret) is used and shows menu with locations. 1080 1081[[File:cudatext-lsp-refs.png]] 1082 1083* Code linting: checks the syntax of code, and places underlines and/or bookmarks on "incorrect lines". 1084* Document formatting. 1085 1086All LSP servers should have a homepage with description of their functions, and installation information. 1087LSP Client was initially tested with 2 popular servers: Python, C#. 1088 1089In the server config "lsp_*.json", key "lexers", you need to specify the mapping between CudaText lexer names and LSP language names. 1090For example, while CudaText lexer name is "Bash script", LSP language name is "bash". 1091And while CudaText lexer name is "C#", LSP language name is "csharp". 1092 1093<syntaxhighlight lang="json"> 1094{ 1095 "lexers": { 1096 "C#": "csharp" 1097 }, 1098 ... 1099} 1100</syntaxhighlight> 1101 1102LSP Client also has the settings file, use menu item to open it: "Options / Settings-plugins / LSP Client". 1103 1104==LSP server for Python== 1105Python server has [https://github.com/palantir/python-language-server this homepage] and supports: 1106 1107* Auto-completion 1108* Go to definition 1109* Function signature help 1110* Hover 1111* Find references 1112* Code linting 1113* Document formatting 1114 1115Use "pip" to install the Python LSP server: 1116 1117 pip install python-language-server 1118 1119Server installation adds the command "pyls" which is not in the PATH. 1120You need to write the full path to LSP Client config. 1121Create the file "[CudaText]/settings/lsp_py.json" with text like this: 1122 1123<syntaxhighlight lang="json"> 1124{ 1125 "lexers": { 1126 "Python": "python" 1127 }, 1128 "cmd_windows": ["C:\\Python_folder\\pyls.exe"], 1129 "cmd_macos": ["pyls"], 1130 "cmd_unix": ["~/.local/bin/pyls"] 1131} 1132</syntaxhighlight> 1133 1134Open some Python script, and call some commands of LSP Client. It will run the server, and it should work. 1135 1136==LSP server for CSS/SCSS/LESS== 1137 1138The CSS (and SCSS, LESS) server is not easy to install, so here is the instruction, from the author of LSP Client: 1139 1140* Download the repository of VSCode: https://github.com/microsoft/vscode 1141* From the repository, get the folder "extensions/css-language-features/server" and enter in it. 1142* Replace the file "tsconfig.json" with content: 1143<syntaxhighlight lang="json"> 1144{ 1145 "compilerOptions": { 1146 "target": "es2018", 1147 "lib": [ 1148 "es2018" 1149 ], 1150 "module": "commonjs", 1151 "strict": true, 1152 "alwaysStrict": true, 1153 "noImplicitAny": true, 1154 "noImplicitReturns": true, 1155 "noImplicitOverride": true, 1156 "noUnusedLocals": true, 1157 "noUnusedParameters": true, 1158 "forceConsistentCasingInFileNames": true, 1159 1160 "outDir": "./out" 1161 }, 1162 "files": [ 1163 "src/node/cssServerMain.ts" 1164 ] 1165} 1166</syntaxhighlight> 1167 1168* Install dependencies and TypeScript. In Terminal: 1169 1170 npm install 1171 npm install -g typescript 1172 1173* Compile it. In Terminal: 1174 1175 npx tsc 1176 1177Server should be compiled. To use the server in LSP Client, create the file "lsp_css.json" with such content: 1178<syntaxhighlight lang="json"> 1179{ 1180 "name": "vsc-css", 1181 "lexers": { 1182 "CSS": "css", 1183 "SCSS": "scss", 1184 "Sass": "sass", 1185 "LESS": "less", 1186 }, 1187 "cmd_unix": [ 1188 "node", 1189 "path_to_server/server/out/node/cssServerMain.js", 1190 "--stdio" 1191 ] 1192} 1193</syntaxhighlight> 1194 1195==LSP server for Nim== 1196 1197Server from https://github.com/PMunch/nimlsp works good. Config "lsp_nim.json": 1198 1199<syntaxhighlight lang="json"> 1200{ 1201 "name": "nim-lsp", 1202 "lexers": { 1203 "Nim": "nim" 1204 }, 1205 "cmd_unix": [ 1206 "~/.nimble/bin/nimlsp" 1207 ] 1208} 1209</syntaxhighlight> 1210 1211==LSP server for Rust== 1212 1213Q: I've successfully configured several language servers with this plugin, but rls ( https://github.com/rust-lang/rls ) seems to be unresponsive. Does this work for anyone else? 1214 1215A: Seems to be a rls issue: https://github.com/rust-lang/rls/issues/536 . A workaround is to comment out the line in <cudatext>/py/cuda_lsp/sansio_lsp_client/io_handler.py, replace this: 1216 1217 "Content-Type": f"application/vscode-jsonrpc; charset={encoding}", 1218 1219with this 1220 1221 #"Content-Type": f"application/vscode-jsonrpc; charset={encoding}", 1222 1223==LSP server for AutoHotkey== 1224 1225* Download the repository of AutoHotkey2: https://github.com/thqby/vscode-autohotkey2-lsp 1226* Extract and enter the directory: "vscode-autohotkey2-lsp-main" 1227* Install dependencies and TypeScript. In Terminal: 1228 1229 npm install 1230 npm install -g typescript 1231 1232* Enter the directory "server", and compile the server. In Terminal: 1233 1234 npx tsc 1235 1236Server should be compiled now. To use the server in LSP Client, create the file "lsp_ahk.json" in the "settings" with such content: 1237<syntaxhighlight lang="json"> 1238{ 1239 "name": "AutoHotkey2", 1240 "lexers": { 1241 "AutoHotkey": "ahk" 1242 }, 1243 "cmd_unix": [ 1244 "node", 1245 "path_to_server/server/out/server.js", 1246 "--stdio" 1247 ] 1248} 1249</syntaxhighlight> 1250 1251==LSP server for JavaScript/ReactJS== 1252 1253* In "Addons Manager", install the lexer for ReactJS: "JavaScript Babel". 1254* Install TypeScript and the LSP server. In Terminal: 1255 1256 npm install -g typescript typescript-language-server 1257 1258To use the server in LSP Client, create a file "lsp_js.json" in the "settings" directory with such content: 1259<syntaxhighlight lang="json"> 1260{ 1261 "name": "JavaScript", 1262 "lexers": { 1263 "JavaScript": "javascript", 1264 "JavaScript Babel": "javascriptreact" 1265 }, 1266 "cmd_unix": [ 1267 "typescript-language-server", 1268 "--stdio" 1269 ] 1270} 1271</syntaxhighlight> 1272 1273==LSP servers for C/C++== 1274 1275Install one of the servers following the instructions: 1276* clangd: https://clangd.llvm.org/installation.html 1277* ccls: https://github.com/MaskRay/ccls/wiki/Build + https://github.com/MaskRay/ccls/wiki/Install 1278 1279To use the server in LSP Client, create a file "lsp_c.json" in the "settings" directory with such content: 1280<syntaxhighlight lang="json"> 1281{ 1282 "lexers": { 1283 "C++": "cpp", 1284 "C": "c" 1285 }, 1286 "cmd_unix": [ 1287 "clangd-9", 1288 ], 1289} 1290</syntaxhighlight> 1291 1292Replace "clangd-9" with "ccls" if it was chosen. 1293 1294==LSP server for Red== 1295 12961) On Linux x64. 1297 1298* Install Red. Download "red" binary, "chmod +x red", then copy it to PATH dir (/usr/bin on Ubuntu). Command "red" must work from Terminal. Red release 0.6.4 may give errors with the LSP server, so better install build from 30-Sep-2021. 1299* Install server from https://github.com/bitbegin/redlangserver, put the repo e.g. to ~/redlangserver. 1300* Create file "redlangserver.sh" and put it to some PATH dir. Content: 1301 1302<syntaxhighlight lang="bash"> 1303#!/bin/bash 1304red ~/redlangserver/server.red 1305</syntaxhighlight> 1306 1307* Create file (CudaText)/settings/lsp_red.json with content: 1308 1309<syntaxhighlight lang="json"> 1310{ 1311 "lexers": { 1312 "Red": "red" 1313 }, 1314 "cmd_unix": ["redlangserver.sh"], 1315 "cmd_windows": ["c:\\red\\red.exe", "--cli", "c:\\red\\redlangserver\\server.red"] 1316} 1317</syntaxhighlight> 1318 1319Server should work now. It gives: mouse hover tooltips (Ctrl + mouse hovering over names), go to definition. 1320 13212) On Windows 10 x64. 1322 1323* Install Red to "c:\Red". Tested the build from 02-Oct-2021. 1324* Install server from https://github.com/bitbegin/redlangserver, put the repo to "c:\Red\redlangserver". 1325* Run once the command "c:\red\red.exe --cli", it will print "Compiling Red console..." with the big pause. 1326* Create file (CudaText)\settings\lsp_red.json with the same content as for Unix. Adjust path to Red folder, if needed. 1327 1328Server should work now. It gives: mouse hover tooltips (Ctrl + mouse hovering over names), go to definition (works not always, logic when it works is unclear). 1329 1330Note: don't create .bat or .cmd file with the "red.exe" calling, because it does not work in LSP Client for some reason. 1331 1332[[Category:CudaText]] 1333