From 5211e9ed04ba0aef5cab6239092ad9ab2264f7aa Mon Sep 17 00:00:00 2001 From: Alex Yatskov Date: Tue, 24 Jan 2023 19:48:55 -0800 Subject: [PATCH] Update README --- README.md | 86 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 44 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 0117a7e..0ff887c 100644 --- a/README.md +++ b/README.md @@ -1,50 +1,16 @@ # guid.nvim -This Neovim-exclusive plugin simplifies common operations when working with [Globally Unique +This Neovim plugin simplifies common operations when working with [Globally Unique Identifiers](https://en.wikipedia.org/wiki/Universally_unique_identifier) (GUIDs). The produced values fully conform to -the [RFC 4122](https://www.rfc-editor.org/rfc/rfc4122) spec for for pseudo-random GUIDs. +the [RFC 4122](https://www.rfc-editor.org/rfc/rfc4122) spec for pseudo-random GUIDs. Classic Vim is not supported. ![](img/guid.nvim.gif) -## GUID Styles - -There are several ways to represent GUIDs as text. The format specifier syntax outlined by -[Guid.ToString](https://learn.microsoft.com/en-us/dotnet/api/system.guid.tostring?view=net-7.0) is borrowed for styling -text output. This convention is expanded to allow the casing of hexadecimal characters to be specified. The casing of -the format specifier determines whether lowercase or uppercase will be used. - -* n `cbb297c014a940bc8d911d0ef9b42df9` -* d `cbb297c0-14a9-40bc-8d91-1d0ef9b42df9` -* D `CBB297C0-14A9-40BC-8D91-1D0EF9B42DF9` -* b `{cbb297c0-14a9-40bc-8d91-1d0ef9b42df9}` -* B `{CBB297C0-14A9-40BC-8D91-1D0EF9B42DF9}` -* p `(cbb297c0-14a9-40bc-8d91-1d0ef9b42df9)` -* P `(CBB297C0-14A9-40BC-8D91-1D0EF9B42DF9)` -* x `{0xcbb297c0,0x14a9,0x40bc,{0x8d,0x91,0x1d,0x0e,0xf9,0xb4,0x2d,0xf9}}` -* X `{0xCBB297C0,0x14A9,0x40BC,{0x8D,0x91,0x1D,0x0E,0xF9,0xB4,0x2D,0xF9}}` - -## GUID Commands - -* `GuidInsert [style]` \ - Inserts a GUID at the cursor position using the default or provided style. - -* `GuidFormat [style]` \ - Formats the GUID at the cursor position using the default or provided style. - -* `GuidObject` \ - Selects the GUID at the cursor position (useful for text objects). - -## GUID Text Object - -A custom text object for GUIDs is provided. By default it is bound to the `g` key. For example to yank a GUID you would -input `yig` in normal mode (the functionally identical `yag` can also be used). The GUID text object supports all of the -GUID formatting styles described above. Make sure to call `setup` if you wish to use GUID text objects (details in the -next section). ## Configuration -The plugin should be configured by calling the `setup` function. Options can be optionally provided if you wish to -override the default settings, which are shown below: +The plugin should be configured by calling the `setup` function. Options may be provided to override the default +settings which are shown below: ```lua require('guid').setup({ @@ -54,13 +20,49 @@ require('guid').setup({ }) ``` -Specifically, these options are: +These options are: * `comma_space` \ - Determines if commas should be followed by spaces in GUIDs formatted with the `x` specifier. + Specifies if commas should be followed by spaces in GUIDs formatted with the `x` and `X` specifiers. * `default_style` \ - Determines what style to use if one is not provided for `GuidInsert` and `GuidFormat` commands. + Specifies which format to use if one is not provided for `GuidInsert` and `GuidFormat` commands. * `object-char` \ - Determines which character should be used for the GUID text object. + Specifies which character should be used for the GUID text object. + +## GUID Formatting + +The format specifier syntax outlined by +[Guid.ToString](https://learn.microsoft.com/en-us/dotnet/api/system.guid.tostring?view=net-7.0) is borrowed for styling +GUID text representation. The case of the format specifier determines whether lowercase or uppercase will be used. + +| Format | Example | +| - | - | +| n | `cbb297c014a940bc8d911d0ef9b42df9` | +| n | `CBB297C014A940BC8D911D0EF9B42DF9` | +| d | `cbb297c0-14a9-40bc-8d91-1d0ef9b42df9` | +| D | `CBB297C0-14A9-40BC-8D91-1D0EF9B42DF9` | +| b | `{cbb297c0-14a9-40bc-8d91-1d0ef9b42df9}` | +| B | `{CBB297C0-14A9-40BC-8D91-1D0EF9B42DF9}` | +| p | `(cbb297c0-14a9-40bc-8d91-1d0ef9b42df9)` | +| P | `(CBB297C0-14A9-40BC-8D91-1D0EF9B42DF9)` | +| x | `{0xcbb297c0,0x14a9,0x40bc,{0x8d,0x91,0x1d,0x0e,0xf9,0xb4,0x2d,0xf9}}` | +| X | `{0xCBB297C0,0x14A9,0x40BC,{0x8D,0x91,0x1D,0x0E,0xF9,0xB4,0x2D,0xF9}}` | + +## GUID Commands + +* `GuidInsert [format]` \ + Inserts a GUID at the cursor position using the default or provided format. + +* `GuidFormat [format]` \ + Formats the GUID at the cursor position using the default or provided format. + +* `GuidObject` \ + Selects the GUID at the cursor position (useful for text objects). + +## GUID Text Object + +A custom text object for GUIDs is provided. By default it is bound to the `g` key. For example to yank a GUID you would +input `yig` in normal mode. The functionally identical `yag` can also be used. The GUID text object supports all of the +GUID text representations described above. Be sure to call `setup` if you wish to use GUID text objects.