vis

a vi-like editor based on Plan 9's structural regular expressions
vis-open.1

(2289B)
      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 .
     19 .Sh DESCRIPTION
     20 .Nm vis-open
     21 takes a list of filenames and directories on the command-line
     22 and displays them in a menu for the user to select one.
     23 If the user selects a directory
     24 (including
     25 .Li .. ) ,
     26 the directory contents are displayed as a fresh menu.
     27 Once the user has selected a filename,
     28 its absolute path is printed to standard output.
     29 .Pp
     30 .Nm vis-open
     31 uses
     32 .Xr vis-menu 1
     33 as its user-interface,
     34 so see that page for more details.
     35 .
     36 .Bl -tag -width flag
     37 .It Fl p Ar prompt
     38 Display
     39 .Ar prompt
     40 before the list of items.
     41 This is passed straight through to
     42 .Xr vis-menu 1 .
     43 .It Fl f
     44 Normally,
     45 if
     46 .Nm vis-open
     47 is provided with a single filename or directory argument,
     48 it will automatically select it
     49 (printing the filename to standard output,
     50 or presenting a new menu with the contents of the directory).
     51 If
     52 .Fl f
     53 is provided,
     54 .Nm vis-open
     55 will always present the arguments it's given,
     56 even if there's only one.
     57 .It Fl -
     58 If this token is encountered before the first non-option argument,
     59 all following arguments will be treated as menu-items,
     60 even if they would otherwise be valid command-line options.
     61 .Pp
     62 If encountered after the first non-option argument,
     63 or after a previous instance of
     64 .Li --
     65 it is treated as a menu-item.
     66 .It Ar files
     67 File and directory names to be presented to the user.
     68 If a name does not exist on the filesystem
     69 and the user selects it,
     70 it is treated as a file.
     71 .It Fl h
     72 If present,
     73 .Nm vis-open
     74 prints a usage summary and exits,
     75 ignoring any other flag and arguments.
     76 .El
     77 .
     78 .Sh EXIT STATUS
     79 .Ex -std vis-open
     80 .Pp
     81 In particular,
     82 like
     83 .Xr vis-menu 1 ,
     84 .Nm vis-open
     85 prints nothing and sets its exit status to 1
     86 if the user refused to select a file.
     87 .
     88 .Sh EXAMPLES
     89 .Bd -literal -offset indent
     90 CHOICE=$(vis-open -p "Select a file to stat")
     91 if [ $? -gt 0 ]; then
     92 	echo "No selection was made, or an error occurred"
     93 else
     94 	stat "$CHOICE"
     95 fi
     96 .Ed
     97 .
     98 .Sh SEE ALSO
     99 .Xr vis 1 ,
    100 .Xr vis-menu 1
    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.