Add support for editor preferences in editor scripts (#493)

* Add support for editor preferences in editor scripts

* Update editor-scripts.md to clarify usage of editor preferences

* Typo

docs/en/manuals/editor-scripts.md

@@ -33,6 +33,10 @@ function M.get_language_servers()
   -- TODO - define language servers
 end
 
+function M.get_prefs_schema()
+  -- TODO - define preferences
+end
+
 return M
 ```
 Editor then collects all editor scripts defined in project and libraries, loads them into single Lua VM and calls into them when needed (more on that in [commands](#commands) and [lifecycle hooks](#lifecycle-hooks) sections).
@@ -63,6 +67,7 @@ You can interact with the editor using `editor` package that defines this API:
 - `editor.save()` — persist all unsaved changed to disk.
 - `editor.transact(txs)` — modify the editor in-memory state using 1 or more transaction steps created with `editor.tx.*` functions.
 - `editor.ui.*` — various UI-related functions, see [UI manual](/manuals/editor-scripts-ui).
+- `editor.prefs.*` — functions for interacting with editor preferences, see [prefs](#prefs).
 
 You can find the full editor API reference [here](https://defold.com/ref/alpha/editor/).
 
@@ -244,6 +249,47 @@ You can publish libraries for other people to use that contain commands, and the
 
 Also note that although dependencies are shown in Assets view, they do not exist as files (they are entries in a zip archive). It's possible to make the editor extract some files from the dependencies into `build/plugins/` folder. To do it, you need to create `ext.manifest` file in your library folder, and then create `plugins/bin/${platform}` folder in the same folder where the `ext.manifest` file is located. Files in that folder will be automatically extracted to `/build/plugins/${extension-path}/plugins/bin/${platform}` folder, so your editor scripts can reference them.
 
+## Prefs
+
+Editor scripts can define and use preferences — persistent, uncommitted pieces of data stored on the user's computer. These preferences have three key characteristics:
+- typed: every preference has a schema definition that includes the data type and other metadata like default value
+- scoped: prefs are scoped either per project or per user
+- nested: every preference key is a dot-separated string, where the first path segment identifies an editor script, and the rest 
+
+All preferences must be registered by defining their schema:
+```lua
+function M.get_prefs_schema()
+  return {
+    ["my_json_formatter.jq_path"] = editor.prefs.schema.string(),
+    ["my_json_formatter.indent.size"] = editor.prefs.schema.integer({default = 2, scope = editor.prefs.SCOPE.PROJECT}),
+    ["my_json_formatter.indent.type"] = editor.prefs.schema.enum({values = {"spaces", "tabs"}, scope = editor.prefs.SCOPE.PROJECT}),
+  }
+end
+```
+After such editor script is reloaded, the editor registers this schema. Then the editor script can get and set the prefs, e.g.:
+```lua
+-- Get a specific preference
+editor.prefs.get("my_json_formatter.indent.type")
+-- Returns: "spaces"
+
+-- Get an entire preference group
+editor.prefs.get("my_json_formatter")
+-- Returns:
+-- {
+--   jq_path = "",
+--   indent = {
+--     size = 2,
+--     type = "spaces"
+--   }
+-- }
+
+-- Set multiple nested preferences at once
+editor.prefs.set("my_json_formatter.indent", {
+    type = "tabs",
+    size = 1
+})
+```
+
 ## Execution modes
 
 The editor script runtime uses 2 execution modes that are mostly transparent to editor scripts: **immediate** and **long-running**.