Skip to content

Full Manual

Brett Estrade edited this page Nov 15, 2026 · 12 revisions

Full embedded manual

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.


Clone this wiki locally