class Ruby::SourceRange

An object representing the source-code range for a Ruby callable.

Source ranges are returned by Proc#source_range, Method#source_range, and UnboundMethod#source_range. They include the source path, absolute path when available, start line, start byte column, end line, and end byte column.

The primary purpose of this class is to implement Prism.find precisely and cleanly on all Ruby implementations, in a way which does not depend on implementation details like node_id. For that we need the start/end line/column and the absolute_path, which is exactly what this class provides.

The user of Prism.find can then tweak the result as desired to, for example, include heredocs as mentioned in Ruby::SourceRange#end_line. Or for Proc#source_range to include the method to which the block is passed.

Note that the returned source range is not always an evaluable fragment by itself, notably because heredocs can go beyond the end of the method and for blocks because the range starts at ‘{`/do.

Public Instance Methods

absolute_path → String or nil

Source

static VALUE
source_range_absolute_path(VALUE self)
{
    return source_range_data_get(self)->absolute_path;
}

Returns the absolute source path for the callable associated with this source range, or nil if the source has no absolute path, such as eval’d code.

end_column → Integer

Source

static VALUE
source_range_end_column(VALUE self)
{
    return INT2NUM(source_range_data_get(self)->end_column);
}

Returns the 0-indexed byte column where this source range ends.

Note that this does not include a potential heredoc that spans beyond the callable’s end, for example:

proc { <<~HEREDOC }.source_range.end_column # => 19
  heredoc
  contents
HEREDOC

To get the location of the final HEREDOC you can use +Prism.find(Proc|Method|UnboundMethod)+ and then compute the maximum end_line and end_column.

end_line → Integer

Source

static VALUE
source_range_end_line(VALUE self)
{
    return INT2NUM(source_range_data_get(self)->end_line);
}

Returns the 1-indexed line number where this source range ends.

Note that this does not include a potential heredoc that spans beyond the callable’s end, for example:

proc { <<~HEREDOC }.source_range.end_line # => 1
  heredoc
  contents
HEREDOC

To get the location of the final HEREDOC you can use +Prism.find(Proc|Method|UnboundMethod)+ and then compute the maximum end_line and end_column.

inspect → String

Source

static VALUE
source_range_inspect(VALUE self)
{
    struct source_range_data *data = source_range_data_get(self);
    VALUE str = rb_str_new_cstr("#<Ruby::SourceRange ");
    VALUE path = NIL_P(data->absolute_path) ? data->path : data->absolute_path;

    VM_ASSERT(!NIL_P(path));
    rb_str_append(str, path);

    rb_str_catf(str, ":(%d,%d)-(%d,%d)>",
                data->start_line, data->start_column,
                data->end_line, data->end_column);

    return str;
}

Returns a human-readable string with the absolute_path if available, otherwise the path, and the start and end coordinates.

path → String

Source

static VALUE
source_range_path(VALUE self)
{
    return source_range_data_get(self)->path;
}

Returns the source path for the callable associated with this source range. This is the same path returned as the first element of #source_location.

start_column → Integer

Source

static VALUE
source_range_start_column(VALUE self)
{
    return INT2NUM(source_range_data_get(self)->start_column);
}

Returns the 0-indexed byte column where this source range starts.

-> {}.source_range.start_column     # => 0 # the '->'
l = -> {}.source_range.start_column # => 4 # the '->'
proc {}.source_range.start_column   # => 5 # the '{'
method(def m = 42).source_range.start_column # => 7 # the 'def'

start_line → Integer

Source

static VALUE
source_range_start_line(VALUE self)
{
    return INT2NUM(source_range_data_get(self)->start_line);
}

Returns the 1-indexed line number where this source range starts.