From WikiChip
Difference between revisions of "mirc/identifiers/$read"
< mirc‎ | identifiers

(See Also)
Line 17: Line 17:
 
| t | Do not treat a numeric line#1 as if it's the total number of lines in the text file.
 
| 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>
 
| 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 wildcard. If not a wildcard the line must be exact match. Returns the entire contents of the matching line
+
| 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.
 
| 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.
 
| 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.

Revision as of 16:28, 20 October 2018

The $read returns a line from a disk file

Synopsis

$read(filename [, ntswrp] [,matchtext] [, N] )
Legacy syntax:
$read [switches] [line#] filename

Parameters

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

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 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

//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

Compatibility

For modern documented syntax: Added: mIRC v3.6
Added on: 31 Aug 1995
Note: Unless otherwise stated, this was the date of original functionality.
Further enhancements may have been made in later versions.


For older undocumented syntax: Added: mIRC v3.6
Added on: 31 Aug 1995
Note: Unless otherwise stated, this was the date of original functionality.
Further enhancements may have been made in later versions.

See Also