The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.

NAME

ot - parse text and (hopefully) open an editor with the correct arguments

VERSION

version 0.000034

SYNOPSIS

ot "lib/Foo/Bar.pm line 222"
# Executes $ENV{EDITOR} +222 lib/Foo/Bar.pm

ot "./lib/Foo/Bar.pm:135:20: blah;"
# If you're using vim, opens your file at line 135 and column 20.
# Otherwise, executes $ENV{EDITOR} +222 lib/Foo/Bar.pm This is handy if you
# use, for example, ripgrep:
# rg --vimgrep blah

# open Foo::Bar which is in your lib, t/lib or @INC
ot Foo::Bar

# open Foo::Bar at the do_something() subroutine
ot "Foo::Bar::do_something()"

# open Foo::Bar at the do_something() subroutine
ot "Foo::Bar::do_something('HASH(0x25521248)')"

# open output from git-grep
ot lib/Open/This.pm:17

# Find a core module
ot Test::More

# Open a core module at a function
ot "Test::More::diag()"

# Open a binary which is in your $ENV{PATH}
ot cpanm

# Open a binary which is in your $ENV{PATH} at an arbitrary column and line
ot cpanm:10:3

# open Foo::Bar on the GitHub web site in your browser
ot -b Foo::Bar

# open a file locally, using a GitHub link.  You must be at the top level
# of this repository on a local checkout.
ot https://github.com/oalders/git-helpers/blob/master/lib/Git/Helpers.pm#L50

# open a file that was mentioned in the output of diff or
# git diff or git log -p, etc:
# (this will open foo/bar if it exists)
ot a/foo/bar

# open "/foo/bar.txt" as it appears in an Ansible error message
# (Note the quotes around the arg)
ot "The error appears to be in '/foo/bar.txt': line 14, column 16, but may be"

# open "/foo/bar.java:[3,5]" as it appears in Maven's test output
ot /foo/bar.java:[3,5]

# override $ENV{EDITOR}. [-e|--editor]
ot -e kate Foo::Bar

# Don't open anything. Just print to STDOUT. [-p|--print]
ot -p -e kate Foo::Bar

# Don't open anything. Just print JSON to STDOUT. [-j|--json]
ot -j -e kate Foo::Bar

DESCRIPTION

It can be a pain to have to copy Perl module names from a stack trace or some other output and have to translate that into something which an editor like vim understands. This module aims to take some of the pain out of this and it supports many different editors. See SUPPORTED EDITORS below for a list.

The ot script can parse line numbers from text so that you can open your files at the correct starting point. It will also try to translate subroutine names into the appropriate line numbers. It will look in a lib or t/lib directory relative to your current path. If it thinks it has a Perl module name it will also try to require it and use %INC in order to find the module on disk. All security caveats apply when requiring 3rd party modules.

PARAMETERS

-b|--browse

Open the file on the GitHub web site using your default browser, rather than invoking a local editor.

ot -b Foo::Bar

-e|--editor

Can be used to override $ENV{EDITOR}. Helpful for writing editor-specific plugins.

ot -e kate Foo::Bar

ot --editor kate Foo::Bar

-j|--json

(Experimental). Print editor arguments to STDOUT as well as an indication of success or failure. This can be used for editor integration.

-p|--print

Print the editor arguments to STDOUT rather than invoking an editor. Helpful for writing editor-specific plugins.

ot -p Foo::Bar

ot --print Foo::Bar

ot -p -e kate Foo::Bar

ot --print --editor kate Foo::Bar

ENVIRONMENT VARIABLES

By default, ot will search your lib and t/lib directories for local files. You can override this via the $ENV{OPEN_THIS_LIBS} variable. It accepts a comma-separated list of libs.

export OPEN_THIS_LIBS=lib,t/lib,t/other-lib

Or

OPEN_THIS_LIBS=lib,t/lib,t/other-lib ot Foo::Bar

Probably you want to export this variable in your ~/.bashrc file (or some other appropriate place in your dot files.

SUPPORTED EDITORS

This code has been tested with vim, nvim, emacs, pico, nano, IntelliJ IDEA, Visual Studio Code, VSCodium and kate. Patches for other editors are very welcome.

AUTHOR

Olaf Alders <olaf@wundercounter.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2018 by Olaf Alders.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.