| Parameter |
Meaning |
| Text |
The Filename (may include (absolute) path) to read from and save to (for all functions that write an output file).
Note: by default a filename_copy will be created, use the ! prefix if you want to OverWrite the TextFile (e.g. the source file)
As of v3 "Text" can also be a variable or indeed text directly passed on to the function.
See Textfile and the ! Prefix.
|
| ! Prefix |
If Text starts with ! (eg: "!c:\sample.txt") it will overwrite the text file, otherwise it will save the new file to a copy of the text file eg: Filename_copy.txt (All functions, apart from reading functions because there is no output file)
Tip: you can use concatenation to add the !, e.g. "!" . "Filename.txt", see the examples in the AHK thread.
Note: If Text is a variable, it can start with a ! as TF will detect automatically that it is not a file and will therefore not create a file but return the altered variable instead.
See Textfile and the ! Prefix.
|
| Lines |
Number of lines to read |
| StartLine |
Start of Range (Almost all).
See (StartLine, Endline) Syntax.
|
| EndLine |
End of Range (Almost all).
See (StartLine, Endline) Syntax.
|
| SearchText |
Text to Find (Find / Replace functions) |
| ReplaceText |
Text to Replace (Find / Replace functions) |
**Notes**
1. Many functions also have specific parameters, see the description of each function below.
2. **Backup files:** If a subdirectory "backup" is present in the directory of TextFile
a backup is made before overwriting the original file (both for file.txt and file_copy.txt)
with the BAK extension
3. You can find examples of most functions in the "example script" here [http://www.autohotkey.com/forum/viewtopic.php?p=280363#280363](http://www.autohotkey.com/forum/viewtopic.php?p=280363#280363)
### (StartLine, Endline) Syntax
You can pass on multiple lines (sections) by using the StartLine parameter.
Examples:
- (5) ; start from line 5 to the end (StartLine)
- (5, 15) ; Section: lines 5 to 15 (StartLine, EndLine)
- ("5,13,45,67", 135) ; Specific lines: 5,13,45,67, ignore 135 ("StartLine", Endline - **EndLine value is ignored**)
- ("5-13,45-51", 135) ; Multiple sections of lines: 5 to 13, 45 to 51 ignore 135 ("StartLine", Endline - **EndLine value is ignored**)
Incremental (EndLine will **not** be ignored) in the following cases:
- ("2+3", 150) ; start with line 2, increment 3 up-to line 150 so 2,5,8,11,14 etc
- ("5+15") ; start with line 5, increment 15 until end of file so 5,20,35 etc
Negative Startline
- A Negative startline value makes a TF function operate on the last X lines.
- TF_ColGet and TF_ColPut accept negative StartColumn parameter. This can be used to "Get" or "Put" text in the x-th "column" from the right
### Textfile and the ! Prefix
Valid examples for using a Textfile:
```autohotkey
TF_("file.txt", .... ; Process file.txt and write output to file_copy.txt
F=file.txt ; ; Note how F is a variable, but AHK/TF will see it is meant to represent file.txt and write output to file_copy.txt
TF_(F, .... ; Process file.txt and write output to file_copy.txt
TF_("!file.txt", .... ; Process file.txt and overwrite file.txt
F=file.txt
TF_("!" . F, .... ; Process file.txt and overwrite file.txt
F=!file.txt
TF_(F, .... ; Process file.txt and overwrite file.txt
In a Loop, FilePattern:
TF_(A_LoopFileName, .... ; Process file and write output to file_copy
TF_("!" . A_LoopFileName, .... ; Process file and overwrite file
Loop, *.txt
{
TF_(A_LoopFileName, .... ; Process file and write output to file_copy
}
```
If you want to use multiple TF functions on a single file it is advised to use the ! Prefix
```autohotkey
F=!file.txt
TF_RemoveBlankLines(F) ; remove all empty lines from file.txt and overwrite original file.txt
TF_LineNumber(F) ; add linenumbers to all lines and overwrite original file.txt
TF_Replace(F, "this", "that") ; Replace the word "this" with "that" and overwrite original file.txt
; So the original file.txt has undergone three changes
```
**Files & Variables (v3+)**
You can use TF functions directly on files as well as variables.
Below you will find some easy examples.
**Introduced in v3: TF()**
In order to save you the trouble of using a fileread to read a file into
a variable and proceed to use various TF functions there is the TF()
Function.
```autohotkey
TF("pathtofile", CreateGlobalVar="T")
```
By default it reads the contents of the file in a global variable named **t** and
returns it for further processing. By default it creates variable **t** if a variable
name is **omitted** so if you do not like to use **t** you can use anything you like.
It is NOT mandatory to use TF(), you are welcome to use a fileread as well, TF() is
merely added for convenience as we will see in the examples below. TF() doesn't suddenly
make the TF library "not standard compliant" as some seem to think as it only creates a
global variable if you use the TF() function.
**Repeat:** You only have to use TF() if you want to read a file into a variable
and use it on multiple TF_\* Functions but it is NOT required.
See also [TF Lib Errors](#tf-lib-errors) below.
**TF() Examples:**
```autohotkey
TF("file.txt") ; will create global var t
TF("file.txt", "MyVar") ; will create global var MyVar
```
**Examples on how to use files & variables with TF:**
```autohotkey
#Include tf.ahk
TestFile= ; create variable
(join`r`n
1 Hi this
2 a test variable
3 to demonstrate
4 how to
5 use this
6 new version
7 of TF.AHK
)
FileDelete, TestFile.txt
FileAppend, %TestFile%, TestFile.txt ; create file
F=TestFile.txt ; just a shorthand code for TextFile.txt, so when
; we are using 'F' below we are still passing on a TextFile, not a variable!
; pass on file, read lines 5 to end of file:
MsgBox % "From File 1:`n" TF_ReadLines("TestFile.txt",5)
MsgBox % "From File 2:`n" TF_ReadLines(F,5) ; same
; pass on variable, read lines 1 to 5
MsgBox % "From Variable 1:`n" TF_ReadLines(TestFile,"1-5")
MsgBox % "From Variable 2:`n" TF_ReadLines("Hi`nthis`nis`na`ntest`nvariable`nfor`ntesting",1,3) ; pass on string
; Examples using TF(): (it will save you a FileRead if you want to work with Variables)
TF("TestFile.txt") ; read file, create global var t
t:=TF_ReadLines(t,5) ; pass on global var t created by TF(), read lines 5 to end of file, assign result to t
MsgBox % "TF(), example 1:`n" t
TF("TestFile.txt", "MyVar") ; read file, create global var MyVar
MyVar:=TF_ReadLines(MyVar,5) ; pass on global var MyVar created by TF(), read lines 5 to end of file, assign result to MyVar
MsgBox % "TF(), example 2:`n" MyVar
; Note how we can use TF() here
t:=TF_ReadLines(TF("TestFile.txt"),5) ; pass on global var t created by TF(), read lines 5 to end of file, assign result to t
MsgBox % "TF(), example 3:`n" t
MyVar:=TF_ReadLines(TF("TestFile.txt","MyVar"),5) ; pass on global var t created by TF(), read lines 5 to end of file, assign result to t
MsgBox % "TF(), example 4:`n" MyVar
t:=TF_ReadLines(TF(F),5) ; pass on global var t created by TF(), read lines 5 to end of file, assign result to t
t:=TF_ReverseLines(t,5) ; pass on global var t created by TF(), reverse lines, assign result to t
MsgBox % "TF(), example 5:`n" t
; Work directly with the clipboard or another other variable
Clipboard=Line 1`nLine 2`nLine 3`nLine 4`nLine 5`nLine 6`nLine 7`nLine 8
Clipboard:=TF_RemoveLines(Clipboard, 3, 6) ; remove lines 3 to 6
MsgBox % "Clipboard, example 6:`n" Clipboard
```
**Note** TF_Merge, TF_Prepend, TF_Append currently do not support variables and only work with FILES.
**Common mistake(s):**
```autohotkey
MyVar:=TF_ReadLines("TestFile.txt",5) ; this is wrong. It is AN INCORRECT EXAMPLE!
```
The example above is incorrect: You pass on a file so the output is
testfile_copy.txt. In this case nothing meaningful is assigned to the
variable MyVar. Correct would be:
```autohotkey
MyVar:=TF_ReadLines(MyVar,5) ; this is OK
MyVar:=TF_ReadLines(TF("TestFile.txt","MyVar"),5) ; this is OK
```
--------------------------------------------------------------------------
# Functions and Examples
**Note:** Some of these functions are very similar, but they are included in the library for ease of use ...
You can find examples of most functions in the "example script" here [http://www.autohotkey.com/forum/viewtopic.php?p=280363#280363](http://www.autohotkey.com/forum/viewtopic.php?p=280363#280363)