tree.txt

*tree.txt*	Neovim file explorer powered by C++.

Version: 0.1.0
Author: zgp <zgpio@qq.com>
License: MIT license

                                      Type |gO| to see the table of contents.

==============================================================================
INTRODUCTION						*tree-introduction*

*tree* is the neovim file explorer powered by C++.

==============================================================================
INSTALL							*tree-install*

Note: tree requires Neovim 0.5+.

1. Extract the files and put them in your Neovim config directory
   (usually `$XDG_CONFIG_HOME/nvim/`).

==============================================================================
INTERFACE						*tree-interface*

------------------------------------------------------------------------------
COMMANDS 						*tree-commands*

:Tree [{options}] {paths}				*:Tree*
		Creates a new Tree buffer.

------------------------------------------------------------------------------
FUNCTIONS 						*tree-functions*

tree#action({action}[, {args}])				*tree#action()*
		Fire {action} action with {args} asynchronously.
		See |tree-actions|.
		{args} behavior depends on {action}.
		Note: It is only used to define mappings.
		Note: You cannot fire the next action until the previous
		action is finished.

							*tree.call_action()*
tree.call_action({action}[, {args}])
		Fire {action} action with {args}.  See |tree-actions|.
		{args} behavior depends on {action}.

						*tree.call_async_action()*
tree.call_async_action({action}[, {args}])
		Fire {action} action with {args} asynchronously.
		See |tree-actions|.
		{args} behavior depends on {action}.
		Note: You cannot fire the next action until the previous
		action is finished.

						*tree.custom_column()*
tree.custom_column({column-name}, {option-name}, {value})
tree.custom_column({column-name}, {dict})
		Set {column-name} column specialized variable {variable-name}
		to {value}.  You may specify multiple sources with the
		separator "," in {column-name}. >

	tree.custom_column('icon', {
	    directory_icon='▸',
	    opened_icon='▾',
	    root_icon=' ',
	})

	tree.custom_column('filename', {
	    min_width=40,
	    max_width=40,
	})

	tree.custom_column('mark', {
	    readonly_icon='✗',
	    selected_icon='✓',
	})
<
						*tree.custom_option()*
tree.custom_option({buffer-name}, {option-name}, {value})
tree.custom_option({buffer-name}, {dict})
		Set {option-name} option to {value} in {buffer-name}
		buffer.
		If {buffer-name} is "_", the options are used for all buffers.
		If {dict} is available, the key is {option-name} and the value
		is {value}.
		Note: The all options are in |tree-options|.  However, "-" is
		substituted to "_", and "-" prefix is removed. >

	tree.custom_option('_', {
	    columns='mark:indent:icon:filename:type:size:time',
	})
<
							*tree.custom_source()*
tree.custom_source({source-name}, {var-name}, {value})
tree.custom_source({source-name}, {dict})
		Set {source-name} source specialized variable {variable-name}
		to {value}.  You may specify multiple sources with the
		separator "," in {source-name}.
		Note: Not yet implemented.
>
	function! Root(path) abort
	  return fnamemodify(a:path, ':t')
	endfunction

	call v:lua.tree.custom_source('file', {
	     \ 'root': 'Root',
	     \})
<
tree.get_candidate()					*tree.get_candidate()*
		Returns the current cursor candidate as |Dictionary|.

tree.is_directory()					*tree.is_directory()*
		Returns true if the current cursor candidate is directory.

		Example: >

		nnoremap <silent><buffer><expr> <CR>
		\ v:lua.tree.is_directory() ?
		\ tree#action('open') : tree#action('multi', ['drop', 'quit'])


tree.is_opened_tree()					*tree.is_opened_tree()*
		Returns true if the current cursor candidate is opened
		directory tree.

------------------------------------------------------------------------------
KEY MAPPINGS 						*tree-key-mappings*

Tree does not provide any of default key mappings.
You need to define original key mappings by |tree#action()|.

------------------------------------------------------------------------------
ACTIONS 						*tree-actions*

add_session 					*tree-action-add_session*
		Add the current directory in current sessions and save to
		|tree-option-session-file|.
		Note: You must set to |tree-option-session-file| save current
		sessions.
		Note: Not yet implemented.

		Current session feature saves below states.

		* current path
		* opened tree state

		Action args:
			0. session directory path

call 						*tree-action-call*
		Call the function.
		You can get the files path as "a:context.targets".

		Action args:
			0. function name
			Note: It must be string.  You cannot use |funcref| or
			|lambda|.

		Example: >

		function! Test(context) abort
		  echomsg string(a:context.targets)
		endfunction
		nnoremap <silent><buffer><expr> f
		\ tree#action('call', 'Test')

		" or you can use SID hack
		function! s:Test(context) abort
		  echomsg string(a:context.targets)
		endfunction
		function! s:SID_PREFIX() abort
		  return matchstr(expand('<sfile>'),
		  \ '<SNR>\d\+_\zeSID_PREFIX$')
		endfunction
		let g:sid = s:SID_PREFIX()
  		nnoremap <silent><buffer><expr> f
		\ tree#action('call', g:sid.'Test')

