aboutsummaryrefslogtreecommitdiffstatshomepage
diff options
context:
space:
mode:
authorDavid Walter Seikel2015-03-11 16:00:22 +1000
committerDavid Walter Seikel2015-03-11 16:00:22 +1000
commitb3e40b7cfc2e95288751d3af67086b5e55e4b1cb (patch)
treef7c903261fcfc96458046fbd34c8eea548d8bad7
parentTODO++ (diff)
downloadboxes-master.zip
boxes-master.tar.gz
boxes-master.tar.bz2
boxes-master.tar.xz
Adding old documentation.HEADmaster
-rw-r--r--BOXES.txt1130
-rw-r--r--BUGS.txt6
2 files changed, 1136 insertions, 0 deletions
diff --git a/BOXES.txt b/BOXES.txt
new file mode 100644
index 0000000..745b7c9
--- /dev/null
+++ b/BOXES.txt
@@ -0,0 +1,1130 @@
1What's needed for MC like program. Call the library toyboxes, and the MC clone toysoldier. B-)
2
3Use ANSI for terminal control.
4UTF-8 support is welcome in toybox where it makes sense, here it makes sense.
5
6Command defining - key, name, script, context.
7 Internal commands for the scripts.
8 Which can depend on the context.
9 Context is important. Gotta handle stuff like vi modes, MC browse / view / edit modes, less search popping into readline mode, etc.
10 Learnable keys ala GIMP.
11
12Split the screen up into boxes.
13 Each box is a context.
14 Current box should have it's box graphics drawn in a different colour to highlight it.
15 Tab/shift-Tab cycles through boxes.
16 Though the editor has it's own use for tab. Ctrl-tab as an alias perhaps?
17 Horizontal / vertical splits, with some sort of size control.
18 Each box can be split h or v once,
19 with a control of what proportion the current box has (initially half),
20 a minimum size set by the contents,
21 and initially a copy of the pointer to the function that supplies it's contents / deals with it's input / includes it's context.
22 Later it can have that pointer set to something else.
23 Any given box can be deleted, which deletes it's sub boxes, drops it's pointer, and merges it's area with the one it split from.
24 See if screen and tmux agree on keys to use for box control.
25 Though, as usual, it's definable, but screen/tmux can be the defaults.
26 Choose to make a box full screen. With menu to select other boxes, or swap back to full set of boxes.
27 Can be without borders and such.
28
29 The borders can be the usual box graphics, +-| characters, or inverse spaces, in that order of priority.
30 Show bits of text on top and bottom borders (left and right sides of them).
31 MC includes a couple of tiny mouse controlled widgets.
32 Perhaps a scroll widget in left or right borders. Emacs dired has that.
33
34 Single line 'boxes', across the entire terminal, or across each box.
35 Should be context sensitive.
36 Menu - a list of commands showing their names and keys, with sub menus.
37 Function keys - Any function keys with commands showing the command names and key.
38 Perhaps could just be a specialized menu.
39 Programmable status line.
40
41 Contents scrolling.
42 Virtual memory buffers.
43 If a file viewer, just mmap it.
44 Editor should be able to only load in bits of a large file, perhaps with a UNDO/REDO buffer.
45 If command output, can create a temp file and mmap it.
46
47 file viewer (less, man).
48 editor (vi, mcedit, nano).
49 Like e3, make generic editor, with pluggable command keys, that kick in depending on how it's called.
50 Uses a file list in a box to select files for opening.
51 Poor mans top and similar commands.
52 Top at least could make use of internal boxes, with the command list using a sortable list.
53 Put command output in boxes. Each line can be selected and operated on.
54 Title bar across top, with click to sort style column names.
55 Each line is a single line 'box'.
56 ls.
57 ls with display options.
58 archive listing
59 find command result.
60 All these can show current directory with diving in and out, or tree and current directory in a sub box.
61 Also, allow an edit mode for editing the file attributes that are displayed, inline and full box if possible.
62 Shell console, with various text substitutions on input.
63 Can be a single line 'box' as well as an ordinary box.
64 Though the ordinary ones show their output in their box,
65 but the single line one should swap to a full screen, which can be a full screen box.
66
67A box has content. Each content type is a context. So we can have -
68 Plain scrollable text view.
69 Fancy text view (hex and so on).
70 Text edit.
71 Directory browse.
72 Script controlled.
73
74Popup widgets centered on box/boxes that they affect.
75 Labels, Text line (with optional history), check boxes, radio buttons, OK/Cancel/etc buttons, popup select list (useful for history to, can be just a menu specilization).
76 Widget sets, though try to keep things simple enough to not need them.
77 Notifications, with the addition of an abort button.
78 If a single widget in the popup, prompt in a single line "box" near the bottom (like nano).
79 Options.
80 Keep options down to a bare minimum.
81 Command params.
82 Fetch command params from internal toybox structures, map them to the appropriate widget.
83 F2 menu - list of commands to apply to file/s or current directory.
84 The list is selectable by file type.
85 Should use the same code as the menu box, and allow sub menus.
86 Context sensitive history lists for selecting stuff.
87 Could also be a widget inside the popup when needed.
88 Search / replace.
89 Delete / save confirmation.
90 Command progress meter.
91 Use xargs, and have it output something useful per 'argument' for the progress meter.
92 xargs has an option to print the command to stdout, and to ask for confirmation per command.
93 xargs can run multiple threads.
94
95Scripting, so we can make things fancy and tie it together.
96 Don't forget to make it 'scriptable' via internal C.
97 MC uses that for the F2 menu, user menu, and archive access.
98 We should use scripts to define most of the above.
99 I'd like to use Lua, but shell is likely a better choice.
100 Coz toybox will have a shell.
101 And MC scripts are mostly shell bits.
102 Should have an actual toyboxes command that you can feed toyboxes scripts into.
103 Might actually get away with using that to define most of MC, AND be the editor plugins.
104 See how far I get, but that's what I'll start with for testing.
105 I should reuse the old emu protocol for this.
106 Not gonna actually sort function names or key combos.
107 A linear search is good enough for keys, they only come in at human speeds.
108 People might want the scripts to run faster, but in toybox we strive for simplicity.
109 Well, maybe a binary search within each modules function block that is sorted by hand in the source code.
110 On the other hand, might be able to make use of the toybox command parsing infrastructure for script functions.
111 Leaving that as a problem for toybox itself.
112 But it's not reusable, it uses globals, and not sure if we can screw with those globals.
113
114NOTE - toybox is designed to only deal with one command per process. So we can't call other toybox commands internally.
115 Or can we? Toysh does it.
116
117Events
118 We need a time event. Top has a resolution of hundredths of a second, though says that only tenths is officially supported.
119 Tenths makes sense for human speed UI. Hundredths makes sense if you want video frame rates. lol
120 Termios only allows tenths of seconds for read anyway.
121 Hmm, seems read() wants to wait for at least one byte, it's a between byte counter. Doh!
122 Select() is likely less simple, poll() the same, and epoll() seems to be linux specific. All allow more precise timeouts.
123 On the other hand, Rob is using poll() in netcat.
124
125Common bits / differences.
126 Initial toybox command arguments.
127 Ability to change those within the editor.
128 Files - passed as arguments, or can add / remove them from the running editor.
129 Process the file through some proggy, or just some function of the editor script.
130 Save / save as / backups.
131 Modelines are actualy discouraged as a security issue by the standard, but encouraged by toybox to use vi modelines.
132 Filename completion.
133 Filename prompts could have a couple of features.
134 Can pass things in and out of a shell command, append to the file, edit a specific fixed section of a file or special file (disk block editing!), or use stdin and stdout (joe in a pipe).
135 Directory / file browsing in a window.
136 Windows per current design.
137 Multiple files in the command line each have their own window.
138 Different / same file in each.
139 Each has it's own cursor / marks / block, etc.
140 Delete / scroll some other window.
141 Open a file in some other window, possibly creating one first.
142 Show one window full screen.
143 Method to show some hidden window, can be hidden if there's not enough space for them all.
144 Buffers - holds the contents of the files being edited / viewed.
145 Attached to windows, but can shift them around?
146 Edit / view / read only, named / unnamed buffers.
147 Special purpose buffers.
148 Emacs has - scratch, help, grep, compile, gdb, man, shell, probably others.
149 Though most of those are just running some other command in a window.
150 Kill ring buffer.
151 Kill goes to the buffer, delete just vanishes, on the other hand, this is really the difference between "cut" and "delete".
152 "Yank" just means "paste from kill buffer" then.
153 Emacs can have different working directory for each buffer, OR one global directory.
154 List them, perform some operation on the members of the list. Go through them all, prompting to save modified buffers.
155 Display text - navigate within it, scroll it in various ways.
156 Many ways to display otherwise unprintable text.
157 Inverted video for high bit characters.
158 Just show high bit characters.
159 UTF8.
160 ^X
161 Could be a problem with "where's my cursor" for the code.
162 Hex mode, wrap mode, raw / parsed mode, as well as formatted / unformatted mode.
163 Parsed mode has the text being processed by some command specified in the config file.
164 Formatted mode converts common formatting stuff to bold / underline.
165 Line numbers.
166 Scrolling can be definable amounts.
167 Some editors count buffer lines, some display lines.
168 Move to top, bottom, middle of screen / line.
169 Marks.
170 One mark and cursor.
171 Hmmm, Emacs uses the idea of a "point" which is between characters, with the "cursor" on the right side.
172 Not sure if this will be a problem.
173 Emacs has only one mark, and everything between point and mark is the "region", a block I think.
174 Multiple marks - numbered, named, just arbitrary, automated marks for various reasons. Line / line and character marks.
175 Next / previous / goto / remove one / all marks.
176 Whitespace / word boundaries / line / paragraph / "sections", etc. Should be definable.
177 Vi has multiples types of all of them. Pffft
178 Smooth scrolling (line by line).
179 Slow serial line support - do we need it?
180 Maybe. B-(
181 Status line.
182 Show cursor position, details of file / character under cursor / working directory. Often used for line input of parameters to.
183 Top of screen, bottom, above the key display in nano. Can have left, middle, right widgets.
184 Nano has essentially two status lines.
185 Expert mode to turn it off, disable it for more screen space.
186 Regexs - basic / extra / extended
187 Replacable stuff in search & replace. Ex/vi has this as an option.
188 Commands - invoked immediately with no echo, or typed via readline.
189 Pre command numbers (usually not echoed) / post command arguments. Also pre command regexs and other things to select the lines to work on.
190 Methods of repeating commands. Repeat last / next command, possibly X times.
191 Direction / motion.
192 Execute line / buffer / file.
193 Select lines, apply command to them.
194 Parameter expansion.
195 Key handling.
196 Bind / learn keys.
197 Emacs has "keymaps" for major and minor modes, as well as a global one.
198 Unbind keys. Mask keys from a lower level, but without actually binding them to anything, a NOP.
199 Command keys can be one or more keys.
200 Emacs and wordstar generally use a control key followed by some other key.
201 Show help page in a window with key bindings. Show binding for specific key.
202 Shortcut keys display. Nano has two lines of 6 each, showing only the most common. MC has one line, showing 10 function keys. No one else cares?
203 Esc key same as Alt / Meta key OR used for function keys OR used by itself. sigh
204 Meta key used to insert high bit characters.
205 Abort current command key.
206 Emacs has a keymap per buffer, which is the keybindings.
207 A global keymap.
208 The buffers major mode keymap.
209 Minor modes can have keymaps that override the major mode keymap when the minor mode is turned on.
210 Del <-> BS swapping.
211 Readline type widget. Called "minibuffer" in emacs.
212 For command parameters, also just go to one at the bottom to type commands into.
213 A fullscreen editor could be considered to just be a stack of these.
214 History, completion, editing, escape from. Position and length.
215 Same editing keys, and treat it just like a one line window.
216 Restricted or different editing keys while in some random line editing mode.
217 Moving readline to some other line (the basis of full screen editing perhaps).
218 Perhaps allow it to autoexpand if the input covers multiple lines.
219 Though that might be better to do as just creating more lines, then moving the readline between them.
220 Still would need the prompt on the top one, and to know to send them all at once when done.
221 How exactly does one create multiple lines?
222 Only way that makes sense is if the ENTER key is different from the "now do this" key.
223 Or wrapping long lines instead of scrolling them.
224 The prompt could include the default in ().
225 Mouse support - left click, double click, scroll wheel.
226 Only used to click on a widget, move cursor, or scroll around.
227 Shift click is used for X cut and paste support, think that just works from the terminal.
228 Shell - In a window / full screen.
229 Make editor a background task with bg / fg standard shell stuff.
230 Pass a block or buffer as stdin. Append / insert stdout to the buffer.
231 The shell output can just appended to the window contents as text that can be edited like every other window. When the cursor is at the bottom of the shell windov, stuff typed in is the next shell command.
232 Simple editing.
233 Move cursor, insert, delete, overwrite.
234 Basic editing.
235 Modes.
236 Vi has a lot of them - command, insert, ex, and moooore.
237 Emacs has definable modes that are a different concept to vi.
238 There are "major" and "minor" modes per buffer.
239 Major modes is for file type specific editing like "editing C, latex, etc" or "Dired".
240 Includes things like indenting, syntax highlighting, function boundaries (for ctags I guess), invoking the right compiler, keymaps, etc.
241 Can include other specialisations, like a python shell, and dired.
242 Minor modes are extras you can add, they seem to be things like "autofill", "wrap", "overwrite", "line numbers", etc.
243 Insert / overwrite mode.
244 Automatic detection of file type (typically source files) to put editor into different modes.
245 Cut, copy, paste, delete - blocks, word / line /etc, to end / beginning line, others.
246 To / from other buffers, files, "clipfile", maybe even the clipboard/s (thought that's an X thing I think).
247 Blocks - cut, copy, move, write to file.
248 Unhighlight block.
249 Search / replace - regex / shell glob / straight text / whole words. Case / charset sensitive. Forward / backward.
250 Regexs - basic / extra / extended
251 File / all files / within selection. Wrap around searching.
252 Incremental. Interactive / all replace. Inverted (find non matches).
253 Highlight / filter found.
254 Regex for the replace bit. Replacable stuff in search & replace. Ex/vi has this as an option.
255 Can search mixed hex and strings.
256 History, repeat, repeat in other direction.
257 Modified state.
258 Can be used by some commands to pester the user.
259 Ability to turn that state off.
260 Tabs / spaces / half tabs. Setting tab size.
261 Advanced editing.
262 Insert a character that is otherwise hard to insert, like command keys.
263 Insert date/time.
264 Quick search for a character in current line / forward / back.
265 "Smart" home, home goes to actual beginning, or first non blank.
266 Replace lots of space horizontally / vertically with just one / zero spaces.
267 Insert empty line/s above / below.
268 End of line space removal.
269 Allow cursor beyond end of line.
270 Visible white space.
271 DOS / Mac line ending convert. On the other hand, might just be good to do that transparently, remember on read, convert on save.
272 Change text encoding.
273 Add a newline at end of file if it's missing one.
274 Think we are doing that anyway, but an option to turn that off might be good.
275 Transpose, upper, lower, reverse case, capitalize words.
276 Adding a prefix / suffix string to selected lines.
277 Indent / outdent / line wrapping / centreing which can be auto / manual. Left and right margins.
278 Column blocks.
279 Deleting might just replace the column block with spaces / tabs.
280 Macros. Various ways of defining / invoking a macro.
281 Nested macros.
282 Auto expanding abbreviations.
283 Auto save after certain commands, or certain time.
284 Multi level undo / redo. Also undo current line (revert it?).
285 Disable undo.
286 Ability to list the undo "records"?
287 Emacs undo boundaries?
288 Spell checker.
289 Pretty printer (likely via shell command like indent).
290 Email quote handling.
291 Count / highlight lines matching or not matching regexes.
292 Sort block.
293 Persistant cursor position and selection.
294 Complete the word being typed based on other words in the file.
295 Code editing.
296 Ctags - basically lookup a symbol (word cursor is on) in the ctags files, which gives you a position in some other file that defines this symbol. Then display this other file somehow, probably allowing editing.
297 Ctags is in the standards, but do we want to write a toybox version?
298 Bracket / character matching. Goto / highlight matching bracket. Auto insert the closing one.
299 Include "insert one, blink the other".
300 Auto detect code block for indenting?
301 Syntax highlighting.
302 Next / previous error (compile errors usually).
303
304Readline.
305 toybox has get_line() and get_rawline(), but they are not interactive readlines.
306 In order to have our readline() be useful for generic use, the keystrokes that do stuff must be definable.
307 So, what do we need?
308 GNU readline has (leaving out a few things) -
309 Editing
310 How is a "word" defined?.
311 Hitting ENTER anywhere in the line submits it. An editor would want to actually insert the ENTER into the text.
312 Move cursor / insert / delete / backspace / undo (all the way back) / revert.
313 Perhaps redo might be nice.
314 Move cursor to start / end of line, forward / back one word, redraw.
315 Cut / copy / paste. Kill ring with ring rotation?
316 Entire line.
317 All spaces around cursor.
318 From cursor to mark.
319 Highlighted block.
320 From cursor to start / end of line.
321 to end of word, or end of next word if between words.
322 to beginning of word, or of the previous word if between words.
323 to previous white space. Different from above coz apparently white space is different from word boundaries. shrugs
324 Numbers in front of commands. Vi and emacs probably need this? More and less "needs" this. Otherwise... eww.
325 For repeats, or sometimes to reverse the direction if it's negative.
326 Insert / overwrite mode.
327 Upper and lower casing characters or words.
328 Transpose characters / words.
329 Marks - setting a mark and moving the cursor to it / swapping with it.
330 Character search within the string - forward / back.
331 Insert comment - bloat we don't need.
332 History.
333 Back / forward one line. Goto start / end of history.
334 Incremental and non incremental searching, forwards or back.
335 During incremental search - ability to abort and restore original line.
336 Remember the last (incremental?) search.
337 Either return the found history (ENTER), or allow editing (editing keys).
338 Option to save edited history lines, and mark them as edited.
339 Show key bindings / macros / etc.
340 Tab completion.
341 List / select completions.
342 Cycle through the matches.
343 Macros!
344 Config files.
345 Not likely to emulate these, we have our own needs, and it's not a standard.
346 Expansions.
347 MC will want argument expansions at least.
348 Though perhaps this is best left to the code that calls this to expand the result.
349
350more
351 Can handle switch between multiple files.
352 Searches are regexs. Can also search for non matches.
353 Multiple marks.
354 Forward and back half screenful, with "half" being the specified number, but defaulting to actual half.
355 Shell commands (not in the standard).
356 Invoke the editor mentioned in EDITOR, or default to vi. Pass line number if it's vi.
357 Print info about file.
358 Ctags.
359 Some commands are single letters, some are ":" followed by a single letter, possible with more text, then ENTER.
360 Or other variations.
361
362less
363 Has bracket matching, but only from top-open / bottom-close.
364 Can search between multiple files, or add more.
365 Files on the command line, add / remove files, just open a new file now.
366 Highlight found text.
367 Filter found lines.
368 Option to NOT do regex search.
369 Change the command line arguments while running.
370 Shell commands with replacable params.
371 Input processor - some proggy that the input file is processed through, the output of that is shown.
372 Um, why not use pipes and input redirection?
373
374ed - obsolete for toybox, ancestor of ex.
375 A line editor.
376 In command mode, type the command, then ENTER.
377 In input mode, type text, with "." on a line by itself to go back to command mode.
378 Uses one or two optional line addresses (can be regex) followed by a single character command, then arguments.
379 The "address" can be various symbols with various meanings, see the manual.
380 Usual basic editing and navigation commands.
381 Join lines.
382 Mark lines.
383 Display lines (with line numbers).
384 Copy / move lines.
385 Apply a command to a bunch of lines matching / not matching the address.
386 Insert a file / write lines to a file.
387 Search and replace.
388 Undo.
389 Shell command, with filename replacement character.
390
391sed
392 Stream editor.
393 Fairly similar to ed, except it applies a script of commands to each line in turn.
394 Branch to a label within the script. Can test if a substitution happened before deciding to branch.
395 Includes a "hold space" for cut and paste type operations, as well as swapping.
396 Can output line numbers.
397 Can read in a file, or write to one.
398 Can be commented.
399
400ex - obsolete for toybox, but part of vi.
401 A line editor, apparently the line oriented editing mode for vi.
402 So while the command itself is obsolete, it's internal stuff might be needed for vi.
403 In fact a lot of the standard for vi just refers to ex.
404 ":" means to perform an ex command from vi. lol
405 Starts in command mode (":" prompt).
406 Basically a "type command then ENTER" command mode.
407 Text input mode (append, insert, change) ended by "." on it's own line.
408 Has line addresses before the commands, similar to ed.
409 Commands have complex parsing requirements. Ewww.
410 Has some really basic command line editing.
411 Has a bunch of buffers, with modes. Commands apply to a named buffer, or the unnamed one if no name is given.
412 Abbreviations and maps. Same thing? They interact. lol
413 Think the difference is that maps don't have to have blank space after them.
414 They expand during typing.
415 Seems that maps are for binding to keys?
416 Set various options.
417 Shell command, with optional interaction.
418 Read commands from a file.
419 Can scan ctags files looking for regexs.
420 Can switch to "open" and "visual" modes, whatever they are.
421 "Visual" mode is just vi.
422 "Open" mode I think is a vi for dumb terminals?
423 Has a concept of "window", also not sure what that is. Might just be the number of terminal lines.
424 Shell escape - pass selected lines to a shell command, replace them with whatever it returns.
425 Shift lines back and forth. Indent and outdent in other words.
426 Execute a buffer as ex commands.
427 Regexs have extra thingies.
428 Replace commands can refer to other bits of text using parameters. See the manual.
429 Autowrite - basicaly save the file after certain commands.
430 Mode that strips out non printables on file read.
431 Can be made ed compatible. lol
432 Can display line numbers.
433 Paragraph boundary pairs can be set.
434 Definable scroll distance.
435 Visual and open modes have "sections", with definable pairs of boundary characters.
436 Can show matching braces.
437 Can optionally warn on some commands if the buffers are modified.
438 Margin auto wrap and end of line blanks removal.
439 Can wrap searches.
440 "modelines" (as used at the top of toybox source files) are apparently is strongly discouraged by the standard. shrugs
441 Overlaping copies are allowed.
442 Automatic marks created sometimes.
443
444vi
445 Notable for it's variety of modes, and it's standard command mode that uses non echoed ordinary keys for common commands.
446 "Visual" editor, a screen oriented superset of ex, that lets you use ex commands.
447 A lot of the standard simply refers to ex.
448 Seems to mostly be similar to ex commands, only done full screen, and with full screen navigation.
449 Has "open" and "visual" modes, but not sure what they are. Also "ex" mode, with means using ex commands.
450 I think "open" mode is for dumb terminals, it's all done on the bottom line, perhaps with full screen redraws.
451 "Visual" mode then must be full screen editing.
452 Text input mode can return to command mode with Esc.
453 Has five kinds of "words" and four kinds of "bigwords", six types of "sections", four types of "paragraphs", and three types of "sentences".
454 There can be a multi digit count before commands, it's not echoed anywhere when not in a command line mode, the command key then does its command count times.
455 For instance typing "12h" does not echo anything, but just moves the cursor back 12 places when the "h" is hit.
456 Lots of those seem to be letters, or control keys, though there are others.
457 [count] ! motion shell-commands <newline> run a shell command, replacing count lines with the output. Looks like you get to type and edit the command while you see it.
458 Move to matching brace.
459 Repeat last command, for specific commands.
460 Move to last context, where I think "context" means where we was before the last command, it gets a special mark.
461 Move to words, bigwords, sections, paragraphs, etc.
462 Reverse case.
463 Find character in current line. Move cursor to before / after specific character.
464 Move to top / middle / bottom of screen.
465 Insert empty line above / below.
466 Paste above / below, depending on if the buffer is line or character mode as well.
467 Replace count characters with the entered character.
468 Undo current line.
469 Some editing command keys while in text input mode.
470
471nano
472 Has a file browser mode.
473 Has a title bar, with three areas for showing status type info.
474 And a status line, which shows messages and lets users type stuff like file names.
475 Optional shortcut lists show 12 of the most common keystrokes in the current mode, and can be mouse clickable.
476 Mouse moves the cursor, double click sets marks.
477 "Smart" home - the usual go to first non blank, or go to actual start of line.
478 Tabs to spaces.
479 Multiple file buffers.
480 Search and replace history.
481 Deal with DOS / Mac line endings sanely.
482 Restricted mode.
483 Smooth scrolling.
484 Setting tab size.
485 Syntax highlighting.
486 Display cursor position.
487 Backspace and delete fixes, coz that's always confusing.
488 Autoindent.
489 Optional line wrap.
490 "Soft wrapping", no idea what that is.
491 External spell checker.
492 Undo and redo.
493 Hard to use method to insert otherwise unusable characters.
494 Optional search case sensitivity.
495 Optional regex searches.
496 Email quote handling.
497 Source code bracket handling of some sort.
498 Turning command line options on and off within the editor.
499 Write selected text to a file.
500
501microemacs (microGNUemacs lol)
502 Go to line number.
503 Scratch buffer, help buffer, grep buffer, compile buffer.
504 Named buffers - per file. Can have their own working directory, or a global one for all.
505 Kill a named buffer, prompting if it's changed.
506 List buffers.
507 Has the concept of "modes", default ones are - fill (wrap), indent, overwrite, and notab.
508 Can set a list of (minor?) modes as default for buffer creation.
509 Run a script (commands from a file).
510 Split windows. B-)
511 Window / buffer specific cursor and mark (depending on which emacs you have).
512 Can swap them.
513 Esc key same as Alt-key.
514 Get help, describe binding, describe key briefly (hit a key, it's binding is displayed).
515 Apropros - prompt the user for a string, open help buffer, list all commands with that string.
516 Auto execute - a shell glob pattern that is matched on files read into buffers, then executes a command.
517 Recenter - position cursor in center of screen / center of line / center of line counted from the bottom.
518 Open line - open up some space by inserting empty lines below cursor, leaving cursor at the top of them.
519 Quoted insert - insert the next key verbatim, ignoring what it's bound to.
520 Universal argument - repeat the next command 4 times, can apply to itself.
521 Toggle read only.
522 Find file read only.
523 Find alternate file - loading a different file into the current buffer, erasing the original buffer contents.
524 Find file in buffer, or load it into new buffer, then switch to it.
525 Find file other window - opens file in new buffer, splitting the window if needed.
526 Delete window.
527 Delete other windows.
528 Split window.
529 Enlarge / shrink window.
530 Next / previous window.
531 Scroll other window - scrolls the next window X pages.
532 Switch to buffer other window - "switch to buffer in another window"?
533 Switch to buffer - ask which buffer should be in this window.
534 Switch to a shell screen, and back again.
535 What cursor position - show a bunch of info about cursor position and what's there.
536 Next / previous error.
537 Dired - basically a multi window MC. lol
538 Save some buffers - looks for buffers that need saving and prompts user.
539 Just one space - delete all white space around cursor, then insert one single space.
540 Query replace - an interactive search and replace. Also a replace all with no interaction.
541 Oh nice - can do a search and replace with a regex for both the search string, AND for the replacable strings (selecting which ones get replaced with that regex).
542 Beginning / end of buffer.
543 Capitalize / upper / lower word.
544 Delete word.
545 Delete blank lines.
546 Delete horizontal / vertical space.
547 Delete leading / trailing space.
548 Delete lines non / matching regex after cursor.
549 Hmm, difference between "kill" and "delete"?
550 "Kill" goes into the kill buffer, "delete" just vanishes.
551 "Yank" inserts things from the kill buffer.
552 Kill buffer is a ring buffer in full emacs, but might not be a ring in microemacs.
553 So it's just an old fashioned concept for "cut and paste".
554 Fill paragraph - just means to wrap and justify it. Command to ask the user what the wrap column is.
555 Copy region as kill.
556 Execute extended command - does the readline thing to ask user for a command and arguments to run.
557 Execute one buffer / line.
558 Not modified - turn off the modified flag in current buffer.
559 Blink and insert - insert a character, then search backwards for it's match (bracket, or the character itself) and blink that.
560 Mini buffer - it's just a readline for command arguments and such, but treated as a one line window, with an uneditable prompt.
561 It does have the trick of expanding to more lines if it's content goes over multiple lines.
562 The prompt can include a default argument in ().
563 Numbers can proceed commands, seems to be what the universal argument is for.
564 Looks like they have a key to introduce them, then get put into the mini buffer.
565 "Digit-argument" and "negative-argument" might be the functions for that.
566 Swap Del and BS.
567 C program "mode" - no idea what that involves.
568 Count regex non / matches.
569 Define key (includes a keymap, what ever they are). Can also undefine a key, and there's a "global" keymap. Can also bind keys in specific modes.
570 Meta key can insert 8 bit characters, or not.
571 Keyboard quit - abort current action.
572 Insert spaces instead of tabs.
573 Toggle overwrite / insert mode.
574 Add a prefix string to lines in a selected region. Or set that string.
575 Show working directory in the status line.
576 Refresh screen, including recomputing window sizes if needed.
577 Scroll window without changing cursor position within window.
578 Toggle read only.
579 Undo boundaries?
580 Undo on/off.
581 List undo records for current buffer, in a new buffer.
582
583wordstar (joe, turbo C) - Using joe, which also comes in emacs and pico flavours.
584 Help window, with commands to page through that help text.
585 Something about "inverting" 8 bit characters, but we want to be 8 bit clean. Not a WordStar thing I think. shrugs
586 Ah, for displaying high bit characters in other languages, normally inverts the display, but "as is" mode just prints them normally.
587 Option to auto append a new line at end of files on save.
588 Option to disable the status line.
589 Windowed & buffered like emacs, but for when it's pretending to be emacs.
590 Can be windowed anyway.
591 Split window on same file.
592 Make one window full screen.
593 Can move to hidden windows (hidden when there's not enough space for them all).
594 Horizontal split only.
595 Height change.
596 Multiple files on the command line go to multiple windows.
597 Option to define how many lines are kept on screen between page up / down commands.
598 Option to not use X lines at the top, for embedding in a BBS.
599 Multi level undo and redo.
600 Scrolling.
601 Automatic detection of source code files, other types get word wraping and autoindent by default.
602 Can set left and right margins for word wrapping.
603 Can center between them to.
604 Can manually indent lines, highlighted blocks, or autodetected code blocks.
605 Command to insert a single space while in overwrite mode.
606 Overwrite mode makes backspace just move left, no deleting.
607 File name completion.
608 History. History is described as a single line read only edit window, just like other windows, so the usual commands will work in them.
609 Status line can be edited in the setup string, to add or remove escape sequences that include various things.
610 Also a command to show the cursor position and character code in the status line.
611 Suspend the proggy and go to shell. Actually, I think most editors have this in some form or another.
612 Most seem to use the shell foreground/background thingy for this.
613 Search prompts for the thing to search, then prompts for a bunch of character flags that are search options.
614 One of the options is if this is a replace command, then it prompts for the replacement text.
615 It's regexs are slash escaped.
616 Highlighted block can be sent through a shell filter command.
617 Highlighted block can be un highlighted.
618 Macros keyed by digit, and can be nested.
619 Repeat command, hit the repeat, type the numbers, hit the command you want repeated.
620 Also works with characters.
621 Column select mode.
622 Delete block command replaces the entire column with spaces and tabs instead of deleting.
623 Ctags support, prompt for symbol (default is word the cursor is on), search ctags files, replace the file in the current window with the file ctags points to, and the cursor position of the symbol definition.
624 Shell in a window.
625 Very intersening, the shell output is just appended to the window contents as text that can be edited like every other window. When the cursor is at the bottom of the shell windov, stuff typed in is the next shell command.
626 Filename prompts have a couple of features. Can pass things in and out of a shell command, append to the file, edit a specific fixed section of a file or special file (disk block editing!), or use stdin and stdout (joe in a pipe).
627 Keys can be bound in the settings file.
628
629mc viewer
630 Hex mode.
631 Can search mixed hex and strings.
632 Wrap mode.
633 Raw / parsed mode toggle, as well as formatted / unformatted mode toggle.
634 Parsed mode has the text being processed by some command specified in the config file.
635 Formatted mode converts common formatting stuff to bold / underline.
636
637mcedit / cool edit
638 User menu - run a script, insert result.
639 Mark columns.
640 Bookmarks, toggle, next, previous, "flush" (meaning to remove all bookmarks.)
641 Copy / cut insert clipfile as well as prompting for a file.
642 Highlight all lines with found text.
643 Search for hexidecimal, within selection, for whole words, and in "all charsets".
644 Goto matching bracket.
645 Show line numbers.
646 Find "declaration", back from and forward to declaration.
647 It's ctags support.
648 Change text encoding.
649 Create, invoke, and delete macros (hotkeys).
650 Spell check.
651 Email current file.
652 Sort selected lines.
653 Insert output of shell command.
654 Format (wrap) paragraph.
655 Run external format script on selection.
656 Insert date/time.
657 Half tabs.
658 Persistant cursor position and selection.
659 Visible white space.
660 Optional go beyond end of line.
661 Learn keys.
662 Syntax highlighting.
663 Edit syntax and menu files.
664
665Make the fancy features optional in the "wrap if(constant) around things so the compiler can optimise it out" way that Rob likes.
666 So the basic compile choices are -
667 File / stdout viewer.
668 Editor (the following options might depend on how the "pluggable" part is done).
669 Minimal vi?
670 Nice to have vi?
671 Minimal emacs?
672 Nice to have emacs?
673 Nano?
674 Minimal mcedit/cooledit?
675 Nice to have mcedit/cooledit?
676 Lists.
677 Simple top like.
678 Fancy top like.
679 Simple shell.
680 Fancy shell.
681 Basic MC.
682 Full on MC with all bells and whistles.
683 With the fancy compile options being (only if they are substantial amounts of code to support) -
684 Full popups or mere single line prompts?
685 One pane, or multiple panes?
686 Function key single line 'box'?
687 Menu?
688 Status line?
689 Border texts?
690 Border widgets?
691 Sortable lists?
692 History lists?
693 Progress bar?
694 Shell text substitutions?
695 Scriptable?
696 Learnable keys?
697
698Probably got most of what we need to do screen / tmux / multitail, and other full screen terminal stuffs.
699
700Are we ncurses yet? Or twin? lol
701
702------------------------------------------------------------------------------------------------------
703
704NOTES
705
706From Rob -
707----------
708
709On 06/21/2012 09:28 AM, David Seikel wrote:
710> What are the chances that get_optflags() could be made re usable by
711> toys?
712
713Well, right now you can put a NULL as your optstring and then set
714which->options yourself and call get_optflags().
715
716> For toys that need to make their own little scripting system for
717> example. Currently it seems to want to use the toys global, and I'm
718> not sure if it's safe to screw with that after pulling all of my toys
719> options out of it.
720>
721> Would it get reused like that for shell internal commands?
722
723Already does. In toys/toysh.c function run_pipeline() look for the
724TOYFLAG_NOFORK bit.
725
726This probably needs to be genericized somewhere in lib, but I never got
727around to it.
728
729From Rob -
730----------
731
732I need to write a getline() with cursor control, which means I need to
733query the tty size. The magic for that is:
734
735struct winsize tty = { 0, 0, 0, 0 };
736int ret = ioctl(1, TIOCGWINSZ, &tty);
737
738plus $COLUMNS and $LINES, plus echo -e "\e[s\e[999C\e[999B\e[6n\e[u"
739
740Add command history parsing to getline().
741
742From Rob -
743----------
744
745Digging up ancient issues from toybox development, one of which is an
746interesting design issue with querying the terminal size.
747
748When you're on a serial console (happens a lot in the embedded world),
749the local tty device doesn't know the width and height of the window at
750the far end, so ioctl(TIOCGWINSZ) can't report it to you.
751
752If the term program at the other end supports ansi escape sequences
753(everything does, including xterms), there's an escape sequence you can
754use to ask it, but there's multiple levels of non-obvious to the
755implementation.
756
757The escape sequence itself is "\e[6n", to which the terminal program
758responds with another escape sequence, "\e[YY;XXR" where the "XX" part
759is a decimal number with the current cursor's Y location, and XX is the
760cursor X location. (Both decimal, top left is 1;1.)
761
762Since what we want is the size of the screen, we wrap that in some more
763commands, saving the current position, moving to the cursor 999 down and
764999 to the right (which should stick it at the lower right corner),
765query that position, and the jump back to the saved location. The full
766escape sequence is therefore "\e[s\e[999C\e[999B\e[6n\e[u".
767
768The problem is, the response comes back from the terminal program on
769stdin: along with whatever else is coming in on stdin. There could be a
770delay of a significant fraction of a second (especially through a rial
771port, even when you aren't overcommitted and swapping), and there's no
772guarantee the terminal will actually respond. So blocking and waiting
773for a response isn't the greatest idea, and can eat other input the user
774has queued up.
775
776This means you need to do a nonblocking read, assemble an ansi sequence
777a piece at a time (luckily the term programs generate these atomically
778so you don't get part of an ansi sequence with user-typed keys in the
779middle of it), and keep any other data you get for use later. The
780logical place to do this is in the line editing code the shell has to
781have anyway, which responds to cursor keys, page up and down, and so on.
782
783From Rob -
784----------
785
786Less has to get it _right_, as does line editing for a command shell.
787Even before you get to cursor up: unix tty handling is epically crappy.
788My commodore 64 could backspace past the left edge of the screen and
789continue from the right edge one line up. A TRS-80 could do this. Unix
790derivatives _can't_, you have to know when you're at the left edge of
791the screen and do the ansi sequences for "cursor up one, jump right
792999". Which means you have to know when backspace puts you at the left
793edge of the screen, which means you need to know when outputting normal
794characters put you off the _right_ edge of the screen...
795
796That's right: if you don't know what your current screen size is, your
797command shell can't backspace past a line wrap. Welcome to unix
798terminal handling.
799
800From Rob -
801----------
802
803Here's a fun one:
804
805cat /proc/mounts | less
806
807When less outputs the escape sequence to query terminal parameters, it
808has to peek not stdin but /dev/tty. Except the cursor keys scrolling up
809and down also come from /dev/tty, as do "user hit forward slash and
810wants to type in a search regex"... Innit fun?
811
812Plus you have to figure out the width of what you're outputting, which
813means isprint() and probably UTF8 awareness... (Flashbacks to
814fontmetrics in java 1.1, but we can assume monospace text grid...)
815
816From Rob -
817----------
818
819Alas, POSIX does not seem to like simple. To start with, the spec
820requires "more" to be terminal aware, which isn't entirely surprising
821given what it does. But it's not just _height_ aware, it's width aware
822too.
823
824It's actually kinda fiddly: more needs to be able to wrap lines at the
825screen size to figure out when to prompt, but the first 32 ascii
826characters (all the stuff below space) don't consistently print one
827character. Some print nothing, some move the cursor around (tab,
828newline, linefeed, backspace, form feed, whatever the heck "vertical
829tab" does...)
830
831In theory I can hijack catv and just escape most of the low-ascii
832weirdness (so it's two characters, but it's _consistently_ two
833characters whatever $TERM thinks). In practice, when not hooked up to a
834tty more is supposed to act like cat and pass data through unmodified...
835
836I plan to do the simplest standards conformant implementation I can, and
837every once in a while I go "you know, the standard's nuts, let's just
838document the divergence"...
839
840
841From Rob -
842----------
843
844Keep in mind that Unix doesn't implement backspace sanely (like the
845commodore 64 did), thus you have to figure out when you're at the left
846edge of the screen (keeping track of your cursor position)
847
848That's why if you do "echo -n this will screw bash up" and then cursor
849up a few times bash's command history gets all wonky because it _thinks_
850it knows where the cursor is but actually started farther to the right.
851(I contributed ansi escape screen position querying code to busybox to
852improve the situation for ash.)
853
854From Rob -
855----------
856
857The question here is how much of this we already need to do for shell
858history, which is what I was going to implement first. (Actually the one
859I've already sat down and wrestled with is "more", which turns out to
860have rather a lot of these issues as well. Knowing what printable
861characters actually _print_ so you know where your darn cursor is and
862where the screen wraps. You'd think less would have more issues here,
863but more actually hits just about all of 'em...)
864
865Moving the cursor isn't the issue. Querying the screen size is a
866reasonably contained issue. Knowing how the cursor will move when you
867print out an arbitrary string: that's the hard part. (utf8 awareness is
868kinda required here. And I'm assuming a monospaced font even in klingon.
869And replacing the !isprint() characters below space with escape
870sequences...)
871
872
873From Rob and others -
874---------------------
875
876http://lists.busybox.net/pipermail/busybox/2008-October/067348.html
877
878http://lists.busybox.net/pipermail/busybox/2009-May/069314.html
879
880From Rob -
881----------
882
883Implementing ascii programming in the library itself was what I was
884referring to. (It's on my todo list...) All sorts of stuff needs it:
885more, toysh, vi... Even ls wants to know the width of the screen for -C
886mode.
887
888The problem is parsing the replies, since the user could type arbitrary
889stuff. It's stdout that needs to be a tty (because "ls | blah" is not
890going to a tty even if stdin is a tty), but the input _could_ come back
891in on stdin if that's another filehandle to the same tty... as could any
892other random input. If you're filtering all your input through a line
893reading function that needs to parse cursor keys to implement command
894history, doing this is easy. But if _all_ you care about is the probe
895response and you want to leave the rest of the input alone, it's kinda
896hard.
897
898What I might wind up doing is adding it to toysh and having that export
899COLUMNS and LINES environment variables. It wouldn't catch resizes in
900the middle of a command, but I think I'm ok with that...
901
902
903------------------------------------------------------------------------------------------------------
904
905/*
906key / mouse -> command
907menu choice -> command
908border click -> command
909popup + args -> command
910typed string -> command
911script call -> command
912script callback -> command
913C call -> command
914
915Arguments - should use the same argument defining stuff as used by the toys.
916 Keys and menus have to have fixed arguments, and take the rest from their content.
917 Popup and typed get their arguments from what the user selected in the popup, or typed.
918 Popup is told what it's widgets are and how they map to arguments.
919 Popups eventually construct a command string.
920 Script call uses generic text to call the command and set it's arguments.
921 Script callback should be similar.
922 C calls can call the functions direct, or even just pass a string command.
923
924So every command call involves it's content, and can take default arguments from that content, to be overridden by arguments.
925Keys and menus just have arguments coded into their string on definition, though might mostly be argument less.
926Popups have a structure that defines their argument widgets, and how to turn them into command arguments.
927Popups need to be created from string commands to.
928Typed commands can just have their arguments as part of the typed string.
929Scripts and callbacks just send a string that is treated the same way as typed commands.
930C can do the same as scripts, but should be able to call things directly.
931
932Sending commands back to scripts, should use the same format as our commands.
933
934Would be nice to have parameter substitution to, but that would have to be per content.
935
936Use an event system.
937
938---------------------------------------------
939
940Events
941 keystroke / mouse click
942 menu item select
943 timer
944 draw all
945 scroll contents
946 box was redrawn?
947 box destroyed
948 leave box
949 enter box
950
951void doScript(struct content *content, char commandString, struct event *event, void *blob)
952
953Define a command
954 name, argsDefinitionString, pointer to C function - void myCommand(struct box *box, char *command, struct ToyboxArguments *args, struct event *event, void *blob)
955
956Define a key
957 keyName, commandString
958
959Define a menu item
960 menuTitle, commandString
961
962Define a border widget
963 borderPosition, borderType, textOrCommand
964
965Define a popup
966 popupName, commandStub, thingThatMapsWidgetsToArgs
967
968Define a script callback
969 name, command, someKey
970
971---------------------------------------------
972
973Script interface.
974
975We might have multiple scripts running, but only one per box.
976 But what if a script wants to split it's box?
977They can't access our data structures, and we can't access theirs.
978All needs to be done via stdin/stdout plain text, which should all look like the commands in the rest of the system.
979
980Scripts can register simple callbacks on these events - key, menu, timer, box destroyed.
981The first three might want to return a damage list.
982The last means that the box wants to be destroyed, but the script gets a chance to clean up.
983
984Scripts need to be able to hook into the damage system, so there needs to be a text representation of damage areas.
985
986boxes <-> script
987
988Boxes knows which script is attached to which box.
989Registering a key for the box is optional, and it's only passed back if it exists.
990A split box gets no key, or can have the key optionally sent with the split command.
991 So how does the script deal with stuff coming from multiple boxes?
992
993<- keyForBox someKey
994<- registerKey keyName, commandString arguments
995<- registerKey keyName, callBackCommand arguments
996user hits a key
997 if the key has a command, execute it.
998 if the command is not one of ours, send it to the script instead
999-> callBackCommand arguments, someKey
1000 otherwise do our command
1001 else
1002 send the key event to the script.
1003-> handleEvent keyName, someKey
1004
1005 In any case, the script might want to change things in response.
1006 Note that it could do these at any time.
1007<- damage x, y, h, w
1008 line
1009 line
1010 line
1011 line
1012-> doneRedraw someKey
1013<- border borderPosition, borderType, textOrCommand
1014<- status line
1015
1016 *
1017 */
1018
1019
1020struct function
1021{
1022 name // Name for script purposes.
1023 description // Human name for the menus.
1024 type
1025 union
1026 {
1027 *scriptCallback
1028 *cFunction
1029 }
1030};
1031
1032struct command
1033{
1034 key // Note that any given context might have different keys for any given function.
1035 *function
1036};
1037
1038struct item
1039{
1040 type
1041 union
1042 {
1043 *command
1044 *menu
1045 }
1046}
1047
1048struct menu
1049{
1050 *items[] // Circular pointer definiton for sub menus.
1051}
1052
1053struct context // Somehow I get the feeling I'm having a failure of imagination here with the menus and function keys. Might be better to manage them seperately per box, but have common ones available? Nano might have a problem with this.
1054{
1055 *commands[] // The master list, the ones pointed to by the menu structs should be in this list.
1056 menu *menu // Can be NULL.
1057 menu *functionKeys // Can be NULL.
1058 // This can be used as the sub struct for various context types. Like viewer, editor, file browser, top, etc.
1059 // Could even be an object hierarchy, like generic editor, which Basic vi inherits from.
1060};
1061
1062char borderchars[][]
1063{
1064 // usual box graphic symbols
1065 '-|+',
1066 // ANSI code for inverse spaces.
1067}
1068
1069struct borderWidget
1070{
1071 text
1072 *clickFunction(int position)
1073}
1074
1075struct border
1076{
1077 *topLeftWidget
1078 *topRightWidget
1079 *bottomLeftWidget
1080 *bottomRightWidget
1081 *leftWidget
1082 *rightWidget
1083}
1084
1085struct damage
1086{
1087 X, Y, W, H // The rectangle to be redrawn.
1088 char **lines // Pointer to an array of text lines, or NULL.
1089 *damage // Perhaps a linked list might be in order, for fast redraws.
1090}
1091
1092struct content // For various instances of context types, in other words, the editor might have several files open, so one of these per file.
1093{
1094 minW, minH, maxW, maxH
1095 *context
1096 *handleEvents() // Should set the damage list if it needs a redraw, and flags if border or status line needs updating.
1097 // Keyboard / mouse events if the box did not handle them itself.
1098 // DrawAll event for when drawing the box for the first time, on reveals for coming out of full screen, or user hit the redraw key.
1099 // Scroll event if the content wants to handle that itself.
1100 // Timer event for things like top that might want to have this called regularly.
1101 *doneRedraw() // The box is done with it's redraw, so we can free the damage list or whatever now.
1102 *delete()
1103 // This can be used as the sub struct for various content types.
1104};
1105
1106struct contentData
1107{
1108 *border // Can be NULL.
1109 *statusLine // Text of the status line, or NULL if none.
1110 offsetX, offsetY, W, H // Offset and size within the content, coz box handles scrolling, usually.
1111 bool redrawStatus, redrawBorder
1112 *damage // Can be NULL. If not NULL after content->doneRedraw(), box will free it and it's children.
1113 void *data // The content controls this blob, it's specific to each box.
1114}
1115
1116struct box
1117{
1118 box *sub, *parent
1119 bool noBorderOnFullScreen
1120 bool horizontalSplit // Marks if it's horizontally or vertically split.
1121 splitProportion // proportion of this boxes part of the split, the sub box gets the rest.
1122 *content
1123 contentData // Data blob specific to this box, passed to each content function. For sharing contents, like a split pane editor for instance. Not a pointer, but the struct.
1124 X, Y, W, H // Position and size of the box itself, not the content. Calculated, but cached coz that might be needed for speed.
1125 cX, cY // Position of the content within the box. Calculated, but cached coz that might be needed for speed.
1126};
1127
1128box root; // Always a full screen, parent of the rest of the boxes, or the only box.
1129box current;
1130bool currentIsFullScreen;
diff --git a/BUGS.txt b/BUGS.txt
new file mode 100644
index 0000000..87c3d4b
--- /dev/null
+++ b/BUGS.txt
@@ -0,0 +1,6 @@
1xterm current box characters are wrong
2joe - ^K^D not working, but ^Kd is
3 Even odder, ^D works, all other ^K^? combinations work.
4F1 seems to not work, at least under xterm.
5
6should clear the command line prompt when not in use