diff --git a/docs/api.md b/docs/api.md index 70cc113..01fa47a 100644 --- a/docs/api.md +++ b/docs/api.md @@ -16,46 +16,39 @@ local care_api = require("care").api # Methods ## Is Open -`api.is_open(): boolean` - +`api.is_open` This function returns a boolean which indicates whether the completion menu is currently open or not. This is especially useful for mappings which should fallback to other actions if the menu isn't open. ## Confirm -`api.confirm(): nil` - +`api.confirm` Used to confirm the currently selected entry. Note that there is also `(CareConfirm)` which should preferably be used in mappings. ## Complete -`api.complete(source_filter?: fun(name: string): boolean): nil` - +`api.complete` This function is used to manually trigger completion ## Close -`api.close(): nil` - +`api.close` Closes the completion menu and documentation view if it is open. For mappings `(CareClose)` should be used. ## Select Next -`api.select_next(count: integer): nil` - +`api.select_next` Select next entry in completion menu. If count is provided the selection will move down `count` entries. For mappings `(CareSelectNext)` can be used where count defaults to 1. ## Select Prev -`api.select_prev(count: integer): nil` - +`api.select_prev` Select next entry in completion menu. If count is provided the selection will move up `count` entries. For mappings `(CareSelectPrev)` can be used where count defaults to 1. ## Doc Is Open -`api.doc_is_open(): boolean` - +`api.doc_is_open` Indicates whether there is a documentation window open or not. This is especially useful together with the function to scroll docs to only trigger the mapping in certain cases. @@ -68,20 +61,17 @@ end ``` ## Scroll Docs -`api.scroll_docs(delta: integer): nil` - +`api.scroll_docs` Use `scroll_docs(delta)` to scroll docs by `delta` lines. When a negative delta is provided the docs will be scrolled upwards. ## Set Index -`api.set_index(index: integer): nil` - +`api.set_index` Allows the index which represents which entry is selected to be directly set. This allows to jump anywhere in the completion menu. ## Get Index -`api.get_index(): integer` - +`api.get_index` Returns the index of the currently selected entry, 0 representing no selection. This is e.g. useful to determine if an entry is selected: ```lua @@ -91,15 +81,13 @@ end ``` ## Select Visible -`api.select_visible(index: integer): nil` - +`api.select_visible` This function is used to select the entry at index `index` where `index` indicates the visible position in the menu. This is really useful to create shortcuts to certain entries like in the [example in configuration recipes](/configuration_recipes#labels-and-shortcuts). ## Is Reversed -`api.is_reversed(): boolean` - +`api.is_reversed` Indicated whether the menu is reversed Only relevant when using sorting direction "away-from-cursor" \ No newline at end of file diff --git a/docs/config.md b/docs/config.md index f2809aa..1ca10b2 100644 --- a/docs/config.md +++ b/docs/config.md @@ -103,8 +103,7 @@ configuration of the completion behaviors of care. # Methods ## Snippet Expansion -`config.snippet_expansion?(body: string): nil` - +`config.snippet_expansion?` With this field a function for expanding snippets is defined. By default this is the builtin `vim.snippet.expand()`. You can also use a plugin like luasnip for this: ```lua @@ -114,38 +113,31 @@ end ``` ## Enabled -`config.enabled?(): boolean` - +`config.enabled?` This function can be used to disable care in certain contexts. By default this disables care in prompts. # Fields ## Ui -`config.ui? care.config.ui` - +`config.ui?` The [UI Configuration](#Ui-Configuration) is used to configure the whole UI of care. One of the main goals of this is to be as extensible as possible. This is especially important for the completion entries. Read more about that under [Configuration of item display](/design/#configuration-of-item-display). ## Selection Behavior -`config.selection_behavior? "select"|"insert"` - +`config.selection_behavior?` With the selection behavior the user can determine what happens when selecting an entry. This can either be `"select"` or `"insert"`. Selecting will just select the entry and do nothing else. Insert will actually insert the text of the entry (this is not necessarily the whole text). ## Confirm Behavior -`config.confirm_behavior? "insert"|"replace"` - +`config.confirm_behavior?` This field controls the behavior when confirming an entry. ## Sources -`config.sources? table` - -See [care.config.source](/config/#source-configuration) - +`config.sources?` This field is used to configure the sources for care.nvim. Use a table where the fields is the source name and the value is the configuration ```lua @@ -160,40 +152,34 @@ sources = { ``` ## Completion Events -`config.completion_events? string[]` - +`config.completion_events?` The `completion_events` table is used to set events for autocompletion. By default it just contains `"TextChangedI"`. You can set it to an empty table (`{}`) to disable autocompletion. ## Keyword Pattern -`config.keyword_pattern? string` - +`config.keyword_pattern?` The keyword pattern is used to determine keywords. These are used to determine what to use for filtering and what to remove if insert text is used. It should essentially just describe the entries of a source. ## Preselect -`config.preselect? boolean` - +`config.preselect?` Whether items should be preselected or not. Which items are preselected is determined by the source. ## Sorting Direction -`config.sorting_direction? "top-down"|"away-from-cursor"` - +`config.sorting_direction?` How to sort the entries in the completion menu. This can either be top to bottom or so the best match is always next to the cursor. ## Debug -`config.debug? boolean` - +`config.debug?` Whether debugging should be enabled or not. This will write a log to a `care.log` file in the current directory. ## Max View Entries -`config.max_view_entries? integer` - +`config.max_view_entries?` The max entries to display in the menu. Note that this just affects the entries displayed at a time. So there are still more entries on which you can filter by continue typing. This limit just exists for performance reasons @@ -210,25 +196,21 @@ This is used to configure the whole UI of care. # Fields ## Menu -`config.ui.menu? care.config.ui.menu` - +`config.ui.menu?` Configuration of the completion menu of care.nvim ## Docs View -`config.ui.docs_view? care.config.ui.docs` - +`config.ui.docs_view?` This configuration allows you to configure the documentation view. It consists of some basic window properties like the border and the maximum height of the window. It also has a field to define the character used for the scrollbar. ## Type Icons -`config.ui.type_icons? care.config.ui.type_icons` - +`config.ui.type_icons?` This is a table which defines the different icons. ## Ghost Text -`config.ui.ghost_text? care.config.ui.ghost_text` - +`config.ui.ghost_text?` Configuration of ghost text. With this field the user can control how ghost text is displayed. @@ -237,14 +219,12 @@ With this field the user can control how ghost text is displayed. # Fields ## Enabled -`config.ui.ghost_text.enabled? boolean` - +`config.ui.ghost_text.enabled?` You can use the `enabled` field to determine whether the ghost text should be enabled or not. ## Position -`config.ui.ghost_text.position? "inline"|"overlay"` - +`config.ui.ghost_text.position?` The `position` can either be `"inline"` or `"overlay"`. Inline will add the text inline right where the cursor is. With the overlay position the text will overlap with existing text after the cursor. @@ -260,10 +240,7 @@ scrollbar. Set `scrollbar` to `nil` value to disable the scrollbar. # Methods ## Format Entry -`config.ui.menu.format_entry?(entry: care.entry, data: care.format_data): { [1]: string, [2]: string }[][]` - -See [care.entry](/dev/entry) - +`config.ui.menu.format_entry?` Another field is `format_entry`. This is a function which recieves an entry of the completion menu and determines how it's formatted. For that a table with text-highlight chunks like `:h nvim_buf_set_extmarks()` is used. You can create @@ -293,28 +270,23 @@ added in between the two. # Fields ## Max Height -`config.ui.menu.max_height? integer` - +`config.ui.menu.max_height?` Maximum height of the menu ## Border -`config.ui.menu.border? string|string[]|string[][]` - +`config.ui.menu.border?` The border of the completion menu ## Scrollbar -`config.ui.menu.scrollbar? care.config.scrollbar` - +`config.ui.menu.scrollbar?` Configuration of the scrollbar ## Position -`config.ui.menu.position? "auto"|"below"|"above"` - +`config.ui.menu.position?` If the menu should be displayed on above, below or automatically ## Alignments -`config.ui.menu.alignments? ("left"|"center"|"right")[]` - +`config.ui.menu.alignments?` How the sections in the menu should be aligned ## Source configuration @@ -324,26 +296,20 @@ Configuration for the sources of care.nvim # Methods ## Enabled -`config.source.enabled? boolean|fun():boolean` - +`config.source.enabled?` Whether the source is enabled (default true) ## Filter -`config.source.filter?(entry: care.entry): boolean` - -See [care.entry](/dev/entry) - +`config.source.filter?` Filter function for entries by the source # Fields ## Max Entries -`config.source.max_entries? integer` - +`config.source.max_entries?` The maximum amount? of entries which can be displayed by this source ## Priority -`config.source.priority? integer` - +`config.source.priority?` The priority of this source. Is more important than matching score Configuration of the completion menu of care.nvim @@ -352,28 +318,23 @@ Configuration of the completion menu of care.nvim # Fields ## Max Height -`config.ui.docs.max_height? integer` - +`config.ui.docs.max_height?` Maximum height of the documentation view ## Max Width -`config.ui.docs.max_width? integer` - +`config.ui.docs.max_width?` Maximum width of the documentation view ## Border -`config.ui.docs.border? string|string[]|string[][]` - +`config.ui.docs.border?` The border of the documentation view ## Scrollbar -`config.ui.docs.scrollbar? care.config.scrollbar` - +`config.ui.docs.scrollbar?` Configuration of the scrollbar ## Position -`config.ui.docs.position? "auto"|"left"|"right"` - +`config.ui.docs.position?` Position of docs view. Auto will prefer right if there is enough space @@ -383,23 +344,19 @@ Additional data passed to format function to allow more advanced formatting # Fields ## Index -`format_data.index integer` - +`format_data.index` Index of the entry in the completion menu ## Deprecated -`format_data.deprecated boolean` - +`format_data.deprecated` Whether the item is marked as deprecated by the source or not ## Source Name -`format_data.source_name string` - +`format_data.source_name` The name of the source from which the entry was completed ## Source Display Name -`format_data.source_display_name string` - +`format_data.source_display_name` The display name of the source from which the entry was completed which is more detailed than the normal name @@ -409,16 +366,13 @@ is more detailed than the normal name # Fields ## Character -`config.scrollbar.character? string` - +`config.scrollbar.character?` The character used for drawing the scrollbar ## Enabled -`config.scrollbar.enabled? boolean` - +`config.scrollbar.enabled?` Whether the scrollbar is enabled or not ## Offset -`config.scrollbar.offset? integer` - +`config.scrollbar.offset?` Offset of the scrollbar. 0 is at the border of the window \ No newline at end of file diff --git a/docs/dev/context.md b/docs/dev/context.md index 4a58985..52dac09 100644 --- a/docs/dev/context.md +++ b/docs/dev/context.md @@ -12,18 +12,12 @@ cursor position. It is passed to completion sources to get completions. # Methods ## Changed -`context.changed(care.context): boolean` - -See [care.context](/dev/context) - +`context.changed` Whether the context changed in comparison to the previous one. This is used to check whether to get new completions or not when using autocompletion. ## New -`Context.new(previous: care.context?): care.context` - -See [care.context](/dev/context) - +`context.new` Create a new context. This takes a previous context as argument. This one is stored to determine if the context changed or not when completing. The previous context of the previous one is deleted so this data structure doesn't grow @@ -31,42 +25,32 @@ really large. # Fields ## Previous -`context.previous care.context?` - -See [care.context](/dev/context) - +`context.previous` The previous context which is used to determine whether the context changed or not. The `previous` field of the previous context should always be `nil` so the data structure doesn't grow infinitely. ## Cursor -`context.cursor care.context.cursor` - -See [care.context](/dev/context) - +`context.cursor` The cursor position. This will have a `col` and a `row` field and has 1-based line and 0-based column indexes. This is the same as in `nvim_win_{get, set}_cursor()` (`:h api-indexing`). ## Bufnr -`context.bufnr integer` - +`context.bufnr` Number of the buffer. ## Reason -`context.reason care.completionReason?` - +`context.reason` Reason for triggering completion. This is a `completionReason` so either 1 for automatic triggering and 2 for manual triggering. ## Line -`context.line string` - +`context.line` The complete line on which the cursor was when the context was created. ## Line Before Cursor -`context.line_before_cursor string` - +`context.line_before_cursor` The line before the cursor. This is mostly important to be correct in insert mode. In normal mode the character on which the cursor is is not included. @@ -76,11 +60,9 @@ A cursor position # Fields ## Row -`context.cursor.row integer` - +`context.cursor.row` 1-based line index ## Col -`context.cursor.col integer` - +`context.cursor.col` 0-based column index \ No newline at end of file diff --git a/docs/dev/core.md b/docs/dev/core.md index 330cca5..5212e06 100644 --- a/docs/dev/core.md +++ b/docs/dev/core.md @@ -12,77 +12,60 @@ most important things being the menu being opened and the completion triggered. # Methods ## New -`Core.new(): care.core` - -See [care.core](/dev/core) - +`core.new` Use this function to create a new instance. It takes no arguments and should be called only once when the plugin is first set up. ## Complete -`core:complete(reason: care.completionReason?, source_filter?: fun(name: string): boolean): nil` - +`core.complete` This function starts the completion. It goes through all the sources, triggers them (completion and sorting) and opens the menu with the result. You can also add an optional filter to only complete certain sources. ## On Change -`core:on_change(): nil` - +`core.on_change` This function is invoked on every text change (by default, see `completion_events` in config). It updates the context field and triggers completion if the context changed. ## Block -`core:block(): fun(): nil` - +`core.block` The `block` method can be used to temporarily disable care. It returns a function which is used to unblock it again. This is used for the `insert` selection behavior where you don't want to get new completions when changing the text. ## Setup -`core:setup(): nil` - +`core.setup` The setup function is used to setup care so it will actually provide autocompletion when typing by setting up an autocommand with the `completion_events` from the configuration. ## Filter -`core:filter(): nil` - +`core.filter` Filter currently visible menu. This is used when moving the cursor. # Fields ## Context -`core.context care.context` - -See [care.context](/dev/context) - +`core.context` This is used to store the current context. There is always a new one created in `on_change` and compared to see if it changed. ## Menu -`core.menu care.menu` - -See [care.menu](/dev/menu) - +`core.menu` In this field a menu instance which is used in core is stored. ## Blocked -`core.blocked boolean` - +`core.blocked` This field is used by the [block()](#block) method. It just completely disables autocompletion when set to true. ## Last Opened At -`core.last_opened_at integer` - +`core.last_opened_at` This variable is used to determine where a new completion window was opened for the last time. This is used to determine when to reopen the completion window. ## Completing -`core.completing boolean` - +`core.completing` Boolean to indicate if care is currently completing. This is used to avoid compmleting and sorting on the same keystroke. \ No newline at end of file diff --git a/docs/dev/entry.md b/docs/dev/entry.md index ab868e5..e3fd182 100644 --- a/docs/dev/entry.md +++ b/docs/dev/entry.md @@ -12,76 +12,58 @@ completion item for which the lsp type is used. # Methods ## New -`Entry.new(completion_item: lsp.CompletionItem, source: care.internal_source, context: care.context): care.entry` - -See [care.entry](/dev/entry), [care.context](/dev/context), [care.internal_source](/dev/internal_source) - +`entry.new` The new function is the constructor for a new completion entry. ## Get Insert Text -`entry:get_insert_text(): string` - +`entry.get_insert_text` This function is used to get the text that will be inserted for the entry. This is important for the ghost text. ## Get Insert Word -`entry:get_insert_word(): string` - +`entry.get_insert_word` This function is used to get part of the text that will be inserted for the entry. It just uses a pattern to match the insert text and get the beginning of it which matches a vim `word`. This is often e.g. the method name but without the parentheses and parameter names. That function is used for the `insert` selection behavior. ## Get Offset -`entry:get_offset(): integer` - +`entry.get_offset` Essentially where entry insertion should happen (column, 0-based) ## Get Insert Range -`entry:get_insert_range(): lsp.Range` - +`entry.get_insert_range` Gets the range for inserting the entry (insert of InsertReplaceEdit) ## Get Replace Range -`entry:get_replace_range(): lsp.Range` - +`entry.get_replace_range` Gets the range for inserting the entry (insert of InsertReplaceEdit) ## Get Default Range -`entry:_get_default_range(): lsp.Range` - +`entry._get_default_range` Gets the default range for entry (if there is no textEdit) # Fields ## Completion Item -`entry.completion_item lsp.CompletionItem` - +`entry.completion_item` ## Source -`entry.source care.internal_source` - -See [care.internal_source](/dev/internal_source) - +`entry.source` This is the source from which the entry came. This is important for using the right keyword pattern and getting the right offset. ## Context -`entry.context care.context` - -See [care.context](/dev/context) - +`entry.context` This is the context in which the entry was completed. This is important to now what context text- edits of the entry target. ## Matches -`entry.matches integer[]` - +`entry.matches` Position of matches which were found during filtering. This is just used to highlight them in the completion menu with `@care.match`. ## Score -`entry.score number` - +`entry.score` This is the score obtained from filtering. It is used to sort which happens in the `care.matcher` module. \ No newline at end of file diff --git a/docs/dev/internal_source.md b/docs/dev/internal_source.md index 82536e2..85c55f4 100644 --- a/docs/dev/internal_source.md +++ b/docs/dev/internal_source.md @@ -12,71 +12,49 @@ metadata about which the source author doesn't have to care and sometimes can't # Methods ## New -`Internal_source.new(completion_source: care.source): care.internal_source` - -See [care.internal_source](/dev/internal_source), [care.source](/dev/source) - +`internal_source.new` This function creates a new instance. ## Get Keyword Pattern -`internal_source:get_keyword_pattern(): string` - +`internal_source.get_keyword_pattern` This function is used to get the keyword pattern for the source. It uses the string field, the method to get it and as fallback the one from the config. ## Get Offset -`internal_source:get_offset(context: care.context): integer` - -See [care.context](/dev/context) - +`internal_source.get_offset` With this function the offset of the source is determined. The offset describes at which point the completions for this source start. This is required to be able to remove that text if needed and to determine the characters used for filtering and sorting. ## Get Trigger Characters -`internal_source:get_trigger_characters(): string[]` - +`internal_source.get_trigger_characters` This function is used to get the trigger characters for the source. At the moment it just checks if the method exists on the source and otherwise just returns an empty table. ## Is Enabled -`internal_source:is_enabled(): boolean` - +`internal_source.is_enabled` This function checks whether the function is enabled or not based on it's config. ## Execute -`internal_source:execute(entry: care.entry)` - -See [care.entry](/dev/entry) - +`internal_source.execute` Executes a function for an entry after completion This can e.g. be used for snippet expansion by a source # Fields ## Source -`internal_source.source care.source` - -See [care.source](/dev/source) - +`internal_source.source` This field is used to store the source written by the source author. ## Entries -`internal_source.entries care.entry[]` - -See [care.entry](/dev/entry) - +`internal_source.entries` In the entries field entries gotten from the source are stored. This is used to be able to sort and filter the entries when not getting new ones. ## Incomplete -`internal_source.incomplete boolean` - +`internal_source.incomplete` Here a boolean is set which shows whether the source already completed all it's entries or not. This is mostly used by sources for performance reasons. ## Config -`internal_source.config care.config.source` - -See [care.config.source](/config/#source-configuration) - +`internal_source.config` The configuration for the source \ No newline at end of file diff --git a/docs/dev/menu.md b/docs/dev/menu.md index ab26323..2eb74c7 100644 --- a/docs/dev/menu.md +++ b/docs/dev/menu.md @@ -13,160 +13,119 @@ completions. # Methods ## New -`Menu.new(): care.menu` - -See [care.menu](/dev/menu) - +`menu.new` Creates a new instance of the completion menu. ## Draw -`menu:draw(): nil` - +`menu.draw` Draws the menu. This includes formatting the entries with the function from the config and setting the virtual text used to display the labels. It also adds the highlights for the selected entry and for the matched chars. ## Is Open -`menu:is_open(): boolean` - +`menu.is_open` This is a function which can be used to determine whether the completion menu is open or not. This is especially useful for mappings which have a fallback action when the menu isn't visible. ## Select Next -`menu:select_next(count: integer): nil` - +`menu.select_next` This function can be used to select the next entry. It accepts a count to skip over some entries. It automatically wraps at the bottom and jumps up again. ## Select Prev -`menu:select_prev(count: integer): nil` - +`menu.select_prev` This function is used to select the previous entry analogous to [Select next](#select-next) ## Open -`menu:open(entries: care.entry[], offset: integer): nil` - -See [care.entry](/dev/entry) - +`menu.open` The `open` function is used to open the completion menu with a specified set of entries. This includes opening the window and displaying the text. ## Close -`menu:close(): nil` - +`menu.close` This function closes the menu and resets some internal things. ## Get Active Entry -`menu:get_active_entry(): care.entry?` - -See [care.entry](/dev/entry) - +`menu.get_active_entry` With this function you can get the currently selected entry. This can be used for the docs view or some other api functions. It is also used when the selection is confirmed. ## Confirm -`menu:confirm(): nil` - +`menu.confirm` This is the function to trigger the completion with a selected entry. It gets the selected entry closes the menu and completes. ## Complete -`menu:complete(entry: care.entry): nil` - -See [care.entry](/dev/entry) - +`menu.complete` This function completes with a given entry. That means it removes text used for filtering (if necessary), expands snippet with the configured function, applies text edits and lsp commands. ## Readjust Win -`menu:readjust_win(offset: integer): nil` - +`menu.readjust_win` This function readjusts the size of the completion window without reopening it. ## Docs Visible -`menu:docs_visible(): boolean` - +`menu.docs_visible` Checks whether docs are visible or not ## Scroll Docs -`menu:scroll_docs(delta: integer): nil` - +`menu.scroll_docs` Scroll up or down in the docs window by `delta` lines. ## Select -`menu:select(direction?: integer): nil` - +`menu.select` This method is used for selection. It's called in `select_prev` and `select_next` and is responsible for redrawing the menu, opening documentation and inserting the selected entry if required. Direction can either be 1 (down) or -1 (up) ## Draw Docs -`menu:draw_docs(entry: care.entry?): nil` - -See [care.entry](/dev/entry) - +`menu.draw_docs` Opens the documentation window for a selected entry # Fields ## Menu Window -`menu.menu_window care.window` - -See [care.window](/dev/window) - +`menu.menu_window` Wrapper for utilities for the window of the menu ## Docs Window -`menu.docs_window care.window` - -See [care.window](/dev/window) - +`menu.docs_window` Wrapper for utilities for the window of the docs ## Ghost Text -`menu.ghost_text care.ghost_text` - +`menu.ghost_text` The ghost text instance used to draw the ghost text. ## Entries -`menu.entries care.entry[]` - -See [care.entry](/dev/entry) - +`menu.entries` This field is used to store all the entries of the completion menu. ## Ns -`menu.ns integer` - +`menu.ns` The namespace is used to draw the extmarks and add the additional highlights. ## Config -`menu.config care.config` - +`menu.config` In this field the user config is stored for easier access. ## Buf -`menu.buf integer` - +`menu.buf` This is the buffer used for the menu. It's just created once when initially creating a new instance. ## Index -`menu.index integer` - +`menu.index` The index is used to determine the selected entry. It is used to get this entry when confirming the completion. The function to select the next and previous entries simply change this index. ## Scrollbar Buf -`menu.scrollbar_buf integer` - +`menu.scrollbar_buf` This field is used to store the buffer for drawing the scrollbar. ## Reversed -`menu.reversed boolean` - +`menu.reversed` Indicates if the menu is reversed (window above cursor and sorting_direction away from cursor) \ No newline at end of file diff --git a/docs/dev/source.md b/docs/dev/source.md index a1d3cf4..b819322 100644 --- a/docs/dev/source.md +++ b/docs/dev/source.md @@ -10,9 +10,8 @@ The sources are used to get get completions for care.nvim. # Methods -## Is Available -`source.is_available?(): boolean` - +## Is Available (optional) +`source.is_available?` Each source can have a function to show whether it's available or not. If your source should for example be enabled for a certain filetype you can just do it like this: ```lua @@ -23,17 +22,15 @@ end This function will be called quite often so developers should try to keep it more or less performant. This won't be an issue in the vast majority of cases though. -## Resolve Item -`source:resolve_item?(item: lsp.CompletionItem, callback: fun(item: lsp.CompletionItem)): nil` - +## Resolve Item (optional) +`source.resolve_item?` This is a function used to get additional details for completion items. This is especially important for the lsp source which needs to send the `completionItem/resolve` request. Resolving completion items is used for performance reasons so e.g. the documentation for an item doesn't always have to be sent. -## Get Trigger Characters -`source.get_trigger_characters?(): string[]` - +## Get Trigger Characters (optional) +`source.get_trigger_characters?` This function should return characters which trigger completion for the source. If one of those characters is types the completion will be retriggered. Otherwise newly entered characters are used for sorting and filtering. @@ -44,39 +41,31 @@ function my_source.get_trigger_characters() end ``` -## Get Keyword Pattern -`source:get_keyword_pattern?(): string` - +## Get Keyword Pattern (optional) +`source.get_keyword_pattern?` The `get_keyword_pattern` function has higher priority and will overwrite the string if provided. ## Complete -`source.complete(completion_context: care.completion_context, callback: fun(items: lsp.CompletionItem[], is_incomplete?: boolean)): nil` - +`source.complete` This is arguably the most important function of each source. This function returns completions. The function takes in a completion context and should return a list of entries. -## Execute -`source:execute?(entry: care.entry): nil` - -See [care.entry](/dev/entry) - +## Execute (optional) +`source.execute?` # Fields ## Name -`source.name string` - +`source.name` The `name` field is used for configuring the source. It should just contain characters, `_`, and `-`. -## Display Name -`source.display_name? string` - +## Display Name (optional) +`source.display_name?` The `display_name` of a field can be any string. This name is displayed in sources overview. It falls back to `name`. -## Keyword Pattern -`source.keyword_pattern? string` - +## Keyword Pattern (optional) +`source.keyword_pattern?` The keyword pattern is used to overwrite the keyword pattern from the config per source. It should basically represent the format of entries the source will provide as regex. \ No newline at end of file diff --git a/docs/dev/window.md b/docs/dev/window.md index 90fa529..583cba0 100644 --- a/docs/dev/window.md +++ b/docs/dev/window.md @@ -11,108 +11,84 @@ Utility class for working with windows in care # Methods ## New -`Window.new(): care.window` - -See [care.window](/dev/window) - +`window.new` Creates a new instance of the menu window ## Is Open -`window:is_open(): boolean` - +`window.is_open` Method to check whether the window is open or not ## Scrollbar Is Open -`window:scrollbar_is_open(): boolean` - +`window.scrollbar_is_open` Method to check whether the scrollbar window is open or not ## Readjust -`window:readjust(content_len: integer, width: integer, offset: integer): nil` - +`window.readjust` Adjust the window size to new entries. Modifies height and width while keeping position ## Open Scrollbar Win -`window:open_scrollbar_win(width: integer, height: integer, offset: integer): nil` - +`window.open_scrollbar_win` Opens the window for the scrollbar ## Close -`window:close(): nil` - +`window.close` Closes the window and the scrollbar window and resets fields ## Set Scroll -`window:set_scroll(index: integer, direction: integer, reversed: boolean): nil` - +`window.set_scroll` Sets the scroll of the window ## Open Cursor Relative -`window:open_cursor_relative(width: integer, wanted_height: integer, offset: integer, config: care.config.ui.docs|care.config.ui.menu): nil` - +`window.open_cursor_relative` Opens a new main window ## Draw Scrollbar -`window:draw_scrollbar(): nil` - +`window.draw_scrollbar` Draw the scrollbar for the window if needed ## Scroll -`window:scroll(delta: integer)` - +`window.scroll` Change scroll of window ## Get Data -`window:get_data(): care.window.data` - -See [care.window](/dev/window) - +`window.get_data` # Fields -## Winnr -`window.winnr? integer` - +## Winnr (optional) +`window.winnr?` ## Config -`window.config care.config` - +`window.config` Instance of the care config ## Buf -`window.buf integer` - +`window.buf` -## Position -`window.position? "above"|"below"` - +## Position (optional) +`window.position?` Whether the window is currently opened above or below the cursor ## Scrollbar -`window.scrollbar {win: integer, buf: integer}` - +`window.scrollbar` Data for the scrollbar of the window ## Max Height -`window.max_height integer` - +`window.max_height` The maximum available height where the window is currently open ## Opened At -`window.opened_at {row: integer, col: integer}` - +`window.opened_at` Where the window was last opened ## Ns -`window.ns integer` - +`window.ns` Namespace used for setting extmarks ## Current Scroll -`window.current_scroll integer` - +`window.current_scroll` Current scroll of the window @@ -121,50 +97,40 @@ Current scroll of the window # Fields ## First Visible Line -`window.data.first_visible_line integer` - +`window.data.first_visible_line` ## Last Visible Line -`window.data.last_visible_line integer` - +`window.data.last_visible_line` ## Visible Lines -`window.data.visible_lines integer` - +`window.data.visible_lines` ## Height Without Border -`window.data.height_without_border integer` - +`window.data.height_without_border` ## Width Without Border -`window.data.width_without_border integer` - +`window.data.width_without_border` ## Border -`window.data.border any` - +`window.data.border` ## Has Border -`window.data.has_border boolean` - +`window.data.has_border` ## Width With Border -`window.data.width_with_border integer` - +`window.data.width_with_border` ## Height With Border -`window.data.height_with_border integer` - +`window.data.height_with_border` ## Total Lines -`window.data.total_lines integer` - +`window.data.total_lines` diff --git a/docs/preset_components.md b/docs/preset_components.md index 475678c..d6c0c42 100644 --- a/docs/preset_components.md +++ b/docs/preset_components.md @@ -11,32 +11,25 @@ This module contains some high-level components for easily creating `format_entr # Methods ## ShortcutLabel -`preset_components.ShortcutLabel(labels: string[], entry: care.entry, data: care.format_data, highlight_group?: string): { [1]: string, [2]: string }[]` - -See [care.entry](/dev/entry) - +`preset_components.ShortcutLabel` This adds a label for shortcuts [described here](/configuration_recipes#labels-and-shortcuts). By default this will use the `Comment` highlight group. This can be overridden though. +![image](https://github.com/user-attachments/assets/c476d4e4-9cee-4168-96a5-08a7492f08a8) ## KindIcon -`preset_components.KindIcon(entry: care.entry, style?: "blended"|"fg"): { [1]: string, [2]: string }[]` - -See [care.entry](/dev/entry) - +`preset_components.KindIcon` This components displays a kind icon. You can choose between the blended and foreground style. +![image](https://github.com/user-attachments/assets/aea84adf-578d-401d-bbbc-911198357a13) +![image](https://github.com/user-attachments/assets/9d4918e7-2f5b-491e-a21e-8213d705b8a0) ## Label -`preset_components.Label(entry: care.entry, data: care.format_data, display_colored_block?: boolean): { [1]: string, [2]: string }[]` - -See [care.entry](/dev/entry) - +`preset_components.Label` This adds a completion item label to be displayed. Optionally this can also include a colored block if the items is a color and we know the value of the color. +![image](https://github.com/user-attachments/assets/28415670-8799-45fa-b175-cd1d643b2cd4) ## ColoredBlock -`preset_components.ColoredBlock(entry: care.entry, character?: string): { [1]: string, [2]: string }[]` - -See [care.entry](/dev/entry) - +`preset_components.ColoredBlock` This component adds a colored block for the item if it is a color. The character used for the block can -optionally be configured. \ No newline at end of file +optionally be configured. +![image](https://github.com/user-attachments/assets/e6bf8620-92af-4ffa-8973-635cab7beec4) \ No newline at end of file diff --git a/docs/preset_utils.md b/docs/preset_utils.md index 7627d74..bca1fda 100644 --- a/docs/preset_utils.md +++ b/docs/preset_utils.md @@ -11,30 +11,22 @@ This module contains lower level utilities for the presets and the preset compon # Methods ## Label Entries -`preset_utils.label_entries(labels: string[]): fun(_,data: care.format_data): string` - +`preset_utils.label_entries` This function can be used to get a function to label the entries with shortscuts as [described here](/configuration_recipes#labels-and-shortcuts). ## Get Color -`preset_utils.get_color(entry: care.entry): string?` - -See [care.entry](/dev/entry) - +`preset_utils.get_color` With this function you can get a color if the entry is a color and the hex color code is available in the completion item. ## Get Highlight For Hex -`preset_utils.get_highlight_for_hex(hex: string): string` - +`preset_utils.get_highlight_for_hex` This function allows to get a highlight group for a certain hex color code. This is useful because like that the user doesn't have to constantly create new highlight groups to apply a hex value to a certain thing. The highlight group will have the hex value as foregroung color. ## Kind Highlight -`preset_utils.kind_highlight(entry: care.entry, style: "fg"|"blended")` - -See [care.entry](/dev/entry) - +`preset_utils.kind_highlight` With this function you can get the kind highlight group for a specific entry. The style can either be foreground or blended. \ No newline at end of file diff --git a/docs/presets.md b/docs/presets.md index 4430958..262b831 100644 --- a/docs/presets.md +++ b/docs/presets.md @@ -5,23 +5,23 @@ description: Type description of care.presets # Presets -In this module some presets for the format_entry function are available. +In this module some presets for the format_entry function are available. They can be accessed like this +```lua +format_entry = function(entry, data) +return require("care.presets").(entry, data) +end +``` # `care.presets` # Methods ## Default -`presets.Default(entry: care.entry, data: care.format_data): { [1]: string, [2]: string }[][]` - -See [care.entry](/dev/entry) - +`presets.Default` The default preset. Just includes the label and a simple icon. +![image](https://github.com/user-attachments/assets/d3d7d338-db32-471f-ae20-89ea7703cb55) ## Atom -`presets.Atom(entry: care.entry, data: care.format_data): { [1]: string, [2]: string }[][]` - -See [care.entry](/dev/entry) - +`presets.Atom` The atom preset is an atom-like configuration. It displays the kind icon with a blended colored background and -the labelatom preset is an atom-like configuration. It displays the kind icon with a blended colored background -and the label. \ No newline at end of file +the label. +![image](https://github.com/user-attachments/assets/f8715fa7-1a0e-4be9-85ae-14b85cc2b7fd) \ No newline at end of file