Repository navigation
Full Manual
Brett Estrade edited this page Nov 15, 2026
·
12 revisions
Generated from pvim --manual for version 0.1.13.
NAME
pvim - Vim-style editing for restricted environments
SYNOPSIS
pvim [--no-splash] [file]
printf 'hi\n' | pvim
printf 'hi\n' | pvim -
pvim --help
pvim --manual
pvim -v
pvim --version
pvim --batch -c '%s/old/new/g' -c w file
DESCRIPTION
pvim is for those accounts where Perl is there and Vim isn't. You have a shell,
files to edit, and no install privileges. Maybe it's cheap shared web hosting. Maybe
it's a minimal Unix install without gcc, make, or a way to add OS packages. I'd
still like to have a capable editor there.
The goal is a highly capable, Perl-centric Vim replacement that you can copy into
your own account and use. One Perl file, core modules, Perl 5.10 and up. No root, no
compiler, and no CPAN dependency hunt to get the editor running. The standalone
download includes the editor and this manual.
The basics are here: normal/insert/replace modes, familiar motions, search,
substitution, undo/redo, shell commands and filters, and optional perltidy. Large
files use temporary disk storage so opening a big file doesn't require putting the
whole thing in RAM. Vim is the reference for command behavior; search and
substitution use Perl regular expressions.
This is still an early release. Visual selection, tabs, splits, dot-repeat,
Vimscript and plugin support aren't here yet. Text editing is byte oriented, and
there is no crash recovery. The goal is a useful Vim replacement for these systems;
the supported commands and present limits are spelled out below.
REQUIREMENTS
You need Perl 5.10+ with its standard library, a POSIX shell account with an
ANSI/VT100 terminal, and writable space for temporary files and your edits. A
hosting account that only runs CGI scripts, without an interactive shell, won't
provide the terminal needed for full-screen editing. Local scripts must be allowed
to run under your account's existing restrictions.
The standalone file includes pvim, not Perl itself or missing core libraries. Some
distributions split the standard library into separate OS packages. Perl::Tidy is
optional; everything else the editor needs comes with a full Perl.
Interactive tests cover Linux and macOS. Native Windows supports the editing engine
and batch commands; its console UI isn't implemented. Other Unix systems, 32-bit
builds and vintage machines still need testing. See
<https://github.com/oodler577/pvim/blob/master/docs/PORTABILITY.md> for the record.
The earliest tested Perl is 5.10.1; 5.10.0 is the compatibility target.
OPTIONS
--help, -h
Print a short usage reminder. --manual prints the full manual, even if perldoc
is missing.
--version, -v
Print the pvim and Perl versions. Both flags do the same thing here. Vim uses
"-v" for Vi mode; in pvim it's a version shortcut.
--batch
Execute -c commands in order without opening a terminal. Changes are saved only
by an explicit write command. Errors produce exit status 1; option errors
produce status 2. This mode uses the same editor engine as interactive use.
--command, -c *command*
Execute an ex command. Repeat for multiple commands. Quote shell metacharacters.
Paths passed inside ex commands are literal, including spaces; no shell
expansion or command execution is performed. Use "--" before filenames beginning
with "-".
--no-splash
Suppress the initial unnamed-buffer splash. Opening splash text is centered
horizontally and vertically, and recenters when the terminal is resized.
STANDARD INPUT
"pvim -" imports standard input into an unnamed, modified buffer, as in Vim.
Interactive "pvim" with no filename also imports redirected or piped stdin when
stdin is not a terminal. You can use "echo hi | pvim" directly; Vim asks for the
explicit "-". Use "pvim ./-" for a file named "-". With a named file, stdin is not
imported; interactive use requires terminal stdin.
printf 'hi\n' | pvim
cat source.pl | pvim -
pvim < source.pl
printf 'old\n' | pvim --batch -c 's/old/new/' -c 'w result.txt' -
Input is streamed to the disk-backed store until EOF, preserving bytes and line
endings. Empty input is also marked unsaved. ":w filename" saves it; ":q" refuses to
discard it, and ":q!" explicitly discards it. No startup splash is shown. pvim waits
for EOF before editing begins. A command that keeps writing forever needs to finish
or be terminated first. Temporary-disk and giant-line limits still apply.
Interactive keystrokes are read separately from the POSIX controlling terminal
("/dev/tty"); input text is never executed as editor commands. Terminal stdout is
required. Without a controlling terminal, startup fails before consuming the input.
Redirecting screen output into another pipeline is not supported. "--batch" imports
stdin only with explicit "-" and requires no terminal. It never writes the imported
buffer unless a write command is supplied.
NORMAL MODE
Escape returns to normal mode and cancels pending operators. Most movement and edit
commands accept a numeric count. Counts on both sides of an operator multiply.
h j k l / arrows left, down, up, right
0 ^ $ / Home End line start, first nonblank, line end
w b e word forward, backward, end (ASCII word classes)
gg G first / last line; 20G or 20gg jumps to line 20
Ctrl-F Ctrl-B page forward / backward; PageDown / PageUp also work
Ctrl-D Ctrl-U half-page forward / backward
Ctrl-L or L redraw
Ctrl-Z suspend to shell; fg resumes with a full redraw
i a I A insert before/after cursor, first nonblank/end of line
o O open line below/above and insert
R overwrite mode; Backspace moves left
rX replace character with X; 3rX replaces three
x / Delete delete character(s)
dd yy cc delete / yank / change line(s)
d c y + w e b h l 0 $ same-line characterwise operators
D C delete / change through end of line
p P put register after/before cursor or below/above line
J join next line with whitespace handling
u Ctrl-R undo / redo; one insert session is one undo unit
/pattern ?pattern forward / backward regex search, wrapping
n N repeat search in same / opposite direction
: ex prompt
ZZ write and quit
\t format Perl (backslash, then t); same as :pt
Insert accepts ASCII, Tab, newline, Backspace (including joining lines), and arrows.
Escape exits insert. Bracketed paste enters insert mode and treats pasted printable
text, tabs and newlines as data; other controls are discarded. Normal mode "g" waits
for another "g", as in Vim. "^" means first nonblank, while 0 means absolute line
start. "cw" on a word leaves trailing whitespace, as in Vim. Registers clear when
opening a new buffer.
EX COMMANDS
:w [file] write; :w! permits replacing existing/changed contents
:wq [file] write and quit; :x also writes and quits
:q / :q! quit with unsaved guard / discard changes
:e [file] open or reload; :e! discards unsaved changes
:enew / :enew! new unnamed buffer, with unsaved guard / discard
:set number show yellow line numbers; :set nonumber hides (default)
:undo / :redo undo / redo
:123 go to line 123; :$ goes to last line
:s/foo/bar/ replace first occurrence on current line
:%s/foo/bar/g replace all occurrences throughout file
:2,10s/foo/bar/gi range, global, case insensitive
:.,$s#old#new#g current line through EOF, alternate delimiter
:pt / :perltidy format buffer if Perl::Tidy is installed
:! command run a shell command and display output; no buffer edit
:.! command filter the current line; !! opens this prompt
:r !command insert command output below the current line
:0r !command insert command output at the top of the file
:2,10! command filter a line range; :.,$! command also works
:%! command filter the whole buffer
:help short controls reminder
Patterns are Perl regular expressions, not Vim regular expressions. Replacement
supports "&" for the whole match, "\1" through "\9" for captures, "\t", and escaped
delimiters/backslashes/ampersands. Replacement is never evaluated as Perl. Only "g"
and "i" flags are accepted. Multiline substitutions, confirmation, Vim expression
replacement, named registers, macros, dot-repeat, splits, tabs, and visual selection
are not implemented.
Perltidy uses the installed "Perl::Tidy" module with "-npro -l=500", ignores
project/user tidy profiles, and never invokes a shell. Formatting is undoable and
does not save. Formatting is capped at 8 MiB and 200,000 lines because Perl::Tidy
materializes the whole source. Failure leaves the buffer unchanged.
PERL FEATURES
Perl is the focus, but you can edit other text too. Search and substitution use Perl
regexes, and "\t", ":pt" and ":perltidy" can format code if Perl::Tidy is installed
for the Perl running pvim. The formatter is optional.
Syntax highlighting can wait; file text is plain for now. Yellow line numbers and
status colors are available. There is no completion, language server, buffer-aware
"perl -c", debugger or integrated test runner yet.
Batch commands use the same editing engine, so you can use it in scripts too.
External commands and filters let you use whatever tools the host already has. See
"SHELL FILTERS" before using a command that doesn't produce replacement text.
SHELL FILTERS
":! command" runs a shell command and displays output without altering the buffer.
Interactive use waits for Enter before returning to the editing screen. ":.!
command" sends the current line to the command's stdin and replaces it with stdout.
Normal-mode "!!" opens the current-line filter prompt. ":2,10! command", ":.,$!
command" and ":%! command" filter ranges or the entire file. Output can grow, shrink
or delete the selected lines. A replacement is one undo unit and never saves
automatically.
":r !command" inserts stdout below the current line; ":0r !command" inserts it at
the top. An explicit read address inserts below that line. Read commands do not send
the existing buffer as stdin. Empty read output leaves the buffer alone.
:! ls
:.! tr '[:lower:]' '[:upper:]'
:2,10! sort
:%! perl -pe 's/old/new/g'
:%! perltidy -st -npro -l=500
:r !date
This follows Vim's separation of execution, filtering and reading command output.
Command-history ":!!", filename "%"/"#" expansion inside shell commands, general
"!motion" filters, and ordinary ":r file" are not implemented yet. Only explicitly
typed shell/read/filter commands execute programs.
POSIX uses "/bin/sh -c"; native Windows batch uses COMSPEC/cmd.exe. Commands must
read stdin and write replacement text to stdout; pipelines/redirection follow the
shell's semantics. A nonzero command status, output-read error or edit failure
leaves the buffer unchanged. Up to 4096 stderr bytes become a status diagnostic.
Successful empty stdout deletes the selected lines. A filter is not a syntax-check
command: "perl -c" normally emits no replacement source and would erase its range on
success. Use ":! perl -c path/to/saved.pl" or Ctrl-Z / "fg" for checks. These check
the saved file, not unsaved buffer text.
Capture files prevent stdout/stderr pipe deadlocks and bound capture RAM. Input,
output and the replacement line index use temporary disk; the external command has
its own resource requirements. Commands are synchronous. Interactive tty state and
the main screen are restored while a filter runs, then editing resumes. Shell
commands can modify external files; undo reverses only the buffer edit.
LARGE FILES AND PERFORMANCE
Large files shouldn't need file-sized amounts of RAM. pvim streams input into
private temporary files and builds a disk index using 24 bytes per line. Opening
still means reading the input once. Allow roughly the file size plus the line index
on temporary disk, with more room for edits and saving. Set "TMPDIR" to a private,
writable location with enough space if the host's default is too small.
Undo keeps references to edited pieces instead of copying the whole buffer. RAM use
grows with edits and fragmentation, rather than the initial file size. Saving
streams the text back out. The terminal driver redraws changed rows.
There are practical limits. Editing, searching or displaying an individual line
loads that line into RAM, so a huge single line can be slow and expensive. Searches,
whole-file substitutions, formatting and saves are synchronous; they can pause
editing. A bad regex can take a long time. Temporary edit storage and undo history
aren't compacted until the buffer closes. Use a 64-bit Perl for files beyond 2 GiB.
Benchmarks live in "tools/benchmark.pl" and the portability notes; they describe
tested workloads, not a speed guarantee for every file.
FILE SAFETY AND ENCODING
The editor is byte oriented. Printable ASCII and tabs display normally; other bytes
display as "<HH>", preserving their bytes. It does not provide Unicode
character/grapheme editing. No language lexer runs during display. Long lines pan
horizontally; they do not wrap.
Untouched LF/CRLF line endings, mixed endings, and a missing final newline survive
round trips. New lines use the first observed newline style. A new unnamed/file
buffer uses LF and a final newline. Files save via a same-directory temporary file
and rename; ordinary permission bits are preserved. Symlink and hard-linked save
targets are refused. Read-only targets are refused even with "!". Ownership, ACLs,
xattrs, sparse layout and durability across power failure are not preserved or
guaranteed. No fsync, locking, swap recovery, autosave, or crash journal yet.
External-content changes are detected by SHA-256 before saving. This is a guard, not
an atomic compare-and-swap against concurrent writers. Avoid concurrent edits.
On normal exit and handled terminal errors the tty is restored. SIGKILL, power
failure and terminal loss can lose unsaved edits; this release has no recovery. All
handled interactive exits restore the main screen and emit a newline. Ctrl-Z
restores terminal settings and suspends the editor from normal, insert, replace,
command-prompt or splash mode. Resume the shell job with "fg" to restore the editing
screen and mode, retaining unsaved changes. External SIGTSTP follows the same path.
Bracketed-paste control bytes do not trigger suspension.
Line numbers are off by default. ":set number" uses a right-aligned three-column
number field in ANSI yellow, followed by one separating space. The field widens for
four or more digits without truncating numbers. The number color is terminal UI
styling, independent of the deferred syntax-highlighting feature.
Ctrl-C is a normal input byte in raw mode; use Escape then ":q" to quit. Terminal
resize is handled at the next keypress. Native Windows interactive UI is pending.
INSTALLATION
If you don't have install privileges, use the standalone file. Download "pvim" or
"pvim-standalone.pl" from <https://github.com/oodler577/pvim/releases>, save it as
"pvim", and make it executable:
chmod +x pvim
./pvim file.pl
That's the editor. There is nothing to compile or unpack at startup. It uses the
Perl interpreter on PATH and needs no make, gcc, module installation or separate
fat-packing step. The two standalone release assets have identical bytes.
To keep it in your account:
mkdir -p "$HOME/.local/bin"
cp pvim "$HOME/.local/bin/pvim"
"$HOME/.local/bin/pvim" -v
Add that directory to PATH if needed, then call "pvim file.pl" from anywhere. You
can transfer the file from another machine if the host has no download tool.
The "App-Pvim-VERSION.tar.gz" release asset is a normal Perl distribution. You can
point "cpanm" at its URL and install it under your account. That route needs the
usual Perl build tools, including make; pvim itself has no C code to compile. Choose
the standalone file if make is missing too. Consumers don't need Dist::Zilla or
Moose. "App::Pvim" supplies the CPAN namespace and version; the installed "pvim"
command contains the editor; its POD supplies "man pvim".
Use "pvim --help" for the short version and "pvim --manual" for this manual. Both
work offline. The wiki is at <https://github.com/oodler577/pvim/wiki>.
BUGS AND SUPPORT
Please try it on copies of your files first. There is no crash recovery yet. If
something breaks, report it at <https://github.com/oodler577/pvim/issues>. Include
"pvim -v", the OS and terminal, what you typed, and the smallest example that shows
the problem. Leave private file contents out of the report.
SEE ALSO
App::Pvim, Perl::Tidy, <https://github.com/oodler577/pvim>
AUTHOR
Brett Estrade <OODLER@cpan.org> and contributors.
LICENSE
Copyright 2026 Brett Estrade. Available under the same terms as Perl 5 itself: the
Artistic License 1.0 or the GNU General Public License version 1 or later.
pvim source · Downloads · Issues
Generated from source documentation for pvim 0.1.13. How these pages stay current.
pvim 0.1.13