GRASS Complete README file Started by A. Sorokine $Id: README,v 1.2 2005/02/18 22:06:13 xs7 Exp $ 1. What is GRASS Complete? GRASS Complete allows you to complete automatically correct arguments for GRASS commands when you press 'complete' key (usually ). It uses a 'complete' feature that is available in such UNIX shells as bash, zsh and probably others. For more information on how to use bash feature more effectively see wonderful Ian Macdonalds's page http://www.caliban.org/bash/index.shtml 2. Requirements - sed, grep, etc. - GRASS 5 - a shell that has cutomizable completions (bash, tcsh) - perl 5 (for compilation only) 3. Usage - type a GRASS command on the command line - press 'complete' key (usually ) - you will see available completions - type in just a single letter of an option or file name you want to select - press 'complete' key (usually ) again - you will see an updated list of the available completions 4. How it works - Init.sh calls 'complete' functions with a list of GRASS commands to complete on - after pressing of a 'complete' key, shell determines what command is on the command line and sources appropriate script from complete/ directory - the script check what parameter you cursor is on and if there is a function that can determine a list of possible completions for that parameter - if there is such a function, then a list of completions is printed below the command line 5. Files and directories README TODO BUGS Gmakefile standard distribution files args/ contains descriptions of arguments for all GRASS commands args/*.args_ descriptions of arguments generated automatically by help2args.pl args/*.args manually created descriptions of arguments args.types argument types common for all GRASS commands help2args.pl tries to build a description of arguments from the help output from a GRASS command help2args.log error log for the latest help2args.pl run Init.sh replacement for $GISBASE/etc/Init.sh that supports imitialization of completions bash/ bash-specific files bash/args2bash.pl converts argument description into bash functions bash/functions.sh common completion-related bash functions bash/Init.sh initialization script that is eventually called by grass5 start up bash/*.bash_ automatically generated bash completion function specific for a particular GRASS command bash/*.bash manually created bash completion function specific for a particular GRASS command tcsh/ tcsh-specific files tcsh/args2tcsh.pl converts argument description into tcsh completion built-in arguments tcsh/functions.sh common completion-related functions tcsh/Init.sh initialization script that is eventually called by grass5 start up tcsh/*.tcsh_ automatically generated tcsh completions specific for a particular GRASS command tcsh/*.tcsh manually created tcsh completions specific for a particular GRASS command xml/ zsh/ reserved for future use 6. Compilation and Internals - genargs.sh script runs each GRASS command with parameter 'help' and tries to convert its output in an args file using help2args.pl filter, the filter does a lot of guesswork concerning argument types, current version produces results that are about 80% correct, [not yet] rules for guessing argument types are read from args.types file - resulting argument description are saved in args/*.args_ file for each GRASS module - help2args.log records errors that are produced by help2args.pl - *.args_ files are almost human readable, to make correction to a particular command if its arguments were not guessed correctly, make a copy of an .args_ file to a file with extension .args and edit it - args2bash.pl script reads args/* files and converts them into bash scripts that actually perform completions, *.args files take precedence over *.args_ files - if you are not satisfied with the default completion for a particular module, write your own script, name it the same as the module but add extension .bash and put it into bash/ directory (scripts *.bash take precedence over *.bash_, you can use *.bash_ scripts as templates but do not edit them) See TODO file for what can be done and what had been already done.