cd 						*tree-action-cd*
		Change the current directory.
		Note: If the action args is empty, it means the home
		directory.

		Action args:
			0. new current directory path

change_vim_cwd					*change_vim_cwd*
		Change current working directory to the current directory.

clear_select_all				*tree-action-clear_select_all*
		Clear the all candidates select.

close_tree					*tree-action-close_tree*
		Close the directory tree.

copy 						*tree-action-copy*
		Copy the selected files to tree clipboard.

drop							*tree-action-drop*
		Open the file like |:drop| command.

		Action args:
			0. open command(The default is |:edit|)

execute_command 					*tree-action-execute_command*
		Execute the command.

		Action args:
			0. command(The default is your input)

execute_system 					*tree-action-execute_system*
		Execute the file by system associated command.

move 						*tree-action-move*
		Move the selected files to tree clipboard.

multi 						*tree-action-multi*
		Multiple actions.

		Action args:
			0. action 1
			1. action 2
			...

		Example: >

		" auto quit like behavior
		nnoremap <silent><buffer><expr> <CR>
		\ tree#action('multi', ['drop', 'quit'])
		nnoremap <silent><buffer><expr> s
		\ tree#action('multi', [['drop', 'split'], 'quit'])

new_file 						*tree-action-new_file*
		Create a new file or directory.
		If the input ends with "/", it means new directory.

					*tree-action-new_multiple_files*
new_multiple_files
		Create new files and directories if provided.
		If the input ends with "/", it means new directory.

open							*tree-action-open*
		Open the file.

		Action args:
			0. open command(The default is |:edit|)

open_directory					*tree-action-open_directory*
		Open the directory.

		Action args:
			0. open file path(The default is the selected
			directory)

open_or_close_tree			*tree-action-open_or_close_tree*
		Open the directory tree if the directory is not opened.
		Close the directory tree if the directory is opened.

open_tree					*tree-action-open_tree*
		Open the directory tree.

open_tree_recursive			*tree-action-open_tree_recursive*
		Open the directory tree recursively.

		Action args:
			0. max recursive leavel(The default is "20")

paste							*tree-action-paste*
		Fire the clipboard action in the current directory.
		Note: It is used after |tree-action-copy| or |tree-action-move|.

print 						*tree-action-print*
		Print the filename.

quit							*tree-action-quit*
		Quit the buffer.

redraw						      *tree-action-redraw*
		Redraw the buffer.

repeat						      *tree-action-repeat*
		Redraw the previous action.

rename						      *tree-action-rename*
		Rename the file/directory under cursor or from selected list.
		Note: If you select multiple files, it will be buffer-rename
		mode.

remove							*tree-action-remove*
		Delete the file/directory under cursor or from selected list
		completely.
		Note: You cannot undo the action.

		Action args:
			0. If it is "true", suppress the confirmation.

remove_trash					*tree-action-remove_trash*
		Delete the file/directory under cursor or from selected list
		to trashbox.

		Action args:
			0. If it is "true", suppress the confirmation.

search						      *tree-action-search*
		Search the path.

		Action args:
			0. search the path

toggle_columns			*tree-action-toggle_columns*
		Toggle the current columns.

		Action args:
			0. ":" separated tree columns.

toggle_sort			*tree-action-toggle_sort*
		Toggle the sort method.

		Action args:
			0. sort method.

toggle_ignored_files			*tree-action-toggle_ignored_files*
		Toggle the enable state of ignored files.

toggle_select					*tree-action-toggle_select*
		Toggle the cursor candidate select.

toggle_select_all				*tree-action-toggle_select_all*
		Toggle the all candidates select.

toggle_select_visual
*tree-action-toggle_select_visual*
		Toggle the visual mode selected candidates select.

yank_path					*tree-action-yank_path*
		Yank the all candidates path.

------------------------------------------------------------------------------
OPTIONS							*tree-options*

							*tree-option-no-*
-no-{option-name}
		Disable {option-name} flag.
		Note: If you use both {option-name} and -no-{option-name} in
		the same denite buffer, it is undefined.

							*tree-option-auto-cd*
-auto-cd
		Change the working directory while navigating with tree.
		Default: false

					*tree-option-auto-recursive-level*
-auto-recursive-level={level}
		The level to expand tree automatically.
		Default: 0

						*tree-option-buffer-name*
-buffer-name={buffer-name}
		Specify tree buffer name.
		Default: "default"

							*tree-option-columns*
