SPFLite

Contents of Article

Operands

Description

Performing joins when a search Picture of P'[' or P']' is desired

Simulating a JOIN with a search string of P'[' or P']'

Simulating a JOIN with a search string of P'[]'

Suppose you really want to JOIN and not just simulate it ?

Line joining and line exclusion

Syntax

Operands

 

Abbreviations and Aliases

PREFIX can also be spelled as PRE or PFX

SUFFIX can also be spelled as SUF or SFX

WORDS can also be spelled as WORD

CHARS can also be spelled as CHAR

 

Description

The JOIN edit primary command is used to selectively combine lines of text based on a search string. After a join occurs, a line on which the from-string is found will be combined either with the line before it, or with the line after it. So, each time a join takes place, two lines of text will become one line of text.

Notes:

• The SPLIT command performs the opposite function, breaking one line into two. See SPLIT - Split Lines Using Find/Change Strings for more information.
• The "joining" action could be termed a "physical" join, without trimming of leading or trailing blanks from any of the lines involved in the JOIN process. In that sense, the action is comparable to what is done by the G and GG "glue" line commands, rather than by the J/JJ "join" line commands or the by text-mode line commands TG/TGG and TJ/TJJ. 
• The effect of inserting text between lines that takes place with J/JJ and TJ/TJJ commands, or with the GLUEWITH command, can be achieved by how the to-string is defined. In that sense, the capabilities of the JOIN primary command are more powerful and flexible.
• SPLIT and JOIN, as new SPFLite technologies, have been extensively tested, but it is possible you may run into issues using them. If you have any questions about how these commands operate, feel free to leave us your feedback on the SPFLite web site.

The from-string describes the join point where the joining operation takes place. Because a join operation joins a given line to the line that precedes it or to the line that follows it, a join can take place at only one of two join points: at the beginning or a line, or at the end of a line.

The from-string may be specified as a Regular Expression, in addition to a Picture string.

The from-string must be either:

• a Picture string in one of the following formats:

P'[string'

JOIN is being asked to perform a left-join operation.  The value of string must appear on the left side of lines within the line range in order to be joined; otherwise any lines not beginning with string will be ignored for JOIN purposes. When a [ Picture code appears in the from-string of a JOIN command, it must appear in the left-most position of the Picture string, and nowhere else.

P'string]'

JOIN is being asked to perform a right-join operation.  The value of string must appear on the right side of lines within the line range in order to be joined; otherwise any lines not ending with string will be ignored for JOIN purposes. When a ] Picture code appears in the from-string of a JOIN command, it must appear in the right-most position of the Picture string, and nowhere else.

• a Regular Expression string in one of the following formats:

R'^expression'

JOIN is being asked to perform a left-join operation.  The regular expression must start with the ^ directive to indicate the left-hand edge of the line. The remaining expression may be any valid RegEx expression. 

R'expression$'

JOIN is being asked to perform a right-join operation.  The regular expression must end with the $ directive to indicate the right-hand edge of the line. The remaining expression may be any valid RegEx expression. 

It is not possible to directly join one line to both the line that precedes it and the line that follows it, at the same time. That is to say, a from-string of a JOIN command cannot be specified in the form of P'[string]' or R'^expression$'. For any given line, only one JOIN, on one side of a line, is allowed. JOIN cannot perform a left-join and a right-join at the same time, since this would imply converting three lines of data into one line in a single join operation, an action that SPFLite does not support. See the discussion below for ways to simulate such complex joins.

Note: Because the from-string must be a Picture or RegEx, there could be cases where you are trying to find data containing characters that are already defined as special-purpose Picture or RegEx codes. If you need such characters treated as ordinary data rather than as Picture codes, you can escape those characters by preceding them with a \ backslash. See Specifying a Picture or Format String for more information. See Specifying a Regular Expression for escaping within a Regular Expression. 

Note: In a Picture string, any character can be escaped with a backslash, whereas in a Regular Expression, only a limited number of "special" codes can be escaped. If you try to escape a Regular Expression character that is not eligible for being escaped, your Regular Expression will not properly match strings in the way you expected. This behavior is caused by the design of the Regular Expression "engine" and is outside the control of SPFLite. Read the Regular Expression documentation carefully on this point.

The from-string must be in exactly one of these two formats. The string value cannot be omitted. That is, you cannot have a JOIN from-string appearing literally as P'[' or P']'. The main reason for this is that the [ and ] codes represent edges of a line, but do not represent actual data values. So, a picture of P'[' or P']' would actually represent a zero-length string, and the string-search engine in SPFLite will not "find" strings of zero length, because there is literally nothing to find. For the same reason, a picture of P'[]' is not allowed either. See the discussion below for ways to simulate such joins.

The to-string is optional. If you omit it, the found-string is copied as is (ignoring the [ or ] Picture code), the same as if a to-string of P'!' was specified. That means the following JOIN commands all work the same way:

       JOIN P'[ABC' 'ABC'        

       JOIN P'[ABC' P'!'

       JOIN P'[ABC'

It is not illegal to ask JOIN to left-join line 1 of a file, or to right-join the last line of a file. Since there is no data to join such lines to, the JOIN request is simply ignored for those lines.

