Add File Read/Write example, using folder.userData

Author: zlovatt

docs/file-system-access/file-object.md

@@ -955,3 +955,82 @@ Writes the specified text to the file at the current position, and appends a Lin
 #### Returns
 
 Boolean. `true` on success.
+
+---
+
+## File Object Examples
+
+### Read & Write Files
+
+The below example writes text to a file, then reads the contents of that file and presents it as an alert.
+
+Keep in mind that this is just one way to do this. Some host apps may also require a user-specified permissions check before being able to access the local file system.
+
+Note that this stores (and fetches) the file from the user's appdata folder, using the built-in [Folder.userData](../file-system-access/folder-object.md#folderuserdata) shortcut.
+
+```js
+/**
+ * Reads data from a given file in userdata folder
+ *
+ * @param {string} filename Filename, with extension
+ * @return {string}         File contents, if file exists
+ */
+function readUserDataFromFile(filename) {
+  var userDataFolder = Folder.userData;
+
+  var filepath = userDataFolder.fullName + "/" + filename;
+  var file = new File(filepath);
+
+  // Default encoding
+  file.encoding = "UTF-8";
+
+  if (!file.exists) {
+    throw "Could not find file '" + String(file.fsName);
+  }
+
+  file.open();
+  var contents = file.read();
+  file.close();
+
+  return contents;
+}
+
+/**
+ * Writes data to a given file in userdata folder
+ *
+ * @param {string} filename Filename, with extension
+ * @param {string} data     Data to write
+ */
+function writeUserDataToFile(filename, data) {
+  var userDataFolder = Folder.userData;
+
+  var filepath = userDataFolder.fullName + "/" + filename;
+  var file = new File(filepath);
+
+  // Default encoding
+  file.encoding = "UTF-8";
+
+  // Write file contents
+  file.open("w");
+  var success = file.write(data);
+  file.close();
+
+  if (!success) {
+    throw "Could not write to file '" + String(file.fsName);
+  }
+}
+
+try {
+  var filename = "myFile.txt";
+  var contents = "Hello world!";
+
+  writeUserDataToFile(filename, contents);
+
+  var readData = readUserDataFromFile(filename);
+
+  // "Hello world!"
+  alert("File Contents: '" + String(readData) + "'");
+} catch (e) {
+  alert(e);
+}
+```