View source for $read

Returns a line of text from a text file.
 $read(''filename'',[ntswrp],[''string''],[''N''])
The first parameter is the filename and the only required parameter.
If you omit all other parameters you will be returned with a random line from the file.

The second parameter is a set of options that determin the type of search you wish to use, for a full description see the table below.
if ''string'' is numerical and you do not use ''swr'' switch the line corresponding to the numerical value will be returned.

If the ''N'' parameter is given it starts to search the file from that line number.

'''Note:''' If the first line of your text file is a numerical value mIRC treats this number as the total number of lines in the text file, be careful not to accidently have your file cut short due to an unexpected numerical value.
If you specify N = 0, mIRC returns the value of the first line if it's a number.
Take good note of the ''t'' switch in the table below.

{| style="width:100%"
| style="width:5%" | '''''Switch''''' || style="width:95%" | '''''Meaning'''''
|-
| n || If the ''n'' switch is specified then the line read in will not be evaluated and will be treated as plain text.
|-
| t || If the ''t'' switch is specified then mIRC will treat the first line in the file as plain text, even if it is a numeric.
|-
| s || Scans the ''filename'' for a line beginning with the ''string'' and returns the text following the match value.
|-
| w || Scans the ''filename'' for a line matching ''string'', where ''string'' can contain [[If-Then-Else#iswm|wildcards]].
|-
| r || Scans the ''filename'' for a line matching ''string'', where ''string'' is taken as a [[Regular_Expression|regular expression]].
|-
| p || If the ''p'' switch is specified, command <nowiki>|</nowiki> separators are treated as such instead of as plain text.
|}

== Examples ==
 '''''Example.txt:'''''
 5
 Ave It
 Hash Help Dot Script
 6
 Cows dont go moo, Fish go moo!
 Fish go moo
 Yes they do
The above is an example text file used in the following examples.

 $read(''Example.txt'',''s'',''Ave'')  ;Returns ''It'', all data that follows the first line starting with ''Ave''.
 $read(''Example.txt'',''w'',''*moo'')  ;Returns ''Fish go moo'', note the lack of pending asterisks means moo has to be the last word.
 $read(''Example.txt'',''3'')  ;Returns ''6'', This is the 3rd line in the file if you count line 1 as the linecount line because it is a number.
 $read(''Example.txt'',''t'',''3'')  ;Returns ''Hash Help Dot Script'', This is the 3rd line in the file if you count line 1 plain text.
 $read(''Example.txt'',''w'',''*moo'')  ;Returns ''
 
 [[kick]] [[$chan]] [[$nick]] $read(Example.txt)  ;Kicks a user with a random line from the text file.
== See Also ==
* [[$readn]] This returns the line number that $read just returned.
* [[$lines]] This returns the total number of lines in the given file.
* [[play]] This is a much better alternative if you require to list the content of a whole file to a channel.
* [[filter]] This can help with more complex needs when reading in content from files or windows.
* [[loadbuf]] This is a much better alternative if you need to dump many lines of text to a dialog or to a custom window

[[Category:File and Directory Identifiers]]