10. Deriving the Current Context

This chapter deals with how to derive the current context, and also how a language maintainer can get the current context API to work with their language.

By default, the behavior will function in C like languages. This means languages with parenthetical blocks, and type dereferencing which uses a similar form.

10.1 Blocks and Navigation

Source code is typically built up of control structures, and blocks of context, or lexical scope. Semantic terms these lexical scopes as a "context". The following functions can be used to navigate contexts. Some of them are override functions. Language authors can override a subset of them to make them work for their language.

Function: semantic-up-context &optional point

Move point up one context from POINT. Return non-nil if there are no more context levels. Overloaded functions using up-context take no parameters.

Function: semantic-beginning-of-context &optional point

Move POINT to the beginning of the current context. Return non-nil if there is no upper context. The default behavior uses semantic-up-context. It can be overridden with beginning-of-context.

Function: semantic-end-of-context &optional point

Move POINT to the end of the current context. Return non-nil if there is no upper context. Be default, this uses semantic-up-context, and assumes parenthetical block delimiters. This can be overridden with end-of-context.

These next set of functions can be used to navigate across commands.

Function: semantic-end-of-command

Move to the end of the current command. Be default, uses semantic-command-separation-character. Override with end-of-command.

Function: semantic-beginning-of-command

Move to the beginning of the current command. Be default, users semantic-command-separation-character. Override with beginning-of-command.

10.2 Deriving local variables

Within a given context, or block of code, local variables are often defined. These functions can be used to retrieve lists of locally scoped variables.

Function: semantic-get-local-variables &optional point

Get the local variables based on POINT's context. Local variables are returned in Semantic token format. By default, this calculates the current bounds using context blocks navigation, then uses the parser with bovine-inner-scope to parse tokens at the beginning of the context. This can be overridden with get-local-variables.

Function: semantic-get-local-arguments &optional point

Get arguments (variables) from the current context at POINT. Parameters are available if the point is in a function or method. This function returns a list of tokens. If the local token returns just a list of strings, then this function will convert them to tokens. Part of this behavior can be overridden with get-local-arguments.

Function: semantic-get-all-local-variables &optional point

Get all local variables for this context, and parent contexts. Local variables are returned in Semantic token format. Be default, this gets local variables, and local arguments. This can be overridden with get-all-local-variables. Optional argument POINT is the location to start getting the variables from.

10.3 Deriving the Current Context

While a context has already been used to describe blocks of code, other context include more local details, such as the symbol the cursor is on, or the fact we are assigning into some other variable.

These context deriving functions can be overridden to provide language specific behavior. By default, it assumes a C like language.

Function: semantic-ctxt-current-symbol &optional point

Return the current symbol the cursor is on at POINT in a list. This will include a list of type/field names when applicable. This can be overridden using ctxt-current-symbol.

Function: semantic-ctxt-current-assignment &optional point

Return the current assignment near the cursor at POINT. Return a list as per semantic-ctxt-current-symbol. Return nil if there is nothing relevant. Override with ctxt-current-assignment.

Function: semantic-ctxt-current-function &optional point

Return the current symbol the cursor is on at POINT. The function returned is the one accepting the arguments that the cursor is currently in. This can be overridden with `ctxt.current-function'.

Function: semantic-ctxt-current-argument &optional point

Return the current symbol the cursor is on at POINT. Override with ctxt-current-argument.

10.4 Analysis of the current context

The context parsing API is used in a context analysis library. This library provides high level routines for scanning through token databases to create lists of token associates. At it's core is a set of EIEIO classes defining a context. The context contains information about what was parsed at a given position, such as the strings there, and they type of assignment. The analysis library then searches the databases to determine the types and names available.

Two high level functions which can be run interactively are:

*NOTE TO SELF: Add more here*

Command: semantic-analyze-current-context position

Analyze the current context at POSITION. If called interactively, display interesting information about POSITION in a separate buffer. Returns an object based on symbol semantic-analyze-context.

Command: semantic-analyze-possible-completions point

Return a list of semantic tokens which are possible completions. Analysis is done at POINT.