-columns={…:indent:…:icon:filename:…}
		Specify tree columns.
		Default: "mark:indent:icon:filename:type"

						*tree-option-direction*
-direction={direction}
		Specify the window direction as {direction} if
		|tree-option-split| is set.
		You can use "topleft" or "botright".
		Default: ""

						*tree-option-ignored-files*
-ignored-files={pattern}
		Specify the ignored files pattern.
		The pattern is comma separated.
		Default: ".*"

							*tree-option-listed*
-listed
		Enable 'buflisted' option in tree buffer.

		Default: false

							*tree-option-new*
-new
		Create new tree buffer.
		Resume existing tree buffer by default.

		Default: false

							*tree-option-profile*
-profile
		Enable profile feature.
		Note: It is for debugging.

		Default: false

						*tree-option-root-marker*
-root-marker={marker}
		Root marker.

		Default: "[in]: "

							*tree-option-search*
-search={path}
		Search the {path}.
		Note: It must be full path.

		Default: ""

						*tree-option-session-file*
-session-file={path}
		Session file {path}.
		Note: It must be full path.

		Default: ""

							*tree-option-show-ignored-files*
-show-ignored-files
		Show ignored files by default.
		Default: false

							*tree-options-sort*
-sort={method}
		Sort method.
		If the method is upper case, the order will be reversed.

		"extension": file extension sort
		"filename": file name sort
		"size": file size sort
		"time": file modified time sort

		Default: "filename"

						*tree-option-split*
-split={direction}
		Specify the split direction.

		"vertical": Split buffer vertically
		"horizontal": Split buffer horizontally
		"no": No split
		"tab": Create the new tab
		"floating": Use neovim floating window feature

		Default: "no"

							*tree-option-toggle*
-toggle
		Close tree buffer window if this tree window exists.
		Default: false

						*tree-option-wincol*
-wincol={window-column}
		Set the column position of the Tree window if
		|tree-option-split| is "floating".

		Default: &columns / 4

						*tree-option-winheight*
-winheight={window-height}
		Set the height of the window if |tree-option-split| is
		"horizontal".

		Default: 30

						*tree-option-winrelative*
-winrelative={direction}
		Specify the relative position in floating window.
		|nvim_open_win|

		Default: "editor"

						*tree-option-winrow*
-winrow={window-row}
		Set the row position of the Tree window if
		|tree-option-split| is "floating".

		Default: &lines / 3

						*tree-option-winwidth*
-winwidth={window-width}
		Set the width of the window if |tree-option-split| is
		"vertical".

		Default: 90

------------------------------------------------------------------------------
COLUMNS							*tree-columns*

							*tree-column-filename*
filename	File name.

		variables:
		min_width	  the minimum width of a tree buffer
				  (default: 40)
		max_width	  the maximum width of a tree buffer
				  (default: 100)
		root_marker_highlight
				the root marker highlight
				  (default: "Constant")

							*tree-column-icon*
icon		Basic icon.

		variables:
		directory_icon	  the closed directory icon
				  (default: "+")
		opened_icon	  the opened directory icon
				  (default: "-")
		root_icon	  the root directory icon
				  (default: " ")

							*tree-column-indent*
indent		Tree indentation.
		Note: It depends on |tree-column-filename|.

		variables:
		indent		  the indent marker.
				  (default: " ")

							*tree-column-mark*
mark		File selected mark.

		variables:
		length		  the column length
				  (default: 1)
		readonly_icon	  the readonly file icon
				  (default: "X")
		selected_icon	  the selected file icon
				  (default: "*")

							*tree-column-size*
size		File size.

							*tree-column-time*
time		File modified time.

		variables:
		format		  the time format
				  (default: "%y.%m.%d %H:%M")

							*tree-column-type*
type		File type.

		variables:
		types		  the types definition
				  (default: complicated)

EXTERNAL COLUMNS					*tree-external-columns*


------------------------------------------------------------------------------
SOURCES 						*tree-sources*

file		File

		variables:
		root		  root function name
				  Note: It must be string.  You cannot use
				  |funcref| or |lambda|.
				  (default is v:null)

==============================================================================
EXAMPLES						*tree-examples*
>
	...
<
==============================================================================
FREQUENTLY ASKED QUESTIONS (FAQ)			*tree-faq*

Q: How to explore the folder where the current file is?

A: >
	Tree `expand('%:p:h')` -search=`expand('%:p')`

Q: How to open tree window like explorer?

A: >
	Tree -split=vertical -winwidth=50 -direction=topleft

Q: How to open file use drop?

A: >
	nnoremap <silent><buffer><expr> <CR> tree#action('drop')

==============================================================================
COMPATIBILITY						*tree-compatibility*

2019-03-10
* ...

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