vis-open.1

   1 .Dd MONTH DAY, YEAR
   2 .Os Vis VERSION
   3 .Dt VIS-OPEN 1
   4
   5 .Sh NAME
   6 .Nm vis-open
   7 .Nd Interactively select a file to open
   8
   9 .Sh SYNOPSIS
  10 .Nm vis-open
  11 .Op Fl p Ar prompt
  12 .Op Fl f
  13 .Op Ar --
  14 .Op Ar files
  15 .Pp
  16 .Nm vis-open
  17 .Fl h |
  18 .Fl -help
  19
  20 .Sh DESCRIPTION
  21 .Nm vis-open
  22 takes a list of filenames and directories on the command-line
  23 and displays them in a menu for the user to select one.
  24 If the user selects a directory
  25 (including
  26 .Li .. ) ,
  27 the directory contents are displayed as a fresh menu.
  28 Once the user has selected a filename,
  29 its absolute path is printed to standard output.
  30 .Pp
  31 .Nm vis-open
  32 uses
  33 .Xr vis-menu 1
  34 as its user-interface,
  35 so see that page for more details.
  36
  37 .Bl -tag -width flag
  38 .It Fl p Ar prompt
  39 Display
  40 .Ar prompt
  41 before the list of items.
  42 This is passed straight through to
  43 .Xr vis-menu 1 .
  44 .It Fl f
  45 Normally,
  46 if
  47 .Nm vis-open
  48 is provided with a single filename or directory argument,
  49 it will automatically select it
  50 (printing the filename to standard output,
  51 or presenting a new menu with the contents of the directory).
  52 If
  53 .Fl f
  54 is provided,
  55 .Nm vis-open
  56 will always present the arguments it's given,
  57 even if there's only one.
  58 .It Fl -
  59 If this token is encountered before the first non-option argument,
  60 all following arguments will be treated as menu-items,
  61 even if they would otherwise be valid command-line options.
  62 .Pp
  63 If encountered after the first non-option argument,
  64 or after a previous instance of
  65 .Li --
  66 it is treated as a menu-item.
  67 .It Ar files
  68 File and directory names to be presented to the user.
  69 If a name does not exist on the filesystem
  70 and the user selects it,
  71 it is treated as a file.
  72 .It Fl h | Fl -help
  73 If present,
  74 .Nm vis-open
  75 prints a usage summary and exits,
  76 ignoring any other flag and arguments.
  77 .Sh EXIT STATUS
  78 .Ex -std vis-open
  79 .Pp
  80 In particular,
  81 like
  82 .Xr vis-menu 1 ,
  83 .Nm vis-open
  84 prints nothing and sets its exit status to 1
  85 if the user refused to select a file.
  86 .Sh EXAMPLES
  87 .Bd -literal -offset indent
  88 CHOICE=$(vis-open -p "Select a file to stat")
  89 if [ $? -gt 0 ]; then
  90         echo "No selection was made, or an error occurred"
  91 else
  92         stat "$CHOICE"
  93 fi
  94 .Ed
  95 .Sh SEE ALSO
  96 .Xr vis-menu 1 ,
  97 .Xr vis 1
  98
  99 .Sh AUTHORS
 100 .An "Marc Andr\('e Tanner" Aq mat@brain-dump.org
 101
 102 .Sh BUGS
 103 Because
 104 .Nm vis-open
 105 uses
 106 .Xr ls 1
 107 to obtain the contents of a directory,
 108 weird things might happen if you have control-characters in your filenames.