Commits

abudden committed 9f13689

Much more documentation and some further tidying up of some of the options (hooks and standard libraries).

Comments (0)

Files changed (6)

autoload/TagHighlight/Generation.vim

 let g:loaded_TagHLGeneration = 1
 
 function! TagHighlight#Generation#UpdateTypesFile(recurse, skiptags)
-	call TagHighlight#Option#LoadOptionFileIfPresent()
+	let option_file_info = TagHighlight#Option#LoadOptionFileIfPresent()
 	" Initial very simple implementation
 	
 	" Call any PreUpdate hooks
-	let hooks = TagHighlight#Option#GetOption('Hooks')
-	if has_key(hooks, 'PreUpdate')
-		for preupdate_hook in hooks['PreUpdate']
-			exe 'call' preupdate_hook . '()'
-		endfor
-	endif
+	let preupdate_hooks = TagHighlight#Option#GetOption('PreUpdateHooks')
+	for preupdate_hook in preupdate_hooks
+		exe 'call' preupdate_hook . '()'
+	endfor
 	
 	" Start with a copy of the settings so that we can tweak things
 	let RunOptions = TagHighlight#Option#CopyOptions()
 	if types_file_info['Found'] == 1
 		let RunOptions['TypesFileLocation'] = types_file_info['Directory']
 	endif
+
+	if ! has_key(RunOptions, 'SourceDir')
+		" The source directory has not been set.  If a project config file was
+		" found, use that directory.  If not, but a types file was found,
+		" use that directory.  If not, but a tag file was found, use that
+		" directory.  If not, use the current directory.
+		if option_file_info['Found'] == 1
+			let RunOptions['SourceDir'] = option_file_info['Directory']
+		elseif types_file_info['Found'] == 1
+			let RunOptions['SourceDir'] = types_file_info['Directory']
+		elseif tag_file_info['Found'] == 1
+			let RunOptions['SourceDir'] = tag_file_info['Directory']
+		else
+			let RunOptions['SourceDir'] = '.'
+		endif
+	endif
 	
 	call TagHighlight#RunPythonScript#RunGenerator(RunOptions)
 
-	if has_key(hooks, 'PostUpdate')
-		for postupdate_hook in hooks['PostUpdate']
-			exe 'call' postupdate_hook . '()'
-		endfor
-	endif
+	let postupdate_hooks = TagHighlight#Option#GetOption('PostUpdateHooks')
+	for postupdate_hook in postupdate_hooks
+		exe 'call' postupdate_hook . '()'
+	endfor
 endfunction

autoload/TagHighlight/Libraries.vim

 	let libraries_to_load = []
 	let forced_standard_libraries = TagHighlight#Option#GetOption('ForcedStandardLibraries')
 
+	if TagHighlight#Option#GetOption('DisableStandardLibraries')
+		return []
+	endif
+
 	for library in values(g:TagHighlightPrivate['Libraries'])
 		let load = 0
 		if index(library['TypesSuffixes'], a:suffix) != -1

autoload/TagHighlight/Option.vim

 	" Got an option file, load it in:
 	let b:TagHighlightConfigFileOptions = TagHighlight#LoadDataFile#LoadFile(option_file['FullPath'])
 
+	return option_file
 endfunction
 
 function! TagHighlight#Option#LoadOptions()

autoload/TagHighlight/ReadTypes.vim

 
 	let fullname = expand(file . ':p')
 
-	let hooks = TagHighlight#Option#GetOption('Hooks')
 	" Call Pre Read hooks (if any)
-	if has_key(hooks, 'PreRead')
-		for preread_hook in hooks['PreRead']
-			exe 'call' preread_hook . '(fullname, a:suffix)'
-		endfor
-	endif
+	let preread_hooks = TagHighlight#Option#GetOption('PreReadHooks')
+	for preread_hook in preread_hooks
+		exe 'call' preread_hook . '(fullname, a:suffix)'
+	endfor
 
 	let skiplist = TagHighlight#Option#GetOption('ParsingSkipList')
 	if len(skiplist) > 0
 	endif
 
 	" Call Post Read Hooks (if any)
-	if has_key(hooks, 'PostRead')
-		for postread_hook in hooks['PostRead']
-			exe 'call' postread_hook . '(fullname, a:suffix)'
-		endfor
-	endif
+	let postread_hooks = TagHighlight#Option#GetOption('PostReadHooks')
+	for postread_hook in postread_hooks
+		exe 'call' postread_hook . '(fullname, a:suffix)'
+	endfor
 
 	" Restore the view
 	call winrestview(savedView)

