Symbols and Language Parsing. Source Dynamics Source Insight 4.0
विज्ञापन
विज्ञापन
Symbols and Language Parsing
Symbols and Language Parsing
One of Source Insight’s most important strengths is its static analysis of source code while you edit. Its language parsers determine where symbols are defined in your project, and where they are used. It displays source code with syntax formatting based on that analysis.
Languages
Source Insight uses a language abstraction to encapsulate the properties of various programming languages.
For a given file buffer, the file's name determines its file type. The file type determines its language parser.
The Options > File Type Options dialog box is used to associate a file type with a file extension and a language. For example, the Java Source File file type uses the
*.java
file filter to associate Java files with that
To see a list of the currently supported languages, use the Options > Preferences: Languages dialog box.
Languages in Source Insight are divided into two categories: Built-In, and Custom.
Built-In Languages
Source Insight contains built-in optimized support for several languages, including C/C++, C#, Java, Objective-C, Python, Perl, ASP, Visual Basic, and others.
Most built-in languages support extra features, like finding references and generating call-trees.
Custom Languages
You can also add your own custom language support to Source Insight using the Options > Preferences: Lan-
guages
dialog box. A custom language is a simple generic language that specifies syntax rules, syntax format-
ting keywords, and simple parsing expressions. See “Language Options” on page 235.
Custom languages can also be exported and imported.
To Add a Custom Language
Adding support for a new language is basically a two-step process:
1.
2.
Add the language, using Options > Preferences: Languages. See “Language Options” on page 235.
Note:
The File Types dialog still allows you to add a custom parsing pattern directly into the file type properties, in lieu of adding a new language. However, you have more control by adding a new custom language and using your file type to point to the new language.
The Language Options topic in the Command Reference contains more details on custom language proper-
ties. See “Language Options” on page 235.
52 Source Insight 4 User Guide
Symbols and Language Parsing
Symbol Naming
In Source Insight, symbol names are stored as a "dotted path." The dotted path contains the symbol's container name, followed by a dot (.) and the symbol's name. For example, a member of a class may look like:
MyClass.member
All symbols that have their declarations nested inside of another symbol will have a dotted path. If you look through the symbols listed in the Project Window, you will see the dotted paths. Even in languages like C++, where the scope resolution operator
::
is used to declare members, the symbol name is stored internally as a dotted path.
When typing the full name of a symbol, you should use the dot in the symbol name if you want to also specify its container.
Note:
It is possible for a symbol to have an embedded dot (.) character in its name. Source Insight will store the symbol name so that the embedded dot is not confused with the dotted path dot character.
Resolving Symbol Definitions
When Source Insight displays source code, it formats identifiers based on their declaration. For example, is it a function, or a class, or a struct? Is it a local variable? Is it a class member? And so on. Source Insight uses its symbol lookup engine to resolve an identifier’s declaration.
When Source Insight looks up a symbol definition, it searches in a particular order to find it.
1.
It searches all open files and the symbol database for the current project (if a project is open).
2.
3.
4.
5.
It searches the project’s import library list. See “Importing Symbols from Libraries” on page 53.
It searches the global import library list.
It searches every project in the project symbol path.
Finally, the Base project is searched.
Common Projects
Consider the case when you have a set of header files from a library that you often use with multiple projects.
You could add these files to each of your projects, but that would be redundant. A better solution is to create a single common project for each set of common header files, and let Source Insight search the common project from any open project.
Common projects enables you to create smaller, self-contained projects, but still have the ability to locate
Source Insight looks to find symbols; it is implicitly at the end of the project symbol path.
Common projects are used in two ways:
•
You can add the common project as an import library project. There global and project-specific import
library lists. See “Importing Symbols from Libraries” on page 53.
•
You can put the common project onto the project symbol path. There is only one project symbol path
that is used regardless of what the current project is. See “The Project Symbol Path” on page 54.
Source Insight will search the import library projects, and the project symbol path whenever it looks up a symbol and can't find it in your current project, or in an open file.
Importing Symbols from Libraries
You can import symbols from external sources, such as INCLUDE path header files, Java packages, and .NET assemblies. Source Insight creates a special import library project for imported symbols. You can use the
Project > Import Library Symbols
dialog to maintain the list of import library projects. See “Import External
Source Insight 4 User Guide 53
Symbols and Language Parsing
An import library is a special Source Insight project, whose symbols come from an external sources. Symbols can be imported from the following types of files:
•
All the source files on the INCLUDE path
•
.NET .dll files
•
A whole directory tree of .NET .dll files
•
Java .jar files
•
Java .class files
•
A whole directory tree of Java .class files
•
A whole directory tree of source files (such as *.h files)
•
Another Source Insight project
When you import symbols from one of these sources, a new special Source Insight project is created to hold the symbols, and Source Insight opens and searches these import projects automatically.
Note:
Import projects have an "_import_" prefix in their name. You can open an import project by selecting
Project >
Open Project
and enabling "Show import projects". The project list will contains all your projects, plus the import projects.
There is both a global import library list, and a project-specific import library list. Therefore, import libraries are more flexible than using the project symbol path.
The Global Import Library List
Source Insight maintains a single global import-library list that is used for all projects, or in the case where you don't have a project open. The import list is searched when a symbol needs to be found. To manage this list, select Project > Import External Symbols.
The Project-Specific Import Library List
Each project also contains an import-library list, which is only used when that project is the current project.
The import list is searched when a symbol needs to be found. To manage the project-specific list, select Proj-
ect > Import External Symbols for Current Project
, or select Project > Project Settings, and click the "Import
Symbols" button.
Only Definitions are Found via the Import Lists
The import libraries are only used to locate symbol definitions. They are not used to locate symbol references, or used by Search Files, or Smart Rename. Those operations only work on the files in the current project.
The Project Symbol Path
The project symbol path is a delimited list of common projects that Source Insight will search when looking up a symbol definition. It gets searched after all the open files, the current project, and the import library projects.
There is only one project symbol path that is searched regardless of what the current project is.
Every project in the project symbol path is searched. If the symbol is still not found, then the Base project is searched. If more than one symbol is found with the specified name, then Source Insight will ask you to pick from a list of the matching symbols, their locations, and types.
You can enable the Always search symbol path option in the Preferences: Symbol Lookups dialog box. When this option is on, all projects in the symbol path are searched every time Source Insight looks up a symbol, even if the symbol was already found in an open file or the current project. You may want to turn this option
54 Source Insight 4 User Guide
Symbols and Language Parsing
on if you want to see if there are redundant (or at least like-named) symbols in your project and any others on the project symbol path.
The project symbol path is only used to locate symbol definitions. It is not used to locate symbol references, or used by Search Files, or Smart Rename. Those operations only work on the files in the current project.
C/C++ Symbols
When editing C/C++ files, Source Insight can perform symbol completion for the standard libraries, such as the C-runtime, STL, WinAPI, or any other library such as Boost. This is accomplished by importing symbols from the C/C++ files and header files on your machine.
To import the C/C++ runtime symbols, use the Project > Import External Symbols command, or use the Pref-
erences: Symbol Lookups
dialog box and click the Import Symbols button.
To import C/C++ runtime symbols:
1.
In the Options > Preferences: Symbol Lookups dialog box, click the Import Symbols button.
2.
In the Import External Symbols dialog box, click on the Add... button. If you already have an
INCLUDE path environment variable, then click on Import from an INCLUDE path. Otherwise, you can click on
Import from a source code tree
and navigate to the directory that contains the runtime library include files.
3.
The directories will be scanned and symbol declarations will be extracted into a special project called an import library. This may take a few minutes depending on the number of file encountered.
Now, auto-complete should work for the symbols that are defined in the header files.
C# and .NET Framework Symbols
When editing C# files, Source Insight can perform symbol completion for the .NET Framework class library symbols. This is accomplished by importing symbols from the .NET Framework assemblies on your machine.
To import the .NET Framework assemblies, use the Project > Import External Symbols command, or use the
Preferences: Symbol Lookups
dialog box and click the Import Symbols button.
To import .NET Framework symbols:
1.
In the Options > Preferences: Symbol Lookups dialog box, click the Import Symbols button.
2.
In the Import External Symbols dialog box, click on the Add... button. Click next on Import a direc-
tory tree of .NET assemblies.
Navigate to the directory that contains the .NET Framework assemblies. This is typically in a location like C:\Windows\Microsoft.NET\Framework\v2.0.50727. Select the directory and click OK.
3.
The directory tree containing .NET dlls will be scanned and symbol declarations will be extracted into a special project called an import library. This may take a few minutes since there are many
.NET Framework assemblies.
Now, auto-complete should work for the packages that have been imported into the C# source file using the
using
statement.
Java Symbols
When editing Java files, Source Insight can perform symbol completion for the standard Java runtime libraries. This is accomplished by importing symbols from the Java jar files on your machine.
To import the Java runtime symbols, use the Project > Import External Symbols command, or use the Prefer-
ences: Symbol Lookups
dialog box and click the Import Symbols button.
Source Insight 4 User Guide 55
Symbols and Language Parsing
To import Java runtime symbols:
1.
In the Options > Preferences: Symbol Lookups dialog box, click the Import Symbols button.
2.
3.
In the Import External Symbols dialog box, click on the Add... button. Click next on
Import a Java jar file.
Navigate to the jar file that contains the runtime library. This is typically in a location like C:\Program Files (x86)\Java\jre6\lib\rt.jar. Select the jar file and click Open.
The jar file will be scanned and symbol declarations will be extracted into a special project called an import library. This may take a few minutes since the jar file is large.
Now, auto-complete should work for the packages that have been imported into the Java source file using the import statement.
HTML and Scripts
The HTML File Type, which uses the HTML Language parser, parses HTML elements along with client-side scripts elements. Client-side scripting blocks will appear using the syntax formatting appropriate for whatever scripting language is used. Symbols defined in the scripts are also displayed in the symbol window, and are saved in the symbol database.
Source Insight uses the script language specified in the
SCRIPT
element. You can specify the default scripting language to use in HTML in the Options > Preferences: Languages dialog box. Click on the Special button and select the default language where it says "Default script language".
PHP Pages
The PHP File Type, which uses the PHP Page language parser, supports PHP with embedded HTML, plus client-side script. PHP scripting blocks will appear using the syntax formatting for PHP, and the appropriate formatting for client-side script elements. PHP symbols are also displayed in the symbol window, and are saved in the symbol database. The Relation Window will show references and call trees for PHP symbols.
Source Insight supports the PHP script start tokens:
<?
and
<?=
and
<?php
. The PHP end script token is
?>
.
The deprecated
<%
and
%>
tokens are not supported. Source Insight parses both the script and the HTML.
To populate the symbol information, Source Insight parses multiple streams from the same file: one for the server side PHP and one for the client side HTML. In addition, the client side may contain HTML script elements. Given the way PHP pages are typically written, the HTML elements from a PHP page file usually are parsed and recognized by Source Insight. However, it is not guaranteed to work, since PHP fragments can emit conflicting HTML tags, or they can be out of order.
You may notice in Options > Preferences: Languages, that there is a separate PHP Language which is not bound to a file type. This is responsible for parsing pure PHP code, and does not understand interleaved
HTML at all. A separate language type: The PHP Page parser brokers the HTML and PHP server-side pieces to either the HTML or PHP Language.
Active Server Page Scripts
The Active Server Page (ASP) File Type, which uses the Active Server Page language parser, supports HTML with embedded server-side scripts, plus client-side script elements. Script blocks will appear using the syntax formatting appropriate for whatever scripting language is used. Symbols defined in the scripts are also displayed in the symbol window, and are saved in the symbol database.
You can specify the default scripting language to use in HTML or ASP in the Options > Preferences: Languages dialog box. Click on the Special button and select the default language where it says "Default script language".
Source Insight supports embedded ASP script using the start token
<%
and the end token
%>
. Source Insight parses both the script and the HTML. Source Insight supports script sections embedded anywhere within the
HTML, just as the web server does.
56 Source Insight 4 User Guide
Symbols and Language Parsing
To populate the symbol information, Source Insight parses multiple streams from the same file: one for the server side ASP script, and one for the client side HTML. In addition, the client side may contain script elements. The Active Server Page parser brokers HTML and server-side script to different languages, depending on the language specified in the ASP file.
Source Insight 4 User Guide 57
डाउनलोड
विज्ञापन