contrib/nvi/perl_api/VI.pod

   1 =head1 NAME
   2
   3 VI - VI module within perl embedded nvi
   4
   5 =head1 SYNOPSIS
   6
   7     sub wc {
   8       my $words;
   9       $i = $VI::StartLine;
  10       while ($i <= $VI::StopLine) {
  11         $_ = VI::GetLine($VI::ScreenId, $i++);
  12         $words+=split;
  13       }
  14       VI::Msg($VI::ScreenId,"$words words");
  15     }
  16
  17 =head1 DESCRIPTION
  18
  19 This pseudo module is available to perl programs run from within nvi and
  20 provides access to the files being edited and some internal data.
  21
  22 Beware that you should not use this module from within a C<perldo> or
  23 from within an C<END> block or a C<DESTROY> method.
  24
  25 =head2 Variables
  26
  27 These are set by nvi before starting each perl command.
  28
  29 =over 8
  30
  31 =item * $ScreenId
  32
  33 Screen id of the current screen.
  34
  35 =item * $StartLine
  36
  37 Line number of the first line of the selected range or of the file if no
  38 range was specified.
  39
  40 =item * $StopLine
  41
  42 Line number of the last line of the selected range or of the file if no
  43 range was specified.
  44
  45 =back
  46
  47 =head2 Functions
  48
  49 =over 8
  50
  51 =item * AppendLine
  52
  53     VI::AppendLine(screenId,lineNumber,text);
  54
  55 Append the string text after the line in lineNumber.
  56
  57 =item * DelLine
  58
  59     VI::DelLine(screenId,lineNum);
  60
  61 Delete lineNum.
  62
  63 =item * EndScreen
  64
  65 VI::EndScreen(screenId);
  66
  67 End a screen.
  68
  69 =item * FindScreen
  70
  71     VI::FindScreen(file);
  72
  73 Return the screen id associated with file name.
  74
  75 =item * GetCursor
  76
  77     ($line, $column) = VI::GetCursor(screenId);
  78
  79 Return the current cursor position as a list with two elements.
  80
  81 =item * GetLine
  82
  83     VI::GetLine(screenId,lineNumber);
  84
  85 Return lineNumber.
  86
  87 =item * GetMark
  88
  89     ($line, $column) = VI::GetMark(screenId,mark);
  90
  91 Return the mark's cursor position as a list with two elements.
  92
  93 =item * GetOpt
  94
  95     VI::GetOpt(screenId,option);
  96
  97 Return the value of an option.
  98
  99 =item * InsertLine
 100
 101     VI::InsertLine(screenId,lineNumber,text);
 102
 103 Insert the string text before the line in lineNumber.
 104
 105 =item * LastLine
 106
 107     VI::LastLine(screenId);
 108
 109 Return the last line in the screen.
 110
 111 =item * MapKey
 112
 113     VI::MapKey(screenId,key,perlproc);
 114
 115 Associate a key with a perl procedure.
 116
 117 =item * Msg
 118
 119     VI::Msg(screenId,text);
 120
 121 Set the message line to text.
 122
 123 =item * NewScreen
 124
 125     VI::NewScreen(screenId);
 126     VI::NewScreen(screenId,file);
 127
 128 Create a new screen.  If a filename is specified then the screen is
 129 opened with that file.
 130
 131 =item * Run
 132
 133     VI::Run(screenId,cmd);
 134
 135 Run the ex command cmd.
 136
 137 =item * SetCursor
 138
 139     VI::SetCursor(screenId,line,column);
 140
 141 Set the cursor to the line and column numbers supplied.
 142
 143 =item * SetLine
 144
 145     VI::SetLine(screenId,lineNumber,text);
 146
 147 Set lineNumber to the text supplied.
 148
 149 =item * SetMark
 150
 151     VI::SetMark(screenId,mark,line,column);
 152
 153 Set the mark to the line and column numbers supplied.
 154
 155 =item * SetOpt
 156
 157     VI::SetOpt(screenId,command);
 158
 159 Set an option.
 160
 161 =item * SwitchScreen
 162
 163     VI::SwitchScreen(screenId,screenId);
 164
 165 Change the current focus to screen.
 166
 167 =item * UnmapKey
 168
 169     VI::UnmmapKey(screenId,key);
 170
 171 Unmap a key.
 172
 173 =item * Warn
 174
 175 This is the default warning handler.
 176 It adds any warnings to the error string.
 177
 178 =back
 179
 180 =head1 EXAMPLES
 181
 182     sub showmarks {
 183       my ($mark, $all);
 184       for $mark ('a' .. 'z') {
 185         eval {VI::GetMark($VI::ScreenId, $mark)};
 186         $all .= $mark unless ($@);
 187       }
 188       VI::Msg($VI::ScreenId,"Set marks: $all");
 189     }
 190
 191     sub forall {
 192       my ($code) = shift;
 193       my ($i) = $VI::StartLine-1;
 194       while (++$i <= $VI::StopLine) {
 195         $_ = VI::GetLine($VI::ScreenId, $i);
 196         VI::SetLine($VI::ScreenId, $i, $_) if(&$code);
 197       }
 198     }
 199
 200 Now you can do
 201
 202     :perl forall sub{s/perlre/substitution/}
 203
 204 Although you'll probably use
 205
 206     :perldo s/perlre/substitution/
 207
 208 instead.
 209
 210 See L<perlre> for perl regular expressions.
 211
 212 =head1 SEE ALSO
 213
 214 L<nviperl>
 215
 216 =head1 AUTHOR
 217
 218 Sven Verdoolaege <skimo@dns.ufsia.ac.be>