Purpose To shift a substring at given positions; to insert, overwrite, delete, or replace a string also at positions or each occurrence in the entire lines in one large text file. Its significance is that although itself the task can be made with a right text editor, this program will work even when all the others just crash or hang out because of the large size of the file. One step can be carried out only one operation, more actions are feasible in the successive steps of process. The adjusting can be limited to certain lines with an optional condition added to the operation, otherwise all lines, except the empty ones, will be adjusted.
Usage It is to be launched in Command Line as follows:
=> atl input output {statement | *} [/E] [/S]
Input Any MS-DOS named, but TXT-type file even if it has other extension as .TXT, or has not any. The full name should be given; may be supplemented by the path.
Output It is created with the given name from the input lines transmitted as a TXT-type file even if its name has no .TXT at end. The program does not overwrite its input, so you can just give different paths to the same name.
Parameters The operation to be performed can be described by one ATL-statement which is written into a 1-line text file. The name of this file is arbitrary but must be valid MS-DOS name. You must not, however, store all the usable statements in different files: you may collect all the best tried statements into one package, and before use, place the actual line on top of the pile, with which the step is run. It is possible, because the program ignores all lines but first. Therefore:
statement = name of the file in which the first line contains the ATL-statement to be executed;
* = in.BAT procedures, it is convenient to write the statement for steps before them into the DOS Environment instead of a file;
/E = this option removes all blank lines, those that were emptied by the ATL too;
/S = with this option, the program displays the syntax summary screen, you can read below in detail.
2 The SET command If the command line has no filename but has * as the "statement", then the ATL- statement must be entered in this manner:
=> set *=alter |enter |shift ...
that is, the character combination *= is immediately followed by the name of the operation, as well as other parts of the statement in place of .... Important constraint due to the limitations of DOS, that in such a case the statement itself cannot contain equal (=)sign, but this is avoidable with negating of the unequal (#) sign in logical expressions, or with the chr(61) expression in strings.
The ATL-statement
{ ALTER old [WHEN condition] [FILL new ] } { ENTER at [WHEN condition] [FILL plaster] } { SHIFT to,from [WHEN condition] [[FILL patch ]] }
The command begins an operation of the three possible verbs, then one or two operands must follow, finally you may give one or two clauses: one is FILL, other is WHEN; they are optional and may stand in any order.
The FILL clause cannot be used always, the double brackets express this above.
Must be at least 1 space between the syntactical units; leading spaces before the operation indifferent, if any. No matter nor the spelling of the keywords, the upper or lower case letters may be mixed either.
Operands old ::= string at ::= numerical expression to,from ::= constant number new | plaster | patch ::= string condition ::= logical expression
The expressions must be written in dBase Application Development Language (ADL), which is very concise and simple, similarly to the BASIC, and a small subset is enough to write an ATL-statement: the subset is included in the Appendix, but let us mention here that the term string simple means series of characters, one after other.
Processing The program copies lines of the input to the output, either unchanged or modified with the specifyed operation: the blank lines remain unchanged, and in case of WHEN clause those ones too which do not satisfy the condition, moreover those that are short for execution of the required action.
If long-term work accidentally started, you can shoot it with Esc-key to exit the program.
3 The input line is waiting for its fate in the string variable called LINE; by default, the program wants to write the same number of lines as it has read: in case of option /E, however, both the originally blank lines and those which have been emptied because of the processing, will be missed in the output.
Giving positions, values, and conditions in an ADLexpression, you should refer to content of LINE or its substrings; the NL variable can be used to insert standard end-of-line, and I is the sequence number of the actual line.
The spaces disappear at end of output lines, even if they were already there, and if they are caused by the operation.
Operations
ALTER old [FILL new]
Its effect applies to the entire line, operands are strings, the first is obligatory: each occurrence of "old" is deleted, but if "new" is given, it exchanges "old"; consequently the line even longer or shorter can be as it was. If the line has not "old" anywhere, it remains unchanged.
ENTER at [FILL plaster]
Its operand is the position to which the entry is making: the data are entered overwrite the input substring, therefore the length of the line will not change. Note that the position not only may be a constant number, but it can depend on the content of LINE; perhaps for this the best example is:
Enter rat(".",LINE) fill ";" in which the last point is replaced with a semicolon, wherever it was in the line, and if it was not, nothing happens, so what you get it without a WHEN clause.
without a FILL clause the program inserts 1 space, otherwise it uses the total length of the "plaster"; but if this would stretch beyond end of the line, then the plaster is trimmed.
SHIFT to,from [[FILL patch]]
Its two obligatory operands are constant numbers which define the positions of sending and receiving substrings, thus it shifts either to left or to right: in the latter case the resulting gap will be covered with the "patch" which is determined by the FILL clause; if length of this differs from the gap size, spaces are added or unnecessary characters are cut off. Without a FILL the gap will be of spaces. Shift left removes a substring of the line, thus you cannot give such a meaningless FILL clause.
Conditions You can assign a condition to all kinds of ATL-statement in a WHEN clause with a dBase- type logical expression: this, of course, will be limited to the attributes of the input line, so although the Appendix provides a more detailed description of the ADL, the substance can be read here too.
4 You refer to line positions with function SUBS(LINE,begin,length), give numeric constants with digits, give character constants in quotation marks or with function CHR(0..255), use operators, namely relation (> >> > = < << < # $) such as compound (.and. .or. .not.) as the following example illustrates:
Shift 49,61 when subs(LINE,61,1)=chr(30)
Note: Readers familiar with the ADL should also read Appendix at least once.
Error Messages
*Error: Different Names required! [You must not give the same name to neighter files.] File not found!
You may receive one of the messages, since the program stops running owing to any of them.
*Param in Error:
The only one you can receive a variety of messages, because of any error the program exits. The messages are:
SET *=command not prepared [There is * in the command line but SET *=alter|enter|shift ... is missing.] ????????.??? (File Not Found for Specifications) ????????.??? (Not a Valid Text Line) First word (and space) must be ALTER | ENTER | SHIFT Condition omitted (in WHEN) Invalid Logical Expression (in WHEN) String omitted (in FILL) Invalid String (in FILL) Ambiguous definition (in FILL) Invalid definition: ... Invalid Argument: ... Nullstring not permitted [Neither as old, nor as new.] No Altering Defined [Argument of ALTER is the same as of FILL.] Invalid 'at' Specification [In the ENTER statement.] Invalid 'to,from' Specification [In the SHIFT statement.] #,# (No Shifting Defined) Cannot FILL ... while Cutting Data
Commentary Spinning digits you see while running, then a message appears at the end of job in addition to the stopped counter:
You can find a complete description of the Application Developing Language in different FoxBASE and dBase publications, as well as the brochure of Clipper Summer87 by Nantucket. The latter should not be confused with the CLIPPER (5 or so) version by Symantec, which compels you to write in C language even the database operations, so it does not narrate the ADL.
Restriction Comment is not allowed to write anywhere (NOTE, *, &&). If the statement is too long, you can continue its parts by syntactic units in more lines: before a keyword or an operator in the text can break and can be applied on a new line; then put one semicolon at end of the previous line to indicate the continuation.
Variable Like the BASIC it is created by an assignment, but its content determines its type too. The ATL-statement can refer only one character type, that is, string variable known as LINE which contains the input line. It is also possible to use the above mentioned NL (newline) and I (sequence number) variables. Do not forget, NL contains two control characters: chr(13)+chr(10).
Constant String: it is none, or 1, or any more characters in quotation marks, within which the quotation mark itself is forbidden; for reasons of convenience, therefore, one reflected pair and two others, altogether four characters serve as quotation marks: [ ] ' " ' " ' " ' " Thus in each string-constant there may be, except enclosing, the other two or three quotes: ' '' '[" "" "]' '' ' " "" "]' '' '[" "" " [' '' ' " "" "] The empty string is so called nullstring when the quotes are standing directly side by side having nothing between them; nothing differs from space. The expression given string is also constant, for example, this two-term expression may be the so called subfield-lower-case-bee identifier of a particular representation in certain coding:
chr(hex(" "" "BA" "" "))+" "" "b" "" " This is equivalent to chr(186)+" "" "b" "" " code, but can be used as the " "" "b" "" " notation if you do not care that the first symbol depends on the operating system's code page. Do not, however, quote a control character, because in printing, either they do not seem, or cause unwanted effects.
6 Number: To write ATL-statement you need not the features of ADL except positive integers, of which size is comprehendly limited to 32767 by the ATL Utility, because that is the longest line size can read in. Other limit may be likewise, because characters range up to 255. In the above examples, both 186 and hex(" "" "BA" "" ") are constant numbers. (Also nicknamed as numeric.)
Operators Connect terms of expressions; type of the terms must be identical so there are two categories. String: + or - connecting operators combine the terms into one single string. The effect of - impacts you a little, it should not be used generally: if terms do not have idling swinging spaces at their right side, it does not differ from the results of + but if they have, all that spaces are moved from their original location to rightmost positions of the new string. Number: the usual five basic operators + - * / % (mod, remainder: %)
Relators Are nicknamed as relational operators or relation signs: < = > # $ In addition to the usual signs, # states unequality and $ is the operator of occurrence. Relators build logical expressions, their result is always logical: true or false. There is a significant restriction on terms of $: they must be strings, while the other relators are valid on numbers too; the type of terms should always be the same. Note that if you are not sure what is going to happen you can use the == exactly equal operator in case of strings, and the following example illustrates application of the $:
" "" "LINE" "" "$ LINE true if the LINE occurs anywhere in the string named LINE, or false otherwise. It will also be true if LINES may be found. This would be limited with " "" " LINE " "" " constant. You know, [LINE] never equals to [Line].
Connectors Are compound logical operators, do not worry about, you can create connected logical expressions with them: .and. .or. .not. Type of terms here can only be logical. Instead of .not. you may write an exclamation point, but it is not always advisable! Do not go into the precedence rules now, quite as much that in arithmetic and logical expressions, the redundant parentheses always reach to happen what you expected.
Expressions Are either compound having much term or single, consisting of two terms; type of terms must be the same. After all, depending on the result, the type of an expression is either number, or string, or logical. As the ADL subset is used to describe condition of WHEN in an ATL-statement, it is clear that your expression must provide logical result.
Functions create almost all the terms of your expression, those may result either string, or number, (or logical) product and of which arguments also fall into these types: do not confuse type of a given function with type of whichever argument of it, if it has more. Only an important subset of the functions is described in alphabetical order within the types, and the last capital letter of the lowercase model denotes the type of argument:
7
MODEL(withinC,thisC,fromN) illustrates the function MODEL has three arguments, "within" and "this" are string, and from is number. Type of the function itself (= return value), however, turns out that which group of types contains it. (It is suspected this would be number-type, but unfortunately it is only a sample, there is no such a function... Truly, there is in the BASIC!) Therefore the last (capital) letter of models means: C = string N = number [L = logical]
In the ADL, there are logical functions too but those are ignored in this subset.
List of Functions by Types String: CHR (codeN) Returns one character which is specified by value 0..255 of code.
LEFT (LINE,countN) Returns characters from left side: if argument 2 is 0, the result is empty; if greater than length of argument 1, original string is returned.
REPL (whatC,repeatN) The argument 1 is repeated times argument 2: if argument 2 is 0, the result is empty.
RIGHT (LINE,countN) Returns characters from right side: if argument 2 is 0, the result is empty; if greater than length of argument 1, original string is returned.
SPAC (countN) Returns spaces: if the argument is 0, the result is empty.
SUBS (LINE,begiN[,lengthN]) Returns a part of string (substring): if argument 3 is missing, or greater than length of argument 1, returns characters up to the end of string; if argument 2 is 0, it is changed to 1. Either if argument 3 < 1, or argument 2 greater than length of argument 1 or it is negative, the result is empty.
Number: ASC (whatC) Returns code value 0..255 of specified character (from string, the leftmost).
AT (whatC,LINE) Returns first position of argument 1; if it has not occurred in argument 2, the value is 0.
HEX (notationC) The numeric value of string is returned. The upper or lower case form of hexadecimal digits is indifferent. In ATL-statement, you can only use the " "" "00" "" ".." "" "FF" "" " range.
INT (expressioN) Integer part of the argument is returned. (It is often used in divide operation.)
LEN (LINE) The length of the argument is returned.
RAT (whatC,LINE) Returns last position of argument 1; if it has not occurred in argument 2, the value is 0.
8 VAL (expressionC) Returns the value of the argument if it contains only digits or starts with digits, else returns 0. The - sign is handled.
Other useful functions String: BACKWARD (expressionC) Subtracts code value of each character of argument from 255, one by one, then creates new character with this code value and exchange original characters to the new ones. (Inverted bits.)
DESCEND (expressionC) Subtracts code value of each character of argument from 256, one by one, then creates new character with this code value and exchange original characters to the new ones. Complementer characters except zero.
STR (expressioN,[lengthN[,decimalsN]]) Transforms argument into string; if necessary, puts leading spaces. Reserves place for minus sign, thus numbers not less than 0 are returned with least one space.
STRZERO (expressioN,lengthN,0) Returns length width string in which the argument is right justified, with leading zeros if necessary. You cannot omit third parameter because then ".00" is going to end on the result (2 decimal places).
TRAN (expressioN,templateC) Transforms argument into edited string in accordance to what the editing image of "template" defines. Here we cannot go into detail, each template and functional character of PICT clause in @ SAY command of dBase screen editor can be used according to those rules, see there. An example: TRAN(val(subs(LINE,11,4))," "" "@Z 9999" "" ") returns value of 4 characters in positions 1114 of the line as four-digit number, with zero-suppression.
TRIM (expressionC) Cuts ending spaces of the string.
LTRIM (expressionC) Cuts leading spaces of the string.
ALLTRIM (expressionC) To avoid having to write TRIM(LTRIM(expC)) or LTRIM(TRIM(expC)) ugly monsters...
Mixed: IIF (conditionL,on_true?,on_false?) Type of this function is mixed as its return value depends on argument 2 and 3; when an assignment uses the return value, it is not a problem because in the ADL the type of a variable also may be changed: in ATL statement, however, care should be taken to avoid mixed-type expression, since it is never allowed. If the argument 1 is true then the function returns value of argument 2, else it returns value of argument 3.
Miscellaneous: integerN = INT_UTF(encodedC) Returns numeric value (0..65535) of the 1, 2, or 3-byte UTF-8 code. Invalid argument results a negative number: -3 = too long; -2 = irregular; -1 = empty.
9 encodedC = UTF_INT(integerN) Inverse of the former: returns UTF-8 encoded 1, 2, or 3 bytes of any numeric value between 0..65535. Invalid argument results nullstring ("" "" "" "").
arabicN = CRA(romanC) Returns value of Roman numerals from " "" "I" "" " to " "" "MMMCMXCIX" "" " between 1 and 3999; the argument may be lowercase too. Invalid argument results zero.
romanC = CAR(arabicN) Inverse of the former, the argument must be a number between 1 and 3999 otherwise empty ("" "" "" "") is returned.
hexadecimalC = XE(integerN) Inverse of above described HEX; 4294967295 may be the maximal argument, which results " "" "FFFFFFFF" "" ".
hexadecimalC = XEB(byte_stringC) Returns twice as long hexadecimal representation of argument up to 16K of bytes. [K=1024]
byte_stringC = BXE(hexadecimalC) Inverse of the former: returns half as long byte-string of argument up to 32K hexadecimal digits.
binaryC = BIT(integerN) Returns binary representation of argument consisting of " "" "0" "" " and " "" "1" "" " characters; the greatest may be 32 pieces of " "" "1" "" ".
integerN = BIN(binaryC) Inverse of the former: the argument may be no more than 32 pieces of " "" "0" "" " or " "" "1" "" " character.
Example The program only works with different file names, therefore you copy the parameter misc.txt to inp.txt named, then issue the following commands: atl inp.txt out.txt misc.txt ATL = Adjust Text Lines / Kostyn (R) 2009. 5 Lines processed; 1 adjusted Line. - type out.txt Enter 1 fill ; str(hex(" "" "face" "" "),5,0)+" "" " " "" "+xe(3469655758)+" "" " " "" "+; xe(bin(" "" "0101010110101010" "" "))+" "" " " "" "+bit(21930)+; " "" " " "" "+xeb(" "" "" "" ") WHEN I>4 64206 CECEBECE 55AA 101010110101010 DACA !
The line 5 of the original input file contains all spaces, only on position 52 has included an exclamation point (or any other non-space), because the program does not work with blank lines. The WHEN condition ensures that the 4-line ATL-statement will not be overwritten by the program, so that you can study together both the statement, and the input, and the output.
Attachment How to Get Yours Copy of ATL.exe Extract (CopyPaste) all lines, from next page to very end, into Notepad and save for any Base_64 tool, whichever you can download; then decode: filename have to be ATL.exe as output. Donotprintfromhere!