<commit_before>
# `write(options, [goptions], callback)`

Write a file or a portion of an existing file.   

## Options

*   `append`   
    Append the content to the destination file. If destination does not exist,
    the file will be created.   
*   `backup`   
    Create a backup, append a provided string to the filename extension or a
    timestamp if value is not a string.   
*   `content`   
    Text to be written, an alternative to source which reference a file.   
*   `destination`   
    File path where to write content to.   
*   `diff` (boolean | function)   
    Print diff information, pass the result of [jsdiff.diffLines][diffLines] as
    argument if a function, default to true.   
*   `eof`   
    Ensure the file ends with this charactere sequence, special values are
    'windows', 'mac', 'unix' and 'unicode' (respectively "\r\n", "\r", "\n",
    "\u2028"), will be auto-detected if "true", default to false or "\n" if
    "true" and not detected.   
*   `from`   
    Replace from after this marker, a string or a regular expression.   
*   `gid`   
    File group name or group id.   
*   `local_source`   
    Treat the source as local instead of remote, only apply with "ssh"
    option.   
*   `match`   
    Replace this marker, a string or a regular expression, default to the
    replaced string if missing.   
*   `mode`   
    File mode (permission and sticky bits), default to `0666`, in the form of
    `{mode: 0o0744}` or `{mode: "0744"}`.   
*   `replace`   
    The content to be inserted, used conjointly with the from, to or match
    options.   
*   `source`   
    File path from where to extract the content, do not use conjointly with
    content.   
*   `to`   
    Replace to before this marker, a string or a regular expression.   
*   `uid`   
    File user name or user id.   
*   `write`   
    An array containing multiple transformation where a transformation is an
    object accepting the options `from`, `to`, `match` and `replace`.   
*   `ssh` (object|ssh2)   
    Run the action on a remote server using SSH, an ssh2 instance or an
    configuration object used to initialize the SSH connection.   
*   `stdout` (stream.Writable)   
    Writable EventEmitter in which the standard output of executed commands will
    be piped.   

## Callback parameters

*   `err`   
    Error object if any.   
*   `modified`   
    Number of written actions with modifications.   

## Implementation details

Internally, this function uses the "chmod" and "chown" function and, thus,
honor all their options including "mode", "uid" and "gid".

## Diff Lines

Diff can be obtained when the options "diff" is set to true or a function. The
information is provided in two ways:   

*   when `true`, a formated string written to the "stdout" option.
*   when a function, the array returned by the function `diff.diffLines`, see
    the [diffLines] package for additionnal information.

## More about the `append` option

The `append` option allows more advance usages. If `append` is "null", it will
add the value of the "replace" option at the end of the file when no match
is found and when the value is a string.   

Using the `append` option conjointly with the `match` and `replace` options gets
even more interesting. If append is a string or a regular expression, it will
place the value of the "replace" option just after the match. Internally, a
string value will be converted to a regular expression. For example the string
"test" will end up converted to the regular expression `/test/mg`.   

## Replacing part of a file using from and to markers

```js
require('mecano').write({
  content: 'here we are\n# from\nlets try to replace that one\n# to\nyou coquin',
  from: '# from\n',
  to: '# to',
  replace: 'my friend\n',
  destination: scratch+'/a_file'
}, function(err, written){
  // '# here we are\n# from\nmy friend\n# to\nyou coquin'
})
```

## Replacing a matched line by a string
<commit_msg>write: fix typo<commit_after>
# `write(options, [goptions], callback)`

Write a file or a portion of an existing file.   

## Options

*   `append`   
    Append the content to the destination file. If destination does not exist,
    the file will be created.   
*   `backup`   
    Create a backup, append a provided string to the filename extension or a
    timestamp if value is not a string.   
*   `content`   
    Text to be written, an alternative to source which reference a file.   
*   `destination`   
    File path where to write content to.   
*   `diff` (boolean | function)   
    Print diff information, pass the result of [jsdiff.diffLines][diffLines] as
    argument if a function, default to true.   
*   `eof`   
    Ensure the file ends with this charactere sequence, special values are
    'windows', 'mac', 'unix' and 'unicode' (respectively "\r\n", "\r", "\n",
    "\u2028"), will be auto-detected if "true", default to false or "\n" if
    "true" and not detected.   
*   `from`   
    Replace from after this marker, a string or a regular expression.   
*   `gid`   
    File group name or group id.   
*   `local_source`   
    Treat the source as local instead of remote, only apply with "ssh"
    option.   
*   `match`   
    Replace this marker, a string or a regular expression, default to the
    replaced string if missing.   
*   `mode`   
    File mode (permission and sticky bits), default to `0666`, in the form of
    `{mode: 0o0744}` or `{mode: "0744"}`.   
*   `replace`   
    The content to be inserted, used conjointly with the from, to or match
    options.   
*   `source`   
    File path from where to extract the content, do not use conjointly with
    content.   
*   `to`   
    Replace to before this marker, a string or a regular expression.   
*   `uid`   
    File user name or user id.   
*   `write`   
    An array containing multiple transformation where a transformation is an
    object accepting the options `from`, `to`, `match` and `replace`.   
*   `ssh` (object|ssh2)   
    Run the action on a remote server using SSH, an ssh2 instance or an
    configuration object used to initialize the SSH connection.   
*   `stdout` (stream.Writable)   
    Writable EventEmitter in which the standard output of executed commands will
    be piped.   

## Callback parameters

*   `err`   
    Error object if any.   
*   `modified`   
    Number of written actions with modifications.   

## Implementation details

Internally, this function uses the "chmod" and "chown" function and, thus,
honor all their options including "mode", "uid" and "gid".

## Diff Lines

Diff can be obtained when the options "diff" is set to true or a function. The
information is provided in two ways:   

*   when `true`, a formated string written to the "stdout" option.
*   when a function, the array returned by the function `diff.diffLines`, see
    the [diffLines] package for additionnal information.

## More about the `append` option

The `append` option allows more advanced usages. If `append` is "null", it will
add the value of the "replace" option at the end of the file when no match
is found and when the value is a string.   

Using the `append` option conjointly with the `match` and `replace` options gets
even more interesting. If append is a string or a regular expression, it will
place the value of the "replace" option just after the match. Internally, a
string value will be converted to a regular expression. For example the string
"test" will end up converted to the regular expression `/test/mg`.   

## Replacing part of a file using from and to markers

```js
require('mecano').write({
  content: 'here we are\n# from\nlets try to replace that one\n# to\nyou coquin',
  from: '# from\n',
  to: '# to',
  replace: 'my friend\n',
  destination: scratch+'/a_file'
}, function(err, written){
  // '# here we are\n# from\nmy friend\n# to\nyou coquin'
})
```

## Replacing a matched line by a string

{'fraction_non_alphanumeric': 0.08498547796438945, 'fraction_numerical': 0.004798585680010102, 'mean_word_length': 2.9979808177688034, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '310011', 'n_tokens_mistral': 2309, 'n_tokens_neox': 2258, 'n_words': 1100}