scScript Ed Package
Functions in the Ed package generally deal with scEmacs and its
buffers. Most will indicate a particular buffer with
a BN (Buffer Number) obtained from Ed.ReadFile
or Ed.GetBuf. But they can also use 0
(default) to mean the latest Cur buffer (from
Ed.SetCurBuf) or *Output* if
no Cur was set. (Write/Writeln/Print will print to stdout
(gdb, terminal, etc.) if BN is -1!)
Many functions accept a P (Position), which will be the
scEmacs CursorPos for visible buffers, where new text is
written to. This number can be based on #Byte (default) or #Char units,
depending on the optional F (Flag). These will only
diverge if the buffer contains UTF-8 (multi-byte) characters. In either
case, P defaults to 0 while -1
indicates the buffer EndPos.
Some functions will indicate a range, using S (Start,
defaults to 0) and E (End, defaults to -1)
values. S is just a position, so is indicated in #Byte
(default) or #Char units. But E can be a position, same
units as S, or a len count of E (#Byte or
#Char) steps from the originating S. An E of
-1 (default value) indicates the
buffer EndPos, whether as position or len. The
optional F (Flag) will indicate #Byte (default) or #Char
units along with #Pos (default) or #Len counts.
Note: When using the *Output*
buffer, EndPos will be the current
end-of-buffer when the function is called.
This EndPos will advance as the script runs and writes
additional information to the buffer!
| Functions: | |
|---|---|
| ReadFile BN = Ed.ReadFile(FStr, F) |
Opens named file (FStr) in scEmacs and returns its buffer number. Will show (attach to a Pane) if #Show flag in F. FStr is required (may include filepath), F is optional. Buffer number is (Int64)BufferP from scEmacs. F can be #Show or #NoShow (default). |
| SaveFile X = Ed.SaveFile(BN, FStr) |
Saves/writes specified scEmacs buffer (BN). If FStr (may include filepath) is given, writes BN buffer to it. Returns 1 if successful, 0 otherwise. |
| GetBuf BN = Ed.GetBuf(NStr, F); |
Opens/Creates named buffer (NStr) in scEmacs and returns its number. Will show (attach to a Pane) if #Show flag in F. NStr is required, F is optional. Creates a new *TEMP-n* buffer if NStr is 0, NULL, or "". NStr can also include a path if necessary. F can be #Show or #NoShow (default). |
| SetCurBuf X = Ed.SetCurBuf(BN, P, F); |
Sets Cur buffer to BN, sets its cursor position to P, then returns 1. Routines use this Cur buffer if their BN parameter is 0. P, if given, defaults to #Byte, but can be #Char if flagged by F. P of -1 means EndPos of buffer (see note above). F can be #Byte (default) or #Char. |
| ShowBuf X = Ed.ShowBuf(BN, P, F); |
Shows BN buffer, sets its cursor position to P, then returns 1. P, if given, defaults to #Byte, but can be #Char if indicated by F. P of -1 means EndPos of buffer (see note above). F can be #Byte (default) or #Char. |
| ShowBufSel X = Ed.ShowBufSel(BN, S, E, F); |
Shows BN buffer, sets cursor SelRange, then returns 1. S (Start) specifies beginning of range, defaults to #Byte pos. E (End) specifies end of range, also defaults to #Byte and #Pos. Both can be in #Char units, and E can be a #Len if indicated by F. E of -1 (default value) means EndPos of buffer (see note above). F can be #Byte (default) or #Char + #Pos (default) or #Len. Note: Only buffers shown in a Pane can have a SelRange! |
| Print X = Ed.Print(BN, "%ld", V); |
Does C-style printf to BN buffer and returns printed byte count. scScript Ints are LONG, use %ld, %lx, etc. Both %f and %lf will work. (Ed.Print uses libffi to call into libc... Prints to stdout (debugging) if BN is -1. |
| Write X = Ed.Write(BN, U, V, W...); |
Writes out concatenation of subsequent IN args to BN buffer. Return total number of bytes written. Write accepts any valid value! |
| Writeln X = Ed.Writeln(BN, U, V, W...); |
Same as Ed.Write, but adds an extra \n at the end. Write and Writeln print to stdout (debugging) if BN is -1. |
| Xfer L = Ed.Xfer(DBN, SBN, S, E, F) |
Reads SBN buffer from S to E and writes it to DBN buffer at its Cursor. Returns number of bytes transferred. S (Start) specifies beginning of range, defaults to #Byte pos. E (End) specifies end of range, also defaults to #Byte and #Pos. Both can be in #Char units, and E can be a #Len if indicated by F. E of -1 (default value) means EndPos of SBN buffer. F can be #Byte (default) or #Char + #Pos (default) or #Len. |
| ScanN E = Ed.ScanN(BN, P, F)(N); |
Reads number N (Int or Flt) from buffer BN at byte pos P. Returns E (EndPos of N) if successful, or 0. Can read +/-, Decimal, Octal, and Hex. (Flt in Dec/Hex only). F defaults to #Sep, use #NoSep to read without separators. |
| Del X = Ed.Del(BN, S, E, F); |
Deletes specified range from BN buffer and returns deleted bytecount. S (Start) specifies beginning of range, defaults to #Byte pos. E (End) specifies end of range, also defaults to #Byte and #Pos. Both can be in #Char units, and E can be a #Len if indicated by F. E of -1 (default value) means EndPos of buffer (see note above). Ed.Del() will zap the entire current contents of Cur (or *Output*)! F can be #Byte (default) or #Char + #Pos (default) or #Len. |
| Read Str = Ed.Read(BN, S, E, F); |
Copies the specified range from BN buffer into a Str and returns it. S (Start) specifies beginning of range, defaults to #Byte pos. E (End) specifies end of range, also defaults to #Byte and #Pos. Both can be in #Char units, and E can be a #Len if indicated by F. E of -1 (default value) means EndPos of buffer (see note above). Ed.Read() will copy the entire contents of Cur (or *Output*)! (F can be #Byte/#Char + #Pos/#Len.) |
| SetPos X = Ed.SetPos(BN, P, F); |
Sets Cursor Pos in buffer BN and returns 1. P, if given, defaults to #Byte, but can be #Char if indicated by F. P of -1 means EndPos of buffer (see note above). (F can be #Byte/#Char.) |
| BLen X = Ed.BLen(BN, S, E, F); |
Returns byte len of specified range in BN buffer. S (Start) specifies beginning of range, defaults to #Byte pos. E (End) specifies end of range, also defaults to #Byte and #Pos. Both can be in #Char units, and E can be a #Len if indicated by F. E of -1 (default value) means EndPos of buffer (see note above). (F can be #Byte/#Char + #Pos/#Len, but #Byte is silly here.) |
| CLen X = Ed.CLen(BN, S, E, F); |
Returns char len of specified range in BN buffer. S (Start) specifies beginning of range, defaults to #Byte pos. E (End) specifies end of range, also defaults to #Byte and #Pos. Both can be in #Char units, and E can be a #Len if indicated by F. E of -1 (default value) means EndPos of buffer (see note above). (F can be #Byte/#Char + #Pos/#Len, but #Char is silly here.) |
| BPos X = Ed.BPos(BN, P, F); |
Returns byte pos of specified location in BN buffer. P, if given, defaults to #Byte, but can be #Char if indicated by F. P of -1 means EndPos of buffer (see note above). P of 0 (default value) means cur CursorPos of buffer. (F can be #Byte/#Char, but #Byte is silly except if P is 0.) |
| CPos X = Ed.CPos(BN, P, F); |
Returns char pos of specified location in BN buffer. P, if given, defaults to #Byte, but can be #Char if indicated by F. P of -1 means EndPos of buffer (see note above). P of 0 (default value) means cur CursorPos of buffer. (F can be #Byte/#Char, but #Char is silly except if P is 0.) |
| Sel X = Ed.Sel(BN, F)(S, E); |
Sets S and E to current SelRange in BN buffer and returns 1. If no sel, sets S and E to a 0-len interval at CursorPos and returns 0. (F indicates desired #Byte/#Char + #Pos/#Len for S and E.) |
| Echo X = Ed.Echo(U, V, W...); |
Writes out concatenation of all IN args to scEmacs Echo line. Return total number of bytes written. |
| QueryMC X = Ed.QueryMC(PStr, CStr); |
Prompts user for multiple-choice selection in scEmacs Echo line. (Pauses script until user enters valid choice or aborts.) Required PStr should present prompt and response chars. Required CStr contains lower-case response chars in order. Will return 0 if aborted (^G) then M-x script-resume. Will return 1..N index for valid selections from CStr. Example PStr: "Copy selection? [YN.!]:> " and CStr: "yn.!". |
| Defs: | |
|---|---|
| Unit flags | #Byte (default) or #Char |
| Count flags | #Pos (default) or #Len |
| Action Flags | #Show (default, usually) or #NoShow (leave hidden) |
| Number Flags | #Sep (default) to accept thousands separator, #NoSep if not. (Uses decimal and separator char defined in sc Params!) |