Revision as of 02:34, 9 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

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

TODO

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)

General Instructions for Using Refactorings

Many refactorings are activated by first positioning the cursor on a variable, subprogram, etc. in a Fortran program. That is, you must click on (or highlight) the name of a variable, subprogram, etc. Then right-click on the selected name, choose Refactoring from the context menu, and click on the name of the appropriate refactoring. Generally speaking, you should always click on name. For example...

1 ! Print hello to the screen
2 program p
3     character(len=*) :: hello = 'hello'
4     print *, hello
5 contains
6     subroutine s
7         character(len=*) :: hello = 'This is a different hello'
8     end subroutine
9 end program

If you are trying to use the Rename refactoring and click on hello in the comment or the string literal (lines 1 and 3), the refactoring will not work, because hello is not a variable in that context; it is just a piece of text. If you click on the variable hello in lines 3 or 4, refactoring will succeed. Note, however, that the variable hello in line 7 is completely different. So if you rename the occurrence of hello on line 3 and 4, those occurrences will both change, but the hello variable on line 7 will remain the same. Similarly, you can rename hello on line 7 without changing the variable on lines 3 and 4.

Rename

• Purpose: Rename essentially acts as a "smart" search and replace, allowing the names of the following entities to be changed. It correctly observes scoping and shadowing rules and renames module entities across files.
• Applies To:
  1. Local variables^1,2
  2. Subprograms³
  3. Derived types
  4. Module entities
  5. Main programs
  6. Namelists
  7. Common blocks
  8. Block data

1. Dummy subprogram arguments cannot be renamed
2. Components of derived types cannot be renamed
3. Subprograms cannot be renamed if they are declared External or Intrinsic

Introduce Implicit None

• Purpose. Introduce Implicit None adds an implicit none statement and adds explicit declarations for all variables that were previously declared implicitly.
• Applies To:
  1. Main programs
  2. Subprograms
  3. Modules

Move Saved Variables to Common Block

TODO

Replace Obsolete Operators

TODO

Extract Procedure

TODO