Editing mirc/identifiers/$read

{{mirc title|$read Identifier}}The '''$read''' returns a line from a disk file

== Synopsis ==
<source lang="mIRC">$read(filename [,ntswrp] [,matchtext] [,N])</source>

Legacy syntax:
<pre>$read [switches] [line#] filename</pre>

== Parameters ==
{{ ArgsList
| filename | The file from which text is returned
| matchtext | Used with switches s w r
| N | Line number to read, except when using s, w, or r switches where it's the first line of the file portion to search.
}}
=== Switches ===
{{ArgsList
| n | Do not evaluate $identifiers contained in the returned line.
| t | Do not treat a numeric line#1 as if it's the total number of lines in the text file.
| s | Search for line beginning with <matchtext> and returns the remainder of the line beyond the spaces following <matchtext>
| w | Scan for line matching <matchtext> which can be a {{mirc|wildcard}}. If not a wildcard the line must be exact match. Returns the entire contents of the matching line
| r | Indicates that <matchtext> is a regex pattern.
| p | When evaluating text in the absence of the 'n' switch, treats the pipe symbol as a command separator allowing the remainder of the line to be executed as a /command.
}}

=== Notes: ===
* All searches are case-insensitive.
* Line can end with $cr or $lf or $crlf or end-of-file. Does not treat $chr(26) as End-of-File-Marker. Contents of a line past $chr(0) are ignored.
* If 't' switch is NOT used - if line 1 is not a number, $read functions normally. If line 1 is a number, random lines will be chosen only for the first N lines, and $readn returns 1 through N while returning the contents of actual lines 2 through N+1.
* If NO switches are used,  $read(file,0) returns the contents of line 1 if it's a number, or returns $null if contents are anything else.
* matchtext must have the presence/absence of spaces in order to match lines having/not-having those spaces, even leading/trailing/consecutive.
* Undocumented legacy syntax can be used  where parameters follow the identifier without being enclosed within quotes.

== Examples ==
<source lang="mIRC">
//echo -a line $readn is $read(versions.txt,nt)
returns: a random line from versions.txt even if it is $null
Note: You can use $read(quotes.txt,nt) as your quit message, and it will display a random line from that file when you /quit a server.

//echo -a $read(versions.txt,nt,3)
returns: line #3
//echo -a $read(versions.txt,nt,2)
returns: line #2. if the line length is blank (length = 0), returns $null

//echo -a $read(versions.txt,nt,invalid)
returns: If s/r/w switches not used and 3rd parameter is used without being a number >= 1, returns line #1.

//echo -a $read(file.txt,t,4)
returns: Contents of line#3. Because the 'n' switch wasn't used, evaluates any identifiers instead of returning strings beginning with "S".

//echo -a $read(file.txt,tp,4)
returns: Same, except if the line contains the | "pipe" symbol, that is treated as a command separator, and the portion beyond the pipe is executed as if a script command.

//echo -a $read(versions.txt,nts,10.fixed) line: $readn
matches: the first line which is either a match for the matchtext, or the first line beginning with the matchtext followed by a space. If matchtext is 'yes' it will not match a line beginning with 'yesterday'. The 's' switch returns the portion of the line excluding the matchtext and the spaces following it.

//echo -a $read(versions.txt,nts,10.fixed,200) line: $readn
matches: Same, except begins scanning at line 200.

//echo -a $read(versions.txt,nts,changes:) $readn 
returns $null because that is the full content of the matching line, so there is no remainder-of-line to return. But $readn indicates there was a match.

//echo -a $read(versions.txt,ntw,changes:) $readn
'w' differs from 's' in that it accepts wildcard, but also returns the entire line including the match.

//echo -a $read(versions.txt,ntw,10.fixed) line: $readn
returns $null and $readn returns 0 because 'w' requires matching the matchtext instead of beginning with it.

//echo -a echo -a $read(versions.txt,nts,$str($chr(32),4)) $readn
matches the 1st line which begins with 4 OR MORE spaces.

//echo -a $read(versions.txt,ntw,& & &) $readn
returns first line containing exactly 3 space-tokenized 'words'.

//var %i 1 | :label | echo -ag $read(versions.txt,ntw,* - mirc*,%i) $readn | var %i = 1 + $readn | if ($readn) goto label
returns all lines of the file matching the matchtext

//write -c test.dat top line | var %i 2 | while (%i isnum 2-100) { write test.dat line %i | inc %i }
This creates a 100-line file, where the 1st line says "top line" and lines 2-99 show their line number.

//write -l1 test.dat top | echo -a $read(test.dat,n)
Because Line#1 is not a number, mIRC does not treat it as a line count for the file, so this returns a random line from the text file.

//write -l1 test.dat  40 | echo -a $read(test.dat,n) $readn
Now that line#1 is a number, returns a random line from line 2 through N+1, so it's possible for this to return $readn 1-40 when reading from lines 2-41.
//write -c test.dat 40 | write test.dat test2 | echo -a with n: $read(test.dat,n,0) . $readn without n: $read(test.dat,0) $readn

//var %pattern \d{5,} | echo -a $read(versions.txt,ntr,%pattern) $readn
'r' switch indicates matchtext is a regex pattern. Returns: first line containing at least 5 consecutive number digits
</source>
== Compatibility ==
For modern documented syntax:
{{mIRC compatibility|3.6}}

For older undocumented syntax:
{{mIRC compatibility|3.6}}
== See Also ==
* {{mIRC|/bread}}
* {{mIRC|$fread}}
* {{mIRC|$readini}}