Clone wiki

TagHighlight / TagHighlightProjects

Projects in TagHighlight - A Specification


This page is intended to be a relatively static summary of the operation of the integration of VimMakeHlTags with TagHighlight. The initial design notes and discussion can be found on the page IntegratingMakeHLTags: issues with this page should be added to the discussion at the bottom of that design page.

Design Notes


The primary Vim interface will continue to be :UpdateTypesFile. In keeping with the current design of TagHighlight, this should generally be the only user interaction required with TagHighlight: everything else should be automatic once initial set-up is complete.

However, since there will be a (probably rarely used) method of updating the types and tags for dependencies as well the core project; this will require a new command, probably :UpdateProjAndLibs, although I might consolidate the commands a bit at some point.

An additional command (not necessarily related to this section of work) will also be added for simpler configuration. This will be called :LoadTagHLConfig and will take a file path (absolute or relative to the current working directory or script directory) of a taghl_config.txt-formatted file that should be loaded into g:TagHighlightSettings. This will simplify project configuration.

Main Option

The main option that will be added as part of this development will simply be called 'Projects'. This option will be a dictionary: the 'keys' will be the project names and the 'values' will be nested dictionaries describing the project. The most important parameter will be 'SourceDir': the path to the root directory of the project. Any other parameters will be standard TagHighlight options that will be set as buffer local variables when opening files from these projects. By default (an option for disabling will be added), any file in the source dir that is opened will automatically be considered part of the project and hence the buffer-local variables will be set. Additionally, an option named something like 'SetWorkingDir' will lcd to 'SourceDir' for the file buffer.

A simplified form will also be supported, where a string is used instead of a dictionary. In this case the string will be considered to be 'SourceDir' and no other options will be set.

For the dictionary within dictionary option, it will be necessary to expand on the data file loading functions. An option file might look like this:


At present, the parser would not cope with the double-indented sections. If it seems practical, I may add a method of including other files:

%INCLUDE ${HOSTNAME}_Projects.txt

All options

Projects: dictionary of dictionaries or strings - as described above.

SetWorkingDir: boolean - should lcd be used to set working dir for project files. Default probably True.

EnableFileList: boolean - should a file list be generated and used when making tags (i.e. should TagHighlight do the recursive file scan itself or just let ctags do it). Filename will probably be filelist.taghl. This will be useful for the cscope support. Default probably False.

EnableFileListForProjects: boolean - as above, but for files in a project. Default probably True?

ProjectFilter: list of glob patterns - files to include in project: will be useful when used in combination with UseFileListForProjects. Default will be empty list, but this will be treated as equivalent to ['*'].

Cscope Support

This is important as well, but Vim's cscope interface doesn't support buffer local configuration. Therefore, the BufEnter and BufLeave autocmds will have to be used if cscope is enabled. There will need to be an option to control this. Details to be expanded on.

Will also need to generate the cscope databases from the python worker. If possible (and compatible with python 2.x and 3.x) this will be done in a separate thread so that ctags and cscope don't have to wait for each other for what are independent tasks.

Python Script

The main expansion to the python code is the ability to generate tags from the command line. This is essentially a replacement for Alexey's BuildTags and MakeVimHlTags scripts. I need to get a better idea of what the distinction between these two is. For generation of library code tags/types etc, it may be that the best way to operate this is to assume that the :LoadTagHLConfig command is being used to configure the projects and add a command like:

python -i config.txt -p ProjectName

To generate tags for the project 'ProjectName' defined in the configuration file config.txt. Config.txt would presumably contain all TagHighlight options and would therefore allow to do whatever was required.

Centralised Tag/Type Repository

Initially, I intend to restrict the use of this to be with TagHighlight projects. In other words, if you're not using a project, TagHighlight will continue to store types/tags etc in the places it currently stores them (all configurable as per the status quo).

If a user wishes to keep all the tags/types together, TagHighlight will have an option 'ProjectTypesRepository'. By default this will be an empty string and tags/types will be stored in the project 'SourceDir' unless explicitly configured otherwise. If the repository is set to a directory, subdirectories will be created for each project. In those subdirectories, there will be a number of files:

  • tags
  • types_*.taghl
  • cscope.db
  • filelist.taghl

depending on configured options.

File List

As described above, TagHighlight will add the ability to scan projects for the files that make up these projects. One of the potential benefits to this is that the TagHighlight project list could be used to generate (on-the-fly) an equivalent of the project.vim project window. The user will then be able to hit a configured key (F12, say, although no mapping will be created automatically) and a small window will open to the left of the current Vim tab with all of the projects and all of their files listed. Folding will be done by project and the current project/file will be unfolded. Selecting a file and pressing ENTER will open that file in the current window.