Documentation for the upcoming storage API

docs/source/api/storage.rst

@@ -0,0 +1,178 @@
+storage
+=======
+
+Simple key/value storage.
+
+Saving happens in the background, so your project can keep running smoothly. If you need to make sure your changes are saved right away (for example, before quitting or switching levels), call storage:flush().
+
+Storage uses string keys (like "highScore"), and the value you save must be either boolean, number, string, or a table containing only those kinds of values. If you store nil for a given key, then that key/value pair will be removed from storage.
+
+You can read and write values directly using property-style access (``storage.highScore = 100`` and ``print(storage.highScore)``).
+
+The default storage is per-project. A device-wide store is available under ``storage.global``.
+
+.. lua:module:: storage
+
+**Basic Usage**
+
+.. code-block:: lua
+
+   -- Default project storage
+   storage.highScore = 9001
+   print(storage.highScore or 0)
+
+   -- Missing key uses default
+   print(storage.missing or 42)
+
+   -- Remove a key
+   storage.temp = nil
+
+.. lua:function:: has(key)
+
+   Checks if a key exists.
+
+   :param key: Key to check
+   :type key: string
+   :return: True if the key exists, false otherwise
+   :rtype: boolean
+
+   .. code-block:: lua
+
+      if storage:has("playerName") then
+          print("Player name saved")
+      end
+
+.. lua:function:: delete(key)
+
+   Removes a key.
+
+   :param key: Key to remove
+   :type key: string
+
+   .. code-block:: lua
+
+      storage:delete("tutorialSeen")
+
+.. lua:function:: keys()
+
+   Returns a sorted array of all keys in the store.
+
+   :return: Sorted list of keys
+   :rtype: table
+
+   .. code-block:: lua
+
+      for _, key in ipairs(storage:keys()) do
+          print(key)
+      end
+
+.. lua:function:: clear()
+
+   Removes all keys from the store.
+
+   .. code-block:: lua
+
+      storage:clear()
+
+.. lua:function:: flush()
+
+   Writes any pending changes synchronously.
+
+   .. code-block:: lua
+
+      storage.level = 3
+      storage:flush()
+
+.. lua:function:: asset()
+
+   Returns the underlying asset key for the storage file.
+
+   :return: Asset key used for the store file
+   :rtype: assetKey
+
+   .. code-block:: lua
+
+      print(storage:asset())
+
+.. lua:function:: namespace(prefix)
+
+   Returns a view of the store that prefixes all keys with ``prefix``. A ``.`` is added automatically if missing.
+
+   :param prefix: Namespace prefix (for example, ``"prefs"``)
+   :type prefix: string
+   :return: Namespaced storage view
+   :rtype: table
+
+   .. code-block:: lua
+
+      local prefs = storage:namespace("prefs")
+      prefs.audioMuted = true -- stored as "prefs.audioMuted"
+      print(prefs.audioMuted)
+
+.. lua:attribute:: storage.project: storage
+
+   Default project-scoped storage (stored under ``asset``). This is the same store used by the top-level ``storage`` functions.
+
+.. lua:attribute:: storage.global: storage
+
+   Default device-wide storage (stored under ``asset.documents``).
+
+.. lua:function:: projectStore(name)
+
+   Convenience wrapper for ``storage(name, "project")``.
+
+   :param name: Store name
+   :type name: string
+   :return: Storage instance
+   :rtype: table
+
+.. lua:function:: globalStore(name)
+
+   Convenience wrapper for ``storage(name, "global")``.
+
+   :param name: Store name
+   :type name: string
+   :return: Storage instance
+   :rtype: table
+
+.. lua:currentmodule:: None
+
+.. lua:function:: storage(name [, scope])
+
+   Returns a named store. Stores are cached by name and scope, so repeated calls return the same store instance.
+
+   :param name: Store name (used to derive the file name)
+   :type name: string
+   :param scope: Store scope (``"project"`` or ``"global"``)
+   :type scope: string
+   :return: Storage instance
+   :rtype: table
+
+   .. code-block:: lua
+
+      local settings = storage("settings")
+      local globalPrefs = storage("prefs", "global")
+
+**Usage Patterns**
+
+.. code-block:: lua
+
+   -- Separate storage for different systems
+   local prefs = storage:namespace("prefs")
+   local stats = storage:namespace("stats")
+
+   prefs.musicEnabled = true
+   stats.gamesPlayed = 12
+
+   -- Project vs global
+   local projectStore = storage.project
+   local globalStore = storage.global
+
+   projectStore.level = 3
+   globalStore.unlocked = { "sword", "shield" }
+
+**Notes**
+
+* Keys must be strings
+* Values must be (``nil``, ``boolean``, ``number``, ``string``, ``table``)
+* Storage saves in the background, call storage:flush() if you need to write storage immediately (for example, before quitting)

docs/source/api/string.rst

@@ -29,11 +29,22 @@ Used to interact with text files.
     :return: The contents of the file.
     :rtype: string
 
-.. lua:function:: save(assetKey, text)
+.. lua:function:: save(assetKey, text [, callback])
 
     Saves text to a file.
 
+    If a callback is supplied, saving will happen in the background. Multiple calls to save the same file are grouped and only the latest save will be performed.
+
     .. helptext:: save the text to a file
 
     :param assetKey assetKey: The asset key of the file.
-    :param string text: The text to save.
+    :param string text: The text to save.
+    :param function callback: Optional completion callback ``function(ok, err)``.
+
+    .. code-block:: lua
+
+        string.save(asset.documents .. "Config.json", json.encode(config), function(ok, err)
+            if not ok then
+                print("Save failed:", err)
+            end
+        end)

docs/source/index.rst

@@ -72,6 +72,7 @@ Codea 4
    api/pick
    api/viewer
    api/device
+   api/storage
 
 Indices and tables
 ==================