DevExpress CodeRush Tips&Tricks

Inside Visual Studio IDE, the source code text has its coordinates: the line number and the column:

These coordinates are 1-based, and the first line has an index equal to 1. These values can be seen in the right bottom corner of the IDE:

• “Ln” is the line number
• “Col” is the column number (offset position)
• “Ch” is the character position (for example, a single ‘Tab’ character can take several columns)

After DXCore automatically parses a source file, the abstract source tree is built for the entire file. Language elements have the same coordinates that correspond to the text coordinates inside of the source file. The coordinates of the language element are accessible through its properties, e.g.:

• StartLine - the starting line of a language element
• StartOffset – the starting offset (column) of a language element
• EndLine – the end line of a language element
• EndOffset – the end offset (column) of a language element

For example, this line of CSharp code:

using System;

Has the following coordinates in Visual Studio:

and

The language element can be located on several lines, e.g. a Class element most likely will have different starting and ending lines. These four numbers are encapsulated into a single property of the LanguageElement called Range, which has a type of the SourceRange structure. The SourceRange may consist of four coordinates: starting line, starting offset, ending line, ending offset, or may consist of two others of the SourcePoint type, which represent the starting point (1,1) and the end point (1,14). So, the SourcePoint contains a single pair of a line/offset values:

SourceRange(int startLine, int startOffset, int endLine, int endOffset)

is the equivalent of:

SourceRange(new SourcePoint (startLine, startOffset), new SourcePoint(endLine, endOffset))

The range and the stating/ending point properties are useful to manipulate the text of the source file. You can replace the piece of code using the SourceRange value of the element, or insert some new code before or after an element using the Start or End SourcePoint values available thought the Range property:

SourceRange elementRange = LanguageElement.Range;
SourcePoint elementStartPoint = LanguageElement.Range.Start;
SourcePoint elementEndPoint = LanguageElement.Range.End;

For example, let’s use these properties to remove, and then insert some text:

TextDocument activeTextDocument = CodeRush.Documents.ActiveTextDocument;
if (activeTextDocument != null)
{
  activeTextDocument.DeleteText(elementRange);
  activeTextDocument.InsertText(elementStartPoint, "/* LanguageElement was here. */");
}

Now, let’s observe useful APIs dealing with the source ranges and source point properties. On the LanguageElement instance there are the following properties and methods:

The three similar methods: GetFullBlockRange, GetFullBlockCutRange and GetFullBlockCoordinates can take a parameter of type BlockElements, which specify what elements should be included into the resulting range. The BlockElement is a flagged enumeration, containing these elements:

[Flags]
public enum BlockElements
{
  All,
  AllLeadingWhiteSpaces,
  AllSupportElements,
  AllTrailingWhiteSpaces,
  AllWhiteSpaces,
  Attributes,
  LeadingEmptyLines,
  LeadingWhiteSpace,
  None,
  Region,
  SupportComments,
  TrailingEmptyLines,
  TrailingWhiteSpace,
  WithoutUnsuitableRegions,
  XmlDocComments
}

Here’s a brief overview of this enumeration:

Here are a few sample results of the above APIs for the following code:

class Program
{
  // private fields...

  #region Main
  /// <summary>
  /// The entry point.
  /// </summary>
  /// <param name="args">Arguments.</param>
  [ThreadStatic]
  static void Main(string[] args)
  {
    Args = args;
    if (args != null)
      ArgsLength = args.Length;
  }
  #endregion

  // public properties...
  public static int ArgsLength { get; set; }
  public static string[] Args { get; set; }
}

These are the results for the Main function:

• Range:

• NameRange:

• GetCutRange():

• GetFullBlockRange():

• GetFullBlockRange(BlockElements.Attributes | BlockElements.XmlDocComments):

• GetFullBlockCutRange():

Your feedback is much appreciated. Let me know if I can improve this article for better understanding of the source code coordinates.

Similar Posts:

• DXCore Services – Code Modification
• Clipboard Tools – Smart Cut and Smart Copy
• DXCore Expression Lab tool window for observing the parsed source code trees
• DXCore Services – Text Classification
• DXCore Services – Refactoring