Merge: lib/config: fix doc

[nit.git] / lib / json / store.nit

diff --git a/lib/json/store.nit b/lib/json/store.nit
index 23a176c..04ed922 100644 (file)
--- a/lib/json/store.nit
+++ b/lib/json/store.nit
@@ -14,54 +14,85 @@
 #
 # ## Usage
 #
-# Create a new JsonStore or reuse an existing one.
+# ### Initialization
+#
+# JsonStore use the file system to store and load json files.
+#
+# For initialization you need to give the directory used in the
+# file system to save objects.
+#
 # ~~~
 # var store = new JsonStore("store_dir")
 # ~~~
 #
-# JsonStore can store json of type JsonObject and JsonArray.
+# ### Documents
+#
+# With JsonStore you manage *documents*.
+# Documents are simple json files that can be stored and loaded from json store.
+#
+# JsonStore can store documents of type JsonObject and JsonArray.
 # ~~~
-# var red = "red"
-# var obj = new JsonObject
-# obj["color"] = red
-# obj["code"] = "FF0000"
+# var red = new JsonObject
+# red["name"] = "red"
+# red["code"] = "FF0000"
 # ~~~
 #
-# Data are stored under a key.
+# Data are stored under a *key*.
+# This is the path to the document from `JsonStore::store_dir`
+# without the `.json` extension.
+#
+# Examples:
+#
+# * key `document` will store data under `store_dir / "document.json"`
+# * key `collection/data` will store data under `store_dir / "collection/data.json"`
+#
 # ~~~
-# var key = "colors/{red}"
+# var key = "colors/red"
 # ~~~
 #
 # Store the object.
 # ~~~
-# store.store_object(key, obj)
-# assert store.has_key(key)
+# store.store_object(key, red)
 # ~~~
 #
 # Load the object.
 # ~~~
-# var res = store.load_object(key)
-# assert res["name"] == red
+# assert store.has_key(key)
+# var obj = store.load_object(key)
+# assert obj["name"] == obj["name"]
+# ~~~
+#
+# ### Collections
+#
+# A collection is a set of documents stored under the same path.
+#
+# ~~~
+# var green = new JsonObject
+# green["name"] = "green"
+# green["code"] = "00FF00"
+# store.store_object("colors/green", green)
+#
+# assert store.has_collection("colors")
+#
+# var col = store.list_collection("colors")
+# assert col.length == 2
+# assert col.has("green")
+# assert col.has("red")
 # ~~~
 #
-# Clear all stored data.
+# ### Clearing store
+#
+# You can delete all the data contained in the `JsonStore::store_dir` with `clear`.
+#
 # ~~~
 # store.clear
 # ~~~
 module store
 
 import static
+import json
 
 # A JsonStore can save and load json data from file system.
-#
-# Json files are stored under a `key`.
-# This key represents the path to the json file from `store_dir`
-# without the `.json` extension.
-#
-# Examples:
-#
-# * key `document` will store data under `store_dir / "document.json"`
-# * key `collection/data` will store data under `store_dir / "collection/data.json"`
 class JsonStore
 
        # Directory where data are stored.
@@ -80,7 +111,7 @@ class JsonStore
 
        # Is there data are stored under `key`.
        fun has_key(key: String): Bool do
-               return (store_dir / "{key}.json").file_exists
+               return ("{store_dir}/{key}.json".simplify_path).file_exists
        end
 
        # Save `json` object under `key`.
@@ -97,10 +128,10 @@ class JsonStore
        #
        # Only `JsonObject` and `JsonArray` are allowed in a json file.
        # Use `store_object` or `store_array` instead.
-       private fun store_json(key: String, json: Jsonable) do
-               var path = store_dir / "{key}.json"
+       private fun store_json(key: String, json: Serializable) do
+               var path = "{store_dir}/{key}.json".simplify_path
                path.dirname.mkdir
-               var file = new OFStream.open(path)
+               var file = new FileWriter.open(path)
                file.write(json.to_json)
                file.close
        end
@@ -118,12 +149,31 @@ class JsonStore
        # Load a JsonObject associated to `key` from store.
        #
        # Ensure `has_data(key)`
-       private fun load_json(key: String): nullable Jsonable do
+       private fun load_json(key: String): nullable Serializable do
                assert has_key(key)
-               var path = store_dir / "{key}.json"
-               var file = new IFStream.open(path)
+               var path = "{store_dir}/{key}.json".simplify_path
+               var file = new FileReader.open(path)
                var text = file.read_all
                file.close
                return text.parse_json
        end
+
+       # Get the list of keys stored under the collection `key`.
+       fun list_collection(key: String): JsonArray do
+               var res = new JsonArray
+               var coll = ("{store_dir}/{key}".simplify_path).to_path
+               if not coll.exists or not coll.stat.is_dir then return res
+               for file in coll.files do
+                       if file.to_s.has_suffix(".json") then
+                               res.add(file.to_s.basename(".json"))
+                       end
+               end
+               return res
+       end
+
+       # Does `key` matches a collection?
+       fun has_collection(key: String): Bool do
+               var path = ("{store_dir}/{key}".simplify_path).to_path
+               return path.exists and path.stat.is_dir
+       end
 end