diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..e3bf56d --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,47 @@ +name: autogen-docs + +on: + push: + branches: [master] + pull_request: + +jobs: + docs: + runs-on: ubuntu-latest + name: generate docs + permissions: + contents: write + steps: + - uses: actions/checkout@v4 + with: + ref: ${{ github.head_ref }} + - if: github.event_name == 'pull_request' + run: git fetch --no-tags --depth=1 origin master + - name: panvimdoc + uses: kdheepak/panvimdoc@v4.0.0 + with: + vimdoc: decipher + pandoc: "README.md" + version: "NVIM >= v0.8.0" + toc: false + description: "A plugin that provides ways to encode and decode text using various codecs like base64." + demojify: false + dedupsubheadings: true + treesitter: true + ignorerawblocks: true + docmapping: false + docmappingprojectname: true + shiftheadinglevelby: 0 + incrementheadinglevelby: 0 + - name: preview changes + if: github.event_name == 'pull_request' + run: | + git diff --color=always origin/master -- "doc/decipher.txt" + cat "doc/decipher.txt" + - uses: stefanzweifel/git-auto-commit-action@v6 + if: github.ref == 'refs/heads/master' + with: + commit_message: "Auto-generate docs" + commit_user_name: "github-actions[bot]" + commit_user_email: "github-actions[bot]@users.noreply.github.com" + commit_author: "github-actions[bot] " diff --git a/API.md b/API.md new file mode 100644 index 0000000..398c427 --- /dev/null +++ b/API.md @@ -0,0 +1,133 @@ +# API + +Below is the specification for the public types and api functions. + +## Types + +## `decipher.Codecs` + +Type: ```lua +enum +``` + +Values: + +* `base32` +* `base64` +* `base64_url` +* `base64_url_encoded` +* `base64_url_safe` +* `crockford` +* `c_escape` +* `url` +* `url_plus` +* `xml` +* `zbase32` + +## `decipher.CodecArg` + +Type: ```lua +string | decipher.Codecs +``` + +General type for functions that accept codecs as arguments. Either a string +(e.g. "base64") or or a an enum (e.g. decipher.codec.base64). + +## API functions + +Any functions not listed here that may be accessed via the decipher module are +not considered public and are subject to change. + +### `decipher.setup({config})` + +Setup global configuration for decipher. See [`decipher.setup`](#decipher-setup) + +Parameters: + • {config} (`decipher.Config`) Setup configuration table + +### `decipher.version()` + +Returns the current version string. + +### `decipher.supported_codecs()` + +Returns a list of currently supported codecs. + +Return: + (type) ... + +### `decipher.encode({codec_name}, {value})` + +Encode a value using a codec. + +Parameters: + • {codec_name} (`decipher.CodecArg`) Setup configuration table + • {value} (`string`) Value to encode + +### `decipher.decode({codec_name}, {value})` + +Decode a value using a codec. + +### `decipher.encode_selection({codec_name}, {options})` + +Encode a visual selection using a codec. + +Parameters: + • {codec_name} (`decipher.CodecArg`) Codec to use for encoding + • {options} (`decipher.Options`) Options to use + +### `decipher.decode_selection({codec_name}, {options})` + +Decode a visual selection using a codec. + +Parameters: + • {codec_name} (`decipher.CodecArg`) Codec to use for decoding + • {options} (`decipher.Options`) Options to use + +### `decipher.encode_motion({codec_name}, {options})` + +Encode using a motion and a codec. + +Parameters: + • {codec_name} (`decipher.CodecArg`) Codec to use for encoding + • {options} (`decipher.Options`) Options to use + +### `decipher.decode_motion({codec_name}, {options})` + +Decode using a motion and a codec. + +Parameters: + • {codec_name} (`decipher.CodecArg`) Codec to use for decoding + • {options} (`decipher.Options`) Options to use + +### `decipher.encode_selection_prompt({options})` + +Encode a visual selection using a codec. Prompts with a list of the active +codecs via `vim.ui.select`. + +Parameters: + • {options} (`decipher.Options`) Options to use + +### `decipher.decode_selection_prompt({options})` + +Decode a visual selection using a codec. Prompts with a list of the active +codecs via `vim.ui.select`. + +Parameters: + • {options} (`decipher.Options`) Options to use + +### `decipher.encode_motion_prompt({options})` + +Encode using a motion. Prompts with a list of the active codecs via +`vim.ui.select`. + +Parameters: + • {options} (`decipher.Options`) Options to use + +### `decipher.decode_motion_prompt({options})` + +Decode using a motion. Prompts with a list of the active codecs via +vim.ui.select. + +Parameters: + • {options} (`decipher.Options`) Options to use diff --git a/README.md b/README.md index 83bd4c8..93fbc63 100644 --- a/README.md +++ b/README.md @@ -10,50 +10,40 @@
-> [!IMPORTANT] -> A bit library is needed which requires that either neovim has been compiled with luajit or you are using v0.9.0+ which provides a bit library. - ![demo](https://github.com/MisanthropicBit/decipher.nvim/assets/1846147/6bc4db76-9a3b-428b-99b4-98e56d06901e) # Table of contents - [Installing](#installing) - [Setup](#setup) +- [JSON view](#json-view) - [Example keymaps](#example-keymaps) +- [Encode/decode text-objects](#encode-decode-text-objects) +- [Highlights](#highlights) - [Supported Codecs](#supported-codecs) - - [base32](#base32) - - [base64](#base64) - - [base64-url](#base64-url) - - [base64-url-safe](#base64) - - [base64-url-encoded](#base64-url-encoded) - - [crockford](#crockford) - - [c-escape](#c-escape) - - [url](#url) - - [url-plus](#url-plus) - - [xml](#xml) - - [z-base32](#z-base32) + - [Base32](#base32) + - [Base64](#base64) + - [Base64-url](#base64-url) + - [Base64-url-safe](#base64) + - [Base64-url-encoded](#base64-url-encoded) + - [Crockford](#crockford) + - [C-escape](#c-escape) + - [Url](#url) + - [Url-plus](#url-plus) + - [Xml](#xml) + - [Z-base32](#z-base32) ## Installing -Requires at least neovim v0.8.0. Please check the [docs](doc/decipher.txt). - -* **[vim-plug](https://github.com/junegunn/vim-plug)** - -```vim -Plug 'MisanthropicBit/decipher.nvim' -``` +> [!IMPORTANT] +> A bit library is needed which requires that either neovim has been compiled with luajit or you are using v0.9.0+ which provides a bit library. -* **[packer.nvim](https://github.com/wbthomason/packer.nvim)** - -```lua -use 'MisanthropicBit/decipher.nvim' -``` +Requires at least neovim v0.8.0. ## Setup Setup decipher using `decipher.setup` unless you are content with the defaults. -The options below are the default values. Refer to the -[docs](doc/decipher.txt) for more help. +The options below are the default values. ```lua require("decipher").setup({ @@ -126,7 +116,7 @@ normal view instead. ## Example keymaps There are several ways in which you can invoke `decipher`. Check out the -[docs](doc/decipher.txt) for the full api. Below are some examples: +[API docs](API.md) for more information. Below are some examples: ```lua -- Encode visually selected text as base64. If invoked from normal mode it will @@ -141,6 +131,32 @@ vim.keymap.set("n", "", function() end) ``` +## Encode/decode text-objects + +Decipher can encode and decode text-objects. The following `lua` code sets up +`decipher` to decode a text-object using base64 using a floating window preview. +Check out the [API docs](API.md) for more information + +```lua + local decipher = require("decipher") + + vim.keymap.set( + "n", + "d", + function() + decipher.decode_motion("base64", { preview = true }) + end, + { noremap = true, silent = true } + ) +``` + +## Highlights + +### `DecipherFloatTitle` + +Highlight group for the title of the floating window preview. Defaults to +`Title`. + ## Supported Codecs #### Base32 diff --git a/doc/.gitkeep b/doc/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/doc/decipher.txt b/doc/decipher.txt deleted file mode 100644 index 17c2447..0000000 --- a/doc/decipher.txt +++ /dev/null @@ -1,283 +0,0 @@ -*decipher.nvim* {Encode and decode text} - -============================================================================== - - █▀▀▄ █▀▀▀ █▀▀▀ █ █▀▀▄ █ █ █▀▀▀ █▀▀▄ █▄ █ █ █ █ █▄ ▄█ - █ █ ██ █ █ █▄▄█ ████ ██ █▄▄█ █▀▄█ █ █ █ █ ▀ █ - █▄▄▀ █▄▄▄ █▄▄▄ █ █ █ █ █▄▄▄ █ █ ▄ █ ▀█ ▀▄▄▀ █ █ █ - - Version 2.1.0 - -A plugin that provides ways to encode and decode text using various codecs -like base64. - -============================================================================== -decipher *decipher* - - `decipher.nvim` - - Setup ....................................................... |decipher.setup| - Types ....................................................... |decipher.types| - Functions ............................................... |decipher.functions| - Mappings ................................................. |decipher.mappings| - Motions ................................................... |decipher.motions| - Highlights ............................................. |decipher.highlights| - Codecs ..................................................... |decipher.codecs| - FAQ ........................................................... |decipher.faq| - License ................................................... |decipher.license| - -============================================================================== -Setup *decipher-setup* - -Warning: A bit library is needed which requires that either neovim has been -compiled with luajit or you are using v0.9.0+ which provides a bit library. - -Setup decipher using `decipher.setup` unless you are content with the defaults. -The options below are the default values. - ->lua - require("decipher").setup({ - float = { -- Floating window options - padding = 0, -- Zero padding (does not apply to title if any) - border = { -- Floating window border - { "╭", "FloatBorder" }, - { "─", "FloatBorder" }, - { "╮", "FloatBorder" }, - { "│", "FloatBorder" }, - { "╯", "FloatBorder" }, - { "─", "FloatBorder" }, - { "╰", "FloatBorder" }, - { "│", "FloatBorder" }, - }, - mappings = { - close = "q", -- Key to press to close the floating window - apply = "a", -- Key to press to apply the encoding/decoding - jsonpp = "J", -- Key to prettily format contents as json if possbile - help = "?", -- Toggle help - }, - title = true, -- Display a title with the codec name - title_pos = "left", -- Position of the title - autoclose = true, -- Autoclose floating window if insert - -- mode is activated or the cursor is moved - enter = false, -- Automatically enter the floating window if - -- opened - options = {}, -- Options to apply to the floating window contents - }, - }) - -============================================================================== -Types *decipher.types* -< - *decipher.Config* - Fields: - {float} `decipher.WindowConfig` - - *decipher.WindowConfig* - Fields: - {padding} `number` - Padding around the contents in the floating window preview. - - {border} (`string | string[]`)[] - Border around the floating window preview. - - {mappings} `table` - Mappings for the floating window preview. Used as the left-hand - side in a normal map defintion. - - {close} `string` - Key to press to close the floating window. - - {apply} `string` - Key to press to apply the encoded/decoded contents of the text - in the floating window preview. - - {jsonpp} `string` - Key to prettily format the contents in the floating window - preview as json if possbile. Note that since lua table keys do - not have any deterministic order, the prettified contents - might have a different order of keys than the original - contents. - - {help} `string` - Toggle help. - - {title} `boolean` - Whether or not to show a title in the floating window preview or - not. This option requires at least nvim 0.9. - - {title_pos} "left" | "center" | "right" - Same as the config argument for |nvim_open_win|. Either "left", - "center", or "right". Not used if the title is disabled. - - {autoclose} `boolean` - Autoclose the floating window preview if insert mode is entered or - the cursor is moved. - - {enter} `boolean` - Automatically enter the floating window preview when opened. - - {options} `table` - Buffer-local options to set for the floating window preview. - - *decipher.Options* - Fields: - {preview} `(boolean)` If true, show a preview of the encoding/decoding - instead of encoding/decoding in place. - - *decipher.CodecArg* - {string | decipher.Codecs} - General type for functions that accept codecs as arguments. Either a - string (e.g. "base64") or or a an enum (e.g. decipher.codec.base64). - -============================================================================== -Functions *decipher.functions* - -Any functions not listed here that may be accessed via the decipher module are -not considered public and are subject to change. - -setup({config}) *decipher.setup* - Setup global configuration for decipher. See |decipher.setup|. - - Parameters: - • {config} (decipher.Config) Setup configuration table - -version() *decipher.version* - Returns the current version as a string. - -supported_codecs() *decipher.supported_codecs* - Returns a list of currently supported codecs. - -encode({codec_name}, {value}) *decipher.encode* - Encode a value using a codec. - - Parameters: - • {codec_name} (`decipher.CodecArg`) Setup configuration table - • {value} (`string`) Value to encode - -decode({codec_name}, {value}) *decipher.decode* - Decode a value using a codec. - -encode_selection({codec_name}, {options}) *decipher.encode_selection* - Encode a visual selection using a codec. - - Parameters: - • {codec_name} (`decipher.CodecArg`) Codec to use for encoding - • {options} (`decipher.Options`) Options to use - -decode_selection({codec_name}, {options}) *decipher.decode_selection* - Decode a visual selection using a codec. - - Parameters: - • {codec_name} (`decipher.CodecArg`) Codec to use for decoding - • {options} (`decipher.Options`) Options to use - -encode_motion({codec_name}, {options}) *decipher.encode_motion* - Encode using a motion and a codec. - - Parameters: - • {codec_name} (`decipher.CodecArg`) Codec to use for encoding - • {options} (`decipher.Options`) Options to use - -decode_motion({codec_name}, {options}) *decipher.decode_motion* - Decode using a motion and a codec. - - Parameters: - • {codec_name} (`decipher.CodecArg`) Codec to use for decoding - • {options} (`decipher.Options`) Options to use - -encode_selection_prompt({options}) *decipher.encode_selection_prompt* - Encode a visual selection using a codec. Prompts with a list of the active - codecs via vim.ui.select. - - Parameters: - • {options} (`decipher.Options`) Options to use - -decode_selection_prompt({options}) *decipher.decode_selection_prompt* - Decode a visual selection using a codec. Prompts with a list of the active - codecs via vim.ui.select. - - Parameters: - • {options} (`decipher.Options`) Options to use - -encode_motion_prompt({options}) *decipher.encode_motion_prompt* - Encode using a motion. Prompts with a list of the active codecs via - vim.ui.select. - - Parameters: - • {options} (`decipher.Options`) Options to use - -decode_motion_prompt({options}) *decipher.decode_motion_prompt* - Decode using a motion. Prompts with a list of the active codecs via - vim.ui.select. - - Parameters: - • {options} (`decipher.Options`) Options to use - -============================================================================== -Mappings *decipher.mappings* - -No mappings are provided by default except for those for floating windows. See -the `float.mappings` option in *decipher.WindowConfig*. Mappings can easily be -set up via the lua api. - ->lua - local decipher = require("decipher") - - vim.keymap.set( - "n", - "de", - function() - decipher.encode_selection("crockford") - end, - { noremap = true, silent = true } - ) - - -============================================================================== -Motions *decipher.motions* - -Decipher can encode and decode across a motion. The following lua code sets up -decipher to decode a text object using base64 using a floating window preview. ->lua - local decipher = require("decipher") - - vim.keymap.set( - "n", - "d", - function() - decipher.decode_motion("base64", { preview = true }) - end, - { noremap = true, silent = true } - ) - -============================================================================== -Highlights *decipher.highlights* - -*DecipherFloatTitle* - Highlight group for the title of the floating window preview. Defaults to - *Title*. - -============================================================================== -Codecs *decipher.codecs* - -Currently supported codecs: - -* base32 -* zbase32: Variant of base32 with a different alphabet. -* crockford: Variant of base32 with a different alphabet. -* base64 -* base64-url: Combination of base64 and url codecs. -* base64-url-safe: Base64-variant that is safe to include in urls. -* url - -============================================================================== -FAQ *decipher.faq* - -Nothing yet. - -============================================================================== -License *decipher.license* - -BSD 3-Clause License. Copyright © 2020 MisanthropicBit - - vim:tw=78:ts=8:ft=help:norl: