ddc-file.txt

*ddc-file.txt*		   Powerful and Performant File Completion for ddc.vim

Author : Luma <world@luma.email>
License: MIT <https://github.com/LumaKernel/ddc-file/blob/main/LICENSE>


==============================================================================
CONTENTS						   *ddc-file-contents*

INTRODUCTION					       |ddc-file-introduction|
DISPLAY RULES					      |ddc-file-display-rules|
INSTALL							    |ddc-file-install|
EXAMPLES						   |ddc-file-examples|
  BASIC EXAMPLES				      |ddc-file-example-basic|
  NODE MODULES EXAMPLES				       |ddc-file-example-node|
PARAMS							     |ddc-file-params|
FREQUENTLY ASKED QUESTIONS (FAQ)			        |ddc-file-faq|

==============================================================================
INTRODUCTION					       *ddc-file-introduction*

This source collects items from file paths under the (1) buffer relative,
(2) cwd relative, (3) project root (.git/, etc...; configurable by
|ddc-file-param-projMarkers|) relative.

==============================================================================
DISPLAY RULES					      *ddc-file-display-rules*

In menu (right side of the completion items), this source shows how was
that completion got from.
>
    /cwd^2
    ^|--||--- (a) if '/' is present, regard input's '/' as relative
     ^--||--- (b) 'buf', 'cwd', or omitted for absolute paths
        ^|--- (c) if '^' is present, project-root found from (b)
         ^--- (d) project-root search recursion level (1 is omitted)
<

It can be disabled by |ddc-file-param-disableMenu| and customized by
following.
- |ddc-file-param-displayCwd|
- |ddc-file-param-displayBuf|

==============================================================================
INSTALL							    *ddc-file-install*

Please install both "ddc.vim" and "denops.vim".

https://github.com/Shougo/ddc.vim
https://github.com/vim-denops/denops.vim

==============================================================================
EXAMPLES						   *ddc-file-examples*

I welcome PRs for your useful ideas.

------------------------------------------------------------------------------
BASIC EXAMPLE					      *ddc-file-example-basic*
>
	call ddc#custom#patch_global('sources', ['file'])
	call ddc#custom#patch_global('sourceOptions', {
	    \ 'file': {
	    \   'mark': 'F',
	    \   'isVolatile': v:true,
	    \   'forceCompletionPattern': '\S/\S*',
	    \ }})
	call ddc#custom#patch_filetype(
	    \ ['ps1', 'dosbatch', 'autohotkey', 'registry'], {
	    \ 'sourceOptions': {
	    \   'file': {
	    \     'forceCompletionPattern': '\S\\\S*',
	    \   },
	    \ },
	    \ 'sourceParams': {
	    \   'file': {
	    \     'mode': 'win32',
	    \   },
	    \ }})
<

------------------------------------------------------------------------------
NODE MODULES EXAMPLE				       *ddc-file-example-node*

Find any files under node_modules/ folder from JS-family filetype buffers. You
can see the completion when typing like `import ... from "<cursor>` in JS
files. This collects files from up to 3 node_modules/ folders for example
useful in monorepos.
This config does not conflict with |ddc-file-example-basic|.
>
	call ddc#custom#alias('source', 'node-modules', 'file')
	call ddc#custom#patch_global({
	    \ 'sourceOptions': {
	    \   'node-modules': {
	    \     'mark': 'NODE',
	    \     'isVolatile': v:true,
	    \     'minAutoCompleteLength': 10000,
	    \     'forceCompletionPattern':
	    \       '(?:'
	    \         . '\bimport|'
	    \         . '\bfrom|'
	    \         . '\brequire\s*\(|'
	    \         . '\bresolve\s*\(|'
	    \         . '\bimport\s*\('
	    \       . ')'
	    \       . '\s*(?:''|"|`)[^''"`]*',
	    \   },
	    \ },
	    \ 'sourceParams': {
	    \   'node-modules': {
	    \     'cwdMaxItems': 0,
	    \     'bufMaxItems': 0,
	    \     'followSymlinks': v:true,
	    \     'projMarkers': ['node_modules'],
	    \     'projFromCwdMaxItems': [],
	    \     'projFromBufMaxItems': [],
	    \     'beforeResolve': 'node_modules',
	    \     'displayBuf': '',
	    \   },
	    \ }})
	call ddc#custom#patch_filetype(
	    \ [
	    \   'javascript',
	    \   'typescript',
	    \   'javascriptreact',
	    \   'typescriptreact',
	    \   'tsx',
	    \ ], {
	    \ 'sourceParams': {
	    \   'node-modules': {
	    \     'projFromBufMaxItems': [1000, 1000, 1000],
	    \   },
	    \ }})
<

==============================================================================
PARAMS							     *ddc-file-params*

							 *ddc-file-param-mode*
mode		("os" | "win32" | "posix")
		Controls path resolving and path separator. "os" will use the
		current OS native mode.

		Default: "posix"

						  *ddc-file-param-takeFileNum*
takeFileNum	(number)
		Limit number of files to filter at very first timing, namely
		before filtering. It is useful if there are too many 'a...'
		files when filtering with 'z'.

		Default: 10000

						  *ddc-file-param-projMarkers*
