parse_f95.rb

Path: parsers/parse_f95.rb
Last Update: Sun Mar 09 01:23:05 +0900 2008

parse_f95.rb - Fortran 90/95 Parser

Note that Japanese and English are described in parallel.

概要

parse_f95.rb は拡張子が f90, F90, f95, F95 のファイルを構文解析します. ソースコードは Fortran 90 もしくは Fortran 95 規格に沿って記述されていることを前提としています.

Overview

"parse_f95.rb" parses Fortran 90/95 files with suffixes "f90", "F90", "f95" and "F95". These files are expected to conform to Fortran 90 or Fortran 95 standards.

書法

基本的な書法はRuby の書法 と同様ですが, コメント部は ’#’ ではなく ’!’ で始まることに注意してください.

Rules

Fundamental rules are same as that of the Ruby parser. But comment markers are ’!’ not ’#’.

RDoc ドキュメンテーションと Fortran 90/95 プログラムとの対応

parse_f95.rb は Fortran 90/95 規格における言語要素, すなわち, 主プログラム, モジュール, サブルーチン, 関数の他, PUBLIC 属性を持つ変数や定数, そして利用者定義演算子, 利用者定義代入を構文解析します. これらの言語要素は RDoc ドキュメンテーションの各項目に, 以下のように記述されます.

Files :ファイル (Ruby と同様です)
Classes :モジュール, NAMELIST 変数群名リスト
Methods :主プログラム, サブルーチン, 関数, 変数, 定数, 構造データ型, 利用者定義演算子, 利用者定義代入, NAMELIST 変数群名
Required files :参照するモジュールが定義されているファイル, 及び参照する外部関数が定義されているファイルのリスト
Included Modules :参照するモジュールのリスト
Attributes :構造データ型のリスト, 参照し且つその全ての言語要素を公開する モジュールのリスト

‘Methods’ にリストされる言語要素 (サブルーチン, 関数, …) は, モジュール内で定義されているのであれば, ‘Classes’ の項目に記述されます. 主プログラム内で定義されたり, 外部手続きとして定義される場合には ‘Files’ の項目に記述されます. 主プログラム自体も ‘Files’ の項目に記述されます.

Correspondence between RDoc documentation and Fortran 90/95 programs

"parse_f95.rb" parses entities of Fortran 90/95 standards, or main programs, modules, subroutines, functions, derived types, public variables, public constants, defined operators and defined assignments. These entities are described in items of RDoc documentation, as follows.

Files :Files (same as Ruby)
Classes :Modules, list of NAMELIST group names
Methods :Main programs, subroutines, functions, variables, constants, derived types, defined operators, defined assignments, NAMELIST group names
Required files :Files in which imported modules, external subroutines and external functions are defined.
Included Modules :List of imported modules
Attributes :List of derived types, List of imported modules all of whose components are published again

Entities listed in ‘Methods’ (subroutines, functions, …) defined in modules are described in the item of ‘Classes’. On the other hand, defined in main programs or as external procedures are described in the item of ‘Files’. Main programs are described in the item of ‘Files’, too.

構文解析される言語要素

主プログラムおよび, 外部から参照が可能なサブルーチン, 関数, 変数, 定数, 構造データ型, 利用者定義演算子, 利用者定義代入, NAMELIST 変数群名がドキュメントとして出力されます. —all オプションをつけて rdoc を実行する場合には, 外部からの参照が許可されない 言語要素も含め, 全てが出力されます.

Parsed entities

Documentation on public entities (main programs, subroutines, functions, variables, constants, derived types, defined operators, defined assignments, NAMELIST group names) are generated. With "—all" option, documentation on all entities are generated (almost same as the Ruby parser).

構文解析される情報

以下の情報は, 自動的に構文解析されてコメント部として出力されます.

  • サブルーチン, 関数の引数のデータ型, 属性
  • 公開変数, 公開定数のデータ型, 属性
  • 構造データ型の要素のデータ型, 初期値, 属性
  • NAMELIST 文で宣言される変数名並びの変数のデータ型, 初期値, 属性

POINTER, TARGET, ALLOCATE, INTENT, OPTIONAL, SAVE 属性は 型宣言文とは別の行で指定することが可能ですが, それら型宣言文と別に指定される属性は構文解析されません.

