    001/*
    002 * Copyright (c) 2009 The openGion Project.
    003 *
    004 * Licensed under the Apache License, Version 2.0 (the "License");
    005 * you may not use this file except in compliance with the License.
    006 * You may obtain a copy of the License at
    007 *
    008 *        http://www.apache.org/licenses/LICENSE-2.0
    009 *
    010 * Unless required by applicable law or agreed to in writing, software
    011 * distributed under the License is distributed on an "AS IS" BASIS,
    012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
    013 * either express or implied. See the License for the specific language
    014 * governing permissions and limitations under the License.
    015 */
    016package org.opengion.fukurou.taglet2;
    017
    018
    019// import jdk.javadoc.doclet.DocletEnvironment   ;
    020import jdk.javadoc.doclet.Doclet  ;
    021import jdk.javadoc.doclet.Reporter ;
    022// import javax.lang.model.element.Element      ;
    023// import javax.lang.model.element.Modifier ;
    024// import javax.lang.model.element.TypeElement;
    025// import javax.lang.model.element.ElementKind  ;
    026// import javax.lang.model.element.VariableElement;
    027import javax.lang.model.SourceVersion ;
    028// import javax.lang.model.util.ElementFilter ;
    029// import javax.lang.model.util.Elements ;
    030import javax.tools.Diagnostic.Kind ;
    031import com.sun.source.doctree.DocCommentTree ;
    032// import com.sun.source.util.DocTrees  ;
    033import com.sun.source.doctree.DocTree  ;
    034
    035import java.util.Locale ;
    036// import java.util.Set;
    037import java.util.List;
    038// import java.util.HashSet;
    039import java.util.Arrays;
    040import java.util.ArrayList;
    041
    042import java.util.Map;
    043import java.util.HashMap;
    044
    045// import java.io.IOException;
    046// import java.io.File;
    047// import java.io.PrintWriter;
    048
    049// import org.opengion.fukurou.util.FileUtil;
    050// import org.opengion.fukurou.util.StringUtil;
    051
    052/**
    053 * ソースコメントから、パラメータ情報を取り出す Doclet クラスです。
    054 * og.paramLevel タグと og.cryptography タグを切り出します。
    055 * これらは、ｼｽﾃﾑパラメータとしてGE12ﾃｰﾌﾞﾙに設定される値をクラスより抽出する
    056 * のに使用します。
    057 *
    058 * @version  7.3
    059 * @author      Kazuhiko Hasegawa
    060 * @since        JDK11.0,
    061 */
    062public abstract class AbstractDocTree implements Doclet {
    063        /** ｴﾝｺｰﾄﾞ {@value} */
    064        public static final String ENCODE = "UTF-8";
    065
    066        /** 情報の出力 */
    067        protected Reporter reporter;                                                                    // JavaDocの情報、警告、エラー情報の出力
    068
    069        /** 空DocTreeﾘｽﾄ */
    070        protected static final List<DocTree> EMPTY_LIST = List.of();    // ゼロ要素を含む変更不可能なリスト
    071
    072        /**
    073         * 指定されたロケールとエラー・レポータでこのドックレットを初期化します。
    074         *
    075         * @og.rev 7.3.0.0 (2021/01/06) 新しいJavaDoc対応
    076         *
    077         * @param locale 使用されるロケール
    078         * @param reporter 使用するレポータ
    079         */
    080        @Override
    081        public void init(final Locale locale, final Reporter reporter) {
    082                reporter.print(Kind.NOTE, getName() + " Start!: ");             // NOTE:情報 WARNING:警告 ERROR:エラー
    083                this.reporter = reporter;
    084        }
    085
    086        /**
    087         * ドックレットを識別する名前を返します。
    088         *
    089         * @return 名前
    090         */
    091        @Override
    092        public String getName() {
    093                return getClass().getSimpleName();
    094        }
    095
    096        /**
    097         * Doclet.Option を継承し、共通メソッドを実装したabstractクラス
    098         *
    099         * 単純に、メソッドのOverrideで共通化しているだけです。
    100         */
    101        protected static abstract class AbstractOption implements Option {
    102                private final List<String> someOption ;
    103
    104                /**
    105                 * コンストラクター。
    106                 *
    107                 * @param prm 引数に対応するキーの可変引数
    108                 */
    109                AbstractOption( final String... prm ) {
    110                        super();
    111                        someOption = Arrays.asList( prm );
    112                }
    113
    114                /**
    115                 * このオプションが消費する引数の数を返します。
    116                 *
    117                 * @return 消費された引数の数
    118                 */
    119                @Override
    120                public int getArgumentCount() {
    121                        return 1;
    122                }
    123
    124                /**
    125                 * オプションの説明を返します。
    126                 *
    127                 * @return 設定されている場合はdescription、そうでない場合は空のString
    128                 */
    129                @Override
    130                public String getDescription() {
    131                        return "an option with aliases";
    132                }
    133
    134                /**
    135                 * オプションの種類を返します。
    136                 *
    137                 * @return このオプションの種類
    138                 */
    139                @Override
    140                public Option.Kind getKind() {
    141                        return Option.Kind.STANDARD;
    142                }
    143
    144                /**
    145                 * オプションを識別するために使用される可能性のある名前のリストを返します。
    146                 *
    147                 * @return オプションの名前リスト
    148                 */
    149                @Override
    150                public List<String> getNames() {
    151                        return someOption;
    152                }
    153
    154                /**
    155                 * オプションのパラメータを返します。
    156                 *
    157                 * @return 設定されている場合はパラメータ、それ以外の場合は空のString
    158                 */
    159                @Override
    160                public String getParameters() {
    161                        return "file";
    162                }
    163        }
    164
    165        /**
    166         * このドックレットでサポートされているJavaプログラミング言語のバージョンを返します。
    167         *
    168         * @return 通常は最新バージョン
    169         */
    170        @Override
    171        public SourceVersion getSupportedSourceVersion() {
    172                // support the latest release
    173                return SourceVersion.latest();
    174        }
    175
    176        /* ************************************************************************************ */
    177
    178//      /**
    179//       * 指定の文字列から、開始文字と終了文字の間を切り抜いて返します。
    180//       * 開始文字か、終了文字のどちらかが存在しない場合は、ｵﾘｼﾞﾅﾙの文字列を返します。
    181//       *
    182//       * @param org   ｵﾘｼﾞﾅﾙの文字列
    183//       * @param stCh  開始文字
    184//       * @param edCh  終了文字
    185//       *
    186//       * @return 切り抜かれた文字列
    187//       */
    188//      protected String cut( final String org , final char stCh , final char edCh ) {
    189//              final int st = org.indexOf( stCh );
    190//              final int ed = st > 0 ? org.indexOf( edCh , st ) : -1;
    191//
    192//              return ed > 0 ? org.substring( st+1,ed ) : org ;
    193//      }
    194
    195//      /**
    196//       * 指定の文字列から、開始文字と終了文字の間を切り抜いて返します。
    197//       * 開始文字か、終了文字のどちらかが存在しない場合は、ｵﾘｼﾞﾅﾙの文字列を返します。
    198//       *
    199//       * @param org   ｵﾘｼﾞﾅﾙの文字列
    200//       * @param omit  先頭から削除する文字列
    201//       *
    202//       * @return 切り抜かれた文字列
    203//       */
    204//      protected String cutTag( final String org , final String omit ) {
    205//              return org.substring( 1+omit.length() ).trim();
    206//      }
    207
    208        /**
    209         * BlockTagsのキーとリストのMapを作成して返します。
    210         * キーと値を分離します。同じキーが複数存在しますので、それらは Listに入れて返します。
    211         * docTreeは、null の場合もあるので、その場合は、空のMapを返します。
    212         *
    213         * @param docTree       DocCommentTreeｵﾌﾞｼﾞｪｸﾄ
    214         *
    215         * @return BlockTagsのキーとリストのMap
    216         */
    217        protected Map<String,List<String>> blockTagsMap( final DocCommentTree docTree ) {
    218                final Map<String,List<String>> rtnMap = new HashMap<>();
    219
    220                if( docTree != null ) {
    221                        for( final DocTree dt : docTree.getBlockTags() ) {
    222                                final String tag = String.valueOf(dt).trim();
    223                                final int ad = tag.indexOf( ' ' );                      // 最初のスペースで分離
    224                                final String key = ad > 0 ? tag.substring( 1,ad ).trim() : tag ;                // 最初の文字列は、@ なので。
    225                                final String val = ad > 0 ? tag.substring( ad+1 ).trim() : "" ;
    226
    227                                rtnMap.computeIfAbsent(key, k -> new ArrayList<String>()).add( val );
    228                        }
    229                }
    230
    231                return rtnMap;
    232        }
    233
    234        /**
    235         * blockTagsMapで作成されたMapｵﾌﾞｼﾞｪｸﾄから、文字列を作成します。
    236         * キーがMapに存在しない場合は、空文字列を返します。
    237         * docTreeは、null の場合もあるので、その場合は、空のMapを返します。
    238         *
    239         * @param key           blockTagのキー
    240         * @param blcMap        blockTagsMapで作成されたMapｵﾌﾞｼﾞｪｸﾄ
    241         * @param delimiter     複数タグを連結する場合の、区切り文字
    242         *
    243         * @return 指定のタグの文字列
    244         */
    245        protected String getBlockTag( final String key,final Map<String,List<String>> blcMap,final String delimiter ) {
    246                final List<String> blkList = blcMap.get( key );
    247
    248                return blkList == null ? "" : String.join( delimiter,blkList );
    249        }
    250}