PageRenderTime 44ms CodeModel.GetById 18ms RepoModel.GetById 1ms app.codeStats 0ms

/AutoHotkey.docset/Contents/Resources/Documents/commands/FileAppend.htm

https://gitlab.com/ahkscript/Autohotkey.docset
HTML | 91 lines | 77 code | 14 blank | 0 comment | 0 complexity | a8bc9fadf1f6f648f096fcb728437652 MD5 | raw file
    

  1. <!DOCTYPE HTML>
    2. 

  2. <html>
    3. 

  3. <head>
    4. 

  4. <title>FileAppend</title>
    5. 

  5. <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
    6. 

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

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

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

  9. </head>
    10. 

  10. <body>
    11. 

  11. 

  12. <h1>FileAppend</h1>
    13. 

  13. 

  14. <p>Writes text to the end of a file (first creating the file, if necessary).</p>
    15. 

  15. 

  16. <pre class="Syntax">FileAppend [, Text, Filename, Encoding]</pre>
    17. 

  17. <h3>Parameters</h3>
    18. 

  18. <dl>
    19. 

  19. 

  20.   <dt>Text</dt>
    21. 

  21.   <dd><p>The text to append to the file. This text may include linefeed characters (`n) to start new lines. In addition, a single long line can be broken up into several shorter ones by means of a <a href="../Scripts.htm#continuation">continuation section</a>.</p>
    22. 

  22.       <p>If <em>Text</em> is blank, <em>Filename</em> will be created as an empty file (but if the file already exists, its modification time will be updated).</p>
    23. 

  23.     <p>If <em>Text</em> is <a href="../misc/Clipboard.htm#ClipboardAll">%ClipboardAll%</a> or a variable that was previously assigned the value of ClipboardAll, <em>Filename</em> will be unconditionally overwritten with the entire contents of the clipboard (i.e. <a href="FileDelete.htm">FileDelete</a> is not necessary).</p></dd>
    24. 

    25. 

  25.   <dt>Filename</dt>
    26. 

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

  27.     <p><strong>End of line (EOL) translation</strong>: To disable EOL translation, prepend an asterisk to the filename. This causes each linefeed character (`n) to be written as a single linefeed (LF) rather than the Windows standard of CR+LF. For example: <code>*C:\My Unix File.txt</code>.</p>
    28. 

  28.     <p>If the file is not already open (due to being inside a <a href="LoopReadFile.htm">file-reading loop</a>), EOL translation is automatically disabled if <em>Text</em> contains any carriage return and linefeed pairs (`r`n). In other words, the asterisk option described in the previous paragraph is put into effect automatically. However, specifying the asterisk when <em>Text</em> contains `r`n improves performance because the program does not need to scan <em>Text</em> for `r`n.</p>
    29. 

  29.     <p id="stdout"><strong>Standard Output (stdout)</strong>: Specifying an asterisk (*) for <em>Filename</em> causes <em>Text</em> to be sent to standard output (stdout). Such text can be redirected to a file, piped to another EXE, or captured by <a href="_ErrorStdOut.htm">fancy text editors</a>. For example, the following would be valid if typed at a command prompt:</p>
    30. 

  30.       <pre>&quot;%ProgramFiles%\AutoHotkey\AutoHotkey.exe&quot; &quot;My Script.ahk&quot; &gt;&quot;Error Log.txt&quot;</pre>
    31. 

  31.     <p>However, text sent to stdout will not appear at the command prompt it was launched from. This can be worked around by piping a script's output to another command or program. For example:</p>
    32. 

  32.       <pre>&quot;%ProgramFiles%\AutoHotkey\AutoHotkey.exe&quot; &quot;My Script.ahk&quot; |more</pre>
    33. 

  33.       <pre>For /F &quot;tokens=*&quot; %L in ('&quot;&quot;%ProgramFiles%\AutoHotkey\AutoHotkey.exe&quot; &quot;My Script .ahk&quot;&quot;') do @Echo %L</pre>
    34. 

  34.     <p><span class="ver">[v1.1.20+]:</span> Specifying two asterisks (**) for <em>Filename</em> causes <em>Text</em> to be sent to the stderr stream.</p>
    35. 

  35.     </dd>
    36. 

  36. 

  37.   <dt>Encoding</dt>
    38. 

  38.   <dd><p><span class="ver">[AHK_L 42+]:</span> Overrides the default encoding set by <a href="FileEncoding.htm">FileEncoding</a>, where <em>Encoding</em> follows the same format.</p></dd>
    39. 

  39. 

  40. </dl>
    41. 

  41. 

  42. <h3>ErrorLevel</h3>
    43. 

  43. <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>
    44. 

  44. <p><a href="../misc/ErrorLevel.htm">ErrorLevel</a> is set to 1 if there was a problem or 0 otherwise.</p>
    45. 

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

    47. 

  47. <h3>Remarks</h3>
    48. 

  48. <p>To overwrite an existing file, delete it with <a href="FileDelete.htm">FileDelete</a> prior to using FileAppend.</p>
    49. 

  49. <p>The target file is automatically closed after the text is appended (except when FileAppend is used in its single-parameter mode inside a <a href="LoopReadFile.htm">file-reading/writing loop</a>).</p>
    50. 

  50. <p><span class="ver">[AHK_L 42+]:</span> <a href="FileOpen.htm">FileOpen()</a> in append mode provides more control than FileAppend and allows the file to be kept open rather than opening and closing it each time. Once a file is opened in append mode, use <code>file.<a href="../objects/File.htm#Write">Write</a>(string)</code> to append the string. File objects also support binary I/O via <a href="../objects/File.htm#RawWrite">RawWrite</a>/<a href="../objects/File.htm#RawRead">RawRead</a> or <a href="../objects/File.htm#WriteNum">Write<i>Num</i></a>/<a href="../objects/File.htm#ReadNum">Read<i>Num</i></a>, whereas FileAppend supports only text.</p>
    51. 

  51. <h3>Related</h3>
    52. 

  52. <p><a href="FileOpen.htm">FileOpen</a>/<a href="../objects/File.htm">File Object</a>, <a href="FileRead.htm">FileRead</a>, <a href="LoopReadFile.htm">file-reading loop</a>, <a href="FileReadLine.htm">FileReadLine</a>, <a href="IniWrite.htm">IniWrite</a>, <a href="FileDelete.htm">FileDelete</a>, <a href="OutputDebug.htm">OutputDebug</a>, <a href="../Scripts.htm#continuation">continuation sections</a></p>
    53. 

  53. <h3>Example</h3>
    54. 

  54. <pre class="NoIndent">FileAppend, Another line.`n, C:\My Documents\Test.txt
    55. 

    56. 

  56. <em>; The following example uses a <a href="../Scripts.htm#continuation">continuation section</a> to enhance readability and maintainability:</em>
    57. 

  57. FileAppend,
    58. 

  58. (
    59. 

  59. A line of text.
    60. 

  60. By default, the hard carriage return (Enter) between the previous line and this one will be written to the file.
    61. 

  61.     This line is indented with a tab; by default, that tab will also be written to the file.
    62. 

  62. Variable references such as %Var% are expanded by default.
    63. 

  63. ), C:\My File.txt</pre>
    64. 

  64. <p>&nbsp;</p>
    65. 

  65. <pre class="NoIndent" id="FTP"><em>; The following example demonstrates how to automate FTP uploading using the operating 
    66. 

  66. ; system's built-in FTP command. This script has been tested on Windows XP.</em>
    67. 

    68. 

  68. FTPCommandFile = %A_ScriptDir%\FTPCommands.txt
    69. 

  69. FTPLogFile = %A_ScriptDir%\FTPLog.txt
    70. 

  70. FileDelete %FTPCommandFile%  <em>; In case previous run was terminated prematurely.</em>
    71. 

    72. 

  72. FileAppend,  <em>; The comma is required in this case.</em>
    73. 

  73. (
    74. 

  74. open host.domain.com
    75. 

  75. username
    76. 

  76. password
    77. 

  77. binary
    78. 

  78. cd htdocs
    79. 

  79. put %VarContainingNameOfTargetFile%
    80. 

  80. delete SomeOtherFile.htm
    81. 

  81. rename OldFileName.htm NewFileName.htm
    82. 

  82. ls -l
    83. 

  83. quit
    84. 

  84. ), %FTPCommandFile%
    85. 

    86. 

  86. RunWait %comspec% /c ftp.exe -s:&quot;%FTPCommandFile%&quot; &gt;&quot;%FTPLogFile%&quot;
    87. 

  87. FileDelete %FTPCommandFile%  <em>; Delete for security reasons.</em>
    88. 

  88. Run %FTPLogFile%  <em>; Display the log for review.</em></pre>
    89. 

    90. 

  90. </body>
    91. 

  91. </html>
    92. 

    93.