Add convenience extensions for NSFileManager cache and document direc…

…tories (#72)

* Add convenience extensions for NSFileManager cache and document directories

* Update documentation for NSFileManager extensions

docs/topics/usage-list-store.md

@@ -1,6 +1,6 @@
 # Using List Store
 > This is experimental API and may be removed in future releases
-{style="warning"}
+{style="note"}
 
 KStore provides you with some convenient extensions to manage stores that contain lists.
 

docs/topics/using-platform-paths.md

@@ -1,35 +1,61 @@
 # Using Platform Specific Paths
 
 Getting a path to a file is different for each platform, and you will need to define how this works for each platform
+
 ```kotlin
-var appDir: String
+var storageDir: String
 ```
 > For this example, we are keeping this as a top level variable. 
-{ style="note" }
+> { style="note" }
 
 ## On Android
-Getting a path on android involves invoking from `filesDir` from a `Context`.
+Getting a path on android involves invoking from `filesDir`/`cacheDir` from a `Context`.
 ```kotlin
 class MainActivity : ComponentActivity() {
   override fun onCreate(savedInstanceState: Bundle?) {
     super.onCreate(savedInstanceState)
-    appDir = filesDir.path
+
+    // for documents directory
+    storageDir = filesDir.path
+
+    // or caches directory
+    storageDir = cacheDir.path
   }
 }
 ```
 
-## On iOS & other Apple platforms
-To get a path on iOS, you can use `NSHomeDirectory`.
-```kotlin
-appDir = NSHomeDirectory()
-```
-
 ## On Desktop (JVM)
 
 This depends on where you want to save your files, but generally you should save your files in a user data directory.
 Recommending to use [harawata's appdirs](https://github.com/harawata/appdirs) to get the platform specific app dir
 
 ```kotlin
-appDir = AppDirsFactory.getInstance()
+storageDir = AppDirsFactory.getInstance()
   .getUserDataDir(PACKAGE_NAME, VERSION, ORGANISATION)
 ```
+
+## On iOS & other Apple platforms
+This depends on where you want to place your files. For most common use-cases, you will want either `NSDocumentDirectory` or `NSCachesDirectory`
+
+KStore provides you a convenience extensions to resolve these for you
+
+```kotlin
+// for documents directory
+storageDir = NSFileManager.defaultManager.DocumentDirectory?.relativePath
+
+// or caches directory
+storageDir = NSFileManager.defaultManager.CachesDirectory?.relativePath
+```
+
+> This is experimental API and may be removed in future releases
+> {style="note"}
+
+> `NSHomeDirectory()` _(though it works on the simulator)_ is **not** suitable for physical devices as the security policies on physical devices does not permit read/writes to this directory
+> {style="warning"}
+
+
+<seealso style="cards">
+  <category ref="external">
+    <a href="https://tanaschita.com/20221010-quick-guide-on-the-ios-file-system/">Learn how to work with files and directories when developing iOS applications</a>
+  </category>
+</seealso>

kstore-file/src/appleMain/kotlin/io/github/xxfast/kstore/file/utils/NSFileManager.kt

@@ -0,0 +1,30 @@
+package io.github.xxfast.kstore.file.utils
+
+import io.github.xxfast.kstore.utils.ExperimentalKStoreApi
+import kotlinx.cinterop.ExperimentalForeignApi
+import kotlinx.cinterop.UnsafeNumber
+import platform.Foundation.NSCachesDirectory
+import platform.Foundation.NSDocumentDirectory
+import platform.Foundation.NSFileManager
+import platform.Foundation.NSURL
+import platform.Foundation.NSUserDomainMask
+
+@ExperimentalKStoreApi
+@OptIn(UnsafeNumber::class, ExperimentalForeignApi::class)
+public val NSFileManager.DocumentDirectory: NSURL? get() = URLForDirectory(
+  directory = NSDocumentDirectory,
+  appropriateForURL = null,
+  create = false,
+  inDomain = NSUserDomainMask,
+  error = null
+)
+
+@ExperimentalKStoreApi
+@OptIn(UnsafeNumber::class, ExperimentalForeignApi::class)
+public val NSFileManager.CachesDirectory: NSURL? get() = URLForDirectory(
+  directory = NSCachesDirectory,
+  appropriateForURL = null,
+  create = false,
+  inDomain = NSUserDomainMask,
+  error = null
+)