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
-vfor 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.