PageRenderTime 41ms CodeModel.GetById 12ms RepoModel.GetById 1ms app.codeStats 0ms

/docs/commands/FileRead.htm

http://github.com/Lexikos/AutoHotkey_L-Docs
HTML | 78 lines | 65 code | 13 blank | 0 comment | 0 complexity | 52a7cfb97072ccf6443e0e89acc985b9 MD5 | raw file
    

  1. <!DOCTYPE HTML>
    2. 

  2. <html lang="en">
    3. 

  3. <head>
    4. 

  4. <title>FileRead - Syntax &amp; Usage | AutoHotkey</title>
    5. 

  5. <meta name="description" content="The FileRead command reads a file's contents into a variable." />
    6. 

  6. <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    7. 

  7. <meta http-equiv="X-UA-Compatible" content="IE=edge">
    8. 

  8. <link href="../static/theme.css" rel="stylesheet" type="text/css" />
    9. 

  9. <script src="../static/content.js" type="text/javascript"></script>
    10. 

  10. </head>
    11. 

  11. <body>
    12. 

  12. 

  13. <h1>FileRead</h1>
    14. 

  14. 

  15. <p>Reads a file's contents into a <a href="../Variables.htm">variable</a>.</p>
    16. 

    17. 

  17. <pre class="Syntax"><span class="func">FileRead</span>, OutputVar, Filename</pre>
    18. 

  18. <h2>Parameters</h2>
    19. 

  19. <dl>
    20. 

  20. 

  21.   <dt>OutputVar</dt>
    22. 

  22.   <dd><p>The name of the <a href="../Variables.htm">variable</a> in which to store the retrieved data. <em>OutputVar</em> will be made blank if a problem occurs such as the file being &quot;in use&quot; or not existing (in which case <a href="../misc/ErrorLevel.htm">ErrorLevel</a> is set to 1). It will also be made blank if <em>Filename</em> is an empty file (in which case ErrorLevel is set to 0).</p></dd>
    23. 

  23. 

  24.   <dt>Filename</dt>
    25. 

  25.   <dd><p>The name of the file to read, which is assumed to be in <a href="../Variables.htm#WorkingDir">%A_WorkingDir%</a> if an absolute path isn't specified.</p>
    26. 

  26.       <p><strong>Options</strong>: Zero or more of the following strings may be also be present immediately before the name of the file. Separate each option from the next with a single space or tab. For example: <code>*t *m5000 C:\Log Files\200601.txt</code>.</p>
    27. 

  27.     <p><strong>*c</strong>: Load a <a href="../misc/Clipboard.htm#ClipboardAll">ClipboardAll</a> file or other binary data. All other options are ignored when <strong>*c</strong> is present.</p>
    28. 

  28.     <p><strong>*m1024</strong>: If this option is omitted, the entire file is loaded unless there is insufficient memory, in which case an error message is shown and the thread exits (but <a href="Try.htm">Try</a> can be used to avoid this). Otherwise, replace 1024 with a decimal or hexadecimal number of bytes. If the file is larger than this, only its leading part is loaded.</p>
    29. 

  29.     <p class="note"><strong>Note</strong>: This might result in the last line ending in a naked carriage return (`r) rather than `r`n.</p>    
    30. 

  30.     <p><strong>*t</strong>: Replaces any/all occurrences of carriage return &amp; linefeed (`r`n) with linefeed (`n). However, this translation reduces performance and is usually not necessary. For example, text containing `r`n is already in the right format to be added to a <a href="GuiControls.htm#Edit">Gui Edit control</a>. Similarly, <a href="FileAppend.htm">FileAppend</a> detects the presence of `r`n when it opens a new file; it knows to write each `r`n as-is rather than translating it to `r`r`n. Finally, the following <a href="LoopParse.htm">parsing loop</a> will work correctly regardless of whether each line ends in `r`n or just `n: <code>Loop, parse, MyFileContents, `n, `r</code>.</p>
    31. 

  31.     <p><strong>*Pnnn</strong>: <span class="ver">[AHK_L 42+]:</span> Overrides the default encoding set by <a href="FileEncoding.htm">FileEncoding</a>, where <em>nnn</em> must be a numeric <a href="http://msdn.microsoft.com/en-us/library/dd317756.aspx">code page identifier</a>.</p></dd>
    32. 

  32. 

  33. </dl>
    34. 

  34. 

  35. <h2>Error Handling</h2>
    36. 

  36. <p><span class="ver">[v1.1.04+]</span>: This command is able to throw an exception on failure. For more information, see <a href="Catch.htm#RuntimeErrors">Runtime Errors</a>.</p>
    37. 

  37. <p><a href="../misc/ErrorLevel.htm">ErrorLevel</a> is set to 0 if the load was successful. It is set to 1 if a problem occurred such as: 1) file does not exist; 2) file is locked or inaccessible; 3) the system lacks sufficient memory to load the file.</p>
    38. 

  38. <p><a href="../Variables.htm#LastError">A_LastError</a> is set to the result of the operating system's GetLastError() function.</p>
    39. 

    40. 

  40. <h2 id="Binary">Reading Binary Data</h2>
    41. 

  41. <p>Depending on the file, parameters and default settings, FileRead may interpret the file data as text and convert it to the <a href="../Compat.htm#Format">native encoding</a> used by the script. This is likely to cause problems if the file contains binary data, except in the following cases:</p>
    42. 

  42. <ul>
    43. 

  43.   <li>If the <span class="Syntax">*C</span> option is present, all code page and end-of-line translations are unconditionally bypassed.</li>
    44. 

  44.   <li>If the <span class="Syntax">*P<i>nnn</i></span> option is present and <i>nnn</i> corresponds to the native string encoding, no code page translation occurrs.</li>
    45. 

  45.   <li>If the current <a href="FileEncoding.htm">file encoding</a> setting corresponds to the native string encoding, no code page translation occurrs.</li>
    46. 

  46. </ul>
    47. 

  47. <p>Note that once the data has been read into <em>OutputVar</em>, only the text before the first binary zero (if any are present) will be &quot;seen&quot; by most AutoHotkey commands and functions. However, the entire contents are still present and can be accessed by advanced methods such as <a href="NumGet.htm">NumGet()</a>.</p>
    48. 

  48. <p>Finally, <a href="FileOpen.htm">FileOpen()</a> and <a href="../objects/File.htm#RawRead">File.RawRead()</a> or <a href="../objects/File.htm#ReadNum">File.Read<i>Num</i>()</a> may be used to read binary data without first reading the entire file into memory.</p>
    49. 

  49. 

  50. <h2>Remarks</h2>
    51. 

  51. <p>When the goal is to load all or a large part of a file into memory, FileRead performs much better than using a <a href="LoopReadFile.htm">file-reading loop</a>.</p>
    52. 

  52. <p>A file greater than 1 GB in size will cause <a href="../misc/ErrorLevel.htm">ErrorLevel</a> to be set to 1 and <em>OutputVar</em> to be made blank unless the <strong>*m</strong> option is present, in which case the leading part of the file is loaded.</p>
    53. 

  53. <p>FileRead does not obey <a href="_MaxMem.htm">#MaxMem</a>. If there is concern about using too much memory, check the file size beforehand with <a href="FileGetSize.htm">FileGetSize</a>.</p>
    54. 

  54. <p><a href="FileOpen.htm">FileOpen()</a> provides more advanced functionality than FileRead, such as reading or writing data at a specific location in the file without reading the entire file into memory. See <a href="../objects/File.htm">File Object</a> for a list of functions.</p>
    55. 

  55. 

  56. <h2>Related</h2>
    57. 

  57. <p><a href="FileEncoding.htm">FileEncoding</a>, <a href="FileOpen.htm">FileOpen()</a> / <a href="../objects/File.htm">File Object</a>, <a href="LoopReadFile.htm">file-reading loop</a>, <a href="FileReadLine.htm">FileReadLine</a>, <a href="FileGetSize.htm">FileGetSize</a>, <a href="FileAppend.htm">FileAppend</a>, <a href="IniRead.htm">IniRead</a>, <a href="Sort.htm">Sort</a>, <a href="URLDownloadToFile.htm">UrlDownloadToFile</a></p>
    58. 

  58. 

  59. <h2>Examples</h2>
    60. 

  60. <div class="ex" id="ExBasic">
    61. 

  61. <p><a href="#ExBasic">#1</a>: Read a text file into <em>OutputVar</em>.</p>
    62. 

  62. <pre>FileRead, OutputVar, C:\My Documents\My File.txt</pre>
    63. 

  63. </div>
    64. 

  64. 

  65. <div class="ex" id="ExSort">
    66. 

  66. <p><a href="#ExSort">#2</a>: Quickly sort the contents of a file.</p>
    67. 

  67. <pre>FileRead, Contents, C:\Address List.txt
    68. 

  68. if not ErrorLevel  <em>; Successfully loaded.</em>
    69. 

  69. {
    70. 

  70.     <a href="Sort.htm">Sort</a>, Contents
    71. 

  71.     FileDelete, C:\Address List (alphabetical).txt
    72. 

  72.     FileAppend, %Contents%, C:\Address List (alphabetical).txt
    73. 

  73.     Contents := ""  <em>; Free the memory.</em>
    74. 

  74. }</pre>
    75. 

  75. </div>
    76. 

  76. 

  77. </body>
    78. 

  78. </html>
    79. 

  79.