Introduction

gasbag is a program which reads Haskell code and generates output files in ctags and etags format. When there are several occurrences of the same name, it makes a determined effort to select the best one. It is an alternative to hasktags and understands all of its options.

Description

gasbag's arguments consist of zero or more options, normally followed by one or more arguments giving the names of Haskell source files. The following is a simple example of usage: This causes gasbag to read all the *.hs files in the current directory and to produce a ctags file and an etags file, both in the current directory. The ctags file is called tags and the etags file is called TAGS.

Options

Option		Argument (if any)	Meaning
-0	--null		When reading a file to get names of input files, split the file on ASCII NUL.
-C	--output-file-ctags	file	Use file as the filename when writing a file in ctags format.
-E	--output-file-etags	file	Use file as the filename when writing a file in etags format.
-F	--on-failure	behaviour	behaviour is one of die, continue, or reuse; it specifies what to do if a Haskell source file cannot be parsed.
-a	--append		Append to an existing tags file, instead of creating a new one. (If your version of vi requires sorted tags (nvi does, for example), this option is largely useless.)
-b	--both		Create a ctags file and an etags file. (This is the default behaviour.)
-c	--ctags		Create only a ctags file.
-e	--etags		Create only an etags file.
	--help		Give a brief usage message.
-f	--files-from	file	read file to get a list of input files.
-v	--verbosity	level	Set the verbosity to level, which must be 1 or 2.

More on options

A few of the options require a bit more discussion. To begin, --on-failure is needed because it is possible to present gasbag with a valid source file which it cannot process. (But fear not: if the file makes no use of Haskell extensions, this is relatively unlikely to occur; more information below.) By default, gasbag will exit with an error message if this happens, but you can set its behaviour by giving the following option: behaviour is one of die, continue, or reuse. die specifies the default behaviour, just described; continue tells gasbag to simply ignore the file; reuse tells gasbag to look in the existing tags file and use any tags that it find there for the problem file.

reuse is useful if the problem file is only temporarily invalid (for example, it might be being edited). continue is useful if you are working on third-party code which makes use of Haskell extensions not understood by gasbag, but which nonetheless contains some files that it can process.

die, continue, or reuse can be abbreviated to di, co, and re respectively.

gasbag issues a warning if it can't parse a file, and in some other situations. You can disable this with the --verbosity option: --verbosity 1 turns off warnings, and --verbosity 2 sets the level of verbosity to be the default.

Sometimes you don't want to supply the filenames on the command line. In this case, you can use the following option.

This causes gasbag to read in a list of input files from file. If file is - (i.e. a dash character), gasbag reads from standard input.

By default, the list of input files is separated by newline characters, but if you specify --null, gasbag splits them on ASCII NUL instead.

Note that you can use --files-from even if you specify filenames on the command line; for example, the following is a valid command.

Examples

gasbag --ctags *.hs

Read all the *.hs files in the current directory. Extract tags and write them in ctags format to the file tags in the current directory. Don't write a file in etags format.

gasbag --etags --output-file-etags ~/TAGS --append *.hs

Read all the *.hs files in the current directory. Extract tags and append them, in etags format, to the file ~/TAGS. Don't write a file in ctags format.

gasbag --ctags --on-failure reuse -v1 *.hs

Read all the *.hs files in the current directory. Extract tags and write them in ctags format to the file tags in the current directory. Don't write a file in etags format. If a Haskell source file cannot be parsed, look in the file tags, and if any tags are found for the problem file, use them when writing out the new file. Issue no warnings.

find . -name "*.hs" -o -name "*.lhs" -print0 | gasbag --files-from - --null --ctags

The find command finds all *.hs and *.lhs files under the current directory and prints them to standard output, with an ASCII NUL character after each name. This list is fed to gasbag on its standard input, which reads the list of filenames, reads each specified file, and creates a tags file called tags, in ctags format, in the current directory.

Deficiencies

• gasbag uses the haskell-src package to parse Haskell source code. This means that it is unable to work with any file which cannot be parsed by haskell-src (even if the parse error is small and localised).

  haskell-src understands all of Haskell 98, with the exception of successor patterns (also known as n + k patterns).

• gasbag ignores operator symbols (as defined in section 2.4 of the Haskell 98 Report). For example, the binding of (++) in the following code (taken from the Haskell 98 Report) would be ignored:
  (++) :: [a] -> [a] -> [a] [] ++ ys = ys (x:xs) ++ ys = x : (xs ++ ys)
• A name such as foldl' won't work properly in vi: if you type Control-T while the cursor is on the initial f of foldl', vi will search the ctags file for a function called foldl (i.e. it will ignore the trailing prime). (Of course, this is really a deficiency in vi, not in gasbag. In vim you can use the iskeyword option to correct this problem.)

Miscellaneous

gasbag has a web page.

Contact details for its author are here.