Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "PTP/photran/documentation/photran5advanced"

(Fortran Search)
(Fortran Search)
Line 87: Line 87:
  
 
==Fortran Search==
 
==Fortran Search==
Fortran search is a syntax-aware search tool. It can find identifiers of a particular type (i.e. only modules or only subroutines). It also allows to define the scope of the search (entire Workspace or a particular project). <br>
+
Fortran search is a syntax-aware search tool. It can find identifiers of a particular type (i.e. only modules or only subroutines). It also allows to define the scope of the search (entire Workspace or a particular project) and filter the search based on whether it is a declaration or a reference to variable/function/etc <br>
 
In order to use Fortran Search, click on <b>Search</b> tab and select <b>Fortran...</b><br>
 
In order to use Fortran Search, click on <b>Search</b> tab and select <b>Fortran...</b><br>
 
In the opened window, you can specify:
 
In the opened window, you can specify:
 
* Type of the identifier that you are looking for in the <b>Search for</b> section.
 
* Type of the identifier that you are looking for in the <b>Search for</b> section.
 
* Scope of your search in the <b>Scope</b> section.
 
* Scope of your search in the <b>Scope</b> section.
* Whether you want to only find <b>Declarations, References</b> or both in the <b>Limit to</b> section.
+
* Whether you want to only find <b>Declarations, References</b> or both in the <b>Limit to</b> section<br>
  
<br>
+
Find references is an easy way to see where the variable/function is referenced. It excludes the actual definition of the token from the search. It is very useful when you are not sure what a particular function does or how a particular variable is used and would like to see some examples of its use.
* Find References
+
In contrast, Find Declaration will only find where the token in declared, so that you don't have to read over lines and lines of code trying to figure out what a particular variable/function is.
  
 
=Refactoring=
 
=Refactoring=

Revision as of 17:56, 15 July 2009

You are here: PTP > Photran > Documentation > Photran 5.0 Advanced Features

Photran 5.0 Advanced Features

IMPORTANT: For the time being, this is just an outline of the documentation we intend to write before the release of Photran 5.0 in September, 2009. It is not useful yet. Of course, you are welcome to fill in any sections you wish... this is a wiki!

Introduction

Photran 5.0 includes a number of sophisticated features that are designed to make it easier to write, modify, search, and maintain Fortran code. These include content assist, which can "auto-complete" variable and function names as you type; a declaration view, which can show the leading comments for the selected variable or procedure; Fortran Search, which allows you to find declarations and references to modules, variables, procedures, etc.; and refactorings, which change your source code to improve its design while preserving its behavior.

Enabling Advanced Features

In order to use any of the advanced features described in this document, you must specifically enable them as described below. After you do this, Photran will index your project; that is, it will build a database of what modules, subprograms, etc. are declared in every file in your project. This information will be updated incrementally every time you save a file. Although this process is reasonably fast in most cases, it may become disruptive when working on very large projects, so it has been disabled by default. Note that the first time your project is indexed, it may take a while, because Photran must analyze every file in your project; after that, it will only index files that have changed (or that depend on a file that has changed), so it will generally be much faster.

How to Enable Advanced Features

  1. Right-click on your project's folder in the Fortran Projects view
  2. Click on Properties
  3. Expand Fortran General in the list on the left, and click on Analysis/Refactoring (see screenshot below)
  4. Check the "Enable Fortran analysis/refactoring" check box
  5. If you want to enable content assist, the Fortran Declaration view, etc., check those boxes as well
  6. You may also want to set module and include paths at this point (see below)
  7. Click OK

Setting Module and Include Paths

If your source code contains INCLUDE lines or USE lines referencing modules in other files, Photran needs to know where to look in order to find these. It will not figure this out automatically. For each project in which you plan to use refactoring support,

  1. Right-click on your project's folder in the Fortran Projects view
  2. Click on Properties
  3. Expand Fortran General in the list on the left, and click on Analysis/Refactoring
  4. List the folders in which Photran should search for INCLUDE files and modules when refactoring. They will be searched in order from the first folder listed to the last. Subfolders are not searched automatically; you must include them explicitly.
  5. Click OK
Photran-refac-properties.png

The Fortran Analysis/Refactoring Problems View

TODO

Advanced Editing Features

Content Assist

TODO

Fortran Declaration View

TODO

Hover Tips

TODO

Search and Navigation

TODO

Open Declaration

TODO

Fortran Search

Fortran search is a syntax-aware search tool. It can find identifiers of a particular type (i.e. only modules or only subroutines). It also allows to define the scope of the search (entire Workspace or a particular project) and filter the search based on whether it is a declaration or a reference to variable/function/etc
In order to use Fortran Search, click on Search tab and select Fortran...
In the opened window, you can specify:

  • Type of the identifier that you are looking for in the Search for section.
  • Scope of your search in the Scope section.
  • Whether you want to only find Declarations, References or both in the Limit to section

Find references is an easy way to see where the variable/function is referenced. It excludes the actual definition of the token from the search. It is very useful when you are not sure what a particular function does or how a particular variable is used and would like to see some examples of its use. In contrast, Find Declaration will only find where the token in declared, so that you don't have to read over lines and lines of code trying to figure out what a particular variable/function is.