INTERFACE 文によって, ある手続きに関して個別名とは別の名前を 宣言する場合, その別名も ‘Methods’ に追加します.

参照した別のモジュール内の公開言語要素 (サブルーチン, 関数, 変数など) を自身の言語要素として改めて公開する場合, その言語要素は自身の言語要素としてモジュールの ‘Methods’ リストに追加されます.

INTERFACE 文によって外部副プログラムを自身の副プログラムとして公開する 場合, その外部副プログラムもモジュールの ‘Methods’ リストに追加します.

Parsed information

The following information is automatically parsed.

  • Data types and attributes of arguments of functions and subprograms
  • Data types and attributes of public variables and public constants
  • Data types, initial values, and attributes of variables in the derived types
  • Data types, initial values, and attributes of variables declared in NAMELIST statement

Only attributes specified in type declaration statements are parsed. Attributes specified in POINTER, TARGET, ALLOCATE, INTENT, OPTIONAL, SAVE statements are not parsed.

Aliases declared by INTERFACE statements are described in the item of ‘Methods’.

Entities which are imported from other modules and published again are described in the item of ‘Methods’.

コメント部の書き方

コメント部は以下のように記述します. 原則的に行末または Fortran の文の下部にコメントを記述します. ’!’ を含まない行が現れた時点で, コメント部は終了したと見なされます. 例ではコメント行もインデントされていますが, インデントすることは 必須ではありません.

     ! (ファイルの行頭)
     !
     ! ファイルに対するコメントはここに記述します
     !
     !--
     ! "!--" と "!++" に囲まれた部分に記述されたコメントは
     ! ドキュメントに反映されません.
     !++
     !
     module hogehoge
       !
       ! モジュール (PROGRAM 文の場合は主プログラム)
       ! に対するコメントはここに記述します
       !

       private

       logical            :: a     ! 非公開変数
       real, public       :: b     ! 公開変数
       integer, parameter :: c = 0 ! 公開定数

       public :: c
       public :: MULTI_ARRAY
       public :: hoge, foo

       type MULTI_ARRAY
         !
         ! 構造データ型に対するコメントはここに記述します.
         !
         real, pointer :: var(:) =>null() ! 変数に対するコメント
         integer       :: num = 0
       end type MULTI_ARRAY

     contains

       subroutine hoge( in,   &   ! 継続行中のコメントは無視されます.
         &              out )
         !
         ! サブルーチンや関数に対するコメントはここに記述します
         !
         character(*),intent(in):: in ! 引数に対するコメント
         character(*),intent(out),allocatable,target  :: in
                                       ! 下の行に記述する
                                       ! ことも可能です.

         character(32) :: file ! NAMELIST 文の変数として構文解析されます
         integer       :: id

         namelist /varinfo_nml/ file, id
                 !
                 ! NAMELIST 文に関する情報はここに記述します. 変数に
                 ! 関する情報は, 変数定義部分を参照します.
                 !

       ....

       end subroutine hoge

       integer function foo( in )
         !
         ! この部分はコメントとして識別されます.

         ! '!' の間隔を空けると以降はコメントとして扱われません.
         ! つまりこの 2 行はコメントとして扱われません.
         !
         integer, intent(in):: inA ! コメントとして識別されます

                                   ! コメントとして識別されません.

       end function foo

       subroutine hide( in,   &
         &              out )      !:nodoc:
         !
         ! 上記のように, SUBROUTINE 文の末尾に
         ! '!:nodoc:' と記述することで, そのサブルーチン
         ! はドキュメントに反映されなくなります.
         ! この指定は, 主プログラム, モジュール, サブルーチン,
         ! 関数, 変数, 定数, 構造データ型, 利用者定義演算子,
         ! 利用者定義代入, 参照するモジュールのリスト (USE 文)
         ! に対して有効です.
         !

       ....

       end subroutine hide

     end module hogehoge

Format of comment blocks

