man/vis-open.1

   1 .Dd November 29, 2016
   2 .Dt VIS-OPEN 1
   3 .Os Vis VERSION
   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 .El
  78 .
  79 .Sh EXIT STATUS
  80 .Ex -std vis-open
  81 .Pp
  82 In particular,
  83 like
  84 .Xr vis-menu 1 ,
  85 .Nm vis-open
  86 prints nothing and sets its exit status to 1
  87 if the user refused to select a file.
  88 .
  89 .Sh EXAMPLES
  90 .Bd -literal -offset indent
  91 CHOICE=$(vis-open -p "Select a file to stat")
  92 if [ $? -gt 0 ]; then
  93         echo "No selection was made, or an error occurred"
  94 else
  95         stat "$CHOICE"
  96 fi
  97 .Ed
  98 .
  99 .Sh SEE ALSO
 100 .Xr vis 1 ,
 101 .Xr vis-menu 1
 102 .
 103 .Sh BUGS
 104 Because
 105 .Nm vis-open
 106 uses
 107 .Xr ls 1
 108 to obtain the contents of a directory,
 109 weird things might happen if you have control-characters in your filenames.