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