Comment blocks should be written as follows. Comment blocks are considered to be ended when the line without ’!’ appears. The indentation is not necessary.

     ! (Top of file)
     !
     ! Comment blocks for the files.
     !
     !--
     ! The comment described in the part enclosed by
     ! "!--" and "!++" is ignored.
     !++
     !
     module hogehoge
       !
       ! Comment blocks for the modules (or the main programs).
       !

       private

       logical            :: a     ! a private variable
       real, public       :: b     ! a public variable
       integer, parameter :: c = 0 ! a public constant

       public :: c
       public :: MULTI_ARRAY
       public :: hoge, foo

       type MULTI_ARRAY
         !
         ! Comment blocks for the derived types.
         !
         real, pointer :: var(:) =>null() ! Comments block for the variables.
         integer       :: num = 0
       end type MULTI_ARRAY

     contains

       subroutine hoge( in,   &   ! Comment blocks between continuation lines are ignored.
           &            out )
         !
         ! Comment blocks for the subroutines or functions
         !
         character(*),intent(in):: in ! Comment blocks for the arguments.
         character(*),intent(out),allocatable,target  :: in
                                      ! Comment blocks can be
                                      ! written under Fortran statements.

         character(32) :: file ! This comment parsed as a variable in below NAMELIST.
         integer       :: id

         namelist /varinfo_nml/ file, id
                 !
                 ! Comment blocks for the NAMELIST statement.
                 ! Information about variables are described above.
                 !

       ....

       end subroutine hoge

       integer function foo( in )
         !
         ! This part is considered as comment block.

         ! Comment blocks under blank lines are ignored.
         !
         integer, intent(in):: inA ! This part is considered as comment block.

                                   ! This part is ignored.

       end function foo

       subroutine hide( in,   &
         &              out )      !:nodoc:
         !
         ! If '!:nodoc:' is described at end-of-line in SUBROUTINE
         ! statement as above, the subroutine is ignored.
         ! This assignment can be used to main programs, modules,
         ! subroutines, functions, variables, constants, derived types,
         ! defined operators, defined assignments,
         ! list of imported modules (USE statement).
         !

       ....

       end subroutine hide

     end module hogehoge

利用者定義演算子, 利用者定義代入のクロスリファレンス

利用者定義演算子と利用者定義代入 (operator(*), assignment(=) 等) をクロスリファレンスによってハイパーリンク化する場合には, ‘operator’ や ‘assignment’ の先頭に ‘#’ を付記して下さい. 具体的には,

     #operator(*)
     #assignment(=)

のように記述してください. 他のモジュール内の利用者定義演算子や 利用者定義代入のクロスリファレンスに関しては, 従来と同様に

     module#operator(*)
     module#assignment(=)

のように記述してください.

Cross-reference of defined operators and defined assignments

If you use cross-reference about defined operators and defined assignments (for example, operator(*), assignment(=), etc.), add ‘#’ at the head of ‘operator’ or ‘assignment’. Practically, describe as follows.

     #operator(*)
     #assignment(=)

About defined operators and defined assignments about other modules, describe as in the past.

     module#operator(*)
     module#assignment(=)

言語要素の表示順序

‘Files’ や ‘Classes’ の項目に表示される言語要素は, 基本的に ASCII コード順に並びます (A-Z, a-z の順番). INTERFACE 文の利用によって同一の ‘Files’ または ‘Classes’ に 同名の異なる手続きが存在する場合は, 引数キーワードおよび コメント部の内容によって順序が決まります.

もしも表示の順序を明示的に指定したい場合は, 言語要素の定義文の 行末に ‘!:doc-priority 100:’ のようなコメントを記述してください. 100 の部分は優先順位を表す数値です. 優先順位は以下のようになっています. (デフォルトは 50 に設定されています).

0 以下の整数 :言語要素を上部に表示します. 値が小さいものほど優先的に上部に表示されます.
1 以上 99 以下の整数 :同名の言語要素の中での優先順位です. 値が小さいものほど上部に表示されます.
100 以上の整数 :言語要素を下部に表示します. 値が大きいものほど下部に表示されます.

以下に例を示します. 例のように ‘doc-priority’ が使用されている場合の 表示順序は

  • top_display, generic_name_procedures (実体: bottom_display), generic_name_procedures (実体: top_display), bottom_display

