Skip to content

Text Editor

The Text Editor is used to create and edit q functions, q data initializers, and small text files. Before we look at the editor in detail, let’s examine the difference between q functions, q data initializers, and files.

Q functions

These contain q function definitions that are referenced by name in other functions. Q functions are created by selecting a module and picking New > Function… from the main or context menus. A function is referenced externally using its fully qualified name, consisting of the module name and function name using dot notation, e.g. .moduleName.functionName.

Q data initializers

These are snippets of q code that are automatically executed when their module is loaded; typically they are used to initialize tables, or other variables required for the module to execute. Data initializers are created by selecting the module and picking New > Data… from the main or context menus.

For example, imagine that you have a table that you use over and over again each time you load a workspace. Instead of having to create and load it manually every time, you can put the code to create it in a q data initializer that loads automatically when you load the module. That way, the table is always available to you. (Initializers for huge tables or databases should make use of unmanaged files or databases placed on the server by their team or administrator.)

Files

These provide a means for managing files, including .q files. Files are created by selecting a repository, module or folder and picking New > File… from the context menu and typing the name of the file path. When the repository is loaded the named file path is created relative to the workspace path for that user. The file will contain the contents entered using the Text Editor.

This example repository contains several modules (e.g. .analysis, .analysis.test, Agenda, Data, etc.). The .analysis and Data modules are opened. In the .analysis module, we can see function (light brown icons) and data (light green icons) artifacts. Data artifacts become available as variables when the workspace is loaded. CITIES, PI, and PLANETS become populated with data on load. Functions can be run in the workspace. The .analysis.hailstoneSequence has been entered with a variable into the Scratchpad. The actual function has been opened in the pane beside it. When the function is displayed in the workspace, the output of the function is shown in the Console.

image1.png

Creating a q function

  1. Right-click on the module in which to create the function and pick New > Function… from the context menu.

    image2.png

  2. Name your function and click OK.

    image3.png

  3. The function appears in the module with a green plus icon to indicate that it has been added.

    image4.png

Opening editors

Functions, data initializers, and files can be opened in several ways:

  • Double-clicking an item in the search pane will open a text editor in the main page.

  • Right-clicking the function and picking Open from the context menu will do the same thing.

  • Picking File > Open from the main menu with an item selected will do the same thing.

    image5.png

    Editors opened on the main page look like this:

    image6.png

    Note the dark dot in the left hand gutter. This is a linter warning to indicate that there is some coding or styling issue with the file. Hover over the dot to find out the issue with the code. In this case, it is warning that that the function has default documentation. See Linting for more details.

  • Right-clicking the tab and picking Undock from the context menu will open the function in a new window.

    image7.png

    Functions opened in a new window look like this:

    image8.png

The rest of this section will use examples where the function editor has been opened in a separate window. In the Text Editor, q keywords are highlighted. Edit and Q menus are provided and a context menu is available for command execution. Some key aspects of the view are summarized below. Please note that other file types can be uploaded, and can be opened using the file editor as long as they are in UTF-8 format, or ASCII format with no extended ASCII characters.

Interactive editing

With any q editor open (functions, data, or .q scripts), any code can be selected and run by either right-clicking the code and selecting Display, or by pressing the associated hotkey of Ctrl+D (⌘D on macOS).

Additionally, if editing a .q file, the file can be run by right-clicking the editor and selecting Run Script.

Set the DEVELOPER_EDITOR_DISPLAY_ON_EXECUTE env var to yes in the install config to enable Ctrl+E as Display

When executing selected text with either Display or Execute, the q context (namespace) of execution is chosen with the following rules:

  • if editing an artifact within a module:
    • if the module name starts with a . (e.g., .ns), the module name is the context
    • otherwise, the context is global (.)
  • if editing a q file (e.g., script.q)
    • the closest \d .ns or system "d .ns" context switch above the selected text is used to determine the context
    • if there is no context switch above, the context is either global (.), or it's folder name if the folder starts with a . (.ns/script.q)

When editing files, dynamic context switches (setting the context from a variable, etc) will not be identified. To always use global as the context for editing files, disable the Infer file context option from File > Settings.

Relevant File menu commands

The following File menu commands are relevant to files open in the Function Editor view.

