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

PTP/photran/documentation/photran5advanced

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

TODO

  • Indexing
  • Problems view (cf. below)

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
  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

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

TODO

  • Fortran Search dialog
  • Find References

Refactoring

Introduction

  • What is refactoring
  • Note fixed form not supported
  • How to activate
    • Refactor menu (if in editor)
    • Editor context menu (if in editor)
    • Fortran Projects View context menu (multiple 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.
  • 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.
      TODO
    3. Click Preview to see what changes will be made, then click OK to apply them.
  • Example:
    TODO

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: TODO
  • Applies To: TODO
  • Operation:
    1. TODO
    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

Back to the top