projMarkers	(string[])
		File or directory names to search for project-root. Don't
		include ending slashes. Used for exact match.

		Default: [
		    ".git",
		    ".vscode",
		    ".github",
		]

					     *ddc-file-param-cwdMaxItems*
cwdMaxItems	(number)
		Max items number for cwd relative.

		Default: 1000

					     *ddc-file-param-bufMaxItems*
bufMaxItems	(number)
		Max items number for buffer relative.

		Default: 1000

				     *ddc-file-param-projFromCwdMaxItems*
projFromCwdMaxItems	(number[])
		Max items number for project-root relative found by cwd.
		n-th number is used for n-th recursively found project-root.

		e.g. Consider following situation.
		  my-project/
		  |- .git/
		  |- sub-project/
		     |- .git/
		     |- src/  <-- cwd
		        |- my-document.txt
		If [10] is set, sub-project/ is only found with up to 10
		files.
		If [10, 5] is set, sub-project/ is found with up to 10 files
		and my-project/ is also found with up to 5 files.

		Default: [1000]

				     *ddc-file-param-projFromBufMaxItems*
projFromBufMaxItems	(number[])
		Project-root from buffer relative version of
		|ddc-file-param-projFromCwdMaxItems|.

		Default: [1000]

						   *ddc-file-param-cwdAsRoot*
cwdAsRoot	(boolean)
		Set to true to complete from cwd even if the input is absolute
		path. e.g. the input is '/REA', and there is
		<cwd>/README.md, this will be completed as well.

		Default: false

						   *ddc-file-param-bufAsRoot*
bufAsRoot	(boolean)
		Buffer relative version of |ddc-file-param-cwdAsRoot|.

		Default: false

						  *ddc-file-param-projAsRoot*
projAsRoot	(boolean)
		Project-root relative version of |ddc-file-param-cwdAsRoot|.

		Default: true

					       *ddc-file-param-trailingSlash*
trailingSlash	(boolean)
		Whether to include trailing slash when completing directory
		name.

		Default: false

					   *ddc-file-param-trailingSlashAbbr*
trailingSlashAbbr	(boolean)
		Whether to display trailing slash when completing directory
		name. Note that this won't be actually inserted.

		Default: true

					      *ddc-file-param-followSymlinks*
followSymlinks	(boolean)
		Whether to follow symlinks to determine whether the filename
		completing is file or directory. Note that, if you are trying
		to complete /foo/bar/bar when /foo/bar is symlink, it'll work
		without this param.

		Default: false

						 *ddc-file-param-disableMenu*
disableMenu	(boolean)
		Disable to show menu like `buf^`. |ddc-file-display-rules|

		Default: false

					       *ddc-file-param-beforeResolve*
						*ddc-file-param-afterResolve*
beforeResolve	(string) Default: ""
afterResolve	(string) Default: ""
		Your input will be transformed as join(find-root,
		beforeResolve, input, afterResolve). Empty strings are
		skipped. Path "find-root" denotes cwd/buf or found
		project-root by other settings. See |ddc-file-example-node|
		for example. You can specify absolute path to complete for
		specific folder, like with configuring
		`beforeResolve: '/usr/bin'` .

		Default: ""

						*ddc-file-param-filenameChars*
filenameChars	(string)
		The characters as filename pattern.
		The pattern is |/collection| pattern.

		Default: "[:keyword:]"

						 *ddc-file-param-displayFile*
						  *ddc-file-param-displayDir*
						  *ddc-file-param-displaySym*
					       *ddc-file-param-displaySymDir*
					      *ddc-file-param-displaySymFile*
displayFile	(string) Default: "file"
displayDir	(string) Default: "dir"
displaySym	(string) Default: "sym"
displaySymFile	(string) Default: "sym=file"
displaySymDir	(string) Default: "sym=dir"
		Texts to show as kind of completed item. To disable, set empty
		strings.
		`displaySymFile` and `displaySymDir` are only used when
		|ddc-file-param-followSymlinks| is set to `true`.

						  *ddc-file-param-displayCwd*
						  *ddc-file-param-displayBuf*
displayCwd	(string) Default: "cwd"
displayBuf	(string) Default: "buf"
		Texts to show as menu of completed item.
		See |ddc-file-display-rules|.

==============================================================================
FREQUENTLY ASKED QUESTIONS (FAQ)			        *ddc-file-faq*

Q: How to complete paths including spaces or punctuations?

A. ddc-file respects value of 'isfname' for backward searching, but as
described in 'isfname', it's not recommended to treat paths including such
special characters. If you still want, I cannot stop you, please try this.
>
	:set isfname+=32,40-41
<
Please take care that leading spaces are also treated as part of path.

Q: I want to include "." as filename pattern.

A. You can change the pattern by |ddc-file-param-filenameChars|.
>
	call ddc#custom#patch_global('sourceParams', {
	    \   'file': {'filenameChars': '[:keyword:].'},
	    \ })

==============================================================================
vim:tw=78:ts=8:noet:ft=help:norl