feat: format code and add cmd doc

lua/Trans/component/content.lua

@@ -12,21 +12,33 @@ function M:new()
     return content
 end
 
---- NOTE :highlight 格式说明:
---- 1. 字符串
 
 
-function M:insert_items_to_line(items, opts)
+-- NOTE :
+-- local items = {
+--     -- style1: string 不需要单独设置高亮的情况
+--     'text', 
+--     -- style2: string[] 需要设置高亮，第二个名称为高亮组
+--     {'text2', 'highlight name'}, 
+-- }
+
+-- local opts = {
+--     -- 可选的参数
+--     highlight = 'highlight name' -- string 该行的高亮
+--     indent = 4 -- integer 该行的应该在开头的缩进
+--     interval = 4 -- integer 该行组件的间隔
+-- }
+function M:insert_items_to_line(items)
     type_check {
         items = { items, 'table' },
-        opts = { opts, 'table', true },
     }
+
     self.size = self.size + 1 -- line数加一
 
     local line = {
-        space = (' '):rep(opts.interval),
+        space = (' '):rep(items.interval),
-        indent = opts.indent,
+        indent = items.indent,
-        highlight = opts.highlight,
+        highlight = items.highlight,
     }
     local highlight = {}
 
@@ -45,7 +57,7 @@ function M:insert_items_to_line(items, opts)
     self.lines[self.size] = line
 end
 
----遍历lines和高亮的迭代器
+
 ---Usage:
 ---     local buffer_id
 ---     local lines, highlights = M:lines()

lua/Trans/component/offline/Title.lua

@@ -3,7 +3,6 @@ local M = {}
 local display = require("Trans.conf.loader").loaded.conf.ui.display
 local icon = require("Trans.conf.loader").loaded.conf.ui.icon
 
-local m_field = {}
 -- {
 --   collins = 3,
 --   definition = "n. an expression of greeting",
@@ -17,64 +16,53 @@ local m_field = {}
 -- }
 
 