となります. 一方で, もしも ‘doc-priority’ が使用されていない 場合には表示順序は

  • bottom_display, generic_name_procedures (実体: top_display), generic_name_procedures (実体: bottom_display), top_display

となります. 詳しい理由は下記の例の中に記述されるコメントを参照してください.

   module sample1
              :
     interface generic_name_procedures
       !
       ! この INTERFACE 文は top_display と bottom_display とを総称名称
       ! generic_name_procedures として再定義しています.
       !
       ! RDoc におまかせにする場合, この 2 つの
       ! generic_name_procedures の表示順序はまず引数キーワード
       ! によって決まります. 従って, 引数キーワードが 'c' で
       ! 始まる top_display が実体である generic_name_procedures
       ! が上に表示されます. (実体の手続名は考慮されません).
       !
       ! 下記では 'doc-priority' が指定してあるため, 数値の小さい
       ! bottom_display が実体である generic_name_procedures の方が
       ! 上に表示されるようになります.
       !
       module procedure bottom_display !:doc-priority 40:
       module procedure top_display    !:doc-priority 60:
     end interface
              :
   contains
              :
     subroutine top_display(char) !:doc-priority -10:
       !
       ! 本来は下記の bottom_display よりも下に表示されますが,
       ! 優先度を -10 に設定しているため, 上部に表示されます.
       !
     ....
     end subroutine top_display

     subroutine bottom_display(real) !:doc-priority 110:
       !
       ! 本来は上記の top_display よりも上に表示されますが,
       ! 優先度を 110 に設定しているため, 下部に表示されます.
       !
     ....
     end subroutine bottom_display
              :
   end module sample1

The sequence of displayed entities

Entities listed in ‘Files’ and ‘Classes’ are displayed in ASCII order usually (in particular, A...Z, a...z, …). Entities with the same names declared by INTERFACE statements are ordered by argument keywords or contents in comment blocks.

If you want to order entities manually, describe a comment like ‘!:doc-priority 100:’ at end-of-line in the statement of the entities. `100` represents priority. Priority level is specified as follows. (Default number is ‘50’).

Integer of 0 or less :Entities are displayed at the head of the document. Entities with more small number go upstairs.
Integer from 1 to 99 :Priority within entities with the same names. Entities with more small number go upstairs.
Integer of 100 or more :Entities are displayed at the foot of the document. Entities with more large number go downstairs.

An example is showed as follows. When ‘doc-priority’ is written as a following example, a sequence of displayed entities is

  • top_display, generic_name_procedures (an original entity: bottom_display), generic_name_procedures (an original entity: top_display), bottom_display.

On the other hand, if ‘doc-priority’ is not written, the sequence become

  • bottom_display, generic_name_procedures (an original entity: top_display), generic_name_procedures (an original entity: bottom_display), top_display.

The details are given in the following example.

   module sample1
              :
     interface generic_name_procedures
       !
       ! This INTERFACE statement redefines "top_display" and
       ! "bottom_display" as an generic name "generic_name_procedures".
       !
       ! RDoc orders two "generic_name_procedures" by argument keywords
       ! essentially. Therefore "generic_name_procedures" that
       ! the original entity is "top_display" is displayed above because
       ! an argument keyword of the procedure begins 'c'.
       ! (The name of the original entity is ignored).
       !
       ! In the following example, because 'doc-priority' is written,
       ! "generic_name_procedures" that
       ! the original entity is "bottom_display" is displayed above because
       ! the numerical value is smaller.
       !
       module procedure bottom_display !:doc-priority 40:
       module procedure top_display    !:doc-priority 60:
     end interface
              :
   contains
              :
     subroutine top_display(arg) !:doc-priority -10:
       !
       ! In a normal situation, this entity is displayed below 'bottom_display'.
       ! But because priority is -10, this entity is displayed above.
       !
     ....
     end subroutine top_display

     subroutine bottom_display(arg) !:doc-priority 110:
       !
       ! In a normal situation, this entity is displayed above 'top_display'.
       ! But because priority is 110, this entity is displayed below.
       !
     ....
     end subroutine bottom_display
              :
   end module sample1

Required files

rdoc/code_objects  

[Validate]