.. index:: syntax; location
.. _syntax_location:

Syntax for Source-Code Locations
================================

A number of commands like "break", and "list" have locations
embedded in them.

A location can be either a *linespec* an explicit function, or a *module linespec*


Linespec
--------

A linespec has a colon-separated pair of a source-location parameter
and a line number.  A source location is a file path or a module name.

In [*path*:] *linenum* , the line *linenum* in the source file *path*
is indicated. When *path* is omitted, some default value is given,
usually it is the *path* associated with the current frame. Or in
list-like commands it is the *path* what was most-recently set; the
most-recently set path starts out as the current frame's path.

If *filename* is a relative file name, then Python's `sys.path` items
(which are assumed to be a list of directories) is tried in the order
given. Often the current working directory or `.` is in that
list. Note that `.` can be set with `cd` debugger command.

To specify a path containing non-alphanumeric characters, specifically
blanks (" "), backslashes ("\"), or quotes, in there are a number of
quoting mechanisms one can use. You can enclose the path in single
quotes, double quotes or triple double as you would do in Python

Examples
++++++++

::

    10                   # line 10 of the most-recently used path
    myfile.py:2          # line 2 of myfile.py where the directory name is
                         #resolved from `sys.path`
    ./../myfile.py:3     # line 3 of the parent of some directory in `sys.path`
    /tmp/foo.py:4        # line 4 of absolute path /tmp/foo.py
    "foo's.py":1"        # One way to specify a path with a quote
    '''foo's.py"''':2    # Another way to specify a path with a quote
    'c:\foo.bat':1"      # One way to specify a Windows file name,
    '/My Docs/foo.py':1" # One way to specify path with blanks in it



function()
----------

Specifies the line that function *function* starts on. This is the
line that contains `def`. We get this information from the Python code
object, in particular the `co_firstlineno` field.

contrast to *gdb*, use parenthesis at the end of the function name
to indicate this is a function.

You can also specify functions though the values in Python program
variables or the function indicated in an instance method.

For example consider this program:

::

    class Foo():
        def food(): return
    f = Foo()
    b = [f.food]
    x = 2

If you are stopped at the last line `x = 2`. You can specify the function `food`
as either of these ways:

::

   Foo.food()
   f.food()
   b[0]()

Although in the last example `b[0]()` the expressions can get a bit
complex, to simplify parsing, we don't allow arbitrary expressions. We
currently allow only alphanumeric symbols as you'd find in valid
Python identifiers along with extra symbols ".", "[", and "]".  This
means `b[i+1]()` would be invalid because it contains "+".  So would
`b["foo"]()`, assuming `b` were a dictionary, because of the quote
symbol.

*Right now we don't allow line offsets from functions. If the need
arises we may do so in the future.*

module linespec
---------------

While functions need a closing `()` to indicate their function-ness,
Python module names don't. What we do here is first look up the name
as a file path.  If that's not found we look up the file as a Python
module name. Modules have to have been imported before it accepted in
the debugger. However you can run `eval` (or `autoeval`) to have
Python import the module inside the debugger.

In sum file names are distinguished from method names purely by
semantic means. However *gdb* and thus this debugger has no means to
explicitly tag names as a file path or Python module name. We, but not
*gdb*, make a distinction between functions versus modules and file
paths.

Examples
++++++++

::

    os.path:45  # Line 45 of the file that contains os.path
    os:1        # First line of module os
    os          # Invalid! (for now)

Note that the last line is invalid. In contrast to functions, you need
to give a line numbers. Also it is assumed there is not a *file*
called `os` in the last example line. Nor a file called `os.path` in
the first example.