doc/TagHighlight.txt

 <
 	Project Options                  *taghl_config.txt*
 
-	    ... TODO
+	    Project options are set in a text file in the project directory.
+	    The location of this file can be specified using the options
+	    |TagHL-ProjectConfigDirModePriority| and (if an explicit location
+	    is needed) |TagHL-ProjectConfigFileDirectory|.  By default. the
+	    file name of the project config file is "taghl_config.txt".  If
+	    for any reason you need to change this, it can be customised using
+	    the option |TagHL-ProjectConfigFileName| (this probably needs to
+	    be a Global option set in |g:TagHighlightSettings|.
+
+	    The format of the project config file is a simple text file with
+	    colons used to delimit keys and values.  A simple example would
+	    look like this:
+>
+		Recurse:True
+		SkipPatterns:Skip.*,AnotherPattern\d+
+		IncludeLocals:1
+		UserLibraryDir:c:/user_libraries
+		PythonVariantPriority:
+			if_pyth
+			if_pyth3
+			python
+			compiled
+<
+	    Most lines start with an option name (there is no leading
+	    whitespace on these lines).  The option name is everything up to
+	    the colon.  After the colon is the value.
+	    
+	    For boolean options (such as Recurse and IncludeLocals in the
+	    example above), any of True, 1, False or 0 are acceptable (note:
+	    True and False are case sensitive).
+	    
+	    For string entries (such as UserLibraryDir above), all of the text
+	    after the first colon is treated as the value.
+	    
+	    For list entries (such as SkipPatterns and PythonVariantPriority
+	    above), you can either put all the entries on one line with commas
+	    to separate them, or you can put one entry on each subsequeunt
+	    line with a tab character at the start of the line.
 
 	Buffer Options                   *b:TagHighlightSettings*
 	
-	    ... TODO
+	    Buffer specific options are set in a buffer-local |Dictionary| in
+	    the same way as the global options in |g:TagHighlightSettings|.
+	    The name of this |Dictionary| is |b:TagHighlightSettings|.  See
+	    the description for |g:TagHighlightSettings| for usage
+	    instructions.
 
 2.4.2 Option Summary                     *TagHighlight-option-list*         {{{3
 
     option name to jump to detailed help on it.
 	
     What files to scan:
-    	Languages                        *TagHL-Languages*
-    	ParsingSkipList                  *TagHL-ParsingSkipList*
-    	Recurse                          *TagHL-Recurse*
-    	SourceDir                        *TagHL-SourceDir*
+
+    	Languages                        Link:|TagHL-Languages|
+	    List of languages to scan when generating highlighter.
+
+    	ParsingSkipList                  Link:|TagHL-ParsingSkipList|
+	   List of files for which types highlighter should not be loaded.
+
+    	Recurse                          Link:|TagHL-Recurse|
+	   When generating tags, recurse into subdirectories.
+
+    	SourceDir                        Link:|TagHL-SourceDir|
+	   Explicit location of the source code that you want to scan.
 
     What to include in the generated types file
-    	IncludeLocals                    *TagHL-IncludeLocals*
-    	IncludeSynMatches                *TagHL-IncludeSynMatches*
-    	SkipPatterns                     *TagHL-SkipPatterns*
-    	SkipVimKeywords                  *TagHL-SkipVimKeywords*
+
+    	IncludeLocals                    Link:|TagHL-IncludeLocals|
+	   Include local variables (not context aware) in types highlighter.
+
+    	IncludeSynMatches                Link:|TagHL-IncludeSynMatches|
+	   Include syntax matches in highlighter (see warning in details).
+
+    	SkipPatterns                     Link:|TagHL-SkipPatterns|
+	   List of python REs for keywords that should be skipped.
+
+    	SkipVimKeywords                  Link:|TagHL-SkipVimKeywords|
+	   Don't include vim keywords in highlighter.
 
     Customisation:
-    	Hooks                            *TagHL-Hooks*
+
+    	PreReadHooks                     Link:|TagHL-PreReadHooks|
+	   List of functions to call before reading types.
+
+    	PostReadHooks                    Link:|TagHL-PostReadHooks|
+	   List of functions to call after reading types.
+
+    	PreUpdateHooks                   Link:|TagHL-PreUpdateHooks|
+	   List of functions to call before updating types.
+
+    	PostUpdateHooks                  Link:|TagHL-PostUpdateHooks|
+	   List of functions to call after updating types.
 
     Disabling built-in functionality:
-    	DisableTypeParsing               *TagHL-DisableTypeParsing*
-    	DoNotGenerateTags                *TagHL-DoNotGenerateTags*
+
+    	DisableTypeParsing               Link:|TagHL-DisableTypeParsing|
+	   Don't read types highlighter (disable highlight functionality).
+
+    	DoNotGenerateTags                Link:|TagHL-DoNotGenerateTags|
+	   Don't generate tags (use an existing tags file).
 
     How to Run The Python App:
-    	ForcedPythonVariant              *TagHL-ForcedPythonVariant*
-    	PathToPython                     *TagHL-PathToPython*
-    	PythonVariantPriority            *TagHL-PythonVariantPriority*
+
+    	ForcedPythonVariant              Link:|TagHL-ForcedPythonVariant|
+	   Specify specific python variant to use.
+
+    	PathToPython                     Link:|TagHL-PathToPython|
+	   Specify path to python executable.
+
+    	PythonVariantPriority            Link:|TagHL-PythonVariantPriority|
+	   Specify priority order of different python variants.
 
     Locations of Files (normal):
-    	DirModeSearchWildcards           *TagHL-DirModeSearchWildcards*
-    	DefaultDirModePriority           *TagHL-DefaultDirModePriority*
+
+    	DirModeSearchWildcards           Link:|TagHL-DirModeSearchWildcards|
+	   What to search for when deciding which directory to use.
+
+    	DefaultDirModePriority           Link:|TagHL-DefaultDirModePriority|
+	   Which directories to search by default.
 
     Location and name of Project Configuration File:
-    	ProjectConfigFileDirModePriority *TagHL-ProjectConfigFileDirModePriority*
-    	ProjectConfigFileDirectory       *TagHL-ProjectConfigFileDirectory*
-    	ProjectConfigFileName            *TagHL-ProjectConfigFileName*
+
+    	ProjectConfigFileDirModePriority Link:|TagHL-ProjectConfigFileDirModePriority|
+	   Which directories to search for project config file.
+
+    	ProjectConfigFileDirectory       Link:|TagHL-ProjectConfigFileDirectory|
+	   Explicit location for project config file.
+
+    	ProjectConfigFileName            Link:|TagHL-ProjectConfigFileName|
+	   File name for project config file.
 
     Location and name of tag file:
-    	TagFileDirModePriority           *TagHL-TagFileDirModePriority*
-    	TagFileDirectory                 *TagHL-TagFileDirectory*
-    	TagFileName		         *TagHL-TagFileName*
+
+    	TagFileDirModePriority           Link:|TagHL-TagFileDirModePriority|
+	   Which directories to search for tag file.
+
+    	TagFileDirectory                 Link:|TagHL-TagFileDirectory|
+	   Explicit location for tag file.
+
+    	TagFileName		         Link:|TagHL-TagFileName|
+	   File name for tag file.
 
     Location and name of types file:
-    	TypesFileDirModePriority         *TagHL-TypesFileDirModePriority*
-    	TypesFileDirectory               *TagHL-TypesFileDirectory*
-    	TypesFileExtension               *TagHL-TypesFileExtension*
-    	TypesFileLocation                *TagHL-TypesFileLocation*
-    	TypesFileNameForce               *TagHL-TypesFileNameForce*
-    	TypesFilePrefix                  *TagHL-TypesFilePrefix*
+
+    	TypesFileDirModePriority         Link:|TagHL-TypesFileDirModePriority|
+	   Which directories to search for types highlighter file.
+
+    	TypesFileDirectory               Link:|TagHL-TypesFileDirectory|
+	   Explicit location for types highlighter file.
+
+    	TypesFileExtension               Link:|TagHL-TypesFileExtension|
+	   File extension for types highlighter file.
+
+    	TypesFileNameForce               Link:|TagHL-TypesFileNameForce|
+	   Force an explicit file name for the types highlighter file.
+
+    	TypesFilePrefix                  Link:|TagHL-TypesFilePrefix|
+	   Prefix for the types highlighter file.
 
     Libraries:
-    	ForcedStandardLibraries          *TagHL-ForcedStandardLibraries*
-    	UserLibraries                    *TagHL-UserLibraries*
-    	UserLibraryDir                   *TagHL-UserLibraryDir*
+
+	DisableStandardLibraries         Link:|TagHL-DisableStandardLibraries|
+	    Don't try loading standard libraries.
+
+    	ForcedStandardLibraries          Link:|TagHL-ForcedStandardLibraries|
+	   Always load specified standard libraries.
+
+    	UserLibraries                    Link:|TagHL-UserLibraries|
+	   List of user libraries that should be loaded.
+
+    	UserLibraryDir                   Link:|TagHL-UserLibraryDir|
+	   Location of user libraries specified with relative path.
 
     Debugging:
-	DebugLevel                       *TagHL-DebugLevel*
+
+	DebugLevel                       Link:|TagHL-DebugLevel|
+	    How much debugging information should be printed.
 
     Internal Use Only:
-	CtagsExeFull                     *TagHL-CtagsExeFull*
-    	CtagsExecutable                  *TagHL-CtagsExecutable*
-    	CtagsFileLocation                *TagHL-CtagsFileLocation*
+
+	CtagsExeFull                     Link:|TagHL-CtagsExeFull|
+	    Internal use only.
+
+    	CtagsExecutable                  Link:|TagHL-CtagsExecutable|
+	   Internal use only.
+
+    	CtagsFileLocation                Link:|TagHL-CtagsFileLocation|
+	   Internal use only.
+
+    	TypesFileLocation                Link:|TagHL-TypesFileLocation|
+	   Internal use only.
 
 2.4.3 Option Details                     *TagHighlight-option-details*      {{{3
 
 	
     DirModeSearchWildcards               *TagHL-DirModeSearchWildcards*
 	
+    DisableStandardLibraries             *TagHL-DisableStandardLibraries*
+	
     DisableTypeParsing                   *TagHL-DisableTypeParsing*
 	
     DoNotGenerateTags                    *TagHL-DoNotGenerateTags*
 	
     ForcedStandardLibraries              *TagHL-ForcedStandardLibraries*
 	
-    Hooks                                *TagHL-Hooks*
-	
     IncludeLocals                        *TagHL-IncludeLocals*
 	
     IncludeSynMatches                    *TagHL-IncludeSynMatches*
 	
     PathToPython                         *TagHL-PathToPython*
 	
+    PreReadHooks                         *TagHL-PreReadHooks*
+	
+    PostReadHooks                        *TagHL-PostReadHooks*
+	
+    PreUpdateHooks                       *TagHL-PreUpdateHooks*
+	
+    PostUpdateHooks                      *TagHL-PostUpdateHooks*
+	
     ProjectConfigFileDirModePriority     *TagHL-ProjectConfigFileDirModePriority*
 	
     ProjectConfigFileDirectory           *TagHL-ProjectConfigFileDirectory*
     TypesFileExtension                   *TagHL-TypesFileExtension*
 	
     TypesFileLocation                    *TagHL-TypesFileLocation*
+	Used internally to tell the python part of the application where the
+	types file should be stored.  Do not use this option as it will be
+	automatically overwritten.  Instead, see |TagHL-TypesFileDirectory|
+	and |TagHL-TypesFileDirModePriority|.
 	
     TypesFileNameForce                   *TagHL-TypesFileNameForce*
 	

plugin/TagHighlight/data/options.txt

 	Default:None
 	Help:Location of the python executable or None to search the path
 
+pre_read_hooks:
+	VimOptionMap:PreReadHooks
+	Type:list
+	Default:[]
+	Help:List of function names to run before reading types.
+
+post_read_hooks:
+	VimOptionMap:PostReadHooks
+	Type:list
+	Default:[]
+	Help:List of function names to run after reading types.
+
+pre_update_hooks:
+	VimOptionMap:PreUpdateHooks
+	Type:list
+	Default:[]
+	Help:List of function names to run before updating types.
+
+post_update_hooks:
+	VimOptionMap:PostUpdateHooks
+	Type:list
+	Default:[]
+	Help:List of function names to run after updating types.
+
 hooks:
 	VimOptionMap:Hooks
 	Type:dict
 	Default:[]
 	Help:List of standard libraries which we should load regardless of whether the matchers match (as long as suffix is correct).
 
+disable_standard_libraries:
+	VimOptionMap:DisableStandardLibraries
+	Type:bool
+	Default:False
+	Help:Don't try to load standard libraries.
+
 user_libraries:
 	VimOptionMap:UserLibraries
 	Type:list
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.