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}