Understanding Symbols

Symbols are a term for parts of your code that have unique meaning such as: functions, constants, classes, methods and variables. If you are working with projects WebScripter is able to compile your files and collect this information. Because WebScripter knows where your symbols came from and what part of the code they are you can navigate multi-file projects and understand your systems better than with a normal editor.

Topics


Editor window with symbol mode open.

7.0 Compiling

Compiling is a process that steps through the files in your project and collects symbolic information which can be used for navigation, code completion and syntax styling. The information gathered is persistent across closing projects so once you compile you have the data next time you open the project.

Generally speaking, compiling is a short operation especially for smaller or medium projects with around 20-100 files. The first time you compile a large project with over 100 files the process will take longer and prompt you to wait but from there forward it will only affect files that have been updated.

When To Compile

Compiling only affects symbolic information so you only need to compile after creating or deleting: functions, classes, methods, constants and variables.

What are the benefits?

By taking the short time to compile your project after making the aforementioned changes you will get superior syntax styling, symbols in the auto-complete window, symbols in the editor symbol browser, and a complete overview of the projects symbols in the symbol mode pane.

Remeber that before using any symbol related features you must compile the project.

To compile a project:

  • Click the Compile button in the editor toolbar or use the Compile command (command-shift-R) in the Project menu.

7.1 Syntax Styling

Because WebScripter can compile your files it maintains persistent information on the symbols in your code that will remain in your project across closing or quitting the application. This means unlike most editors it will properly style symbols, even outside of their definition. This has the benefit of helping you remember names because if typed correct they will styled the correct color and helping identify parts of code.

7.2 Browsing Symbols: Symbol Mode

Sometimes browsing symbols is the best way to navigate a project. You may know the name of function and not remember the file it was defined in or for object-oriented programmers you could want to look at your classes and their methods without browsing the source.

The symbol browser is implemented as project mode. Read more about project modes here.

Using the browser

The browser has a toolbar above it containing 2 items.

  • Symbol Filter. Select from the list the kind of symbol you want to browse: functions, methods, classes, constants and global variables.
  • Files. The files menu contains a popup menu of all the files in the project which contain symbols. Clicking on an item will open the file.

7.3 Editor Symbol Browser

In each editor window (if the editor is from a built-in project.) there is a symbol browse pane in the lower left-hand corner showing all the symbols in the file. WebScripter's parser is smart, so symbols are displayed in hierarchical order and know the parent symbol which they were declared from.


Editor symbol pane

Symbols can be filtered by type by using the menu above the browser. When symbols are being filtered the source code which defined the symbol will be shown under it's name, very helpful for remembering function parameters and constant values.


Editor symbol pane viewing constants.

7.4 Editor Function Menu

Every editor has a function menu in it's toolbar which contains all the files functions, classes and methods.

The menu has the following features:

  • Selecting an item will jump to it's declared line in the file.
  • If you hold the cursor over the item and wait it will display a floating help window showing the source code where the item was declared.
  • If the editor's cursor is within a function, class or method declaration the name of the symbol will be shown in the menu. WebScripter's parser is smart and knows exactly where symbols are declared and end so the menu will accurately show you where you are typing in a file.


The editor function menu.

7.5 Cleaning Symbols

Sometimes the symbols in a project can come to contain erroneous items from out of date files or files no longer existing in the project which you want removed so you can start clean again.

To clean all the symbols in the project:

  • Select the Clean Symbols... command in the Project menu or in the symbol mode action menu .

7.6 Jumping To Symbol Declarations

Because WebScripter knows where symbols were declared you can navigate files by jumping to symbol declarations from occurrences of the symbol in a document. This is a fast way to jump around from file to file without digging around in the source code looking for the symbols declaration.

To jump to a symbol declaration:

  • Right-click or control-click on the symbol you want to jump to.
  • Select the first item in the list which read similar to: "Go to ... declaration in ...".
  • Note that if you hold the cursor over the item and wait it will display a floating help window showing the source code where the symbol was declared.


Jumping to a symbol.

7.7 Dropping Symbols

Symbols in either the symbol mode browser or the editor symbol browser can be dragged and dropped into an editor which will insert it's name into the files contents.

7.8 Symbols and Code Completion

Symbols compiled in the project will appear in the auto-complete window and will help you save time typing and remembering names. Read more here about auto-completion.

7.9 Adding Symbols Manually

Normally symbols are including in the project after the file has been compiled. However you can manually add symbols without including the file in the project.

To manually add symbols:

  • Select the Add Symbols... item in the symbol mode action menu .
  • Choose the file(s) that you want to compile.