Code editor
code_editor_object is a text editor for code and input files: syntax highlighting, line numbers, marks that put a validator's findings on their lines, completion of the words the program knows, find and replace, undo and redo, the clipboard. code_diff draws the difference of two texts. Both are ImGuiColorTextEdit (the goossens fork, MIT, vendored at a recorded commit: Third-party software) with FIGURE's own glue: they draw through Dear ImGui only, so a window, headless mode and the remote UI show the same editor.
Everything is polled, as every FIGURE widget: ed%draw returns .true. on the frame the user changed the text, ed%completing while the completion popup is open; no procedure of the program is called back.
Procedures
| Procedure | Purpose |
|---|---|
ed%init([language] [, stat]), ed%destroy(), ed%is_initialized() → logical | create the editor, empty, highlighting language, a language_object (code_language('fortran'); default plain text); release it; whether it exists |
ed%set_language(language [, stat]) | highlight another language from now on (text, marks and undo history kept) |
ed%set_text(text [, stat]), ed%text() → character, ed%line_count() → int32 | replace the text (UTF-8, LF or CR LF; the marks and the undo history go); the text, every line ended by LF; its lines |
ed%draw(id [, width] [, height] [, stat]) → logical | the editor as a widget at the cursor; .true. on the frame the user changed the text |
ed%mark(line, severity, message [, stat]), ed%clear_marks([stat]), ed%mark_of(line [, message]) → character | mark a line 'error', 'warning' or 'info' with a message (Marks) |
ed%goto(line [, column] [, focus] [, stat]), ed%focus([stat]) | move the cursor and scroll to it; give the editor the keyboard |
ed%cursor(line, column), ed%selection(first_line, first_column, last_line, last_column [, text]) → logical, ed%select(first_line, first_column, last_line, last_column [, stat]) | where the cursor is; the selection; select a range |
ed%insert(text [, stat]), ed%word_at_cursor() → character | insert at the cursor (in place of the selection); the word the cursor is in |
ed%find(text [, case_sensitive] [, whole_word] [, stat]) → logical, ed%replace(text, by [, case_sensitive] [, whole_word] [, stat]) → int32 | select the next occurrence; replace them all, in one undo (Find and replace) |
ed%set_completions(words [, stat]), ed%completing([words]) → logical | the words completion offers; whether its popup is open, and what it offers (Completion) |
ed%undo([stat]) → logical, ed%redo([stat]) → logical | undo, redo a change (as ctrl+z and ctrl+y) |
ed%read_only(on [, stat]), ed%is_read_only() → logical | make it read-only or editable again |
ed%set_options([line_numbers] [, tab_size] [, whitespace] [, line_highlight] [, stat]) | line numbers (default on), tab size [characters] (default 4), blanks and tabs shown (default off), the current line highlighted (default on) |
ed%line_rect(line, x0, y0, x1, y1) → logical | a line's text area on the last draw [pixels], from the left of its text to the editor's right edge: for a popup beside it, or a test; .true. only when the line was in view on that draw (.false. before the first draw) |
code_language(name [, stat]) → language_object, lang%init(name [, keywords] [, ...]), lang%name() → character | a shipped language; one of the program's own (Languages) |
code_diff(id, left, right [, side_by_side] [, language] [, width] [, height] [, stat]), code_diff_lines(left, right, added, removed [, stat]) | the difference of two texts, drawn; its lines (The diff) |
The fork's names, where FIGURE's differ: draw is TextEditor::Render, mark is AddMarker, find is SelectNextOccurrenceOf, replace is SelectAllOccurrencesOf then ReplaceTextInAllCursors, set_completions is SetAutoCompleteConfig with FIGURE's matcher as its callback, code_diff is TextDiff::Render. None of them is in the name map, which covers Dear ImGui and ImPlot.
Rules.
ed%initafterapp%init*;ed%drawandcode_diffinside a frame, in a window (a child region of their own, asig_begin_child's); the other procedures at any point of the main thread, a frame open or not.ed%draw's result is valid on the frame it returns.true.: check the text then (ed%text()).- An editor is drawn at most once a frame, under one id; two editors in one window need two ids.
- A change made by the program (
set_text,insert,replace,undo) is not reported bydraw: the program knows. gotoandfindmove the cursor at once and scroll to it at the next draw.code_editor_objectis not to be copied: a copy shares the editor. It has no finaliser, astexture_object:ed%destroy()releases it.
subroutine start(ed)
!< The editor of an input file: its language, its text, the keys to complete, its first check.
type(code_editor_object), intent(inout) :: ed !< Editor.
call ed%init(code_language('input')) ! [sections], keys, values, ! and # comments
call ed%set_text(CASE_FILE)
call ed%set_completions(KEYS) ! typing "rey" offers "reynolds number"
call validate(ed)
endsubroutine startsubroutine draw(ed)
!< The window: the editor, then where the cursor is.
type(code_editor_object), intent(inout) :: ed !< Editor.
integer(int32) :: line, column !< The cursor.
character(len=48) :: where !< ... as text.
call ig_set_next_window(10.0_real64, 10.0_real64, 560.0_real64, 280.0_real64, always=.true.)
if (ig_begin('case.input')) then
if (ed%draw('editor', height=-30.0_real64)) call validate(ed) ! the user changed it: check it again
call ed%cursor(line, column)
write(where, '(A,I0,A,I0)') 'line ', line, ', column ', column
call ig_text(trim(where))
endif
call ig_end()
endsubroutine drawArguments. Lines and columns are numbered from 1; a column counts characters (a tab is one, ρ is one), not bytes or screen columns. width and height are pixels: 0 the available region, negative up to that distance from its edge (height=-30.0_real64 leaves a line of text below), as ig_begin_child's. Text is UTF-8 throughout; text() ends every line with LF, so a file that ends with LF comes back as it was.
Cursor and selection. ed%goto(line [, column]) moves the cursor (column 1 by default, both clamped to the text) and scrolls to it at the next draw; with focus=.true. it also gives the editor the keyboard, which ed%focus does alone, at the next draw, as a click in it would. A range is half-open: ed%select selects from (first_line, first_column) to just before (last_line, last_column), clamped to the text, and ed%selection gives the selection the same way, with its text; it is .false. when nothing is selected, and the four positions are then the cursor's. ed%undo and ed%redo are .true. when there was a change to undo or redo; undo changes nothing in a read-only editor.
Mouse and keyboard. A click places the cursor, a drag selects, a double click selects a word, a triple click a line, ctrl+click (alt+click on macOS) adds a cursor, the wheel scrolls; arrows, home, end, page up and down move; ctrl+z, ctrl+y (or ctrl+shift+z) undo and redo; ctrl+x, ctrl+c, ctrl+v cut, copy and paste with the clipboard; ctrl+a selects all; ctrl+f opens the fork's find and replace bar. On macOS cmd stands for ctrl.
Font and colours. The editor draws in IBM Plex Mono at the current font size (ig_push_font changes the size), with the fallback font's symbols, ρ∞ ∇. Its colours follow the style: the text, the selection, the line numbers and the background are the style's; keywords, types, numbers, strings and comments take the fork's dark or light palette, chosen by the window background's lightness. ed%set_options turns the line numbers, the blanks and tabs shown as dots and arrows, and the current line's highlight on or off, and sets the tab size; ed%set_language changes the colouring of an editor already made, keeping its text, its marks and its undo history.
Statuses. FIG_ERR_STATE: a procedure before init (the queries text, line_count, mark_of, cursor, selection, word_at_cursor, completing, is_read_only and line_rect return their empty value instead), draw or code_diff with no frame open, insert or replace in a read-only editor, any of them from a task. FIG_ERR_ARGUMENT: an empty id, a line or column below 1, a line past the last (mark), an unknown severity, an empty text to find or replace, a tab size outside [1, 16], an unknown language name, a keyword or type with a blank. stat is optional: absent, a failure stops the program with its message (Error handling).
Modes. Window, headless and remote: the same editor and the same pixels (it draws through Dear ImGui's draw lists only). In remote mode the browser's keys reach it as any field's (Remote mode), and its clipboard is the page's.
Threads. The main thread only: from a task every procedure is refused (FIG_ERR_STATE, the task stopped), the queries return their empty value. code_language, lang%init and code_diff_lines draw nothing: a task may call them.
Languages
A language_object is data: the words the editor colours, its comments and strings, whether numbers are coloured, whether case counts. lang%name() is its name ('Fortran', 'Input', a fork language's in lower case, the one given to lang%init; '' for plain text). code_language(name) gives the shipped ones, by name in any case:
| Name | What it colours |
|---|---|
'fortran' | free-form Fortran 2023: its statements and operators (keywords), its types and attributes (types), ! comments, '...' and "..." strings, numbers with exponents and kinds (2.5d-3, 1.0_real64, 7_int8), # preprocessor lines; any case |
'input' | key = value files: a line [section], the key before a line's = (blanks inside it: reynolds number), numbers, ! and # comments, true, false, yes, no, on, off; any case |
'text', '' | plain text |
'angelscript', 'c', 'c++', 'c#', 'glsl', 'hlsl', 'json', 'julia', 'lua', 'markdown', 'python', 'sql', 'wgsl' | the fork's own languages |
lang%init(name [, keywords] [, types] [, comment] [, comment_alt] [, block_comment] [, preprocessor] [, single_quotes] [, double_quotes] [, numbers] [, case_sensitive] [, key_value] [, stat]) defines one:
keywords(:)andtypes(:): words coloured as keywords and as types, each trimmed, matched whole;comment,comment_alt: what starts a line comment ('!','#','//');block_comment = ['/*', '*/'];preprocessor: the character that starts a preprocessor line ('#');single_quotes,double_quotes(default true):'...'and"..."strings;numbers(default true): numbers coloured (digits, a fraction, an exponent, a kind suffix);case_sensitive(default true): keywords and types matched by case; false, in any case;key_value(default false):[section]lines and the keys before=, as'input'.
FIG_ERR_ARGUMENT for an empty name, a keyword or type that is empty or holds a blank, a preprocessor of more than one character.
call lang%init('solver log', keywords=['converged', 'diverged ', 'restart '], types=['step', 'time'], comment='#', &
case_sensitive=.false.)
Marks
ed%mark(line, severity, message) puts a finding on its line: 'error', 'warning' and 'info' tint the line and its number (vermilion, orange, blue: the Okabe-Ito colours) and put an icon beside the number (a crossed circle, a triangle, an "i"), so the colour is not the only sign; the message, after its severity's word (error: ...), is the tooltip of the line and of its number. A second mark on a line joins the messages, one per line, and keeps the gravest severity. ed%mark_of(line [, message]) reads a line's mark back: the result is its severity, 'error', 'warning' or 'info' ('' for none, or a line out of range), and message the text of its tooltip (each message after its severity's word, LF between two).
A mark moves with its line as lines are inserted or deleted above it, and goes with the line. Deleting text in a marked line removes its mark (the fork's rule: the finding was about the old text); typing in it keeps it. A validator run on each change (if (ed%draw('editor')) call validate(ed)) marks the lines again in any case: clear the marks (ed%clear_marks), then mark what it finds. set_text removes them all.
subroutine validate(ed)
!< Check every line again and mark what is wrong: an unknown key or a value that is not a number (errors), a
!< Reynolds number that is not positive (an error), a supersonic Mach number (a warning).
type(code_editor_object), intent(inout) :: ed !< Editor.
character(len=:), allocatable :: text !< The text.
character(len=:), allocatable :: key !< A line's key.
character(len=:), allocatable :: val !< ... its value.
real(real64) :: x !< ... as a number.
integer(int32) :: n, a, b, eq, ios !< Line, its start and end, its "=", a status.
call ed%clear_marks()
text = ed%text()
n = 0_int32
a = 1_int32
do while (a <= len(text, int32))
b = index(text(a:), LF)
if (b == 0) b = len(text, int32) - a + 2_int32
b = a + b - 2_int32 ! the line is text(a:b)
n = n + 1_int32
eq = index(text(a:b), '=')
if (eq > 0) then
key = trim(adjustl(text(a:a + eq - 2)))
val = trim(adjustl(text(a + eq:b)))
if (all(KEYS /= key)) then
call ed%mark(n, 'error', 'unknown key "'//key//'"')
elseif (key /= 'grid file') then
read(val, *, iostat=ios) x
if (ios /= 0) then
call ed%mark(n, 'error', key//' is a number')
elseif (key == 'reynolds number' .and. x <= 0.0_real64) then
call ed%mark(n, 'error', 'reynolds number must be positive')
elseif (key == 'mach number' .and. x >= 1.0_real64) then
call ed%mark(n, 'warning', 'supersonic: the incompressible solver ignores the mach number')
endif
endif
endif
a = b + 2_int32
enddo
endsubroutine validateA check that takes long (a solver's dry run) belongs in a task: mark the lines when it ends.
Completion
ed%set_completions(words) gives the words completion offers (none: completion off). While the user types a word, a popup under the cursor lists the words that start with it, then those that contain it, in the order given, in any case; up and down choose, tab or enter inserts, escape or a click elsewhere closes it, ctrl+space opens it. In a key_value language a word may hold blanks and dashes: the term is the line's text up to the cursor, its indentation kept, so mach n offers mach number. Completion is not offered in comments and strings.
ed%completing([words]) is true while the popup is open, from the frame after the keystroke that opened it, with the words it offers: what a test checks, or a program shows beside it (a key's documentation).
call frames()
call report('opened')
call ed%goto(2_int32, 21_int32, focus=.true.) ! after the "-" of -15
call frames()
call test_key('backspace') ! as the user would fix it
call frames()
call report('after the fix')
call ed%goto(5_int32, 1_int32, focus=.true.) ! the empty line
call frames()
call test_type(' mach n')
call frames()
if (ed%completing()) write(output_unit, '(A)') 'completion offers a key'
call test_key('tab')
call frames()
write(output_unit, '(A)') 'line 5: "'//line_of(5_int32)//'"'$ ./cb_editor --test
opened:
line 2: error: reynolds number must be positive
line 3: error: unknown key "mach numbr"
after the fix:
line 3: error: unknown key "mach numbr"
completion offers a key
line 5: " mach number"
1 key renamed
selected: "mach number"
9 lines, the word at the cursor: grd
undone: 9 lines
redone: " grid file = naca0012.grd"
line 2 in view, below line 1: T
read-only: F
at the end:Find and replace
ed%find(text [, case_sensitive] [, whole_word]) selects the next occurrence after the cursor, from the start again past the end, and scrolls to it at the next draw: true when found (the selection is then text). ed%replace(text, by [, case_sensitive] [, whole_word]) replaces every occurrence, as one change (one ctrl+z undoes it all), and returns how many there were. case_sensitive defaults to true, whole_word to false. The user has the same in the fork's bar, ctrl+f (cmd+f on macOS): find, find all, replace, replace all, by case, by whole word.
if (ed%find('numbr')) then ! selected, scrolled to at the next draw
fixed = ed%replace('mach numbr', 'mach number') ! every occurrence, in one undo
call validate(ed)
write(output_unit, '(I0,A)') fixed, ' key renamed'
endifThe diff
code_diff(id, left, right [, side_by_side] [, language] [, width] [, height] [, stat]) draws the difference of two texts as a widget at the cursor, read-only: in one column the removed lines of left (tinted red, marked -) before the added lines of right (green, +), or, with side_by_side, the two texts next to each other with their line numbers. It is drawn by id, as a widget: FIGURE compares the texts again only when one of them, the language or the layout changes, and forgets a diff not drawn for 600 frames. Lines are compared whole by the fork's algorithm (dtl's shortest edit script): a changed line is a removed line and an added one.
code_diff_lines(left, right, added, removed [, stat]) reports the same lines without drawing: added, the lines of right (from 1) that are not in left; removed, the lines of left that are not in right. It needs no frame and a task may call it.
call code_diff_lines(OLD, NEW, added, removed) ! no frame needed: a task may call it
write(summary, '(I0,A,I0,A)') size(removed), ' line(s) removed, ', size(added), ' added'$ ./cb_diff --test
1 line(s) removed, 2 added
removed from the old file: 2
added in the new file: 2 7call ig_text(trim(summary))
call ig_separator()
call code_diff('diff', OLD, NEW, side_by_side=.true., language=input)
Statuses and modes. code_diff: FIG_ERR_ARGUMENT for an empty id, FIG_ERR_STATE with no frame open and from a task; the same in every mode. code_diff_lines: always FIG_OK.
Limits
- Symbols of the fallback font keep their own width. The editor lays text out on a grid of Plex Mono's advance; a symbol from Noto Sans Math (
ρ,∇) is drawn at its column with its own width and may touch the next character (Known issues). - One mark per line: a second one joins the first; deleting text in a marked line removes its mark.
- The visible part only: the editor draws the lines in view; a very long line (10⁵ characters) is laid out whole on each change. Input files and source files of a few thousand lines are fine.
- No folding, no word wrap, no minimap in FIGURE's API: the fork has them, behind options FIGURE does not expose yet.
- Language rules are per line: in a key = value file a second
=on a line colours the words before it as a key too. - The diff compares lines, not words within a line.