command description
Save Saves the function.
Save As… Saves the function with an alternate name. You are prompted for the name.
History > View History For repositories, this opens the repository differ. For child artifacts, this opens the version dialog showing previous versions of the artifact.
History > Reset Restore the artifact to the state it was in when it was last pulled.
Restore Restores the function to its last saved contents.
Dock Docks the window inside the work area.
Close Closes the editor.

Supported browser commands

command description
Print Prints the current page.
Bookmarking You can bookmark the landing page. At the present time, you cannot bookmark any other artifacts.

Edit menu commands

command description
Undo Returns the editor to the previous state.
Redo Returns the editor to a latter state. The opposite action of Undo.
Select all Make the entire contents of the file the current selection.
Find/replace… Opens the search and replace dialog.
Toggle line numbers Toggles the display of line numbers in the current editor.
Toggle line wrapping Toggles the line wrapping of the current editor.

Q menu commands

command description
Inspect Opens the current selection in the Visual Inspector.
Profile Opens the current selection in the Visual Profiler.
Execute Executes the currently selected expression.
Display Displays the result of executing an expression in the console.
Display in Editor Displays the result of executing an expression in the current editor.
Open If the selection is a function name and this function is in the workspace, open that function.
Uses (Selection) If the selection is a function name, search for any functions, data initializers or q files using that function.
Interactive Debugger Opens an interactive debugger on the selected code. Only available in KX Platform.
Quick Debugger Opens a debugger to show the stack trace of any errors that occur when executing the selected code.
View Text If the selection evaluates to a string, list of strings, or dictionary of strings, open those strings in a text viewer.
About Evaluates the expression, displaying the type, length and attributes or metadata, depending on the type of the result.
Bench Displays in the console the time in milliseconds it takes to execute the selected code as well as the memory footprint associated with the execution in bytes (e.g. 23 553472).
Uses (File) Search for any functions, data initializers or q files that reference the current function or data initializer.

Help menu commands

command description
Open Help On Editor Selection… Opens the code.kx.com page for the current editor selection.
Keyboard Reference… Shows all the keyboard shortcuts for the current component.
Q Reference… Opens a q reference code.kx.com page.
Developer Function Reference… Opens the documentation for included libraries.
Developer User Guide… Opens user guide.
Developer Notes & Troubleshooting… Opens the troubleshooting, notes, and FAQ.

Context menu support

The context menu can be accessed by right-clicking the editor. See the File or Edit menu command sections for more information about each command.

image9.png

Status bar messages

The Status Bar at the bottom of the window provides status information about each command.

image10.png

When you execute, inspect or display a line or lines of code, your code may not execute properly due to syntax, runtime, parse or system errors. Errors are reported in the Status Bar.

image11.png

Using commands

There are several commands, accessible by the context menu, the Q section of the main menu, or hotkeys that can be run on any expressions in a q editor. These include commands such as display, inspect, about and bench. If code is selected, the command will be run on the selection. If there is no selection, it is run on the current line.

In the example below, the highlighted line of code on the left (partially under the menu) creates a table. The Visual Inspector on the right contains the result of inspecting the evaluated expression on the left. With the inspector, we can see the size and contents of the table.

image12.png

Calls to functions can be profiled or debugged, via the menus, or with hotkeys.

With the name of a function selected, if the function is in the workspace, it can be opened with the Open command.

Autocomplete

Pressing CTRL+Space while typing a variable name will open the autocomplete menu. This gives you a list including variable and column names in the current editor or in memory, qDoc tags and q keywords. If there is only one option available, it will automatically insert that name.

Hover hints

Hovering over the name of a function that is both in the workspace and documented in the QDoc style will display a tooltip for that function showing descriptions of the parameters and the return value.

Using find and replace

A find-and-replace toolbar is available: pick Edit > Find/Replace… from the main menu, or Find/Replace… from the context menu, or type CTRL+F on Windows/Linux or ⌘F on a macOS. The and buttons can be used to cycle through matches, and the Aa, .*, and |Abc| buttons can be used to enable or disable case sensitivity, regex, and whole word options respectively. When searching using regular expressions, the expression does not need to be wrapped in slashes.

image13.png

Syntax highlighting

The editor provides syntax highlighting for the q language as well as some support for detecting common errors. For example, in the function below, the line n:5000; needs to be indented in order to evaluate correctly. As such, the line is highlighted in red indicating an error. Hovering over an error will give an explanation of why it is an error.

Error messages

If there is an error evaluating an expression, an error message will appear in the status bar.

See Reference: Errors for a list of errors and their causes.