Refactoring

Introduction

What is Refactoring?

Refactorings are changes to a program that improve its internal design but do not change its behavior. These include minor, coding style changes (like using IMPLICIT NONE statements), code readability improvements (like replacing a variable named N with one called NUM_POINTS), performance improvements (like interchanging loops under certain conditions), and even larger-scale design changes (like moving a procedure from one module to another).

Although these types of changes can be done by hand, making them is often tedious and error-prone. Photran automates many such refactorings. For example, the Refactor > Rename command can automatically locate the declaration(s) and uses of a particular subroutine, and change its name in all of those locations. It is "smart," too; if there is a subroutine named d and a variable named d in a different context, it won't confuse the two. Moreover, before making such a change, Photran will attempt to verify that the change is safe to make. For example, a subroutine A cannot be renamed to B if there is already a variable named B in a context where that subroutine is called.

For more information on refactoring, see M. Fowler, Refactoring: Improving the Design of Existing Code, Addison-Wesley, 1999.

Refactoring in Photran

Most refactorings can be accessed via the Refactor menu in the menu bar, as described below. However, the most common refactorings also have hotkeys (e.g., Alt+Shift+R for Rename; hotkeys are listed in the Refactoring menu next to each command). Also, most refactorings can be accessed by right-clicking in an editor and choosing Refactor from the popup menu.

Some refactorings (such as Introduce Implicit None and Replace Obsolete Operators) can be applied to several files at once. As described below, this involves selecting one or more files in the Fortran Projects view, then right-clicking on any of the selected filenames and choosing Refactor from the popup menu.

  • Clicking on a filename in the Fortran Projects view selects that file (and only that file).
  • Ctrl+click (Command+click on Mac OS X) can be used to select or deselect additional files.
  • To select a range of files, click on one filename, and Shift+click on a later filename; those files and all of the files in between will be selected as well.

Caution: Photran can only refactor free-format Fortran source code. It is not possible to refactor fixed-form code. Make sure that only free-form Fortran files are selected. The Refactor menu may not be available if any of the files are fixed-form or non-Fortran files.

Rename

  • Description: Rename is essentially a "smart" search and replace: It allows you to change the name of a variable, subprogram, etc. It correctly observes scoping and shadowing rules can also rename subprograms and module entities across files.
  • Applies To:
    1. Local variables1,2
    2. Subprograms3 (including external and interface declarations)
    3. Derived types
    4. Module entities (variables and subprograms)
    5. Main programs
    6. Namelists
    7. Common blocks
    8. Block data subprograms
  • Operation:
    1. Click on the name of a local variable, subprogram, etc.
    2. Click Refactor > Rename... The Rename dialog will appear.
      Rename dialog
    3. Enter a new name for the variable/subprogram/etc.
    4. If you are renaming an external subprogram or a subprogram declared in an interface block, you may want to (un)check the box labeled Match external subprograms with interfaces and external declarations. If this is checked, the refactoring will attempt to find all external subprograms, EXTERNAL statements, and subprogram declarations in INTERFACE blocks that have the given name, and they will all be renamed.
    5. Click Preview to see what changes will be made, then click OK to apply them.
  • Example:
    Simple example of the Rename refactoring

1. Dummy subprogram arguments cannot be renamed
2. Components of derived types cannot be renamed
3. Intrinsic subprograms and type-bound procedures (Fortran 2003) cannot be renamed

Encapsulate variable

  • Description: Encapsulate variable creates getter and setter methods for the selected variable in the module where it is defined and changes variable's visibility to private. It also replaces all uses of that variable in all files to use getter and setter method calls1.
  • Applies To:
    1. Variables defined in the module.
    2. Variables of all basic as well as user-defined types
  • Does Not Apply To:
    1. Arrays
    2. Variables that are not defined in a module
    3. Parameters (i.e. integer, parameter :: CANNOT_ENCAPSULATE)
    4. Pointers (i.e. real, pointer :: CANNOT_ENCAPSULATE)
    5. Targes (i.e. integer, target :: CANNOT_ENCAPSULATE)
  • Operation:
    1. Click on or select the name of variable you want to encapsulate.
    2. Click Refactor > Encapsulate Variable. The Encapsulate Variable dialog will appear.
      Getter and setter name menu for encapsulating variable temp
    3. Enter names for getter and setter methods2.
    4. Click Preview to see what changes will be made, then click OK to apply them.
  • Example:
    Simple example of Encapsulate Variable refactoringtemp
               
    Simple example of Encapsulate Variable refactoringtemp

1. If a variable is used as a parameter to a function/subroutine call, and that function changes the value of the variable as a side-effect, that change will not be preserved.
2. As of 07/14/09 there is no conflict checking for the names of getter and setter functions. This will be introduced soon