-local content = {
+-- local data = {
-    lines = {
+--     { word, 'TransWord' },
-        need_format = {
+--     -- NOTE :如果平配置设置显示，并且数据库中存在则有以下字段
-            {}, -- line
+--     { phonetic, 'TransPhonetic' },
-            {}, -- line
+--     collins,
-            {}, -- line
+--     oxford
-            {}, -- line
+--     -- { phonetic, 'TransPhonetic' },
-        }
+-- }
-    },
+
-    highlight = {
+---@alias stuff
-        [2] = { -- 第几行第几个组件的高亮
+---| 'data'       # 所有组件的信息
-            [1] = 'highlightname',
+---| 'highlight?' # 整个组件的高亮
-        },
+---| 'indent?'    # 每行整体的缩进
-    }
+---| 'interval?'  # 每个组件的间隔
+---@alias component stuff[]
+
+---从查询结果中获取字符串
+---@param field table 查询的结果
+---@return component component 提取的组件信息[包含多个组件]
+M.component = function(field)
+    local component = {}
+    local stuffs = {}
+    local data = {
+        {field.word, 'TransWord'},
     }
 
-local function get_items()
+    if display.phonetic and field.phonetic then
-    local items = {
+        table.insert(data, {
-        m_field.word,
+            '[' .. field.phonetic .. ']', 'TransPhonetic'
-    }
+        })
-    if display.phonetic then
-        table.insert(items, '[' .. m_field.phonetic .. ']')
     end
 
-    if display.collins_star then
+    if display.collins and field.collins then
-        table.insert(items, icon.star:rep(m_field.collins))
+        table.insert(data, {
+            icon.star:rep(field.collins)
+        })
     end
 
-    if display.oxford then
+    if display.oxford and field.oxford then
-        local item
+        table.insert(data, {
-        if m_field.oxford and m_field.oxford == 1 then
+            field.oxford
-            item = icon.isOxford
+        })
-        else
-            item = icon.notOxford
-        end
-        table.insert(items, item)
     end
 
-    return items
+    stuffs.data = data
-end
+    component[1] = stuffs
-
+    return component
-M.content = function(field)
-    -- TODO
-    m_field = field or {}
-    local content = {}
-
-
-    content.lines = {
-        need_format = {
-            get_items()
-        },
-        highlight = {
-            [1] = { -- 第一行
-                'Trans',
-            }
-        }
-    }
-    return content
 end
 
 return M

lua/Trans/conf/default.lua

@@ -96,6 +96,9 @@ M.conf = {
     -- map = {
     --     -- TODO
     -- },
+    -- history = {
+    --     -- TOOD 
+    -- }
 
     -- TODO  add online translate engine
     -- online_search = {

lua/Trans/core/READMD.md

@@ -0,0 +1,96 @@
+# 命令说明
+
+<!--toc:start-->
+- [命令说明](#命令说明)
+  - [Translate](#translate)
+  - [TranslateInput](#translateinput)
+  - [TranslateHistory](#translatehistory)
+  - [自定义](#自定义)
+    - [可选项说明](#可选项说明)
+    - [示例](#示例)
+<!--toc:end-->
+
+## Translate
+**窗口风格默认为:** `cursor`
+- 动作(action):
+    - `vsplit`         水平分屏
+    - `split`          垂直分屏
+    - `float`          窗口样式又`cursor` 变为`float`
+    - `online_query`   使用在线引擎重新进行查询
+    - `history_insert` 将此次查询的单词记录到历史记录  
+    - `next`           展示下一个引擎的查询结果(如果默认设置了多个引擎)
+    - `prev`           展示上一个查询结果
+    > 如果没有设置自动保存历史的话
+
+    - `history`        查看历史查询的记录
+
+- `online_query`:
+    - `local_add`    将此次查询的结果添加到本地数据库  
+    > **如果本地已经存在该单词，会询问是否需要覆盖掉相同的字段**
+
+    - `local_update` 和*local_add* 类似, 但是不会询问是否覆盖
+    - `diff`         对比本地查询结果和此次在线查询的区别
+
+>  **注意**: 动作是任何窗口通用的  
+## TranslateInput
+**窗口风格默认为:** `float`
+- 自行得到要查询的单词
+
+- TODO: 
+    - fuzzy match
+
+## TranslateHistory
+**窗口风格默认为:** `float`
+- 查看历史查询
+
+---
+## 自定义
+
+### 可选项说明
+- 查询方式(method): `string`
+    - `input` 自行输入需要查询的单词
+    - `last`  显示上一次查询的结果
+    - `history`
+
+- 查询引擎(engine): `string | table`
+    - `local` 本地的数据库
+    - `youcao` 有道api
+    - `baidu` 百度api
+    - `google` 谷歌api
+    - `bing` 必应api
+    - `iciba` 金山词霸api
+    - `xunfei` 讯飞api
+
+- 窗口风格(win): `string | table`
+    - 样式(style): 
+        - `cursor` 在光标附近弹出
+        - `float` 悬浮窗口
+        - `split` 在上方或者下方分屏
+        - `vsplit` 在左边或者右边分屏
+
+    - 高度(height):
+        - `value > 1` 实际高度
+        - `0 <= value <= 1` 相对高度
+        - `0 < value` 无限制
+
+    - 宽度(width):
+        > 和`高度(height)`相同
+### 示例
+```lua
+vim.keymap.set('n', 'mi', function ()
+    require('Trans').translate({
+        method = 'input',
+        engine = { -- 异步查询所有的引擎, 按照列表
+            'local',
+            'youdao',
+            'baidu'
+        },
+        -- view = 'cursor'
+        view = {
+            style = 'cursor',
+            height = 50,
+            width = 30,
+        }
+    })
+end, { desc = '在光标旁弹出输入的单词释义'})
+```

lua/Trans/core/query.lua

@@ -14,24 +14,24 @@ local function get_select()
     return word
 end
 
+
 M.get_query_res = function(method)
     type_check {
         method = { method, 'string' },
     }
-
-    -- NOTE : get query word
     local word = ''
     if method == 'cursor' then
         word = vim.fn.expand('<cword>')
     elseif method == 'select' then
-        word = get_select():match('%s+')
+        word = get_select():match('%S+')
     elseif method == 'input' then
         word = vim.fn.input('请输入您要查询的单词:') -- TODO Use Telescope with fuzzy finder
     else
         error('unknown method')
     end
-    -- FIXME
+
     return query(word)
 end
 
+
 return M

lua/Trans/core/translate.lua

@@ -1,32 +1,20 @@
 local M          = {}
-local api        = vim.api
-local conf       = require("Trans").conf
-local display    = conf.display
-local icon       = conf.icon
-local order      = conf.order
-local auto_close = conf.auto_close
-local view       = conf.view
 
 
-local highlight = {
+local opt = {
-    word     = 'TransWord',
+    method = 'select',
-    phonetic = 'TransPhonetic',
+    view = 'cursor',
-    ref      = 'TransRef',
-    tag      = 'TransTag',
-    exchange = 'TransExchange',
-    pos      = 'TransPos',
-    zh       = 'TransZh',
-    en       = 'TransEn',
 }
 
-
+M.Translate = function(opts)
-
-
-M.TransLate = function(opts)
     local res = get_query_res(opts.method)
     -- TODO <++>
 end
 
+-- M.Translate_online = function ()
+--     -- TOOD
+-- end
+
 
 -- local win = 0
 -- local line = 0

lua/Trans/util/format.lua

@@ -10,9 +10,9 @@ end
 
 -- 各种风格的基础宽度
 local style_width = {
-    -- float = require("Trans.conf.window").float.width, -- NOTE : need window parsed conf
+    float = require("Trans.conf.window").float.width, -- NOTE : need window parsed conf
-    -- cursor = require("Trans.conf.window").cursor.width,
+    cursor = require("Trans.conf.window").cursor.width,
-    cursor = 50
+    -- cursor = 50
 }
 
 local s_to_b = true -- 从小到大排列
@@ -120,16 +120,46 @@ local function formatted_lines()
     return lines
 end
 
+-- EXAMPLE : 接受的形式
+-- local content = {
+--     { word, 'TransWord' },
+--     { phonetic, 'TransPhonetic' },
+--     collins,
+--     oxford
+--     -- { phonetic, 'TransPhonetic' },
+--  NOTE :
+-- 可选的:
+-- 1. highlight 整个content的高亮
+-- 2. indent    缩进
+-- 2. space     各个组件的及间隔
+-- }
+
+
+-- EXAMPLE : 返回的形式
+local lines = {
+    { items, opts },
+    { items, opts },
+    { items, opts },
+    -- items: string[]
+    -- opts {
+    --     highlight
+    --     indent
+    -- }
+}
+
+local function format_stuff(stuff)
+
+end
+
+---@alias formatted_items table
 ---将组件格式化成相应的vim支持的lines格式
 ---@param style string 窗口的风格
----@param fields string[] 需要格式化的字段
+---@param component table 需要格式化的字段
----@param indent number 缩进的长度
+---@return formatted_items[] lines
----@return string[] lines 便于vim.api.nvim_buf_set_lines
+M.format = function(style, component)
-M.to_lines = function(style, fields, indent)
     type_check {
         style = { style, { 'string' } },
-        fields = { fields, { 'table' } },
+        component = { component, { 'table' } },
-        indent = { indent, { 'number' }, true },
     }
 
     local length = 0
@@ -151,6 +181,11 @@ M.to_lines = function(style, fields, indent)
     return formatted_lines()
 end
 
+
+
+
+
+
 ---合并多个数组, 第一个数组将会被使用
 ---@param ... string[] 需要被合并的数组
 ---@return table res   合并后的数组

lua/Trans/util/test/test.lua

@@ -1,8 +1,5 @@
-local tmp = {
+local a = nil
-    '1111',
-    '2222',
-    '3333',
-    interval = 4,
-}
 
-print(table.concat(tmp, (' '):rep(tmp.interval)))
+
+
+print((' '):rep(a))