dist/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         $_ = $curscr->GetLine($i++);
  12         $words+=split;
  13       }
  14       $curscr->Msg("$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 * $curscr
  32
  33 Object that represents the current screen.
  34 It can be used as the ScreenId parameter of the functions below,
  35 or you can use object oriented syntax.
  36
  37         # the following two are equivalent
  38         $curscr->DelLine(57);
  39         VI::DelLine($curscr, 57);
  40
  41 =item * $StartLine
  42
  43 Line number of the first line of the selected range or of the file if no
  44 range was specified.
  45
  46 =item * $StopLine
  47
  48 Line number of the last line of the selected range or of the file if no
  49 range was specified.
  50
  51 =back
  52
  53 =head2 Functions
  54
  55 =over 8
  56
  57 =item * AppendLine
  58
  59     VI::AppendLine(screenId,lineNumber,text);
  60
  61 Append the string text after the line in lineNumber.
  62
  63 =item * DelLine
  64
  65     VI::DelLine(screenId,lineNum);
  66
  67 Delete lineNum.
  68
  69 =item * EndScreen
  70
  71 VI::EndScreen(screenId);
  72
  73 End a screen.
  74
  75 =item * FindScreen
  76
  77     VI::FindScreen(file);
  78
  79 Return the screen id associated with file name.
  80
  81 =item * GetCursor
  82
  83     ($line, $column) = VI::GetCursor(screenId);
  84
  85 Return the current cursor position as a list with two elements.
  86
  87 =item * GetLine
  88
  89     VI::GetLine(screenId,lineNumber);
  90
  91 Return lineNumber.
  92
  93 =item * GetMark
  94
  95     ($line, $column) = VI::GetMark(screenId,mark);
  96
  97 Return the mark's cursor position as a list with two elements.
  98
  99 =item * GetOpt
 100
 101     VI::GetOpt(screenId,option);
 102
 103 Return the value of an option.
 104
 105 =item * InsertLine
 106
 107     VI::InsertLine(screenId,lineNumber,text);
 108
 109 Insert the string text before the line in lineNumber.
 110
 111 =item * LastLine
 112
 113     VI::LastLine(screenId);
 114
 115 Return the last line in the screen.
 116
 117 =item * MapKey
 118
 119     VI::MapKey(screenId,key,perlproc);
 120
 121 Associate a key with a perl procedure.
 122
 123 =item * Msg
 124
 125     VI::Msg(screenId,text);
 126
 127 Set the message line to text.
 128
 129 =item * NewScreen
 130
 131     VI::NewScreen(screenId);
 132     VI::NewScreen(screenId,file);
 133
 134 Create a new screen.  If a filename is specified then the screen is
 135 opened with that file.
 136
 137 =item * Run
 138
 139     VI::Run(screenId,cmd);
 140
 141 Run the ex command cmd.
 142
 143 =item * SetCursor
 144
 145     VI::SetCursor(screenId,line,column);
 146
 147 Set the cursor to the line and column numbers supplied.
 148
 149 =item * SetLine
 150
 151     VI::SetLine(screenId,lineNumber,text);
 152
 153 Set lineNumber to the text supplied.
 154
 155 =item * SetMark
 156
 157     VI::SetMark(screenId,mark,line,column);
 158
 159 Set the mark to the line and column numbers supplied.
 160
 161 =item * SetOpt
 162
 163     VI::SetOpt(screenId,command);
 164
 165 Set an option.
 166
 167 =item * SwitchScreen
 168
 169     VI::SwitchScreen(screenId,screenId);
 170
 171 Change the current focus to screen.
 172
 173 =item * TagQ
 174
 175     $screen->TagQ("tag identification string")
 176
 177 Creates a new tag queue object associated to $screen
 178 to which "tags" can be added.
 179 See further about methods you can use on tag queues.
 180
 181 =item * UnmapKey
 182
 183     VI::UnmmapKey(screenId,key);
 184
 185 Unmap a key.
 186
 187 =item * Warn
 188
 189 This is the default warning handler.
 190 It adds any warnings to the error string.
 191
 192 =item * Opt
 193
 194     $screen->Opt;
 195
 196 Returns a tied hash representing the options of the screen.
 197 Note that you can only retrieve and set hash elements.
 198
 199 =item * Map
 200
 201     $screen->Map;
 202
 203 Returns a tied hash representing the mappings of the screen.
 204 Note that you can only retrieve, set and delete hash elements.
 205
 206 =item * Mark
 207
 208     $screen->Mark;
 209
 210 Returns a tied hash representing the marks of the screen.
 211
 212 =item * Line
 213
 214     $screen->Line;
 215
 216 Returns a tied array representing the lines of the screen.
 217
 218 =back
 219
 220 =head2 Tag queue methods
 221
 222 =item * Add
 223
 224     $tagq->Add($filename, $searchstring, $msg)
 225
 226 Adds a tag to the tag queue.
 227 The $searchstring argument is (line)number or
 228 a string representing a regular expression.
 229
 230 =item * Push
 231
 232     $tagq->Push()
 233
 234 Pushes the tag queue onto its associated screen.
 235 The result of the operation is as if the user had enter the
 236 tag command and nvi had found the locations that were added
 237 using the Add method.
 238
 239 For an example, see the make.pl script.
 240
 241 =back
 242
 243 =head1 EXAMPLES
 244
 245     sub showmarks {
 246       my ($mark, $all);
 247       for $mark ('a' .. 'z') {
 248         eval {VI::GetMark($VI::ScreenId, $mark)};
 249         $all .= $mark unless ($@);
 250       }
 251       VI::Msg($VI::ScreenId,"Set marks: $all");
 252     }
 253
 254     sub forall {
 255       my ($code) = shift;
 256       my ($i) = $VI::StartLine-1;
 257       while (++$i <= $VI::StopLine) {
 258         $_ = VI::GetLine($VI::ScreenId, $i);
 259         VI::SetLine($VI::ScreenId, $i, $_) if(&$code);
 260       }
 261     }
 262
 263 Now you can do
 264
 265     :perl forall sub{s/perlre/substitution/}
 266
 267 Although you'll probably use
 268
 269     :perldo s/perlre/substitution/
 270
 271 instead.
 272
 273 See L<perlre> for perl regular expressions.
 274
 275 =head1 SEE ALSO
 276
 277 L<nviperl>
 278
 279 =head1 AUTHOR
 280
 281 Sven Verdoolaege <skimo@kotnet.org>