From 0979cd133054bf151aaaa5e3ead8cdb4c8582950 Mon Sep 17 00:00:00 2001
From: pysan3 <pysan3@gmail.com>
Date: Mon, 29 Jan 2024 21:55:24 +0900
Subject: [PATCH] docs(README): add befefits section

---
 README.md   | 71 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
 README.norg | 62 +++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 129 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index d66adc7..3bc42bf 100644
--- a/README.md
+++ b/README.md
@@ -27,7 +27,56 @@ mutliple OSs in neovim. The plugin API is heavily inspired by Python's
 [neo-tree.nvim](https://github.com/nvim-neo-tree/neo-tree.nvim) but it
 is very simple and portable to be used in any plugin.
 
-# Usage Example
+# ✨ Benefits
+
+## 📦 Intuitive and Useful Methods
+
+``` lua
+local Path = require("pathlib")
+local dir = Path("~/Documents") -- Same as `Path.home() / "Documents"`
+local foo = dir / "foo.txt"
+
+print(foo:basename(), foo:stem(), foo:suffix()) -- foo.txt, foo, .txt
+print(foo:parent()) -- "/home/user/Documents"
+```
+
+## 📋 Git Integration
+
+``` lua
+local git_root = Path("/path/to/git/workdir")
+-- assert(git_root:child(".git"):exists(), string.format("%s is not a git repo.", git_root))
+
+require("pathlib.git").fill_git_state({ file_a, file_b, ... })
+
+file_a.git_state.ignored  -- is git ignored
+file_a.git_state.status   -- git status (modified, added, staged, ...)
+file_a.git_state.git_root -- root directory of the repo
+```
+
+## ⏱️ Sync / Async Operations
+
+The API is designed so it is very easy to switch between sync and async
+operations. Call them inside [nvim-nio
+task](https://github.com/nvim-neotest/nvim-nio) without any change, and
+the operations are converted to be async (does not block the main
+thread).
+
+``` lua
+local foo = Path("~/Documents/foo.txt")
+local content = "File Content\n"
+
+-- # sync
+local sync_bytes = foo:fs_write(content)
+assert(sync_bytes == content:len(), foo.error_msg)
+
+-- # async
+require("nio").run(function()
+  local async_bytes = foo:fs_write(content)
+  assert(async_bytes == content:len(), foo.error_msg)
+end)
+```
+
+# 🚀 Usage Example
 
 ## Create Path Object
 
@@ -51,6 +100,26 @@ local bar = foo .. "bar.txt"
 assert(tostring(bar)          == "folder/bar.txt")
 ```
 
+### Path object is stored with `string[]`.
+
+- Very fast operations to work with parents / children / siblings.
+
+- No need to worry about path separator =\> OS Independent.
+
+  - `/`: Unix, `\`: Windows
+
+### Nicely integrated with vim functions.
+
+There are wrappers around vim functions such as `fnamemodify`, `stdpath`
+and `getcwd`.
+
+``` lua
+path:modify(":p:t:r")                -- vim.fn.fnamemodify
+
+-- Define child directory of stdpaths
+Path.stdpath("data", "mason", "bin") -- vim.fn.stdpath("data") .. "/mason/bin"
+```
+
 ## Create and Manipulate Files / Directories
 
 ``` lua
diff --git a/README.norg b/README.norg
index fedbd09..99f3ae4 100644
--- a/README.norg
+++ b/README.norg
@@ -4,7 +4,7 @@ description:
 authors: takuto
 categories:
 created: 2023-11-14
-updated: 2024-01-26T19:32:04+0900
+updated: 2024-01-29T17:41:30+0900
 version: 1.1.1
 @end
 
@@ -35,7 +35,49 @@ version: 1.1.1
   It is mainly used in {https://github.com/nvim-neo-tree/neo-tree.nvim}[neo-tree.nvim]
   but it is very simple and portable to be used in any plugin.
 
-* Usage Example
+* ✨ Benefits
+** 📦 Intuitive and Useful Methods
+   @code lua
+   local Path = require("pathlib")
+   local dir = Path("~/Documents") -- Same as `Path.home() / "Documents"`
+   local foo = dir / "foo.txt"
+
+   print(foo:basename(), foo:stem(), foo:suffix()) -- foo.txt, foo, .txt
+   print(foo:parent()) -- "/home/user/Documents"
+   @end
+
+** 📋 Git Integration
+   @code lua
+   local git_root = Path("/path/to/git/workdir")
+   -- assert(git_root:child(".git"):exists(), string.format("%s is not a git repo.", git_root))
+
+   require("pathlib.git").fill_git_state({ file_a, file_b, ... })
+
+   file_a.git_state.ignored  -- is git ignored
+   file_a.git_state.status   -- git status (modified, added, staged, ...)
+   file_a.git_state.git_root -- root directory of the repo
+   @end
+
+** ⏱️ Sync / Async Operations
+   The API is designed so it is very easy to switch between sync and async operations.
+   Call them inside {https://github.com/nvim-neotest/nvim-nio}[nvim-nio task] without any change,
+   and the operations are converted to be async (does not block the main thread).
+   @code lua
+   local foo = Path("~/Documents/foo.txt")
+   local content = "File Content\n"
+
+   -- # sync
+   local sync_bytes = foo:fs_write(content)
+   assert(sync_bytes == content:len(), foo.error_msg)
+
+   -- # async
+   require("nio").run(function()
+     local async_bytes = foo:fs_write(content)
+     assert(async_bytes == content:len(), foo.error_msg)
+   end)
+   @end
+
+* 🚀 Usage Example
 ** Create Path Object
   @code lua
   local Path = require("pathlib")
@@ -57,6 +99,20 @@ version: 1.1.1
   assert(tostring(bar)          == "folder/bar.txt")
   @end
 
+*** Path object is stored with `string[]`.
+    - Very fast operations to work with parents / children / siblings.
+    - No need to worry about path separator => OS Independent.
+    -- `/`: Unix, `\\`: Windows
+
+*** Nicely integrated with vim functions.
+    There are wrappers around vim functions such as `fnamemodify`, `stdpath` and `getcwd`.
+    @code lua
+    path:modify(":p:t:r")                -- vim.fn.fnamemodify
+
+    -- Define child directory of stdpaths
+    Path.stdpath("data", "mason", "bin") -- vim.fn.stdpath("data") .. "/mason/bin"
+    @end
+
 ** Create and Manipulate Files / Directories
    @code lua
    local luv = vim.loop
@@ -125,7 +181,7 @@ version: 1.1.1
 
 * TODO
   - ( ) API documentation.
-  - ( ) Git operation integration.
+  - (-) Git operation integration.
   - ( ) Windows implementation, test environment.
 
 * Contributions