UP | HOME
CS 7140 2015-07-25

Specs of Entities and Operations within a Programmer's Editor

Table of Contents

I use editors as target examples in Software Engineering courses I teach. The materials below are hence deliberately incomplete. The context of this article is Programmers' Editor

1 Meta Commentary

  1. Specs can be written in ordinary English. Almost always, these are highly ambiguous.
  2. Specs should be written in stylized English. They should be peer reviewed for the elimnation of ambiguity and to check for completeness. Re-read Meyer's Seven Sins of Specifiers.
  3. A certain amount of notations (formalism) always improves communication – when the notation is well chosen.
  4. Even when good notations are in use, always include well written specs in stylized English.
  5. For sequences, we use the familiar array [] notation.
  6. Let q be a sequence. #q is the number of elements in it. q[#] is the last item. q[ 0] is the first item.
  7. These notes implicitly reference items explained in Editors
  8. Please report errors. I am afraid it is not error-free. Ignore spaces within the = = token.

2 Text Elements

2.1 Lines

  1. A line, el, is a sequence of characters ending in '\n'. el[#] == '\n'
  2. Note the ambiguity. Is this "hello\nthere\n" a line?
    1. Excluding the last character, the line should have no '\n'.
    2. What about strange characters, such as control chars, …
    3. for i in 0 .. #el - 1: el[i] != '\n';

2.2 Text File Content

  1. Consider a text file tf. Its content is almost always thought of as a sequence of bytes. This is often the way the OS gives the content of a text file. This content can also be viewed as a sequence of lines.
  2. is-a You probably have heard of this from AI courses.
  3. tf.content is-a seq of lines
  4. tf.content is-a seq of bytes
  5. There is an unambiguous way of mapping back-and-forth between these two: tf.content.lines and tf.content.bytes

3 Buffers

3.1 Buffer Data Type

  1. An edit buffer B has text content, B.content
  2. It may (not must) also have other "things": e.g., cursors, views/ windows, its file name, …

3.2 Buffer Operation: create

  1. create(file-name fnm) returns buffer b
  2. pre: fnm exists
    1. OS responsibility
    2. f := sys-call-open(fnm) + sys-call-read() + sys-call-close(); f non-null
    3. This is depending on "you-know-what-I-mean" and usurping some amount of "how" it is done.
  3. post: b.content = = f.content, f.name == fnm
  4. Requirements Clarification: If f does not exist, create an empty file, then do as above.

3.3 Buffer Operation: save

  1. save() returns file f
  2. f := sys-call-write(this-buffer.file-name, this-buffer.content)
  3. Requirements Clarification: If f is the file from which we created this buffer, silently replace it with new file content. Retain all file permission, file create time stamp etc. File modification is now.

3.4 Buffer Operations: insert, delete, cut, paste, undo, redo, …

  1. A spec should define all the operations.

3.5 Cut- Paste- Buffers

4 Cursors

4.1 Cursors Overview

  1. We use several cursors.
  2. dot and the mark: two must-have cursors
  3. Cursors exist in the buffers and views/windows.
  4. Cursors do not exist independently of a buffer or a window.
  5. A buffer has these cursors, but not necessarily "alive" at all times.
  6. Constraints (also known as invariants)
    1. Let b be a buffer; it has b.dot and b.mark cursors, among others.
      1. 0 <= b.mark.y < number of lines in b
      2. 0 <= b.mark.x < num chars of b.lines[b.mark.y].
      3. All of these constraints go into the class invariant of Buffer, whose data members include dot and mark

4.2 Cursor Data Type

  1. We model a cursor as a pair x,y of numbers as in Cartesian coordinates. In our context, both are always non-negative integers, and the y grows downwards.
  2. Init values: dot = = mark = = (0, 0)

4.3 Cursor Operations

  1. Here are some suggestively named operations: move-right-by-one-char, move-right-by-one-word, move-right-by-one-line, move-right-by-one-sentence.
  2. Similar operations for "left" moves.
  3. In a spec suggestively naming is necessary but not sufficient. Exercises for you!
  4. The specs depend on definitions of word, line and sentences.
  5. The moves are constrained by the buffer that the cursor is on.
  6. Requirements Clarification: What happens if the cursor is at the end of the buffer, and we (try to) move right?
  7. Requirements Clarification: What happens if the cursor is at the right-bottom of the wind, and we (try to) move right?

5 Windows

5.1 Windows Overview

  1. The window content is "visible". We are not using the word in the sense of the Windows OS, or Linux KDE. We mean it as a rectangular area showing the content of some buffer. We can simplify the first sentence to: The window is visible.
  2. Requirements clarification: Unless a window is on a buffer B, the content of B is invisible.
  3. Requirements Clarification: Should we be able to edit B even when B is invisible? Our answer: No. Even though, it is very powerful to say yes.
  4. Requirements Clarification: Do windows overlap? Tiled? Left to the "GUI Window Manager of the System"?
  5. Requirements Clarification: It is perfect to map our windows into Windows OS or Linux KDE windows.

5.2 Windows Data Type

  1. A window W is of width ww, height hh. Window operations may shrink, enlarge, move it relative to the buffer, etc.
    1. ww >= 0, hh >= 0
    2. Forbid == 0? Why? Why not? Requirements clarification?
  2. A window "has" a buffer B. The window content is dictated by this.
  3. A window has dot mark cursors.

5.3 Window Content

  1. The W.content is a portion of the buffer behind it.
  2. We specifiy the content t for the core (i.e., typical) case first. Then, we worry about fringe cases.
  3. W.content is a sequence of bytes. Does not have '\n'.
  4. #W.content = hh * ww
  5. Recall that W slides along its buffer B, only showing a portion of the buffer. From now on, we will visualize the B as a scroll.
  6. Relative to the buffer B, assume that the left-top corner of window W is positioned at (wx, wy).
    1. W.content.lines[ 0] == Buffer.content.lines[wy], assuming h > 0
    2. W.content.lines[i] == Buffer.content.lines[wy + i -1] truncated to ww chars, for i: 0 .. hh - 1, in general
    3. What if Buffer.content.lines[wy + j], for some j, is too short? We pad it with blanks. Let us call W.content.lines[j] by the name el. Then, el = Buffer.content.lines[wy + j] + enough spaces so that #el = ww.

5.4 Window Operation: Place a Window on a Buffer

  1. Case 1: Buffer B has no windows on it.
  2. Case 2: Buffer B has exactly one window on it.
  3. Case 3: Buffer B has > 1 windows on it.
  4. We focus on Case 1 only. Next subsection.

5.5 Window Operation: Place a New Window on a Buffer

  1. createWin(buffer B, width w, height h) returns Window
  2. create a Window object w x h, so that its buffer is B, its dot and mark cursors are at (0, 0), left-top at (0, 0) of B, the content computed from B.
  3. Generally, we prefer "declarative" specs. Some times, it is easier to do this "operationally", as above.

5.6 Window Operation: Delete a Window

  1. Obviously the window is destroyed/ released.
  2. Requirements Clarfications: What happens to the buffer? Does this depend on whether the buf has other windows? Does the window have its own dot + mark? In addition to those of the buffer? Suppose the buffer has only this window, and now it is deleted. If then place a new window on it, should the new window have the last dot + marks?

5.7 Cursor in a Window

  1. Perennial Goal: The dot cursor should remain in the window.
  2. The mark cursor, if possible, should remain in the window. But may not be possible because the window is too small to contain both.
  3. Requirements Calrification: Both of these should have been described.
  4. Spec Decision: Are the (x, y) of the cursors relative? Relative to window? Or buffer?
  5. Requirements Calrification: Assume that the dot is at the right-bottom of the window. User wants to move right. Complain by beeping? Or move/ reposition the window appropritiately, honoring the wish?

6 Key Bindings

6.1 Key Bindings Overview

  1. Let QM be a sequence of public methods. So, e.g., QM[ 7] might be the creation of new buffer based on a file name you are yet to give.
  2. This QM is well defined at compile/ build time. It will not grow or shrink dynamically.
  3. Key bindings specifies what key stroke invokes what method of QM.

6.2 Key Bindings Data Type

  1. Spec predicated on a design idea: Have an array called KB, of size equal to the number of key "codes". For now, let us say we have 256 codes (based on ASCII 8-bit chars).
  2. KB[x] = = QM[i], 0 <= x < 256, for some i.
  3. The value of KB[x] can be changed by the user, at run time, or through a config file.
  4. Requiremenst Clarification: All the above.
  5. Design Suggestion: QM can be an array of pointers to public methods.

6.3 QM Self-Insert Method

  1. There is a Self-Insert Method. It has one parameter – the key code. Effect: inserts at the dot position this character.
  2. Most key bindings are to Self-Insert.

6.4 KB Operation: Display Current Bindings

6.5 KB Operation: Edit Bindings

6.6 KB Operation: Read Bindings from Config File

7 The Editor

7.1 The Editor Overview

  1. Requirements Clarification: Our editor should be able to edit multiple files simultaneously. It should permit cut-n-paste across these.
  2. Requirements Clarification: Our editor truly edits buffers, never files. Buffers are created from files. When a buffer is saved, it replaces the file it was created from.
  3. Requirements Clarification: New files are created by trying to edit a non-existing file.

7.2 Editor Operation: Start

  1. The editor as a process has already begun.
  2. Requirements Clarification: Start operation should resume where the user left off in the last session.

7.3 Editor Operation: Finish

  1. Exits (i.e., terminates) the editor process.
  2. Requirements Clarification: Warn and take helpful actions if hours of work by the user is about to be abandoned. Introduce the notion of last session.

7.4 Editor Operation: Loop

  1. It is essentially a non-terminating loop listening to key strokes and executing method bound to the keys.
  2. To exit the loop, user must invoke Finish.
Copyright © 2015 • www.wright.edu/~pmateti • 2015-07-25