Interchange loops

  • Description: Swaps inner and outer loops of the selected nested do-loop1. This refactoring merely switches the inner and outer do-headers. It will not make any changes to the body of the loop.
  • Applies To: Selected nested do-loop
  • Operation:
    1. Select the nested loops you wish to interchange
    2. Click Refactor > Interchange Loops. The Interchange loops dialog will appear.
    3. Click Preview to see what changes will be made, then click OK to apply them.
  • Example:
    Simple example of Interchange Loops refactoring

1. In order for refactoring to work correctly, there must be no statements before the second loop. If such statements exist, correctness of the refactoring is not guaranteed.


Introduce Implicit None

  • Description: Introduce Implicit None adds IMPLICIT NONE statements to a file and adds explicit declarations for all variables that were previously declared implicitly.
  • Applies To: All main programs, subprograms, and modules in one or more files.
  • Operation:
    1. This is a multiple-file refactoring.
      • To Introduce Implicit None in a single file, open the file in the editor and choose Refactor > Introduce Implicit None from the menu bar.
      • To Introduce Implicit None in multiple files, select the files in the Fortran Projects view, right-click on any of the selected filenames, and choose Refactor > Introduce Implicit None from the popup menu.
    2. Click Preview to see what changes will be made, then click OK to apply them.
  • Example:
    Example of the Introduce Implicit None refactoring

Move Saved Variables to Common Block

  • Description: Move Saved Variables to Common Block creates a common block for all "saved" variables of a subprogram. Declarations of these variables in the subprogram are transformed such that they are no longer "saved". The generated common block is declared both in the main PROGRAM and in the affected subprogram. Variables placed in the common block are renamed such that they do not conflict or shadow other variables. The current implementation assumes that the subprogram is in the CONTAINS section of the PROGRAM.
  • Applies To: Subprograms.
  • Operation:
    1. Click on the declaration statement of a subprogram.
    2. Click Refactor > Move Saved Variables to Common Block.
    3. Click Preview to see what changes will be made, then click OK to apply them.
  • Example:
    Example of the Introduce Implicit None refactoring

Replace Obsolete Operators

  • Description: Replace Obsolete Operators replaces all uses of old-style comparison operators (such as .LT. and .EQ.) with their newer equivalents (symbols such as < and ==). and adds explicit declarations for all variables that were previously declared implicitly.
  • Applies To: All uses of the following operators in one or more files: .LT. .LE. .EQ. .NE. .GT. .GE.
  • Operation:
    1. This is a multiple-file refactoring.
      • To Replace Obsolete Operators in a single file, open the file in the editor and choose Refactor > Replace Obsolete Operators from the menu bar.
      • To Replace Obsolete Operators in multiple files, select the files in the Fortran Projects view, right-click on any of the selected filenames, and choose Refactor > Replace Obsolete Operators from the popup menu.
    2. Click Preview to see what changes will be made, then click OK to apply them.
  • Example:
    Example of the Replace Obsolete Operators refactoring

Extract Procedure

  • Description: Extract Procedure removes a sequence of statements from a procedure, places them into a new subroutine, and replaces the original statements with a call to that subroutine. Any local variables used by those statements will be passed as parameters to the new procedure. This refactoring is generally used to make long procedures shorter.
  • Applies To: A sequence of one or more action statements inside a procedure or main program.
  • Operation:
    1. Select a sequence of one or more action statements in the editor. Be sure to include the newline following the last statement in the selection.
    2. Click Refactor > Extract Procedure... The Extract Procedure dialog will appear.
      Extract Procedure dialog
    3. Enter a name for the new procedure that will be created.
    4. Click Preview to see what changes will be made, then click OK to apply them.
  • Example:
    Simple example of the Extract Procedure refactoring

Canonicalize Keyword Capitalization

  • Description: Makes all applicable keywords the same case throughout the selected Fortran program files.
  • Applies To: All keywords except those listed below.
  • Does not apply to:
    1. Identifiers
    2. All constants except for integer constants and real constants
  • Operation:
    1. This is a multiple-file refactoring.
      • To Canonicalize Keyword Capitalization in a single file, open the file in the editor and choose Refactor > Canonicalize Keyword Capitalization from the menu bar.
      • To Introduce Implicit None in multiple files, select the files in the Fortran Projects view, right-click on any of the selected filenames, and choose Refactor > Canonicalize Keyword Capitalization from the popup menu.
    2. Select Upper or Lower Case
      Canonicalize keyword capitalization dialog.
    3. Click Preview to see what changes will be made, then click OK to apply them.
  • Example
    Example of Canonicalize Keyword Capitalization refactoring.

Make COMMON Variable Names Consistent

  • Description: Makes the variable names for the selected COMMON block consistent throughout the project.
  • Applies To: All COMMON blocks with a valid name.
  • Does not apply to: COMMON blocks with a NULL name.
  • Operation:
    1. Select the name of the COMMON block in the editor which you wish to make variable names consistent for.
    2. Choose Refactor > Make COMMON Variable Names Consistent form the menu bar.
    3. Click Preview to see what changes will be made, then click OK to apply them.
  • Example
    Example of Make COMMON variable names consistent refactoring.
    Example of Make COMMON variable names consistent refactoring.

Back to the top