Note:  While the to-string can be a Format string, you will find that using a Picture change string here should address most of your JOIN requirements when the to-string isn't a "simple" change string. Where a Format change string comes in handy is when the from-string is a Picture (as is always true for JOIN), and you need one or more codes of = in the to-string that don't match the corresponding character positions in the from-string.  See Specifying a Picture or Format String for more information. When you have an editing requirement of this kind, you will get an error message if an = code is misplaced in a Picture change string; that is your 'clue' that you need a Format string instead. (These comments about the use of the = codes in Pictures also apply to the related < > and ~ codes, which operate in a similar way and have similar rules.)

See Working with SPLIT and JOIN Commands for example usage of the JOIN command.

Performing joins when a search Picture of P'[' or P']' is desired

As noted above, JOIN will not accept a search Picture of P'[' or P']' or P'[]'. These strings are illegal in JOIN, because they all represent zero-length strings, and P'[]' (if legal) would represent a zero-length line; the string search-engine in SPFLite will not find such zero-length strings or lines, because there is literally nothing to find. Suppose, though, you had some reason doing such joins anyway. How could you go about it?

Simulating a JOIN with a search string of P'[' or P']'

A join of this type implies that you want to join a line to another line, such that the contents of the line itself are not the deciding factor. You probably are not (intentionally) trying to find zero-length lines, but (a) you don't care about the exact contents of the line, (b) your are almost certainly using F5 and F6 (or other keys mapped to RFIND/RLOCFIND and RCHANGE) to selectively join lines because you have to manually inspect each one to decide whether to JOIN it or not, and (c) in case you do run into a zero-length line while doing this, you don't want to be stopped from what you are planning on doing.

Suppose you wanted to selectively find lines, perhaps with the FIND command or by some other means, and when you find such lines (even zero-length lines), you want to join them to the line before or after.

Because the line command G will perform a "physical join" of the line it is on to the line that follows it, it basically performs a function similar to what a right-joining command of JOIN P']' '' would do, if such a command were legal. Let's say you issued some kind of FIND command, and you keep pressing F5 to RFIND the desired line(s). You now want to right join the line - whatever it contains, even a zero-length line - to the line after it. For convenience, let's map the line command G to the Ctrl Shift F5 key. The KEYMAP string would appear as {G}. Then, when you find a desired line, you would right-join it by pressing Ctrl Shift F5.

Performing a function similar to what a left-joining command of JOIN P'[' '' would work basically the same way. However, since the join/glue line commands always perform operations that amount to joining on the right, you would have to turn a right join into a left join by moving the cursor up one line and then issuing a the G line command. Let's map the cursor movement and the line command G to the Ctrl Alt F5 key. The KEYMAP string would appear as (Up){G}. Then, when you find a desired line, you would right-join it by pressing Ctrl Alt F5. So, instead of joining the "current" line to the "previous" line, we move the cursor up one line, and then join the "previous" line to the "current" one - but the result is the correct one.

This technique will also work when one of the lines being joined is a zero-length line. In such cases, the zero-length line is effectively deleted.

Simulating a JOIN with a search string of P'[]'

A join of this type implies that you want to find lines of zero length and "join" them to an adjacent line. However, by definition, since the line is of zero-length, "joining" such a line - whether to a preceding line or to a subsequent line - is the same thing as deleting it. So, you are actually trying to delete zero-length lines by using a JOIN to do it.

You cannot directly "find" strings of zero-length, because as noted above, SPFLite's string search engine will not find zero-length strings, as there is literally nothing to find. However, you can find lines in which no characters are present. This relies on the NFIND command. If you issue a command of the form:

       NFIND P'='

you are asking SPFLite to find lines in which not even a single character (of length one) matching a Picture of P'=' is found. Since a Picture of P'=' represents any character, the NFIND command finds any lines where there are no characters found at all, because the test for finding characters that match the pattern of P'='has failed. The only lines that can possibly meet this condition are lines of zero length. This command is repeatable by using the RFIND or RLOCFIND command (traditionally mapped to F5).

Once you find the desired zero-length lines, just delete them. You could map a key to the {D} delete line command for this purpose, or perhaps you might wish to "mark" such zero-length lines with a special character (like the ? character described below) and then go back and delete all of them with a primary command such as:

       DELETE '?' ALL

If your goal was simply to delete all zero-length lines from a file, the easiest way to do this is as follows, which relies on the NEXCLUDE command, abbreviated as NX. (This is not the only to do it, but it's a good general example.)

RESET

NX P'=' ALL

DELETE ALL X

Suppose you really want to JOIN and not just simulate it ?

The main problem to doing this is dealing with zero-length lines. The easiest way to overcome this is to put some data on those lines so they aren't zero-length any more. One method of doing this is to APPEND a blank to such lines. Appending a blank to a zero-length line will make it a line of length 1. For most JOIN purposes, that should be good enough. Here is a sequence that will 'fix' all the zero-length lines in a file:

RESET

NX P'=' ALL

APPEND ' ' ALL X

The Pad to Length command PL can take a / or \ modifier. Putting PL/ on line 1 of a file will ensure that every line of the file is at least one character long.

Line joining and line exclusion

The JOIN command supports the X and NX keywords, to allow you to limit your line-range selection to only excluded (X), or only not-excluded lines (NX), if you wish. Regardless of the use of X or NX keywords, when a line is joined-to, it is considered a "change" to the that line. 

• When a left-join is done, a given line is joined to a prior line; that prior line is the "joined-to" line. 
• When a right-join is done, a given line is joined to a subsequent line; that subsequent line is the "joined-to" line. 

Any joined-to line that was excluded at the time the join is done will be unexcluded.

The JOIN command does not support the MX and DX keywords at this time.