{
  "id": "fn-file-write",
  "dataComponent": "file",
  "heading": {
    "title": "write",
    "badges": [
      "FileIO",
      "PARTIAL"
    ]
  },
  "synopsis": "Writes data to a file. With one or two arguments, writes the entire string at once. If a streaming callback is provided, writes chunk by chunk until you signal completion.",
  "codeBlocks": [
    "# 1) Basic usage (two arguments): write an entire file at once.\n\nextend(\"file\")\n\nfile:write(\"/path/to/output.txt\", \"Hello, world!\\n\")\n# => If successful, returns true (or 'OK').\n#    If an error occurs (permissions, full disk), raises an error.\n",
    "# 2) Streaming usage (three arguments: path, initDataOrNil, chunkCallback)\n\n# If your environment supports streaming writes, pass a callback.\n\nfile:write(\"/path/to/log.txt\", null, chunkSupplier => {\n  # chunkSupplier is a function you call to get the next chunk to write.\n  # or your bridging environment might repeatedly call chunkSupplier to pull data.\n\n  # Example usage:\n  # for each chunk, return a string. If no more data, return false or an empty string.\n\n  chunk = array:shift(myChunkQueue)\n  if chunk == _ then return false  # no more data\n\n  return chunk  # write this chunk\n})\n\n# => The function might block or run asynchronously while chunks are written.\n#    Once you return false or empty from your chunkSupplier, the file is closed.\n",
    "# 3) Partial usage => placeholders\n\n# If your environment supports partial usage, you can do:\n\nmyPartialWrite = file:write(\"/tmp/data.txt\", _)\n\n# Then call that with the content or callback.\nmyPartialWrite(\"Hello!\")\n\n# Or fix the data, waiting for the file path.\n"
  ],
  "notes": [
    "Argument patterns:\n- (path:string, textToWrite:string): writes the given string to that path all at once.\n- (path:string, something, callback:function): if streaming is supported, the callback is used to obtain successive chunks.\n",
    "If the file does not exist, it is created. If it does exist, it’s overwritten unless your environment defaults to append mode.\n",
    "Returns a boolean true or a success message (e.g. \"OK\"). Raises an error if writing fails.",
    "Partial usage is possible, e.g. `file:write(path, _)` or `_` placeholders.\n",
    "If your bridging layer does not implement streaming, the third argument and chunk callback references can be omitted or raise an error."
  ]
}
