<commit_before><?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
	"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<refentry id="cockpit-file">
  <refnamediv>
    <refname>cockpit.js: File Access</refname>
    <refpurpose>Reading, writing, and watching files.</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <para>The <code>cockpit.file</code> API lets you read, write, and watch regular files in their entirety.
    It cannot efficiently do random access in a big file or read non-regular files such as
    <code>/dev/random</code>.
    </para>
<programlisting>
file = cockpit.file(path,
                    { syntax: syntax_object,
                      binary: boolean,
                      max_read_size: int,
                      superuser: string,
                      host: string
                    })

promise = file.read()
promise
    .then((content, tag) => { ... })
    .catch(error => { ... })

promise = file.replace(content, [ expected_tag ])
promise
    .then(new_tag => { ... })
    .catch(error => { ... })

promise = file.modify(callback, [ initial_content, initial_tag ]
promise
    .then((new_content, new_tag) => { ... })
    .catch(error => { ... })

file.watch((content, tag, [error]) => { }, [ { read: boolean } ])

file.close()
</programlisting>
  </refsynopsisdiv>

  <refsection id="cockpit-file-simple">
    <title>Simple reading and writing</title>

    <para>You can read a file with code like this:</para>
<programlisting>
cockpit.file("/path/to/file").read()
    .then((content, tag) => {
        ...
    })
    .catch(error => {
        ...
    });
</programlisting>
    <para>The <code>read()</code> method returns a
      <ulink url="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</ulink>.</para>
    <para>When successful, the promise will be resolved with the content of the<commit_msg>doc: Document paths in cockpit.file<commit_after><?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
	"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<refentry id="cockpit-file">
  <refnamediv>
    <refname>cockpit.js: File Access</refname>
    <refpurpose>Reading, writing, and watching files.</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <para>The <code>cockpit.file</code> API lets you read, write, and watch regular files in their entirety.
    It cannot efficiently do random access in a big file or read non-regular files such as
    <code>/dev/random</code>.
    </para>
<programlisting>
file = cockpit.file(path,
                    { syntax: syntax_object,
                      binary: boolean,
                      max_read_size: int,
                      superuser: string,
                      host: string
                    })

promise = file.read()
promise
    .then((content, tag) => { ... })
    .catch(error => { ... })

promise = file.replace(content, [ expected_tag ])
promise
    .then(new_tag => { ... })
    .catch(error => { ... })

promise = file.modify(callback, [ initial_content, initial_tag ]
promise
    .then((new_content, new_tag) => { ... })
    .catch(error => { ... })

file.watch((content, tag, [error]) => { }, [ { read: boolean } ])

file.close()
</programlisting>
  </refsynopsisdiv>

  <refsection id="cockpit-file-simple">
    <title>Simple reading and writing</title>

    <para>You can read a file with code like this:</para>
<programlisting>
cockpit.file("/path/to/file").read()
    .then((content, tag) => {
        ...
    })
    .catch(error => {
        ...
    });
</programlisting>
    <para>It is recommended to use absolute paths. Relative paths are resolved against <code>/</code>.
      To work with the current user's files <link linkend="cockpit-user">cockpit.user()</link> can be used to get the user's home directory.
    </para>
    <para>The <code>read()</code> method returns a
      <ulink url="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</ulink>.</para>
    <para>When successful, the promise will be resolved with the content of the
{'fraction_non_alphanumeric': 0.15916787614900824, 'fraction_numerical': 0.002902757619738752, 'mean_word_length': 2.662533215234721, 'pattern_counts': {'":': 0, '<': 75, '<?xml version=': 2, '>': 93, 'https://': 2, 'lorem ipsum': 0, 'www.': 2, 'xml': 4}, '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': '1329776', 'n_tokens_mistral': 1338, 'n_tokens_neox': 1274, 'n_words': 309}