- initialize user dot files (.cshrc, .bashrc, …)

Either initialize or just evaluate dot files for:

   - having ABIN in PATH
   - (for macs) having flat_namespace in DYLD_LIBRARY_PATH
   - (optionally) sourcing apsearch tab completion setup file
        .afni/help/all_progs.COMP (depending on shell)

   - also, detect follower files
     For example if .tcshrc sources .cshrc, then .tcshrc is a follower
     and does not need be edited (though .cshrc might need editing).

For some background, please see: -help_dot_files

This program can evaluate what might need to be done to the given files.
It can also make the needed changes.

The potential changes to evaluate or perform are:

   1. Add ABIN to the PATH in all evaluated dot/RC files.
      ABIN can be set by -dir_bin, or else it will be come from:

   2. If requested and on a mac, set DYLD_LIBRARY_PATH to include

   3. If requested, source all_progs.COMP for tab completion of
      AFNI command options.  For example, try typing:

      Where <tab> is pressed when the cursor is still attached to 'regr'.
      If tab completion is working, this should show many possible options
      that start with -regr (-regress, actually).  For a shorter example,

         afni -h<tab>


0. basic terminal examples: get help or list dot files -help -help_dotfiles_all

1. test dot files in the $HOME directory or in some/other/dir

# dot files under $HOME dir -test

# the dot files are under some/other/dir -test -dir_dot some/other/dir

# specify which shells to test (implying corresponding dot files) -test -shell_list tcsh bash

2. do a dry run, for just the path or ALL updates

# just PATH -do_updates path -dir_dot DDIR -dry_run

# all updates -do_updates ALL -dir_dot DDIR -dry_run

3. actually modify the files (e.g., just omit -dry_run)

# update for PATH -do_updates path -dir_dot DDIR

# perform all updates -do_updates ALL -dir_dot DDIR

# only consider .bashrc and .cshrc -do_updates ALL -dir_dot DDIR \
    -dflist .bashrc .cshrc

# only consider shells bash and tcsh -do_updates ALL -dir_dot DDIR \
    -shell_list bash tcsh

terminal options:

      -help                     : show this help
      -help_dotfiles_all        : display dot files known by program
      -help_dotfiles_mod        : display modifiable dot files
      -help_shells              : display shells known by program
      -hist                     : show module history
      -show_valid_opts          : list valid options
      -ver                      : show current version

other options:

      -dflist DFILE DFILE ...   : specify dot files to focus on
                                  (default from -help_dotfiles_mod)

         e.g. -dflist .cshrc .bashrc .zshrc

         Specify the list of RC/dot files to process.  Files outside this
         list will be ignored.

         Special cases:

            ALL : set list to all known dot files (see -help_dotfiles_all)
            MOD : set list to all modifiable dot files (see -help_dotfiles_mod)

      -dir_bin DIR_BIN          : specify bin directory to add to PATH
                                  (default comes from `which`)

         e.g. -dir_bin /some/other/abin

         For use with 'path' modifications, specify the bin directory that
         would be added to the PATH.

      -dir_dot DDIR             : specify directory containing dot files

         e.g.,    -dir_dot some/dot/files/are/here
         default: -dir_dot $HOME

         Specify an alternate location of dot files, besides $HOME.
         This can be for useful if being set up by an admin, or perhaps
         for testing.

      -do_updates UPD UPD ...   : specify which updates to make
                                  (default is nothing)

         e.g. -do_updates flatdir
         e.g. -do_updates path apsearch
         e.g. -do_updates ALL

         Specify one or more updates to attempt.  Valid updates include:

            apsearch    : source ~/.afni/help/all_progs.COMP
                          (or all_progs.COMP.bash or all_progs.COMP.zsh)

                        * if the dotfile is not based on the login or current
                          shell (and no -force), omit apsearch update
                          (since this only applies to an interactive shell)

            flatdir     : add /opt/X11/lib/flat_namespace to DYLD_LIBRARY_PATH

            path        : add DIR_BIN to PATH

            ALL         : do all of the above

      -dry_run                  : do not modify files, but see what would happen

         e.g. -dry_run

         With this option, the program prepares to modify files, but does not
         actually perform the modifications.  Instead, the user is informed of
         what would be done, had the option not been included.

         This is intended as a test run for a command that would otherwise
         perform the operations specified by the -do_updates parameters.

         This is similar to -test, except that it restricts operations to those
         in -do_updates, plus it shows the actual text of all intended file
         modifications.  If a user wanted to make their own changes, for
         example, they could append this modification text to each file in

            See also -test.

      -force                    : force edits, whether they seem needed or not

         e.g. -force

         When considering changes to make (operations to add to the dot files),
         if it seems to the program that the operation is already happening,
         or if it does not seem appropriate (e.g. setting DYLD_LIBRARY_PATH on
         a linux system), such a modification will be skipped.

         Use this -force option to force a change, even if it looks like such a
         change is not needed.

      -make_backup yes/no       : specify whether to make backups of originals

         e.g.,    -make_backup no
         default: -make_backup yes

         By default, this program will make a backup of any file that will be
         changed.  The backup name will be the same as a original name, plus
         the extension '.adot.bak'.  For example:
         would be backed up to

         Use this option to turn off the default behavior.

      -shell_list S1 S2 ...     : specify shells instead of using -dflist

         e.g.,    -shell_list bash tcsh
         default: -shell_list ALL

         This is an optional alternative to -dflist.  The user can specify
         a list of known shells which would imply the dot file list given by
         -dflist.  The same special cases of ALL and MOD apply.

         For example,

            -shell_list bash tcsh

         would have the same effect as:

            -dflist .bashrc .cshrc .tcshrc

         This is merely a convenience option.

            See also -dflist.

      -test                     : just test the files for potential changes

          e.g., -test

          Use this option to simply report on what changes might be needed for
          the given files.  It checks for all possibly appropriate changes,
          reporting the resulting table, and quits.

          Use -do_updates to restrict the applied tests.

            See also -dry_run, -do_updates.

      -verb LEVEL               : set the verbosity level (default 1)

          e.g., -verb 2

          Specify how verbose the program should be, from 0=quiet to 4=max.
          As is typical, the default level is 1.

R Reynolds    December 2022