Spotlight on TdwsSymbolDictionary

A useful, yet not very prominent class of DWScript is TdwsSymbolDictionary. It provides a reference of  all symbols mentioned in your script, where they are declared, where they are used, etc. It is optionally filled up when you compile a script with the coSymbolDictionary compile option, and can be accessed from a compiler program object or interface.

It can be used for multiple purposes, centered around IDE features and auditing. Here are a few usage scenarios.

In-place symbol help and navigation

The most basic use of TdwsSymbolDictionary is probably to figure out which symbol is under the cursor or the mouse in your code editor. You can then use the symbol to provide relevant contextual help (either from your help file, or auto-generated from the script, such as a list of parameters for a function, of fields for a class, etc.) or look up the dictionary once more, and provide information about where it’s declared, implemented, used or forwarded. That positional information can also be used to offer navigation shortcuts between declaration and implementation, or to any of the symbol’s occurrences in the source.

Auto-completion

The TSymbolDictionary can be used it to figure out what is currently being typed, by identifying the symbol at the cursor, or the last recognized symbol in the code being entered. From that point on, you can generate a list of contextual variables, methods, fields, etc. that can be used to fill up an auto-completion drop down.

Code Refactoring

Once you have a symbol pinpointed, either by name or through one of its occurrences in the source, you have access to all the places it’s occurring in the code. A trivial use of such a list is for a rename refactoring: as the list of symbol positions is already sorted by source file, line and column, you merely have to walk the list backwards and replace occurrences in your sources files.

You can also team up TdwsSymbolDictionary with  other information sources to implement more complex refactorings. For instance alongside TdwsSourceContextMap (which is also provided in a compiled program), you can implement “extract method” (or its variants, “pull up” & “push down”).

Code Auditing

The symbol dictionary can be a convenient starting place for symbol-related audits and diagnostics. All audits that relate to the amount of times a symbol is used (or not) being the most trivial.

Another straightforward usage is when you have naming conventions for fields, variables, classes etc. and/or to enforce case consistency. The later can be handled in your IDE in a similar fashion as a rename refactoring, except you only replace in suReference and suImplementation symbol positions, and it is harmless enough you can do it in a background task without requiring user interaction.

You can also use it to diagnose code issues, for instance such patterns:

someObject.someProperty[stuff].otherProperty.function.method(1);
someObject.someProperty[stuff].otherProperty.function.method(2);
someObject.someProperty[stuff].otherProperty.function.method(3);

can be heuristically detected (either as “too many member symbols on the same line” or “member symbol repeated too much in nearby lines”), and the attention brought to the hot-spots so the code can be simplified and cleaned up.

2 thoughts on “Spotlight on TdwsSymbolDictionary

  1. What about symbol name overloading?

    If the same symbol name is declared twice, for example in the interface of two units, with two diverse implementations, how could it be used in an IDE, to allow navigating up to the declaration part of a symbol?

    Is there some extend analysis in the symbol lookup, so that we may know which will be the compiled symbol in one particular unit?

  2. The symbol dictionary’s symbols are TSymbol subclasses, ie. they provide the same degree of information the compiler has. Symbols that have different “meaning” for the compiler are present multiple times in the dictionary (once per meaning).

    If you have a symbol used in many source files, and want to rename it even in files not involved in the current script, you can proceed in three steps:
    - on the current script find the symbol declaration with the dictionary (or forward, or prototype, depending on what you consider to be the “reference” for that symbol), that’ll yeld you a source name and position
    - for all scripts/projects using the above source, compile them with the dictionary, use the source name/position to get the TSymbol for that project, and then get the occurences for all source files where you haven’t already got the occurences
    - for all the files with occurences, perform the rename

Comments are closed.