feat(fixed interval): support fixed interval timing and policy (#59)

Author: linrongbin16

README.md

@@ -14,6 +14,20 @@ I'm greedy that I want all the **most popular** Neovim colorschemes than only on
 
 Let's load all the ultra colorschemes into your Neovim player!
 
+![shuffle-per-seconds-v1](https://github.com/linrongbin16/colorbox.nvim/assets/6496887/74cc205f-fbf6-4edb-abdd-72aaea27b50b)
+
+<details>
+<summary><i>Click here to see how to configure</i></summary>
+
+```lua
+require('colorbox').setup({
+  policy = { name = "interval", seconds = 1, implement = "shuffle" },
+  timing = "interval",
+})
+```
+
+</details>
+
 It use offline github actions to weekly collect and update the most popular Vim/Neovim colorscheme list.
 
 > The **most popular** colorschemes are picked from below websites:
@@ -57,6 +71,8 @@ And multiple trigger timings (colorschemes don't have end time):
   - [lazy.nvim](#lazynvim)
   - [pckr.nvim](#pckrnvim)
 - [Configuration](#-configuration)
+  - [On Startup](#on-startup)
+  - [Fixed Interval](#fixed-interval)
 - [Development](#-development)
 - [Contribute](#-contribute)
 
@@ -122,7 +138,16 @@ You can use command `Colorbox` to control the colorschemes player:
 
 ```lua
 require('colorbox').setup({
-    --- @type "shuffle"|"in_order"|"reverse_order"|"single"
+    -- by filetype policy: filetype => color name
+    --- @alias ByFileTypePolicyConfigFileType string
+    --- @alias ByFileTypePolicyConfigColorName string
+    --- @alias ByFileTypePolicyConfig {name:"filetype",mapping:table<ByFileTypePolicyConfigFileType, ByFileTypePolicyConfigColorName>}
+    ---
+    -- fixed interval seconds
+    --- @alias FixedIntervalPolicyConfig {name:"interval",seconds:integer,implement:"shuffle"|"in_order"|"reverse_order"|"single"}
+    ---
+    --- @alias PolicyConfig "shuffle"|"in_order"|"reverse_order"|"single"|ByFileTypePolicyConfig|FixedIntervalPolicyConfig
+    --- @type PolicyConfig
     policy = "shuffle",
 
     --- @type "startup"|"interval"|"filetype"
@@ -172,6 +197,28 @@ require('colorbox').setup({
 })
 ```
 
+### On Startup
+
+To choose a colorscheme on nvim start, please use:
+
+```lua
+require('colorbox').setup({
+    policy = 'shuffle',
+    timing = 'startup',
+})
+```
+
+### Fixed Interval
+
+To choose a colorscheme on fixed interval per seconds, please use:
+
+```lua
+require('colorbox').setup({
+    policy = { name = "interval", seconds = 1, implement = "shuffle" },
+    timing = 'interval',
+})
+```
+
 ## ✏️ Development
 
 To develop the project and make PR, please setup with:

lua/colorbox.lua

@@ -6,7 +6,28 @@ local json = require("colorbox.json")
 --- @alias colorbox.Options table<any, any>
 --- @type colorbox.Options
 local Defaults = {
-    --- @type "shuffle"|"in_order"|"reverse_order"|"single"
+    -- shuffle playback
+    --- @alias ShufflePolicyConfig "shuffle"
+    ---
+    --- in order
+    --- @alias InOrderPolicyConfig "in_order"
+    ---
+    --- reverse order
+    --- @alias ReverseOrderPolicyConfig "reverse_order"
+    ---
+    --- single cycle
+    --- @alias SinglePolicyConfig "single"
+    ---
+    -- by filetype policy: filetype => color name
+    --- @alias ByFileTypePolicyConfigFileType string
+    --- @alias ByFileTypePolicyConfigColorName string
+    --- @alias ByFileTypePolicyConfig {name:"filetype",mapping:table<ByFileTypePolicyConfigFileType, ByFileTypePolicyConfigColorName>}
+    ---
+    -- fixed interval seconds
+    --- @alias FixedIntervalPolicyConfig {name:"interval",seconds:integer,implement:ShufflePolicyConfig|InOrderPolicyConfig|ReverseOrderPolicyConfig|SinglePolicyConfig}
+    ---
+    --- @alias PolicyConfig ShufflePolicyConfig|InOrderPolicyConfig|ReverseOrderPolicyConfig|SinglePolicyConfig|ByFileTypePolicyConfig|FixedIntervalPolicyConfig
+    --- @type PolicyConfig
     policy = "shuffle",
 
     --- @type "startup"|"interval"|"filetype"
@@ -126,6 +147,16 @@ local function _init()
     )
 end
 
+local function _before_running_colorscheme_hook()
+    if Configs.background == "dark" or Configs.background == "light" then
+        vim.opt.background = Configs.background
+    end
+end
+
+local function _after_running_colorscheme_hook()
+    vim.cmd([[syntax sync fromstart]])
+end
+
 --- @alias PreviousTrack {color_name:string,color_number:integer}
 --- @param color_name string
 --- @param color_number integer
@@ -162,6 +193,7 @@ local function _policy_shuffle()
         --     vim.inspect(ColorNames),
         --     vim.inspect()
         -- )
+        _before_running_colorscheme_hook()
         vim.cmd(string.format([[color %s]], color))
         _save_previous_track(color, i)
     end
@@ -176,6 +208,7 @@ local function _policy_in_order()
                 #FilteredColorNamesList
             )
         local color = FilteredColorNamesList[i + 1]
+        _before_running_colorscheme_hook()
         vim.cmd(string.format([[color %s]], color))
         _save_previous_track(color, i)
     end
@@ -191,21 +224,53 @@ local function _policy_reverse_order()
                 or previous_track.color_number - 1
             )
         local color = FilteredColorNamesList[i + 1]
+        _before_running_colorscheme_hook()
         vim.cmd(string.format([[color %s]], color))
         _save_previous_track(color, i)
     end
 end
 
-local function _policy()
-    if Configs.background == "dark" or Configs.background == "light" then
-        vim.opt.background = Configs.background
+--- @param po colorbox.Options?
+local function _is_fixed_interval_policy(po)
+    return type(po) == "table"
+        and po.name == "interval"
+        and type(po.seconds) == "number"
+        and po.seconds >= 0
+        and type(po.implement) == "string"
+        and string.len(po.implement) > 0
+end
+
+local function _policy_fixed_interval()
+    local later = Configs.policy.seconds > 0 and (Configs.policy.seconds * 1000)
+        or utils.int32_max
+
+    local function impl()
+        if Configs.policy.implement == "shuffle" then
+            _policy_shuffle()
+            _after_running_colorscheme_hook()
+        elseif Configs.policy.implement == "in_order" then
+            _policy_in_order()
+            _after_running_colorscheme_hook()
+        elseif Configs.policy.implement == "reverse_order" then
+            _policy_reverse_order()
+            _after_running_colorscheme_hook()
+            -- elseif Configs.policy.implement == "single" then
+            --     -- TODO: implement single cycle
+        end
+        vim.defer_fn(impl, later)
     end
+    impl()
+end
+
+local function _policy()
     if Configs.policy == "shuffle" then
         _policy_shuffle()
     elseif Configs.policy == "in_order" then
         _policy_in_order()
     elseif Configs.policy == "reverse_order" then
         _policy_reverse_order()
+    elseif _is_fixed_interval_policy(Configs.policy) then
+        _policy_fixed_interval()
     end
 end
 
@@ -215,8 +280,23 @@ local function _timing_startup()
     })
 end
 
+local function _timing_interval()
+    -- Configs.timing
+end
+
 local function _timing()
-    _timing_startup()
+    if Configs.timing == "startup" then
+        _timing_startup()
+    elseif Configs.timing == "interval" then
+        assert(
+            _is_fixed_interval_policy(Configs.policy),
+            string.format(
+                "invalid policy %s for 'interval' timing!",
+                vim.inspect(Configs.policy)
+            )
+        )
+        _policy_fixed_interval()
+    end
 end
 
 --- @param opts {concurrency:integer}?

lua/colorbox/utils.lua

@@ -1,3 +1,5 @@
+local int32_max = 2 ^ 31 - 1
+
 -- Returns the XOR of two binary numbers
 --- @param a integer
 --- @param b integer
@@ -20,7 +22,7 @@ end
 --- @param f fun(v:any):number
 --- @return number
 local function min(l, f)
-    local result = 2 ^ 31 - 1
+    local result = int32_max
     for _, i in ipairs(l) do
         result = math.min(result, f(i))
     end
@@ -37,7 +39,6 @@ end
 --- @param maximal integer?
 --- @return integer
 local function randint(maximal)
-    local int32_max = 2 ^ 31 - 1
     maximal = maximal or int32_max
     local s1 = vim.loop.getpid()
     local s2, s3 = vim.loop.gettimeofday()
@@ -117,6 +118,7 @@ local function readfile(filename, opts)
 end
 
 local M = {
+    int32_max = int32_max,
     min = min,
     math_mod = math_mod,
     randint = randint,