CudaText

Introduction

CudaText is a cross-platform text editor, written in Lazarus.

• Syntax highlighting for lot of languages (230+ lexers exist)
• Code folding
• Code tree (list of functions/classes/etc, if lexer supports this)
• Multi-carets, multi-selections
• Search/replace with regular expressions
• Support for many encodings
• Extendable by Python add-ons
• Command palette
• Configs in JSON files
• Interface and syntax themes
• Based on ATSynEdit engine

Features for HTML/CSS coding:

• Built-in HTML and CSS auto-completion
• HTML tags completion with Tab-key
• HTML color codes underlining
• HTML tooltips on mouse-over
• Viewer for picture files (jpeg, png, gif, bmp, ico)

Screenshot on Windows:

Advantages over Sublime Text 3

• Open source, more OS'es
• Python API is easier to use
• Python API allows to manage dialogs and UI-controls, including CudaText editor control
• Code-Tree for lot of lexers (ST has plugin for very limited set of languages)
• Floating groups (3 groups of UI-tabs in floating windows)
• Powerful lexer format, and easier to configure (via dialogs in additional program)
• Toolbar, configurable via plugin (#Toolbar)
• Horizontal ruler above text
• Markers in editor (#Markers)
• Sessions system (#Sessions)
• Caret position after end of line
• Better support for encodings, including UTF-32
• Correctly saves binary files
• Viewer for files of unlimited size, including hex mode (#File_viewer)
• Perfomance (#Program_perfomance)
• Coloring of UI-tab headers
• Options Editor plugin
• Can plug-in different Python engine
• Character Map dialog (#Char_map)

Download

• Homepage: http://uvviewsoft.com/cudatext/
• Downloads: https://www.fosshub.com/CudaText.html . It has builds for Windows, Linux (x32, x64, ARM, AArch64), macOS, FreeBSD, NetBSD, Solaris.
• GitHub repository: https://github.com/Alexey-T/CudaText . That account https://github.com/Alexey-T contains other packages needed to compile the app.

Configs

CudaText has configuration system in JSON files: call menu item "Settings-default" and you'll see default config. Copy any lines to config called by "Settings-user" and edit this user config - it's actial config file. You can copy JSON comments too. Default config is not read by CudaText, it's only to show possible options.

• User config. File "settings/user.json". Can be opened via menu item "Options / Settings-user".
• Default config. File "settings_default/default.json". Can be opened via menu item "Options / Settings-default". CudaText doesn't read this config, but it's parsed by plugin "Options Editor".
• Lexer specific configs. Files "settings/lexer NNN.json". It is layer which is read after user config, when user activates some lexer. E.g. if you open C file, config file "lexer C.json" is read. You should not write "ui_" options to lexer specific configs (it may give weird effects on changing lexer), and some other global options.
  • For (None) lexer, config file is named "lexer -.json".
  • For lite lexers, config files are named with suffix, e.g. "lexer XML ^.json".
• Default lexer specific configs. Files "settings_default/lexer NNN.json". It is layer which is read after user config, but before lexer specific config. CudaText provides several such files, with useful defaults.
• Hotkeys config. File "settings/keys.json". Special dialog allows to change all hotkeys in CudaText. You should not edit this config file. Dialog is called from "Help / Command palette" by F9. Dialog allows to set 1st and 2nd hotkeys for any command (except dynamically added commands to change lexer).
• Plugin configs. Files "settings/cuda_*". Plugins store their settings in there, and files can be in any format (most used are JSON and INI). Good quality plugins provide menu items in "Options / Settings-plugins" to open their config file, or to show configuration dialog.
• History files. Files "settings/history*.json". Don't edit them. Mentioned here because sometimes users need to delete their history files (dialog positions, recent files list etc, recent search strings etc).

File types config

Section "detect" in user.json. Specifies mapping from "file name" to "lexer name".

  "detect": {
    "*.mht": "HTML",
    "myconfig.conf": "Nginx",
    ".profile": "Bash script",
  },

• Key name: File mask. Must be full name (without path), or extension after "*." chars. More complex masks are not yet supported.
• Key value: Lexer name. Value "-" means "don't activate lexer".

Another method to specify this mapping is dialog "Lexer properties", in which you can add extension or name+extension to a lexer. But dialog is more limited: it saves option to the lexer file (data/lexlib/lexername.lcf), so setting will be reset on reinstalling lexer.

Section "detect_line" in user.json. Allows to detect lexer by first line of file.

  "detect_line": {
    "<html.*": "HTML",
    "<!DOCTYPE.*": "HTML",
    "<\\?xml.*": "XML",
  },

• Key name: Reg-ex for first line. Case sensitive, but you can use (?i) modifier in reg-ex.
• Key value: Lexer name. Value "-" means "don't activate lexer".

Plugin groups config

Section "plugin_groups" in user.json. Allows to add grouping to the Plugins menu, e.g. to put all "HTML ..." and "CSS ..." menu items into "Web" submenu. Example:

  "plugin_groups": {
    "CSS .+": "Web",
    "HTML .+": "Web",
    "JS .+": "Web",
    "Config.+": "Config",
    "Option.+": "Config",
  },

• Key name: regular expression for the first part of menu name. E.g. if menu name in install.inf is "CSS Utils\Misc\Action", then first part is "CSS Utils".
• Key value: group name, it can be with "\" char to make several levels.

Help topics

Command line parameters

Usage:

• cudatext [ key ... ] filename ...

Supported keys:

• -h, --help - Show command line help and exit
• -v, --version - Show application version and exit
• -z=[text|binary|hex|unicode] - Open files from command line in internal viewer, using given viewer mode
• -r - Open files from command line in read-only mode
• -e=value - Open all files from command line in given encoding
• -el - Show possible encoding names and exit
• -n - Ignore option "ui_one_instance", and force new app window
• -nh - Ignore saved file history (caret, selection, scroll position)
• -ns - Ignore saved session
• -nn - Don't suggest to create new file if param not found
• -s=folder - Specify path of settings folder, which contains all config files
• -i - Read the contents of stdin to a new document. Unix only. It can be used in Unix shell like: "ls -l | cudatext -i"
• -id=name - Set "group" for single-instance mode, so that program with one "group" will not interfere and find instances with another "group". Unix only. Default value is "cudatext.0".
• -w=left,top,width,height - Set position/size of window (up to 4 numbers should be specified, any can be skipped to keep previous value)

Notes:

• Filenames can be with ":line" or ":line:column" suffix to place caret.
• Folders can be specified too. They will be opened as a "project" in the Project Manager.
• Project files (.cuda-proj) can be loaded.
• Session files (.cuda-session) can be loaded, if Session Manager installed.
• Non-existing file name can be specified, program will ask to create it.
• File masks with "*" symbol are supported, e.g. command "cudatext test/t*.htm*" will work.

macOS

On macOS you cannot run "cudatext", but you can open Terminal and create the alias for "cudatext":

alias cudatext=open\ /Applications/CudaText.app\ --args

This allows to open in Terminal commands like "cudatext ~/filename.html".

Mouse shortcuts

Note for macOS: use Cmd key instead of Ctrl key, in all commands listed here.

Multi-carets:

• Ctrl+click - add/remove caret.
• Ctrl+drag - add caret with selection.
• Ctrl+Shift+click - add carets column in several lines (from previous caret to clicked line).

Dragging:

• Alt+drag - select column of text. (Note: it may look weird if word-wrap on, because wrap is not considered here at all. Simple rectangle of coordinates [x1,y1]-[x2,y2] is always selected, even if this gives bad looking screen.)
• drag on gutter's line numbers - select by entire lines.
• double-click and immediately drag - select text by words.
• drag-drop of selected text block is supported. If Ctrl is pressed during the drop (you should press Ctrl after drag is started), block will be copied (not moved) to pointed position.

Clicks:

• double-click - select clicked word (see option word_chars).
• triple-click - select entire line (limited by end-of-lines).

• middle-button click (with option mouse_mid_click_scroll) - start "Browser Scroll" mode: circle mark appears and mouse moving around this mark auto-scrolls text in 4 directions; speed of scrolling depends on distance of cursor from circle mark (any click to turn off).

• middle-button click (with option mouse_mid_click_paste) - paste from clipboard. This is like in Linux. Additionally it's good to install plugin "Auto-Copy to Clipboard".

Misc:

• Alt+click (with option mouse_goto_definition) - call "Goto definition" command (if plugin installed).
• Shift+Alt+click - make vertical (column) selection, from first caret to clicked position.
• Shift+ scroll mouse wheel - scroll text horizontally.
• Ctrl+ scroll mouse wheel (with option mouse_wheel_zoom) - zoom text in/out.
• Ctrl+ scroll mouse wheel (on picture preview panel) - zoom picture in/out.

Multi-carets

Multi-carets are several carets at once. All carets work together for many editing commands: caret moving, text typing, deleting, selection with keyboard. See "Mouse shortcuts", how to add/remove carets.

Animation:

Multi-selections

If you add caret with Ctrl+click, caret has no selection. If you add caret with Ctrl+drag, caret will have selection. You can add selections to carets later, by Shift+arrows, Shift+Home, Shift+End etc.

Multi-selections are handled specially on copy/paste. If you copy selections, then move carets, then paste, paste will insert clipboard lines into carets: line-1 at caret-1, line-2 at caret-2 etc (only if carets count equals to lines count in clipboard, otherwise result is different).

Animation shows this:

Clipboard commands with selections

Clipboard-related commands work with carets, both with selections and without them. Some details about this:

Command	Behaviour, when there're no selections	Behaviour, when at last one selection present
Copy to clipboard	Copies entire lines, containing carets. (Ignores multiple carets on same line.)	Copies only selections text. (Ignores carets without selections.)
Cut to clipboard	Similarly to "Copy" w/o selections.	Similarly to "Copy" with selections.
Paste from clipboard	First, selections are cleared (deleted). Then, command pastes text into each caret position. Special case is when clipboard lines count equals to carets count - in this case, first line is inserted at first caret, second line is inserted at 2nd caret, etc.
Delete char	Deletes one char at each caret position.	Deletes only selections text. (Ignores carets without selections.)

Lexers

Syntax highlighters in CudaText are called lexers. Lexers are compatible with SynWrite editor (which is frozen). Lexer engine by EControl.ru is used, with modifications by Alexey Torgashin. Main modification is support for folding in Python and other syntaxes with indentation-based folding. Other modifications are porting from Delphi to Free Pascal and optimizations. EControl.ru's original lexer engine is closed source, but CudaText's version is open source, with the permission from EControl.ru.

• Dialog "Lexer properties" allows to config props of current lexer (selected via statusbar panel in CudaText). You can config: lexer name, file types, commenting for language, colors of tokens, font-styles (bold/italic/underline), borders around tokens.
• Dialog "Lexer library" shows list of installed lexers. Dialog shows lexers which are in the folder "data/lexlib".

Dialog "Lexer library" has hotkeys:

• Enter: same as "Configure" button
• Delete: same as "Delete" button
• Space: same as "Hide/Show" button
• Esc: close dialog

Lexers on SourceForge

Preinstalled lexer library has limited set of lexers. Other lexers, which are compatiable with SynWrite editor, are hosted on SF.net: http://sourceforge.net/projects/synwrite-addons/files/Lexers/

These zip packages can be installed in CudaText: open any zip file via "File / Open" and confirm installation.

Lexers editing

You can modify/create lexers. But not in CudaText. Install SynWrite (needed Wine on Linux) and in it you have lexer editor dialog.

• In SynWrite call menu "Options / Addons manager / Install", install needed lexer from web. SynWrite lexer-library must have lexer before you edit it.
• In SynWrite call "Lexer prop" dialog and edit all you need. Or make new lexer.
• In SynWrite install "ExLexer" addon. Call it in "Plugins" menu, select needed lexer. You have exported zip file.
• In CudaText open this zip file. Confirm installation of lexer.

Screenshot of SynWrite dialog:

How to setup styles of hidden sublexer

Some lexers are distributed in packages together with sub-lexer, and sub-lexer is hidden. Example: "HTML Django" with sub-lexer "HTML Django internal" (the second one isn't visible in the Lexers menu, so it's called hidden). Users, which have option "ui_lexer_themes" off, want to configure styles of all lexers. How to access hidden ones?

• Open "Lexer library" dialog (menu: Options / Lexer / Lexer library).
• In dialog, focus needed lexer, press "Configure" button
• Dialog "Lexer properties" will open for selected lexer
• In dialog's "Styles" tab, configure all you need

You can change visibility of lexer in SynWrite lexer editor (the checkbox will write line "Internal = True" at the end of .lcf file).

How to create distributive of new lexer

In SynWrite, you've created .lcf file in folder SynWrite/Data/LexLib. If you configured "Commenting" options, also file .cuda-lexmap is created. Now you need to create .zip installation of lexer, for both editors: SynWrite, CudaText.

• In lexer file, replace system colors to usual colors: replace "clWindowText" to "clBlack" (clWindowText may be light on CudaText on Linux); replace "clInfoText" and "clInfoBk" too.
• In SynWrite, in Addon Manager, install plugin "ExLexer".
• In SynWrite, run menu item "Plugins / ExLexer", to create .zip for your lexer.
• In CudaText, open this new zip file, this installs lexer to CudaText.
• In CudaText, activate your lexer, dialog should show: "Lexer style mapping". Fill items in this dialog.
• In CudaText, test this "lexer style map" in action: open file with your lexer active, and activate "default" UI theme, then activate "sub" UI theme. Main themes must show nice colors in your syntax file. Call dialog "Options / Lexers / Lexer style mapping" to fix colors.
• In prev step, you configured .cuda-lexmap file, in folder CudaText/data/lexlib. Copy this file to zip installation of your lexer.
• Zip must contain: install.inf, .lcf file(s), .cuda-lexmap file per each lexer.

Lite lexers

Lite lexers are lexers is special format (internally it's JSON file), with very limited features. They don't support code-tree, folding, don't support multi-line comments, don't have rich highlighting (e.g. background highlight of string `12+$var` with additional highlight for 12 and $var inside). And they don't keep tokens information in memory (positions of found tokens in text). But they work very fast for any file size (with average line length). Lite lexers have " ^" suffix in name. Currently few lite lexers are made: XML ^, JSON ^, Log files ^, SQL ^. You can also choose them, from the usual lexers menu (they are visible by suffix).

Lite lexers are auto used for big files, if file size is bigger than option "ui_max_size_lexer". And for small files, if normal lexer not found.

Differences in lexer support in CudaText/SynWrite

• SynWrite has lexer engine with old/outdated "method" for indentation-based folding, so all lexers with indentation-based folding must be different in CudaText and SynWrite
• SynWrite lexers need constructs like \x0D\x0A or \z (any line-break), while CudaText is OK with simple \n (because internal buffer never has CR char)
• For CudaText you must avoid "system colors" in lexer styles (e.g. "window background", "window text", "hint background"), because OSes have different system colors
• SynWrite lexer settings are not used in CudaText:
  • Option "Restart analysis from the line start" has no effect, it is forced to On in CudaText
  • Default style
  • Selection mark style
  • Search mark style
  • Current line style
  • Collapse mark style
  • Character set
  • Multiline border
  • Options in groups "Syntax tree decoration", "Pen"

Add-on types

• "plugins". Extensions with Python code. They add events and/or commands. Commands can be called then via "Plugins" top menu, but only if plugin's install.inf file doesn't hide menu items in "Plugins". In any case, all commands can be called via Command Palette dialog.

• "lexers". Syntax highlighting files. For ex, Arduino lexer adds item "Arduino" to the lexer menu. Some addons can add 2 or more lexers, for ex "HTML nnnnnn" addons often add 2 lexers: one is visible in the lexer menu, another one is hidden (it supports embedded blocks).

• "linters". Sub-plugins for CudaLint plugin. Each supports some lexer (or several similar lexers). To use them, install CudaLint plugin, open your work file, and call CudaLint commands: it calls appropriate linter and shows colored bookmarks on error/warning lines.

• "formatters". Sub-plugins for CudaFormatter plugin. Each supports one or several lexers and can reformat source code for these lexers. Examples: Python ReIndent, JS Sort Imports, AStyle Format.

• "tree helpers": Plugins which show Code Tree structure for some lexer (useful if language is complex, and lexer cannot handle all language complexity).

• "snippets". Collections of text fragments, for Snippets plugin. Install Snippets plugin first. Each addon supports some lexer(s). See details in the #Snippets topic.

• "translations". CudaText UI translations. For ex, JP translation changes all menuitems + dialogs to JP language. Dialogs of plugins are not affected (but authors can support translation in their plugins).

• "themes". UI/syntax themes for the "Options / Color themes" menu. UI themes change colors of CudaText interface. Syntax themes change colors of words in syntax highlighted files.

• "sidebar themes": Icon sets for the sidebar (vertical row of buttons on the left side).

• "toolbar themes": Icon sets for the main toolbar (horizontal row of buttons on the top).

• "toolbar x icons": Icon sets for plugin "Config Toolbar", for user-added buttons.

• "file type icons": Icon sets for the "Project Manager" file list. Most popular lexers have icons here.

• "code tree icons": Icon sets for the Code Tree (icons are visible in the Code Tree with some lexers, e.g. C#).

Location of folders 'settings', 'py', 'data'

When CudaText runs in portable mode (executable file is located near folder "data"), then portable folders are used. Otherwise these locations are used:

• Windows: %AppData%\CudaText
• Linux, *BSD, Solaris: ~/.config/cudatext, or $XDG_CONFIG_HOME/cudatext if this OS variable is set
• macOS: ~/Library/Application Support/CudaText

Encodings

You can change encoding of document by clicking on statusbar item, or by using menu "File / Encoding". Menu will give list of encodings. Menu gives 2 sub-menus:

• "Reload as": Reload file in given encoding from disk.
• "Convert to": Change encoding in memory only (this doesn't save the file).

Possible encoding names for command-line usage:

• utf8
• utf8_bom
• utf16le
• utf16le_bom
• utf16be
• utf16be_bom
• utf32le
• utf32le_bom
• utf32be
• utf32be_bom
• cp1250
• cp1251
• cp1252
• cp1253
• cp1254
• cp1255
• cp1256
• cp1257
• cp1258
• cp437
• cp850
• cp852
• cp866
• cp874
• cp932
• cp936
• cp949
• cp950
• iso88591
• iso88592
• iso885915
• mac

Line ends

All major types of line-ends are supported:

• CR LF (usual for Windows)
• LF (usual for Unix)
• CR (usual for Mac OS 9, now almost not used)

Mixed line-ends (CR with LF with CR LF) in one file are supported. Because of this feature, CudaText saves binary files to disk without corrupting them. To see mixed line-ends, use application option "unprinted_content", which can show text marks ("lf" etc) at line-ends.

To change line-ends for all lines in the current document, click statusbar cell for line-ends, menu will appear. You need to save file then. Changed line-ends can be undone via "Undo".

Groups of tabs

"Groups" are tab sets, each tab has attached editor control. By default only the first group is shown. Totally 6 groups can be shown at once. Menu item "=" (rightmost item in the top menu) allows to choose grouping mode:

• one group
• 2 groups: vertically or horizontally
• 3 groups: vertically, horizontally or 1+2
• 4 groups: vertically, horizontally or grid
• 6 groups: vertically, horizontally or grid

First group cannot be empty, at least one tab exists in it. Other groups can be empty: on closing last tab, if it's active, the first group activates.

• You can drag-drop tabs from any group to any other visible group (drop only on tabs area).
• You can move tabs to other groups (by group number or to the next/previous), using commands in tab headers context menu.
• In grouping modes "2 groups" and "1+2" there's a context menu for splitter, to choose splitting 50/50, 40/60 etc.
• On changing grouping mode, tabs from disappearing group(s) are moved to still visible group.

"Floating" groups are available, besides "fixed" 6 groups, they are inside separate windows (so can be moved to separate monitor). To place some tab to a floating group (1, 2, 3), call context menu over a tab title, "Move tab to group / Floating n" (n=1, 2, 3).

Auto-completion

Command Ctrl+Space shows auto-completion listbox for file, if app has autocompletion file for current lexer. Such files exist for many lexers: they are in dir "data/autocomplete", and additional lexers may have such files.

Example for PHP lexer:

Lexer HTML is handled specially, its completion listbox has 3 modes:

• caret is on tag (opening/closing): list of tags is shown
• caret is after tag on attribute place, before "=": list if attributes for found tag is shown
• caret is after tag, after attribute, after "=": list of values for found attribute is shown

Lexer CSS is handled specially too, its listbox has 2 modes:

• caret is on property name: list of properties is shown
• caret is after property name and ":": list of values is shown

Code Tree

To show code tree, activate side-panel (default hotkey: F12). Many lexers support code tree: most C-based, HTML, XML, CSS, JS etc. Code tree is configured inside each lexer properties (see how to edit lexers). Example of tree for Pascal:

• Double-click on a tree node moves caret to its text.
• Tree is filled after few seconds after file opening (search for options ui_tree* to change this pause).
• When you move caret, tree shows tree node for caret position, after a pause (search for options ui_tree* to change this).

Console panel

Panel is called by key Ctrl+tilde (Ctrl+`). It has read-only memo with output and edit field. You can type Python commands in the edit field, they will run and show output in the memo. E.g. enter "print(10+12)" and you'll see output "22". Can enter complex commands: e.g. "for i in range(10): print(i)".

• If you enter command beginning with "=", then it's the same as you enterted "print()". E.g. command "=10+12" will give "22".
• If you end command with ";", it won't be added to dropdown history.
• Double-click on memo lines starting with ">>>" repeats entered command (after ">>>" symbols).

You can enter commands from CudaText API. Example clears all bookmarks and sets bookmark on line 11 (these are several commands, run one by one):

from cudatext import *
ed.bookmark(BOOKMARK_CLEAR_ALL, 0)
ed.bookmark(BOOKMARK_SET, 10)

How to use Console as calculator

Call Console panel with Ctrl+` (Ctrl+tilde). In its input field, enter valid Python expressions with leading "=" char. To use "sin", "cos", "pi" etc, first enter command "from math import *".

Example of 3 entered lines and their log in console:

 >>> from math import *
 >>> =pi
 3.141592653589793
 >>> =100/5+2
 22.0

Command Palette

Command Palette is a dialog which shows all embedded and external (plugin) commands in a single list. To call it, use hotkey Ctrl+Shift+P (or alias hotkey F1). To configure hotkey for some command in Palette, focus this command in listbox and press F9 - additional dialog will appear. CudaText remembers last chosen listbox item in the history file.

Command Palette (and menu-like dialog in Python API) has filter field. Filter supports fuzzy search, if the option "ui_listbox_fuzzy" is on. "Fuzzy" means that filter leaves only those listbox items, which contain all filter chars in ascending order. Example of fuzzy matches:

• "fop" matches "file: open file"
• "gttb" matches "goto text begin"

If option is off, filter uses normal search. "Normal" means that filter leaves only those listbox items, which contain all words from the filter (in any order).

Filter field can find hotkeys too. Enter only hotkey substring, with first "@" char. E.g. "@ho" finds "Ctrl+Home". This search is not fuzzy.

Command Palette lists all internal CudaText commands, all plugin commands (prefixed with "plugin:"), all lexers (prefixed with "lexer:"), and currently opened files (prefixed with "opened file:"). Filter field allows to type hash symbol "#" followed by a letter, to make filtering by category:

• #p - plugins
• #l - lexers
• #f - opened files
• #r - recently used files

You can type those "hash tags" at begin or end of the field, even without separating space. E.g. "bar#p" will show only plugin commands containing "bar", "#f.md" will show only Markdown files (with .md extension).

Regular expressions

Lexer parser uses regex engine from EControl package. Groups must be referenced as \0 .. \9. It has custom features:

• classes \A, \Z: begin/end of document
• lookahead/lookbehind can find match of variable length
• modifier (?r): treat \w as all national characters too
• modifier (?g)

Search/replace uses TRegExpr engine (by Sorokin), its syntax is documented here: https://regex.sorokin.engineer/en/latest/regular_expressions.html . Groups must be referenced as $0 .. $9.

Change case on replaces

With regex, you can change case of found fragments, use modifiers in replace-with field:

• \l - First char to lower
• \L - All chars to lower
• \u - First char to upper
• \U - All chars to upper

E.g. if found a word, use replace-with field "\L$0" to change word to lowercase (here $0 is group 0, found text).

Modifiers affect only element after them, element is:

• one char (not string), so "\Uabc" and "\uabc" give same result "Abc" (only one char changed),
• or group $0 ... $9, so modifier changes case of this group (not only one char).

Snippets

To use snippets you need:

• plugin "Snippets" (install from Addon Manager)
• snippet package for needed lexer (install from Addon Manager)

Each 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".

Only 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.

Dialog of Snippets plugin:

Texts 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 #Markers.

Snippets for HTML tags

CudaText 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:

 <a href="http" title="Title" target="_blank"></a>

These snippets have markers, so Tab key jumps to the next marker. Last marker is usually placed after the entire tag, ie after ">" bracket.

Snippet Panel

Plugin "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).

Preinstalled folders:

• Arrows
• Currency symbols
• Greek alphabet (lower)
• Greek alphabet (upper)
• HTML - Arrows
• HTML - Color names
• HTML - Color names+values
• HTML - Letters
• HTML - Math symbols
• HTML - Special characters
• Math symbols
• Quote selection
• Special characters

Plugin looks for its folders in two places:

• Folder "clips" in the plugin folder.
• Folder CudaText/data/clips, which is absent by default, for custom user folders.

Each 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.

Output/Validate panels

These lists allow to highlight (e.g. in blue) lines which match some regex. This regex is set by plugin which uses these panels. E.g. plugin HTML Tidy uses panel Validate and sets regex for Tidy result lines. If a line matches regex and highlighted, dbl-click on line navigates to source file.

These panels have hotkeys:

• Up/Down/PgUp/PgDown/Home/End: move selection in list
• Enter: navigate to source file, like dbl-click
• Ctrl+Del: clear entire list
• Ctrl+C: copy to clipboard entire list
• Ctrl+D: copy to clipboard selected line
• Esc: focus editor

Dialogs Find/Replace

Find/Replace dialog has hotkeys, which work only inside this dialog. They can be customized via options "find_hotkey_nnnn".

• Alt+Enter: Find first
• Enter: Find next/ Replace next (depends of focused input)
• Shift+Enter: Find previous
• Ctrl+Enter: Add new line in multi-line input
• Alt+Z: Replace, and find next
• Ctrl+Alt+Z: Replace, and don't find next
• Alt+A: Replace all
• Alt+O: Count all
• Alt+E: Select all
• Alt+K: Mark all
• Alt+Q: Extract

Option buttons have hotkeys too. Hover mouse over them to see floating tooltips about button functions.

• ".*" - Regular expressions - Alt+R
• "aA" - Case sensitive search - Alt+C
• "w" - Search for whole words only - Alt+W
• "O" - Wrap search, ie search from beginning after reaching the end, and vice versa - Alt+N
• "[..]" - Search in selection only - Alt+X
• "+" - Toggle multi-line mode for both dialog input fields (to add a newline in multi-line fields, press Ctrl+Enter) - Alt+M
• "?!" - Show confirmation on each replace - Alt+Y
• "*" - Choose allowed syntax elements: Any / Only comments / Only strings / Only comments+strings / etc. This feature must be supported by lexer (and some lexers are limited, support only "comments" or only "strings" syntax elements). Syntax element is detected from left edge position of a found match.

Button "Find". It's visible if CudaText option "find_show_findfirst":true. It starts the search from document beginning, ignoring the caret position. While button "Find next" continues the search from caret position.

Button "Extract". It's visible if CudaText option "find_show_extract":true. It's enabled only with RegEx option, and it does the following: all found matches are put to a list, list is sorted, duplicates are discarded, and list is written to a new document. Plugin "Extract Strings" does the same task but using Python RegEx engine.

Button "Select all". It's visible if CudaText option "find_show_select_all":true. It finds all matches in a document and places multi-seletions on them.

Button "Mark all". It's visible if CudaText option "find_show_mark_all":true. It finds all matches in a document and places #Markers on them.

Button "Replace global". It's visible if CudaText option "find_show_replace_global":true. It performs replacement in all opened documents in all editor groups. After additional confirmation.

Second click on the "Search" sidebar button toggles dialog between Find and Replace modes.

Dialog "Go to"

Dialog allows to enter text in formats:

• 10 (decimal number): Jump to given line number (to line start)
• 10:10 (two decimal numbers): Jump to given line and column numbers
• 10% (decimal with trailing "%"): Jump to percents of total line count
• d100 (decimal with leading "d"): Jump to absolute decimal offset
• xFFF (hex number with leading "x"): Jump to absolute hex offset
• value with trailing "+": Extend selection to this position, ie, enlarge previous selection so it overlaps the new position

Also it is possible to show Go To dialog by clicking the statusbar's first cell.

Comments

You 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).

• Line comments: from some position to line-end. E.g. in C lexer: "//text here", in Python lexer: "# text here".
• Comments for range (Stream comments): from offset to another offset. E.g. in C lexer: "/* text here */".
• Comments for full lines: from newline to another newline. Rarely used, e.g. used in PowerShell.

For 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.

Comment 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.

Command "Toggle stream comment" in plugin adds/removes comments of last 2 types: for range, for full lines (plugin chooses needed kind).

Comment chars are saved:

• Line comments: in lexer file data/lexlib/nnn.lcf.
• Range comments: in files data/lexlib/nnn.cuda-lexmap.

Sessions

"Session" is a set of opened documents, with properties of each document. CudaText sessions are stored in JSON files with .json and .cuda-session extensions. Default session file name is "history session.json" in the "settings" folder. CudaText shows name of current session in its window title like "filename.txt {session_name} - CudaText".

Program has options:

• "ui_reopen_session": Save last session on closing, and restore it on start.
• "ui_auto_save_session": On program closing, save current session without asking.

If some session is opened, program stores document states, on program closing, to session file. If no session is opened, program stores document states to "history files.json" in the "settings" folder.

Session file contains data:

• List of named documents (file names), and unnamed documents
• For each document:
  • kind of document: text in editor, picture file, text in viewer (and viewer mode: text/binary/hex/unicode)
  • read-only state
  • caret position
  • encoding
  • word-wrap mode
  • lexer
  • bookmarks
  • index of top visible line
  • tab size and "tab as spaces" state
  • minimap and micromap visible state
  • ruler visible state
  • non-printable characters visible state
  • line numbers visible state
  • scale factor
  • list of folded ranges (if lexer supports folding)
  • color of ui-tab (if not default)
  • tab title (if not default)
  • modified state
  • code-tree filter string and history of last filters
• For each modified document: date of modification, full document text
• Layout/sizes of side panel and bottom panel
• Layout/sizes of editor groups
• Index of active editor group and active tab in each group

Plugin "Session Manager" is present in Addon Manager, it gives commands to control sessions: open session file, save session, show list of recent sessions, etc. Session Manager also supports files from SynWrite, with .synw-session extension.

Char map

Char-map dialog can be called in Edit menu. It has 2 modes:

• ANSI: Shows ANSI char codes from 0 to 255 (codes 128..255 map to different Unicode codes, this depends on active OS locale).
• Unicode: Shows almost all Unicode code points, they are divided to groups. Change active group using combobox at the bottom.

Click any cell in the grid to insert this char at caret position. Or select a cell with arrow keys and press Enter.

Tab switcher

CudaText has option "ui_tab_switcher_dialog", which activates modern tab switcher for Ctrl+Tab hotkey. This is dialog which allows to switch tab using visit history. For example: press Ctrl, Tab, Tab, Tab, release Ctrl: this goes 3 steps back in visit history. Visit history is updated on tabs activation (activated tab moves to the top of history).

Alternative way is plugin CudaExt. Plugin gives command "Choose tab to switch to". You need to assign hotkey Ctrl+Tab to this command (hotkey will be removed from CudaText command). Plugin's dialog is richer than CudaText's dialog - it allows to switch to Console/Output/Validate panels, it allows to cancel the operation.

Minimap

Minimap is wide vertical bar near editor's right side (it can be shown on the left side too, by the option). To show it:

• set the option "minimap_show" (show permamently)
• use menu item "View / Toggle minimap" (show temporary, for the current document only)

If you drag mouse over minimap, editor will scroll entirely from top to bottom, even for huge documents (mimics Sublime Text behaviour). Text in minimap is painted by 1-2 pixels per character, not by font rendering, so scale of minimap cannot be changed.

Micromap

Micromap is thin (about 12 pixels) vertical bar near editor's right side. It is not scrollable, it shows overview of entire document from top to bottom. To show it:

• set the option "micromap_show" (show permanently)
• use menu item "View / Toggle micromap" (show temporary, for the current document only)

Micromap shows tiny colored marks:

• wide+tall mark: current visible area of editor
• on the left side: line-states marks (#Line_states)
• on the right side: marks for selections (made e.g. by "Find / Select all", usually blue)
• on the right side: marks from Spell Checker plugin (usually red)

Plugins can place marks on micromap, e.g. plugin "Highlight Occurrences" places marks for highlighted fragments, plugin "Spell Checker" places marks for misspelled words.

Paste with middle-button-click

To paste like in Linux, with middle-click, you need

• set option "mouse_mid_click_paste"
• install plugin "Auto-Copy to Clipboard"

This activates auto-copy of selection (copy to clipboard after text selection changes), and paste to position of mouse cursor on middle-click. But it works only for "editor frame", and don't work for: Console read-only editor, single-line inputs. So this method is limited.

Full-screen

There are two menu items in the View menu:

• Toggle Full-screen. This maximizes app window (in a special way, OS-dependant, even OS taskbar hides), and also, optionally, turns off some UI elements: toolbar, statusbar, sidebar, side panels (Tree, Project, FTP), bottom panels (Console) etc. Option "ui_fullscreen" has set of chars, each char for one UI element to hide. E.g. option value "tp" hides 2 UI elements ("t" for toolbar, "p" for side panels).
• Toggle Distraction-free. Like full-screen, but all UI elements hide. No option currently to configure which elements.

Notes:

• On macOS full-screen modes hide top menu. To show it w/o returning back, just move the mouse cursor to the top of the screen and hold a little.

Python integration

Python on Windows

On Windows, Python engine (currently 3.6) is preinstalled. CudaText finds files "python3*.dll" in its folder, and uses file with the latest version number. No options are used to configure this.

You can use not only version 3.6. From CudaText's Addon Manager, install appropriate package, e.g. "Windows_Python37_64bit", and restart the program.

Python engine requires Visual C++ Redistributable for Visual Studio 2015 (32-bit or 64-bit, same as CudaText). Download it from Microsoft site.

Note for Windows 7. You also need the Update for Universal C Runtime in Windows (KB2999226). Download it from the Microsoft site.

Python on Linux, BSD, Solaris

Linux/*BSD/Solaris version uses Python library from OS. Install Python 3.x (usually already installed). Instruction, if Python library was not automatically used:

• Open file manager, go to /usr
• Search for "libpython3.*so*"

Or use the terminal command:

$ find /usr -name 'libpython3.*so*' 2>/dev/null

• If not found, install Python 3.x, and search again.
• Set option "pylib__linux" ("pylib__freebsd", "pylib__solaris") in the "user.json" config, to one of the found filenames. Write option to the "user.json" or course, not "default.json".

Typical value for Solaris 11.4 x86:

  "pylib__solaris" : "/usr/lib/amd64/libpython3.5m.so",

Python on macOS

On macOS you must install Python 3, from official site python.org. Versions 3.6...3.9 are ok. CudaText will detect this Python. CudaText has option "pylib__mac" with such default value (actual version number is auto-detected):

  "pylib__mac": "/Library/Frameworks/Python.framework/Versions/3.5/lib/libpython3.5.dylib",

If you use "virtualenv" from "conda" with isolated Python, CudaText cannot detect it, so you need to write to the user.json option "pylib__mac" by hands. Example:

  "pylib__mac": "/miniconda2/envs/py3/lib/libpython3.7m.dylib",

Line states

In the gutter bar, you can see colored thin bars next to line numbers: green, yellow. It is line states. They show state of lines:

• usual lines (not changed)
• changed lines
• newly added lines
• changed or added lines, and file was saved after it

Line states help to see which lines were edited since the last opening of a file / last saving of a file. CudaExt plugin gives few commands for line states:

• "Jump: to next/previous changed lines"
• "Jump: to next/previous working lines"
• "Jump: to next/previous saved lines"

Project Manager

This 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).

Plugin has context menu on its panel, with items:

• Project file
  • New project
  • Open project
  • Recent projects
  • Save project as...
  • Go to file... - this shows menu with all project files, and then tree-view selection jumps on selected file
  • Project properties... - this shows dialog with current project's options
  • Config... - this shows dialog with global Project Manager options
• Root nodes - commands for nodes on the project's root level
  • Add folder...
  • Add file...
  • Clear project
  • Remove node
• Selected file - it's shown only for files
• Selected directory - it's shown only for folders
• Refresh - it re-reads state of files/folders from disk

Any 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.

Project Manager shows file/folder icons, using default file-type-icons theme. You can change this theme in the plugin's Config dialog. But first, you must install additional file-type-icons theme from Addons Manager. Example of such theme: VSCode Material 24x24.

Preview tab

To see preview tab, call "File / Open folder" and choose a folder with text files. Folder will open in the side panel "Project". Make single click on files in this panel, they will open in "preview tab". Single preview tab is shared by all clicked files in "Project". It has italic caption. When you begin to edit file in this preview tab, tab becomes "normal".

Linters

CudaLint plugin allows to check correctness of documents in many syntaxes. It was initially ported from SublimeLinter 2.x plugin for Sublime Text. Each lexer must be supported with additionally installed linter, for example:

• JavaScript is supported with linter based on JSLint tool,
• HTML is supported with linter based on HTML Tidy tool,
• CSS is supported with linter based on CSSLint tool,
• etc

You will find all linters in the Addon Manager: "Plugins / Addon Manager / Install". Linters are installable like other plugins but they don't add commands, they only add folders "[CudaText]/py/cuda_lint_*", which are automatically used by CudaLint. After you install a linter, see readme in its folder, maybe how-to-use info is written there.

Linters - usage

To run linting, use menu item "Plugins / CudaLint / Lint", or set hotkey to this command (in CudaText Command Palette, press F9). You will see statusbar message, which tells how many errors linter found. For each found error, you'll see yellow/red bookmark (you can use usual commands for these bookmarks). Plugin also shows list of errors in the "Validate" panel (to show Validate panel, click V icon on the CudaText sidebar).

Linting can also be run by events:

• after opening file
• on saving file
• after text is changed + pause passed

Events aren't used by default (to not slowdown usual work). To use events, you must enable them in config. Call config by menu item in "Options / Settings-plugins".

Linters - Node.js

Some linters require Node.js, so for those linters, you must install Node first. Those linters are sometimes shipped with Node modules preinstalled (in plugin folder) and sometimes you need to install Node modules via NPM. See linter's readme file for details.

• Windows: "node.exe" must be in PATH, command "node -v" must work in console.
• Linux: "nodejs" package must be installed, command "nodejs -v" must work in terminal.

Linters - authoring

To support more lexers, it's a good idea to port linter from SublimeLinter. To port a linter, most you need is:

• 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.
• 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.
• 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.
• If linter was using Node.js, take some code to run Node, from cuda_lint_csslint linter.

Linters - per project

How 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:

linter_css=csslint

Variable 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".

In 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.

How to change icons

Screenshot with icons of main toolbar, sidebar, Project Manager toolbar:

• Icons in the main toolbar. To change them:
  • (Optional) Install add-on(s) of kind "toolbar theme" (each add-on gives additional icon set or several sets).
  • Change option "ui_toolbar_theme" in user.json. Option value is some subfolder in [cudatext]/data/toolbaricons.
  • Restart CudaText.

• Icons in the sidebar (vertical band on the left). To change them:
  • (Optional) Install add-on(s) of kind "sidebar theme".
  • Change option "ui_sidebar_theme" in user.json. Option value is some subfolder in [cudatext]/data/sideicons.
  • Restart CudaText.

• Icons in the Project Manager toolbar. To change them:
  • (Optional) Install add-on(s) of kind "proj toolbar theme".
  • Change option in the dialog: Options/ Settings-plugins/ Project Manager/ Config.
  • Restart CudaText.

• Icons in the Project Manager file list, and on file tab headers. To change them:
  • (Optional) Install add-on(s) of kind "file type icons".
  • Change option in the dialog: Options/ Settings-plugins/ Project Manager/ Config.
  • Restart CudaText.

Toolbar

CudaText has toolbar on the top, which can be shown by menu item "View / Toggle toolbar". To customize it, install plugin "Config Toolbar" from Addon Manager. Plugin gives command (menu "Plugins / Config Toolbar / Customize buttons") to customize toolbar contents: simple buttons, buttons with dropdown menus, separators, icons for buttons.

Plugin also gives command "Hide standard buttons" which allows to hide default CudaText buttons from toolbar. This command shows input box for space-separated indexes of buttons. What are these indexes? Indexes are 0-based numbers of all toolbar items: first button (New File) is index 0, next item (dropdown near New File) is index 1, next item (Open File) is index 2, etc (all separators also have index). So for example, to hide 3rd + 10th items, enter "2 9" into that input box.

File viewer

CudaText has internal file viewer, for files on unlimited size. Only visible portion of file is loaded into memory, so viewer is fast for all files. Viewer has several modes:

• Text: 1-byte encoding, variable line length
• Binary: 1-byte encoding, fixed width (line breaks are ignored)
• Hex: 1-byte encoding, fixed width
• Unicode: like Text, but in UTF-16 encoding
• Unicode/Hex: like Hex, but in UTF-16 encoding

CudaText suggests to use viewer for files of too big size (bigger than option "ui_max_size_open"). And for files with binary contents.

Viewer has simple search support (without reg.ex.), and allows to use "Go to" dialog. In the "Go to" dialog, you can enter "2000" to jump to hex offset 0x2000 (in hex mode, rounded to 16 bytes). If you enter "50%", viewer will jump to the middle. Viewer supports selection of block by mouse, and hotkeys Ctrl+A, Ctrl+C. Viewer supports double-click to select whole word.

In viewer mode, you can click statusbar fields:

• Encoding field. You can change viewer encoding only in non-Unicode modes.
• Mode field, to change view mode: Text, Binary, Hex, Unciode, Unicode/Hex.

Macros

Macro is a sequence of CudaText actions, which can be saved to a file and invoked later by some command. To use macros, you must install plugin "Macros" from Addon Manager. It adds "Macros" menu to CudaText main menu bar. This menu gives items:

• Macros...
• Start record
• Stop record
• Cancel record
• Export...
• Import...
• (items for saved macros)

To record a macro:

• call menu item "Macros / Start record", or use dialog "Macros / Macros..." which gives "Start record" button too
• pefrorm some action(s) in CudaText:
  • built-in commands, plugin commands (invoked by hotkey, by menu, by Command Palette)
  • some mouse actions (clicks/selections, they save/playback relative to caret position)
  • calling of Find/Replace dialog, "Go to" dialog
  • actions in Find/Replace dialog
• call menu item "Macros / Stop record" to save your macro, plugin will ask for macro name

Macro saves action(s) performed inside its original editor tab (not other tabs). And it doesn't save actions inside plugin dialogs (e.g. FindInFiles).

To playback macro:

• call menu item "Macros / (macro name)", the end of this menu lists all available/saved macros
• 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)

Pair brackets

CudaText has built-in pair bracket finder. Before that you needed the plugin Bracket Helper, and now plugin should not be used - it is much slower that built-in code. Bracket finder can highlight pair brackets, when there is only single caret, no selection. It finds symbols "()[]{}<>" (configurable per lexer). Bracket finder respects lexer context, it skips symbols inside syntax comments/strings. If caret is placed not directly on/after a bracket, program will find nearest surrounding brackets.

There are several options:

• "bracket_highlight"
• "bracket_symbols" (includes only symbols ()[]{} by default, but you can enable symbols <> for example in HTML lexer specific config)
• "bracket_distance"
• "auto_close_brackets"

There are several commands in the Command Palette:

• brackets: pair highlight: on
• brackets: pair highlight: off
• brackets: pair highlight: toggle
• brackets: jump to pair
• brackets: select to pair
• brackets: select to pair, inside (it makes selection smaller by 2 characters)

Word jump commands

CudaText provides several word-jump commands, see them in the Command Palette by entering "go to word":

• go to word next
• go to word next + select
• go to word next, simple
• go to word next, simple + select
• go to word previous
• go to word previous + select
• go to word previous, simple
• go to word previous, simple + select
• go to word end
• go to word end + select

"Go to word next" vs "Go to word end"? "...end" first jumps to the end of the current word (right word boundary), only after that it jumps to the next word start. "...next" always jumps to the next word start.

For example, Windows 7 Notepad performs "...next" on pressing Ctrl+Right, while Sublime Text 3 performs "...end" on pressing Ctrl+Right. To configure Ctrl+Right (and Shift+Ctrl+Right) behaviour, re-assign this hotkey from one command to another - press F9 in the Command Palette dialog.

"Go to word next" vs "Go to word next, simple"? "...simple" command performs simplified jump, it treats all alpha-numerical characters and symbols (#$%^&@ etc) as one group, so it makes single jump over "test@#some!" string. "Go to word next" treats alpha-numericals and symbols as different char groups, and stops at the beginning of each group.

Plugin CudaExt provides such related commands:

• Cuda-Ext: Jump: Left into CamelCase/snake_case
• Cuda-Ext: Jump: Right into CamelCase/snake_case

Sorting and finding duplicate lines

CudaText has two sorting methods.

Method 1: Python plugin "Sort", which supports Undo for its commands. It works not fast and takes lot of memory on sorting. It cannot sort huge files, because it reads all file contents from Pascal buffer to Python buffers.

Commands in menu "Plugins / Sort":

• Sort ascending
• Sort descending
• Sort ascending, ignore case
• Sort descending, ignore case
• Sort dialog... (shows all sorting options in dialog)
• Reverse lines
• Shuffle lines
• Remove duplicate lines
• Remove duplicate lines, but keep blanks
• Remove duplicate lines + origins
• Remove adjacent duplicate lines (ie nearest repeated lines)
• Extract duplicate lines (put duplicate lines to a new document)
• Extract duplicate lines, ignore case
• Extract unique lines
• Remove blank lines
• Remove adjacent blank lines
• Ini file: sort sections and keys
• Ini file: sort sections, but not keys
• Sort e-mail list by domain (lines should be valid email addresses to sort them by domain)

The advantage of "Sort" plugin is that is has additional commands (for duplicate lines, for ini files, for e-mails).

Plugin has config file, you can edit it via menu item "Options / Settings-plugins / Sort". In section [sort] you can change option "allow_all" to 0 or 1 to disable/enable sorting of entire document, if nothing is selected. If selection exists (single selection), plugin handles selected lines.

Method 2: Pascal-based sorting commands, which are named like "(without undo) Sort...". They clear current Undo (ie user cannot undo sorting operation), but they are optimized for speed and memory. Commands don't read document contents into additional buffers, they sort document in-place (changing pointers only). So they work with all files which CudaText can load.

Commands in Command Palette:

• (without undo) sort ascending
• (without undo) sort ascending, ignore case
• (without undo) sort descending
• (without undo) sort descending, ignore case
• (without undo) delete all blank lines
• (without undo) delete adjacent blank lines
• (without undo) delete all duplicate lines
• (without undo) delete adjacent duplicate lines
• (without undo) reverse lines
• (without undo) shuffle lines

Markers

"Markers" are text positions which are shown with red (color in default theme) triangles below them. CudaText gives such commands in the Command Palette:

• "markers: drop marker at caret": Adds a marker on current caret position.
• "markers: go to last marker (don't delete)": Moves caret to the last placed marker without deleting it.
• "markers: collect last marker (delete)": Moves caret to the last placed marker and deletes it.
• "markers: remove all": Removes all markers in the current document.
• "markers: swap caret and last marker": Moves caret to the last placed marker, deletes this marker, and adds marker on the previous caret position. Command is to jump to the last marker, second command call jumps back, 3rd command call jumps back, etc.
• "markers: select to last marker": Makes text selection from caret position to the position of last placed marker.
• "markers: delete to last marker": Deletes text from caret position to the position of last placed marker.

Markers are utilized by the Snippets plugin. Snippets plugin finds tab-stops in the inserting snippet text, and places markers for them. After markers are placed by Snippets plugin, Tab-key works special - it jumps to the next marker ("next" by the order of tab-stop: 1, 2, 3... tab-stop 0 is the last). When user "collects" all those markers by Tab-key, this special mode deactivates and Tab-key works as usual again. Command "markers: remove all" also deactivates that mode.

Dialog "Save tabs"

Dialog "Save tabs?" shows on CudaText closing, if at least one document is modified and not saved to disk. Dialog lists all modified file-tabs (usually one file per one file-tab, but it's allowed to have 2 files in a single file-tab). Checkmarks (all checked by default) are used to check/uncheck file-tabs which will be saved on pressing "Save" button. For untitled documents to be saved, program will show "Save as" prompts. Button "Don't save" closes dialog and program, loosing modifications. Button "Cancel" closes the dialog, but not the program.

CudaText has the option "ui_reopen_session". When it is true, dialog "Save tabs?" shows additional button: "Don't save / Keep in session", which doesn't save disk files, but stores modified documents to active "session" file. Program will read it on start.

Also CudaText gives the command "dialog: save tabs" in the Command Palette. It shows the same dialog, the difference is that buttons do not close the program.

External Tools

Several examples of external tools configs. Call dialog of External Tools plugin (menu "Tools / Config..."). Add a new tool. Set dialog properties as shown below. This must add menu item, for new tool, under Tools menu.

Tool to compile by GCC

You 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++".

Properties:

• Name: C - compile
• File name: gcc
• Shell command: unchecked
• Parameters: "{FileNameOnly}" -o "{FileNameNoExt}"
• Initial folder: {FileDir}
• Lexers: C,C++
• Capture output: Output panel
• Encoding: utf_8

Optionally, 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".

• Pattern: (?P<file>[^:]+):(?P<line>\d+):(?P<col>\d+): .+

Tool to run C program

Tool is for Linux, so "File name" don't have an extension. For Windows, change "File name" field to "{FileNameNoExt}.exe".

Tool will catch the program output in the Output panel, program text input will not work.

• Name: C - run
• File name: "./{FileNameNoExt}"
• Shell command: checked
• Parameters: (empty)
• Initial folder: {FileDir}
• Lexers: C,C++
• Capture output: Output panel
• Encoding: utf_8
• Pattern: (empty)

Tool to run C program, on Windows, with input in terminal

Tool is for Windows, it allows to run compiled C/C++ program in new console window. Text input will work in this console.

Example C++ program:

#include <stdio.h>
int main ()
{
  int c;
  puts ("Enter text. Include a dot ('.') in a sentence to exit:");
  do {
    c=getchar();
    putchar (c);
  } while (c != '.');
  return 0;
}

Tool props:

• Name: C - run
• File name: cmd
• Shell command: unchecked
• Parameters: /K "{FileNameNoExt}.exe"
  • Alternative value: /C "{FileNameNoExt}.exe" && pause
• Initial folder: {FileDir}
• Lexers: C,C++
• Capture output: Ignore
• Encoding: utf_8
• Pattern: (empty)

Tool to run C program, on Linux, with input in terminal

Tool is for Linux, it allows to run compiled C/C++ program in new terminal window. Text input will work in this terminal window.

Example C++ program:

#include <stdio.h>
int main ()
{
  int c;
  puts ("Enter text. Include a dot ('.') in a sentence to exit:");
  do {
    c=getchar();
    putchar (c);
  } while (c != '.');
  return 0;
}

Tool props:

• Name: C - run
• Variant for xterm:
  • File name: xterm
  • Parameters: -hold -e "./{FileNameNoExt}"
• Variant for gnome-terminal:
  • File name: gnome-terminal
  • Parameters: -- bash -c "./{FileNameNoExt}; read -s -n1 -r -p 'Press any key... '; echo"
• Shell command: unchecked
• Initial folder: {FileDir}
• Lexers: C,C++
• Capture output: Ignore
• Encoding: utf_8
• Pattern: (empty)

Tool to compile+run C program

In the External Tools dialog, press Join button, to join 2 tools created in above steps. Properties of joined tool:

• Name: C - make+run
• Series: C - compile; C - run
• Lexers: C,C++

Tool to run current Batch file

Tool properties:

• Name: Run batch file
• File name: cmd.exe
• Shell command: unchecked
• Parameters: /c "{FileName}"
• Initial folder: {FileDir}
• Lexers: Batch files
• Capture output: Output panel
• Encoding: the same as file's encoding: e.g. utf_8 or cp1251 (cp1251 is Russian ANSI codepage)

Tool to call file-compare utility

Tools, which call file-compare utility, to compare 2 files: active files in group-1 and group-2.

WinMerge, KDiff, Kompare

• Name: Compare files in G1, G2
• File name: (full name of executable file)
• Shell command: unchecked
• Parameters: "{FileName_g1}" "{FileName_g2}"
• Initial folder: (empty)
• Capture output: Ignore

Meld

• Name: Compare files in G1, G2
• File name: (full name of executable file)
• Shell command: unchecked
• Parameters: --newtab "{FileName_g1}" "{FileName_g2}"
• Initial folder: (empty)
• Capture output: Ignore

diff

• Name: Compare files in G1, G2
• File name: diff
• Shell command: unchecked
• Parameters: -Nau "{FileName_g1}" "{FileName_g2}"
• Initial folder: (empty)
• Capture output: Copy to new document

Tool to run Python scripts

Tool uses Python 3 installation on Linux. For Windows, change "File name" field to the full path to "python.exe" file. Also on Windows you may need to toggle checkbox "Shell command".

• Name: Python3
• File name: python3
• Shell command: unchecked
• Parameters: "{FileNameOnly}"
• Initial folder: {FileDir}
• Lexers: Python
• Capture output: Output panel
• Encoding: utf_8
• Pattern: \s*File "(?P<file>.+)", line (?P<line>\d+)

Tool to open PHP documentation with given topic

Tool 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.

Before 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.

Download PHP documentation in .chm format from PHP.net, google for "php_manual_en chm", it is 16M file.

Tool properties:

• Name: PHP Help
• File name: keyhh.exe
• Shell command: unchecked
• Parameters: -MyHelp -#klink {CurrentWord} "C:\Work\php_manual_en.chm"
• Initial folder: (empty)
• Lexers: PHP
• Save before: Nothing
• Capture output: Ignore

Tool to open AutoIt documentation with given topic

Tool 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.

With AutoIt installed, you also have .chm documentation, its path is usually "C:\Program Files (x86)\AutoIt3\AutoIt.chm".

Tool properties:

• Name: AutoIt Help
• File name: keyhh.exe
• Shell command: unchecked
• Parameters: -MyHelp -#klink {CurrentWord} "C:\Program Files (x86)\AutoIt3\AutoIt.chm"
• Initial folder: (empty)
• Lexers: AutoIt
• Save before: Nothing
• Capture output: Ignore

Tool to open .chm documentation for all lexers

See above example about tool for PHP documentation. Create the similar tool

• File name: keyhh.exe
• Shell command: unchecked
• Parameters: -MyHelp -#klink "{CurrentWord}" "{AppDir}\..\Docs\{Lexer}.chm"
• Lexers: (empty)

This 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.

URL for Google search

This is URL, not tool. In the External Tools dialog, press URL button, then press Add to add a new URL.

• Name: Google find
• URL:

http://google.com/search?q={SelectedText|q}

Tool to open folder of current file in Windows Explorer

Tool properties:

• Name: Open cur dir in Explorer
• File name: explorer.exe
• Shell command: unchecked
• Parameters: {FileDir}
• Initial folder: {FileDir}

Tool to go to current file in FreeCommander

• Name: Go to file in FreeCommander
• File name: path\to\FreeCommander.exe
• Shell command: unchecked
• Parameters: "/L={FileName}" /C
• Initial folder: {FileDir}

Tech topics

Python API

Separate big page about Python API is CudaText API.

Program perfomance

Startup time

CudaText starts quite fast: about 0.3 sec with about 30 plugins, on Linux, on CPU x64 Intel Core i3 3Hz. If no additional plugins are installed, or Python engine is disabled (ie not configured on Unix, or Python DLL files are deleted on Windows), then it starts even faster. If configuration/history are clean, it starts faster.

Perfomance of loading huge files

It's interesting how fast Linux editors open huge log files. Test file has about 300M size, 4M ASCII lines, it's created by Python script:

f = open("a.log", "w")
for n in range(4*1000*1000):
    k = 120-n%100
    f.write(str(n+1)+' '+chr(k%26+ord('a'))*k+'\n')

PC is HP Pavilion g6, CPU AMD A10 x64, 4 cores, RAM 8G, Ubuntu 18.04. Each time is average of 2-3 tries in the same session.

• CudaText 1.98: 9 sec.
• Sublime Text 3.2: 11.5 sec.
• Geany 1.32: 6.5 sec., jump to end: additional 4-5 sec.
• Kate 17.12.3: 7 sec.
• gedit 3.28.1: 1 min 10 sec.
• Vim 8.0, NeoVim 0.2.2: 3 sec.
• Emacs GUI 25.2.2: 2 sec., after showing confirmation for big file
• Bluefish 2.2.10: 24 sec.

Perfomance on huge lines

It's interesting how some Linux editors handle huge lines. Tested several editors on Ubuntu 19.10 on Intel i3 CPU. With XML file with a single line of length 4M. XML file contains line like <id name="nnnnnnnnnnnnnnn"> with the huge "name" value of 4M.

Python script to generate test file:

#!/usr/bin/python3
f = open("a.xml", "w")
f.write('<id name="')
for n in range(1, 4096):
    f.write("n" * 1024)
f.write('">\n')

• CudaText 1.96. Opens file: 1.5sec. Caret moves at the end of line: very fast (<0.1sec). Editing of this line: adding each char is about 0.5sec.

• Sublime Text 3.2. Opens file: 2sec. Caret moves at the end of line: each Left/Right arrow is 0.5sec delay. Editing of this line: not fast.

• Geany 1.35. Opens file: about 10sec, then for next 5-10sec I cannot place caret by mouse, then it works. Caret moves at line begin: fast, caret moves at line end: slow (delay 0.5sec after each Left/Right key). Editing at the end: adding each char is about 6sec.

• Kate 19.04. Gives colored panel "The file ... was opened and contained lines longer than ... The lines were wrapped and document is set to read-only mode...". Caret moves at the end of wrapped doc: fast. Editing is disabled.

• gedit 3.34. Hanged on opening file (from command line and from editor), waited it for 20sec.

• Vim 8.0. Opens file: 2-3sec. In word-wrapped mode. Caret moves at the end of line: each Left/Right command (Vim hotkeys) is 2sec delay. Editing of this line: adding each char is about 3sec.

• Emacs 26.3 GUI. Opens file: 1sec. In word-wrapped mode. With the statusbar error "Internal error in rng-validate-mode triggered at buffer position 10. Stack overflow in regexp matcher". Pressing Ctrl+End to move to end: editor hanged with "wait" cursor.

• Bluefish 2.2.10. On opening file, gives the warning about too long lines, on choosing "don't split lines" it hanged, waited for 30sec.

Perfomance of built-in sorting

Test on ~100M text file with short ASCII lines. Test on Ubuntu 19.10 on Intel i3 CPU.

CudaText 1.97:

• sort time: 18sec
• sort time with ignoring case: 19sec
• memory used after file loading: ~1.0G
• peak memory used on sorting: the same (inplace sorting in the same list)

Sublime Text 3.2:

• sort time: 14sec
• sort time with ignoring case: 16sec
• memory used after file loading: ~1.3G
• peak memory used on sorting: ~3.3G

How to compile program

There is Linux script CudaText_up https://github.com/Alexey-T/CudaText_up - it downloads all sources into ~/cudatext_up, then calls Lazarus (at least 1.8.4) to compile them. You can use it with FPC cross-compilers, installed from FpcUpDeluxe, script will compile CudaText for any of available platforms. Without cross-compilers, script makes CudaText only for the current platform. It puts result to ~/cudatext_up/bin.

And here is the old way to compile:

• install FPC and Lazarus:
  • download FpcUpDeluxe. On Windows, you must unlock .exe file in the Windows Explorer dialog. https://github.com/newpascal/fpcupdeluxe/releases
  • in FpcUpDeluxe, choose FPC 3.0.4 or "trunk", and Lazarus 2.0.4 or "trunk", install them both.
• download GitHub repos:
  • https://github.com/Alexey-T/Python-for-Lazarus (install first)
  • https://github.com/Alexey-T/ATFlatControls
  • https://github.com/Alexey-T/EncConv
  • https://github.com/Alexey-T/ATSynEdit (install after ATFlatControls and EncConv)
  • https://github.com/Alexey-T/EControl (install after ATSynEdit)
  • https://github.com/Alexey-T/ATSynEdit_Ex (install after EControl)
  • https://github.com/Alexey-T/ATSynEdit_Cmp
  • https://github.com/Alexey-T/ATBinHex-Lazarus
  • https://github.com/Alexey-T/Emmet-Pascal
  • https://github.com/Alexey-T/CudaText (no package here, only project)

• install .lpk packages into Lazarus (find all .lpk files, open them in IDE, install from Packages dialog)
• in the Lazarus component palette, you should see:
  • "AT Controls" tab: TATButton, TATButtonsToolbar, TATListbox, TATScroll, TATSynEdit, TATLabelLink, TATGauge
  • "Python" tab: several items
• in Lazarus, open "cudatext.lpi" project, compile it

How to install plugins from GitHub

First, you need to know GitHub repository (repo) URL of plugin. For example, https://github.com/kvichans/cuda_find_in_files . If you have plugin already, then you can see this URL in the plugin's install.inf (line "homepage=").

Next, call CudaText menu item "Plugins / Addons Manager / Install from GitHub". Enter URL in the suggested dialog. Addons Manager will install latest version from GitHub "master" branch.

How to simply install many add-ons

• In the dialog "File / Open file", you can multi-select files in list - with Ctrl+click (on Windows) or Shift+arrows.
• Use command "Plugins / Addons Manager / Download all", which saves all addons zip files to some folder. When done, install many addons from this folder using "File / Open file" multi-selection.
• To download without SourceForge lags, use this page: http://totalcmd.net/plugring/CudaText_addons.html , but page is updated not often.

How to make translation

Translation template-file is in dir "data/lang". How to make translation zip package:

• make file "nn_NN.ini" (utf-8 with bom)
• use standard locale names in filename, e.g. ru_RU pt_PT ja_JP (needed for plugins which uses Python translation API)
• write your contacts in first commented lines. Comments must begin with ";" at line start. Also you can add other comments.
• to set accelerator-chars for menus/dialogs, use "&" char (e.g. "Open &file"). If needed "&" as is, write "&&".
• note: Linux Ubuntu font is 1.3x times wider (than WinXP)

• make "install.inf" with such text:

[info]
title=LangName translation (by AuthorName)
type=cudatext-data
subdir=lang

• make zip file "translation.nn_NN.zip" with files nn_NN.ini, install.inf
• test this zip: open it in CudaText, and check it's installed
• publish zip at CudaText forum or https://github.com/Alexey-T/CudaText/issues
• if package ok, it will be at SF.net downloads, and in Addon Manager

How to make translation of Plugins menu

CudaText supports translation of Plugins menu items. For example, you have plugin with module cuda_nnn, which has "install.inf" with such menu items:

[item1]
...
caption=MyPlugin\ItemOne
...
[item2]
...
caption=MyPlugin\SubMenu\ItemTwo
...

Then you need to create files like "ru_RU.ini" in the folder "data/langmenu/cuda_nnn". Create folder "langmenu" inside "data" if it's absent. Files must be in UTF-8 no BOM encoding. They must have section "menu". All items in the ini-file are optional.

[menu]
MyPlugin=local name
ItemOne=local name of item
ItemTwo=local name of item
SubMenu=local name of menu

To distribute those translation(s), make zip file like "langmenu.MyPlugin.zip", which must have "install.inf" and folder "cuda_nnn" (you can put more folders, for several plugins, if you want so). Install.inf contents:

[info]
title=Translation of menu items of MyPlugin
type=cudatext-data
subdir=langmenu

Submit that zip file to CudaText GutHub page, or post it to the forum.

Color themes

Two kinds of themes exist:

• UI themes, file extension .cuda-theme-ui
• Syntax themes, file extension .cuda-theme-syntax

Two dialogs allow to paint these kinds of themes. To paint a theme:

• Call dialog: "Options/ Settings - more/ Settings - theme - nnnnn"
• For UI themes: customize colors in dialog
• For syntax themes: customize lexer-styles in dialog
• For syntax themes: test theme at last on JS/HTML/CSS/C/Pascal/Ini/Markdown/Go lexers.
  • You can use sample codes in the Lexer Properties dialog.
  • You can use sample files from https://github.com/Alexey-T/lexer_tests/tree/master/test_CudaText_color_themes
• New theme files are saved in the subdir "data/themes"

Don't configure custom lexer styles in Lexer Properties dialog, if option "ui_lexer_themes" is on, because syntax-theme will override all your colors from that dialog. You can config these colors though, if option is off.

How to make theme package

• Make such file "install.inf":

[info]
title=MyName UI theme (by AuthorName)
type=cudatext-data
subdir=themes
homepage=https://github.com/nnnn/pppp

• Make zip file "theme.MyName.zip" with files "MyTheme.cuda-theme-nnnnn" and "install.inf"
• Test zip file: open zip file in CudaText, confirm installation
• Publish file at forum or https://github.com/Alexey-T/CudaText/issues

How to see all UI theme items

• "editor, font" - color of font when no lexer is active. Click statusbar field with lexer-name, call "none".
• "editor, disabled state, font/bg" - editor shown with this bg-color when Replace dialog runs action, with option "confirm on replace" (during confirm message editor is disabled), if no lexer active
• "statusbar alt" - shown on 2nd statusbar, run in console:

  msg_status_alt('dd', 8)
  

• "search progressbar" - to see it, call Replace dlg, with regex, with confirmation (2 options in Replace dlg), replace "." (any char) to "www"

• "editor, marked range bg" - shows for marked-range, to set marked range from line 5 to 10 use console:

  ed.set_prop(PROP_MARKED_RANGE, '5,10')
  

• "editor, markers" - to see markers, call Commands dlg (F1), command "drop marker at caret".
• "editor, separator lines" - lines show eg for lexer Pascal, above "function"/"procedure".

• "listbox, ..." - call Commands dlg (F1 key)
• "listbox, ..., auto-complete..." - call C or Pascal lexer, then press Ctrl+Space to call auto-completion (listbox has 3 columns, 3rd shows not for all items)

• "splitters, main" - shown near Sidebar (vertical) and above Bottom panel (horizontal)
• "splitters, groups" - shown between groups (vert/horz), activate 2-3 groups using "View" menu

Meaning of syntax-theme elements

• Id: Normal id (identifier) or text.
• Id1: Special id, used e.g. for class names (when it is mixed-case id) or const names (when it is upper-case id).
• Id2: Special id, used e.g. for syntax constants (true, false, null...) and standard functions (sin, abs, max...).
• Id3: Special id, used e.g. for measurement units (mm, Kb, px...) and preprocessor directives.
• Id4: Special id, rarely used, e.g. Python uses it for function names after "def".
• IdKeyword: Special id, used for syntax keywords.
• IdVar: Variables, e.g. $name in PHP and Bash.
• IdBad: Incorrect/misslepped id.
• String: String literals.
• String2: String literals, used e.g. for RegEx constants.
• String3: String literals, one more kind, rarely used.
• Symbol: Non-word symbols, ie brackets/punctuation/etc.
• Symbol2: Non-word symbols, used when syntax needs another style for e.g. assignment/math operators.
• SymbolBad: Incorrect non-word symbols.
• Comment: Comments.
• Comment2: Comments, used when syntax needs another style of comments, e.g. shebang in Bash.
• CommentDoc: Documentation comments, ie comments which are parsed by special tools.
• Number: Numbers (decimal, hex, octal, floating...).
• Label: GoTo operator labels, or another special id.
• Color: Color constants, like #RRGGBB in HTML/CSS.
• IncludeBG#, SectionBG#: Styles which have background color set, and foreground color unset (none). Used to highlight function blocks, sub-lexer blocks, parts of a file, etc.
• BracketBG: Style with background+foreground colors. Used to highlight paired brackets, begin/end keywords, repeat/until keywords (when "dynamic highlighting" option is on) etc.
• CurBlockBG: Style with background color set, foreground color unset. Used to highlight block under caret, when "dynamic highlighting" option is on.
• SeparLine: Color of horizontal 1-pixel separator lines. Was used before in Pascal, for lines above functions.
• TagBound: HTML tags: angled brackets.
• TagId: HTML tags: tag names.
• TagIdBad: HTML tags: incorrect tag names.
• TagProp: HTML tags: properties/attributes of tags, before "=" char.
• TagPropBad: HTML tags: incorrect props/attrs of tags.
• TagInclude: Tags used for inclusion of sub-lexer blocks. Used e.g. in PHP, <? ?>.
• LightBG#: Styles with bright background color, and normal foreground. Used e.g. in Diff to highlight deleted (LightBG1) / changed (LightBG2) / added (LightBG3) text blocks.
• Pale#: Styles with pale (barely visible) foreground color. Rarely used.
• TextBold: Style with bold font.
• TextItalic: Style with italic font.
• TextBoldItalic: Style with bold+italic font.
• TextCross: Style with crossed/strikeout font.

How to use on Windows XP

Q: I have Windows XP, what version of CudaText and Python should I have?

A: You need CudaText 1.86 or newer, and older Python 3.4 files. Currently Addon Manager contains packages for Python 3.5 and 3.7, but not for 3.4. Make the package using examples: https://sourceforge.net/projects/cudatext/files/addons/packages/ . No option is needed to configure CudaText for Python 3.4, but you need to delete all newer Pythons from CudaText folder.

How to copy word under caret to clipboard

A1: Install "Macros" plugin. In its dialog start recording a macro, and call these commands using "Command Palette":

• command "selection: select words at carets"
• command "clipboard: copy"
• command "selection: cancel selection"

Then assign a hotkey to this macro (in the "Command Palette", find your new macro and press F9).

A2: Plugin "CudaExt" has commands:

• plugin: CudaExt: Copy word or [expression] or 'expression' without selection
• plugin: CudaExt: Replace word or [expression] or 'expression' with clip

It's good to use these commands with hotkeys Alt+Left and Alt+Right (assign it in the "Command Palette").

Unix specific topics

Linux keyboard input is duplicated

This is known problem, related to some Input Methods (IM) in Linux. To see what is your active IM, open Terminal and enter:

echo $GTK_IM_MODULE

Known IMs with problems: scim, xim. To fix: change IM from e.g."XIM" to "none" in the Language Support settings, then chars should not duplicate.

How to use middle-click paste on Linux

• Set option "mouse_mid_click_paste" to true (in user.json).
• Consider to install plugin "Auto-Copy to Clipboard", which emulates Linux editors behaviour: copying to clipboard by simple text selection (no need to use hotkey Ctrl+C).
  • This plugin has options to copy selection to a) usual clipboard, b) GTK primary selection (CudaText GTK builds only)

Linux installation

On Linux you can install program, not using installers, in such way:

• copy file "cudatext" to folder /usr/bin
• copy dirs [data, readme, settings_default] to "~/.config/cudatext"
• dir "~/.config/cudatext/settings" will appear automatically on run

If program runs and cannot find "data/lexlib" near executable, it opens dirs from "~/.config/cudatext". This allows to install binary to PATH, and data dirs to homedir.

Linux Qt build

For CudaText Qt5 version, library libQt5Pas is required.

• For Ubuntu:

$ sudo apt install libqt5pas-dev

• For Fedora:

$ sudo yum install qt5pas

App cannot run on FreeBSD

If you run app in Terminal, you'll see an error about missing .so file. Reason of this error: FreeBSD version was compiled on Linux with different .so files. To fix error, run command in Terminal:

$ sudo ln -s /usr/local/lib/libiconv.so.2 /usr/local/lib/libiconv.so.3

How to select extra symbols by double-click

Some languages consider special symbols as word-chars. For example, in PHP, "$" symbol is part of a variable name, so double-click should select "$" together with other word-chars. Follow these steps to add extra symbols (e.g. "$") to word-chars.

• Open new file-tab, activate your lexer (click the lexer-cell in the statusbar)
• Call menu item "Plugins / Options Editor"
• In the Options Editor dialog:
  • Select item of option "nonword_chars", read the description about this option in the bottom
  • Your lexer name must be pre-selected in the combobox on the dialog bottom
  • Check the checkmark "For: lexer", so that your option will go to the lexer-specific config
  • Enter new value of the option "nonword_chars" now. Copy/paste the value from the "Default" field, and remove some special symbols from that value.
  • Press Enter-key in the input field. Value must appear in the list of options in the "Lexer" column.
• Close Options Editor, restart the program

What does this procedure do? It creates (or modifies) file "[CudaText]/settings/lexer LexerName.json" to be like this:

{
  "nonword_chars": "-+*=/\\()[]{}<>\"'.,:;~?!@#%^&|`"
}

How to upgrade but keep all the settings

• Q: CudaText for Windows. How can I upgrade but keep all the settings the way I have configured them - including themes, icon sets, etc (basic settings I could just copy the settings file over - but I'm not sure what to do for the icons and the rest...)

• A: Copy all files from the zip package, overwriting old files. All user settings are located in "settings" (which is absent in the zip package) and "data" (in different files). If you did not modify CudaText preinstalled files, you will not loose any settings.

How to customize top menu and context menu

Plugin "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:

,{"cap":"&Save", "cmd":"cmd_FileSave"}

How 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.

How 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 there find needed Python functions names. Then write item like this:

,{"cap":"Toggle line comment", "cmd":"module=cuda_comments;cmd=cmt_toggle_line_body;"}

Here "cuda_comments" is folder name, and "cmt_toggle_line_body" is Python function from install.inf.

How to help the author to reproduce a bug

Bugs are often cannot be reproduced on author's PC because of different "user config", "lexer-specific configs", plugins configs. To help the author, make the ZIP file with CudaText folder, add your test file(s) there too, and send this ZIP to e-mail support(@)uvviewsoft.com .

What CudaText folder to pack?

• On Windows: the folder where you copied the program. Exclude files EXE DLL PYD ZIP from ZIP.
• On macOS: ~/Library/Application Support/CudaText.
• On Linux, other Unixes: ~/.config/cudatext, or $XDG_CONFIG_HOME/cudatext if this OS variable is set.

Make the bug reproducable on your CudaText folder on your test file(s). Put your test file(s) in ZIP too. If needed to reproduce the bug, create the session using Session Manager plugin (bug may be visible only with some session). Put session file in ZIP too (usually it's already in the "settings" subfolder).

Why column selection looks weird sometimes

When full-width characters (CJK or other Unicode) are present in text, column (vertical) selection may look weird. Here is an example picture where starting lines are ASCII and ending lines have full-width characters.

It is not a bug. In this example, user selected column block from column 7 (at line 1) until column 20 (at line 6), so column block takes columns 7...20 from all lines. On first ASCII lines, columns 7...20 take different visual area, than columns on last lines. When you copy/paste that block to another program, block may look differently. But that block contains equal number of chars on each line.

Even more weird look happens when user selects column block over word-wrapped lines.

Here is the program's logic in all these cases (with full-width characters and with word-wrapped lines). Program calculates (line1, column1) text position of column block left-top edge. Then program calculates (line2, column2) text position of column block right-bottom edge. Then program selects characters in range column1...column2 in all those affected lines line1...line2. And this program logic produces so weird look in word-wrapped mode.

How to replace from/to text containing line-breaks

There are several ways to perfrom it:

1. The simplest way: set multi-line mode in the Find/Replace dialog, using "+" button. Input fields will become tall and multi-line. To enter line-breaks there, press Ctrl+Enter.

2. Use plugin CudaExt:

• Select fragment in editor (can contain line-breaks), "what to replace" .
• Copy to clipboard the fragment (can contain line-breaks), which will be "replacement".
• Call command in CudaExt plugin: "Replace all occurrences of selected string with clipbrd".

3. Search for selected editor text (can contain line-breaks) using command "find current selection, next".

4. Copy fragment (can contain line-breaks) which you need to find, to clipboard. Call command in CudaExt plugin: "Find clipbrd: next".

Formats of files

Format of auto-completion acp file

Common auto-completion file format is ANSI text file, it contains list of lines in forms:

Type Id |Hint
Type Id (Param1; Param2; ...) |Hint
Type Id (Param1; Param2; ...): ResultType |Hint

• 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.
• Both ";" and "," chars can be params delimiters. "|Hint" part is optional.
• If "\" char is present in hint part, then it must be escaped: "\\".
• If space is needed in id part, it must be written as "%20" (it's allowed for any char in range 0x20..0x2F).

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:

#chars .-#

Format of install.inf files

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.

• "title" field (required)
• "desc" field, long text for install prompt dialog
• "type" field (required) must be one of:
  • cudatext-plugin: to install plugin to subdir of "py" dir
  • cudatext-data: to copy any files into subdir of "data" dir
  • lexer: to install lexers (zip must be made by SynWrite's ExLexer addon)
  • lexer-lite: to install lite lexer

• "subdir" field (required)
  • for plugins it should begin with prefix "cuda_"
  • for lexers it should be "-"
• "homepage" field, source code repository URL (usually on GitHub)
• "api" field, optional, minimal required API version (3 numbers dot-separated)
• "os" field, optional, comma-separated list of supported platforms, described below

Install.inf supported "os" values

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.

OS names are:

• win
• linux
• macos
• freebsd
• openbsd
• netbsd
• dragonfly
• solaris
• haiku

CPU families are:

• i386
• x86_64
• arm
• aarch64
• sparc
• ppc
• ppc64
• mips

So for example Windows x86 platform values are "win" and "win-i386", Linux AMD64 platform values are "linux" and "linux-x86_64".

Install.inf for plugins

Example of install.inf for plugin (plugin adds 2 menu items with menu separator between):

[info]
title=MyName
desc=Plugin allows smth
type=cudatext-plugin
subdir=cuda_test
homepage=http://github.com/some/name/
api=1.0.200

[item1]
section=commands
caption=MyPlugin\Cmd one
method=run
lexers=CSS,HTML
hotkey=Alt+F

[item2]
section=commands
caption=MyPlugin\-
method=nnnn

[item3]
section=commands
caption=MyPlugin\Cmd other
method=run_more
menu=0

Section names: "item" followed by any string (e.g. "item1"). Fields in sections:

• "section": possible values are "commands", "events".
• "caption": caption of menu item in Plugins menu. "\" separates menu levels. "&" makes accelerator hotkey. "-" as final level name, makes separator menu item.
• "method": Python method name in Command class.
• "lexers": comma-separated lexer names, means that command can be run only when such lexer(s) active.
• "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").
  • If "lexers=" param missed, then hotkey saves to file "keys.json" for all lexers.
  • If "lexers=" param present, then hotkey saves to "keys lexer NNNN.json" for each mentioned lexer.
• "menu": optional. Possible values:
  • "" (empty, default): menu item will be put to "Plugins".
  • "0": hide menu item.
  • "o": menu item will be put to "Options / Settings-plugins".
  • "op": menu item will be put both to "Plugins" and "Options / Settings-plugins".

Only for "section=events":

• "events": comma-separated list of events to handle in plugin, e.g. "events=on_change,on_caret".
• "keys": supported only for several events:
  • 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).
  • for "on_open" / "on_open_pre": comma-separated list of lower-case file extensions, without leading dot, to handle in event.

Install.inf sidebar buttons

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:

• "hint": Tooltip of button, must be the same as used by plugin to create its button.
• "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.
• "method": Python method name to show plugin panel. This command should create side panel for this button.

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.

Install.inf lexer lists

If plugin has many [itemN] sections, it is possible to set list of lexers using vairable (not to write each time "lexers=name,name2,name3"). Declare list of lexers in [info] section like this, any variable name:

[info]
$var=Name1,Name2,Name3

In [itemN] sections set lexers like this:

[itemN]
lexers=$var

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:

[info]
$var=regex:.*SQL.*

Install.inf for data files

Example of install.inf for data files, to be copied into subdir of "data" dir. Name of subdir can be any, for example "themes".

[info]
title=NiceDarkTheme
desc=Nice Dark theme (by AuthorName)
type=cudatext-data
subdir=themes

Install.inf for lexers

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.

[info]
title=HTML Smarty
type=lexer
subdir=-

[lexer1]
file=HTML Smarty internal
[lexer2]
file=HTML Smarty
link1=CSS
link2=VBScript
link3=JavaScript
link4=JavaScript
link5=VBScript
link6=PHP
link7=PHP
link8=HTML Smarty internal

Install.inf for lite lexers

Example of install.inf for lite lexer. Note that "^" suffix not needed here.

[info]
title=MyLexer
type=lexer-lite
subdir=-

Format of snippet files

Snippets tab-stops

Specify tab-stops in the snippet text like this:

• ${NN}
• ${NN:default text}

This places markers (AKA tab-stops) in the editor, marker index NN should be from 0 to 40. After snippet insertion, tab-key goes to next marker(s) and deletes it.

• Markers can be listed in any order (e.g. marker 4 can be between 1 and 2).
• Tab-key first goes to marker 1, 2, 3... and marker 0 is always the last.
• Markers with the same indexes will place multi-carets.
• Nested markers (with default text) are allowed, but only with one nesting level, e.g. ${2:text is {$3:here}}.
• Marker with default text ${NN:...} can specify multi-line default text (character "}" is on another line of snippet).

Snippets macros

Special "macros" are handled by Snippets plugin in snippet text:

• ${sel} - Replaced with text selected before snippet insertion. (If snippet called with Tab key, it's empty string.)
• ${cp} - Replaced with clipboard text.
• ${fname} - Replaced with current file name (w/out path and extension).
• ${date:nnnnnn} - Replaced with current date/time formatted by string nnnnnn. See Python doc.
• ${cmt_start} - Replaced with current lexer's "block comment" start symbols (or empty string).
• ${cmt_end} - Replaced with current lexer's "block comment" end symbols (or empty string).
• ${cmt_line} - Replaced with current lexer's "line comment" symbols (or empty string).

Snippets file names

Snippets are stored in separate files with extensions:

• .cuda-snippet or .synw-snippet: main format.
• .cuda-snips: compact format for collections of tiny snippets.

Encoding 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 recommented to name subfolders like AuthorName.SyntaxName, so users can easily find newly installed snippets.

Format of .cuda-snippet

First lines have format "key=value" (no spaces around "="), where "key" is one of strings:

• "name": snippet full name, shown in dialog.
• "id": snippet short alias for Tab-key (latin letters, digits, "_.$"), line is optional.
• "lex": lexers list, comma-separated, for which snippet is active, line is optional, empty means snippet always active.

Then follows the line "text=" without value, and all next lines - are snippet contents.

• Trailing blank lines are discarded.
• Use tab-chars in text indents, they are auto replaced to spaces if current editor configured so.

Format of .cuda-snips

File contains one or several lines, one snippet per line. Empty lines, lines starting with "#" or space, are ignored. Format of lines:

• id text
• /N=name text
• id /N=name text
• id /L=lexers text
• id /L=lexers /N=name text
• id /L="lexers" /N="name" text

Here "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).

Format of .cuda-lexops files

Files keep lexer styles, which user changed in the "Lexer Properties" dialog. JSON format.

Root keys:

• "files": str: space-separated list of file masks for lexer. Each mask can be "nnn" for extension .nnn, or "/mmm" for full filename mmm.
• "style_NN" for each lexer style name "NN", which user have changed. Subkeys are:
  • "font_color": str: color of font, in Pascal format.
  • "font_style": str: several chars: "i" for italic, "b" for bold, "s" for strikeout.
  • "back": str: color of background, in Pascal format.
  • "brd_c_l", "brd_c_r", "brd_c_t", "brd_c_b": str: color of border (left, right, top, bottom), in Pascal format.
  • "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.

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://github.com/graemeg/lazarus/blob/upstream/lcl/graphics.pp

CudaText vs Sublime Text, different answers to questions

How to call external programs/compilers?

ST3: Use feature of editor called "build systems".

CudaText: Use plugin "External Tools", which adds "Tools" item to the top menu, with dialog to add/configure programs and URLs.

How to change settings for one OS only?

ST3: You need to use platform-specific config files. E.g. for macOS, platform-specific config is "Preferences (OSX).sublime-settings".

CudaText: You need to use the config user.json, but write there options with OS specific suffixes. E.g. Windows option is "font_name", and macOS option is "font_name__mac". Possible suffixes are listed in default.json: __linux, __mac, __freebsd etc. Only limited count of options support OS suffixes, this is marked in the default config (default.json).

How to change settings for one syntax only?

ST3: To edit syntax-specific config, call "Preferences / Settings - Syntax Specific".

CudaText: To edit lexer-specific config, see #Configs.

How to add commands to top/context menu?

ST3: You need to create *.sublime-menu files: https://www.sublimetext.com/docs/3/menus.html#available_menus

CudaText: You need to install plugin "Configure Menu". In its dialog, create "menu.json" file which has default items of top menu and context menu. Then edit that file.

How to find/replace text in many files?

ST3: Use built-in command "Find in files".

CudaText: Use plugin FindInFiles v3 or FindInFiles v4 (totally new plugin, it has bugs yet).

How to find file in a project?

ST3: Use "Goto Anything" (Ctrl+P on Windows/Linux, Command+P on macOS).

CudaText:

• To find file by name, use command "Plugins / Project Manager / Go to file...". After file is focused in project, press Enter to open it.
• To find file by contents, use plugin FindInFiles (v3) which allows to search in project files. Quote from its help:

Set special value "<Project Folders>" (in short <p>) for field "In folder" to search in project files.

How to show vertical lines on some columns?

ST3: Use option

"rulers": [40, 80, 120],

CudaText: Use option

"margin_string": "40 80 120",

How to highlight pair brackets?

ST3: Use plugin, e.g. https://packagecontrol.io/packages/BracketHighlighter

CudaText: Use several "bracket_" options, see in the "Options Editor" plugin.

How to highlight pair HTML tags?

ST3: Use plugin, e.g. https://packagecontrol.io/packages/BracketHighlighter

CudaText: Use options for "dynamic highlighting", "lexer_dynamic_" in "Options Editor" plugin.

How to add custom syntax support?

ST3: You need to create syntax file, https://www.sublimetext.com/docs/3/syntax.html

CudaText: You need to create lexer, see #Lexers.

How to customize hotkeys?

ST3: You need to edit keybinding files like "Default (Windows).sublime-keymap".

CudaText: In the Command Palette dialog, focus needed command item, press F9 - additional dialog will appear to set the hotkey. Method 2: install plugin "Configure Hotkeys" which gives alternative dialog.

How to use Emmet?

ST3: Install plugin "Emmet". Emmet here is written in JavaScript.

CudaText: Use pre-installed plugin "Emmet". Emmet here is written in Pascal with minor differences (e.g. "lorem" works differently).

How to show 2/3/4 files at once?

ST3: Use "View / Layout" menu.

CudaText: Use "=" item in the top menu.

How to split window for single file?

ST3:

• menu "File / New View into File"
• menu "View / Layout / Columns: 2 (or Rows: 2)"
• drag the tab into another group

CudaText: menu "View / Split tab / Toggle split".

How to detect syntax by first line of file?

ST3: It's configured in syntax file: https://superuser.com/questions/752025/sublime-text-3-detect-syntax-based-on-file-header

CudaText: Use "file types config", see #File_types_config.

How to assign syntax to undetected file extension?

ST3: Open your file, click statusbar item for syntax, use item "Open all with current extension as...".

CudaText: Use "file types config", see #File_types_config.

How to select several occurrences of a word?

ST3: Use command "Selection / Expand selection to word".

CudaText: Use command "Selection / Add next occurrence of selected word".

How to select all occurrences of a word?

ST3: In the Find dialog, enter a word, check "whole words", press "Find All".

CudaText:

• In the Find dialog, enter a word, check "whole words", press "Select all".
• Plugin "Highlights Occurrences" gives command "Select all occurrences".

How to record macros?

ST3: Use menu items in the "Tools" menu.

CudaText: Install plugin "Macros", which adds item "Macros" to the top menu.

How to use "Go to symbol"?

ST3: Use menu item "Go to symbol".

CudaText: It doesn't have "Go to anything" but it has "Go to symbol" for a lexer, if lexer finds such symbols for Code Tree. Install plugin "CudaExt", which gives menu "Plugins / Cuda-Ext / Code Tree" with several menu items. One item is "Symbols list" which shows Code Tree items in the menu dialog.

How to switch between C++ (for example) header/implementation files?

ST3: Use command "Switch header/implementation".

CudaText: Use plugin "Switch Header" (it's configurable for all lexers).

How to jump to next/previous modified lines?

ST3: Use commands "Next modification", "Previous modification".

CudaText: Use plugin "CudaExt" which gives commands: "Jump: to next/previous changed lines", "Jump: to next/previous working lines", "Jump: to next/previous saved lines". See #Line_states.

How to detect indentation characters in a file?

ST3: Menu item "View / Indentation / Guess settings from buffer".

CudaText: Plugin "Detect Indent" which does the same.

How to change indentation characters in a file?

ST3: Click statusbar cell "Tab size..."/"Spaces...", it has menu items "Convert indentation to spaces", "Convert indentation to tabs".

CudaText: The same as for ST3.

How to install plugins without package manager?

ST3: Open terminal, go to Packages folder, run "git clone" in that folder, or copy plugin there.

CudaText: Open terminal, go to "py" subfolder, run "git clone" in that folder, or copy "cuda_" plugin folder there.

How to make vertical/column selection?

ST3: See the official documentation page "Column Selection".

CudaText:

• Mouse shortcuts: #Mouse shortcuts.
• Keyboard commands: "column select: up / down / left / right / ....".
• Click the statusbar cell "-", it will toggle to "||", and usual mouse selection will perform column selection.