NAME
Open::This - Try to Do the Right Thing when opening files
VERSION
version 0.000034
DESCRIPTION
This module powers the ot command line script, which tries to do the right thing when opening a file. Imagine your $ENV{EDITOR}
is set to vim
. (This should also work for emacs
and nano
.) The following examples demonstrate how your input is translated when launching your editor.
ot Foo::Bar
# vim lib/Foo/Bar.pm
ot Foo::Bar
# vim t/lib/Foo/Bar.pm
Imagine this module has a sub do_something
at line 55.
ot
"Foo::Bar::do_something()"
# vim +55 lib/Foo/Bar.pm
Or, when copy/pasting from a stack trace. (Note that you do not need quotes in this case.)
ot Foo::Bar line 36
# vim +36 lib/Foo/Bar.pm
Copy/pasting a git-grep
result.
ot lib/Foo/Bar.pm:99
# vim +99 Foo/Bar.pm
Copy/pasting a partial GitHub URL.
ot lib/Foo/Bar.pm
#L100 # vim +100 Foo/Bar.pm
Copy/pasting a full GitHub URL.
# vim +17 lib/Open/This.pm
Open a local file on the GitHub web site in your web browser. From within a checked out copy of https://github.com/oalders/open-this
ot -b Foo::Bar
Open a local file at the correct line on the GitHub web site in your web browser. From within a checked out copy of https://github.com/oalders/open-this:
ot -b Open::This line 50
SUPPORTED EDITORS
This code has been well tested with vim
. It should also work with nvim
, emacs
, pico
, nano
and kate
. Patches for other editors are very welcome.
FUNCTIONS
parse_text
Given a scalar value or an array of scalars, this function will try to extract useful information from it. Returns a hashref on success. Returns undef on failure. file_name
is the only hash key which is guaranteed to be in the hash.
my
$parsed
= parse_text(
't/lib/Foo/Bar.pm:32'
);
# $parsed = { file_name => 't/lib/Foo/Bar.pm', line_number => 32, }
my
$with_sub_name
= parse_text(
'Foo::Bar::do_something()'
);
# $with_sub_name = {
# file_name => 't/lib/Foo/Bar.pm',
# line_number => 3,
# original_text => 't/lib/Foo/Bar.pm:32',
# sub_name => 'do_something',
# };
to_editor_args
Given a scalar value, this calls parse_text()
and returns an array of values which can be passed at the command line to an editor.
my
@args
= to_editor_args(
'Foo::Bar::do_something()'
);
# @args = ( '+3', 't/lib/Foo/Bar.pm' );
editor_args_from_parsed_text
If you have a hashref
from the parse_text
function, you can get editor args via this function. (The faster way is just to call to_editor_args
directly.)
my
@args
= editor_args_from_parsed_text( parse_text(
't/lib/Foo/Bar.pm:32'
) );
maybe_get_url_from_parsed_text
Tries to return an URL to a Git repository for a checked out file. The URL will be built using the origin
remote and the name of the current branch. A line number will be attached if it can be parsed from the text. This has only currently be tested with GitHub URLs and it assumes you're working on a branch which has already been pushed to your remote.
my
$url
= maybe_get_url_from_parsed_text( parse_text(
't/lib/Foo/Bar.pm:32'
));
# $url might be something like: https://github.com/oalders/open-this/blob/master/lib/Open/This.pm#L32
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.
VIM INTEGRATION
If you're a vim
user, you can use the following code to your .vimrc
to integrate ot
directly with your editor.
" Thanks to D. Ben Knoble
for
getting histadd() to work:
" https://vi.stackexchange.com/questions/34818/how-to-
use
-histadd-
with
-a-custom-function/34819
#34819
nnoremap <leader>ot :call OT(input(
"ot: "
,
""
,
"file"
))<cr>
" trim() requires vim 8
function! OT(fname)
let res =
system
(
"ot --editor vim --print "
. shellescape(trim(a:fname)))
if
v:shell_error
echo
"\n"
. res
else
execute
"e "
res
endif
call histadd(
':'
,
printf
(
'call OT("%s")'
, escape(a:fname, '"\')))
endfunction
With the above code, you can enter <leader>ot and then enter your ot
args directly in vim
. If the file is found, it will be opened in a buffer, hopefully at the appropriate line and column number. An up to date copy of this command should generally be available in my dotfiles repo as well: https://github.com/oalders/dot-files/blob/main/vim/vimrc.
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.