Understanding getActiveDocumentContext() function from rstudioapi package

Question

I am trying to understand what the function getActiveDocumentContext() is supposed to do. When I run it in my console I obtain the following output,

> getActiveDocumentContext()
Document Context: 
- id:        '#console'
- path:      ''
- contents:  <1 rows>
Document Selection:
- [1, 1] -- [1, 1]: ''

When I read the documentation related to the function

Details

The selection field returned is a list of document selection objects. A document selection is just a pairing of a document range, and the text within that range.

Value

A list with elements:

id The document ID. path The path to the document on disk. contents The contents of the document. selection A list of selections. See Details for more information.

Which makes me deduce that the return is the pointing to the console with the path being a white space and some sort of document and text within the document.

However when I run this function in a debug mode inside a function the returns are different.

Is this due to the scope being different?

Answer 1

You can think of getActiveDocumentContext as providing information on where the user's cursor is (i.e. the pane with focus).

If the user happens to have their cursor in the R console instead of in a source editor, you'll get information about the R console instead. That's why you always see "console" when you run it at the console.

It's designed mostly to help with add-ins, which often operate on the current editing tab and/or the selection made inside it. See for example this one, which uses getActiveDocumentContext to help you write markdown: https://github.com/ThinkR-open/remedy

If you run getActiveDocumentContext while debugging, or at the R console, you're not going to get a helpful result. You might consider breaking your debugger after you've queried for the document context, so that the debugger doesn't put focus in the console and lose the context.