概要（Otsu-library) (OtsuLibrary)

パッケージ
パッケージ	説明
otsu.hiGadget	XML読み込みなど開発補助機構.
otsu.hiNote	汎用的に使用されるクラス群.
otsu.hiNote.command	コマンドエンジン.
otsu.hiSwing	swing（JAVA-GUIパッケージ）のサポートクラス群.
otsu.symphonie	構文定義に従って構文を解析し、構文要素を順次、または構文木をまとめて取得するライブラリ、コマンド.

OtsuライブラリAPI仕様

このドキュメントはOtsuライブラリのAPI仕様書です.

Otsuライブラリは次の５個のパッケージで構成されます。

パッケージ	jar	説明
ostu.hiNote	hiNote,symphonie	基本のライブラリで広い用途で用いるものです
ostu.hiGadget	hiNote,symphonie	統計処理やXML処理など用途が少し限定されるものをまとめました
otsu.hiSwing	hiSwing	SWING-UI補助ライブラリ
otsu.symphonie	symphonie	構文解析ライブラリ
ostu.hiNote.command	hiNote,symphonie	hiNoteが持つコマンド群のエンジン部です。

核となるクラス

ostu.hiNoteには広範囲に使える核となるクラスが用意されています。

hiU

hiUクラスには配列やクラス内容を表示する
hiU.str(XX);
関数の呼び出し階層を表示する
hiU.i(XX);// 入口で表示
hiU.m(XX);// 中間で表示
hiU.o(XX);// 出口で表示
が用意されています。

hiU.str()の表示機能は強力で、配列やMap,Listの表示の他階層化したクラスデータをインデント付きで表示することや、色々な表示方法の選択ができます。
JSON形式での表示も可能となっています。、

str()でオプションを付けて表示した例を載せます。

import java.util.*;
public class Sample {
   public String firstName;
   public String lastName;
   public int    age;
   public static class Address {
      public String streetAddress;
      public String city;
      public String state;
      public int    postalCode;
      };
   public Address address;
   public static class PhoneNumber{
      public String type;
      public String number;
      };
   public LinkedHashSet phoneNumbers;
   };
のデータを hiU.INDENT , hiU.WITH_TYPE 
オプションを付けてhiU.str()で文字列化しました。
//hiU.str(data,hiU.WITH_INDENT)
{
   firstName="John",
   lastName="Smith",
   age=25,
   address={
      streetAddress="21 2nd Street",
      city="New York",
      state="NY",
      postalCode=10021},
   phoneNumbers=[
      {
         type="home",
         number="212 555-1234212 555-1234"},
      {
         type="fax",
         number="646 555-4567646 555-4567"}]}

//hiU.str(data,hiU.WITH_INDENT|hiU.WITH_TYPE))
(Sample){
   firstName=(String)"John",
   lastName=(String)"Smith",
   age=(int)25,
   address=(Sample$Address){
      streetAddress=(String)"21 2nd Street",
      city=(String)"New York",
      state=(String)"NY",
      postalCode=(int)10021},
   phoneNumbers=(LinkedHashSet)[
      (Sample$PhoneNumber){
         type=(String)"home",
         number=(String)"212 555-1234212 555-1234"},
      (Sample$PhoneNumber){
         type=(String)"fax",
         number=(String)"646 555-4567646 555-4567"}]}

----------------

実際のプログラムでデバッグ用にとったトレースの一部を載せます。
１行が長いので前方を省略しています。

ChunxAuthクラスのreadProject(),switchSection(),doDrawAudioWave()などの関数入り口に
hiU.i()を入れてあります。
hiU.i()の入っていない階層java.awt.event.InvocationEvent.dispatchも表示されているのが
分かります。
(省略)  |  - > java.awt.event.InvocationEvent.dispatch
(省略)  |  |  - > ChunxAuth$1.run
(省略)  |  |  !  - > ChunxAuth.start (from ChunxAuth$1.run#3658)
(省略)  |  |  !  |  - > ChunxAuth.readSavedStatus (from start#3731)
(省略)  |  |  !  |  |  --> ChunxAuth.readProject#202 (from readSavedStatus#187)
(省略)  |  |  !  |  |  |  - > ChunxAuth$ProjectInfo.read (from ChunxAuth.readProject#215)
(省略)  |  |  !  |  |  |  |  - > ChunxAuth.renewSectionList (from ChunxAuth$ProjectInfo.read#1028)
(省略)  |  |  !  |  |  |  |  !  --> ChunxAuth.switchSection#1468 (from renewSectionList#1439) 0
(省略)  |  |  !  |  |  |  --> ChunxAuth.switchSection#1468 (from readProject#217) 0
(省略)  |  |  !  |  |  |  |  - > ChunxAuth.readAudioFile (from switchSection#1480)
(省略)  |  |  !  |  |  |  |  !  --> ChunxAuth.readAudioFile#3111 (from #3090) Murder Onhe Orient Express I..wav
(省略)  |  |  !  |  |  |  |  !  |  - > ChunxAuth.drawAudioWave (from readAudioFile#3186)
(省略)  |  |  !  |  |  |  |  !  |  |  --> ChunxAuth.doDrawAudioWave#3223 (from drawAudioWave#3217)
(省略)  |  |  !  |  |  |  |  - > ChunxAuth.renewSentenceList (from switchSection#1481)
(省略)  |  |  !  |  |  |  |  !  --> ChunxAuth.doRenewSentenceList#2444 (from renewSentenceList#2440)
(省略)  |  |  !  |  |  |  |  --> ChunxAuth.switchChunk#2534 (from switchSection#1482) 0

hiText

日本語空白も考慮したtrim()や空要素も考慮したsplit()、コメントや引用符も考慮したtokens()などの機能を持ちます。

文字列を指定長に短縮するshorten()なども用意されています。

hiFile

簡便なファイルオープンメソッドを用意しました。

hiFile.openTextFileR	テキストファイルを読み込み用にオープンする	BufferedReader
hiFile.openTextFileW	テキストファイルを書き出し用にオープンする	PrintWriter
hiFile.openBinaryFileR	バイナリファイルを読み込み用にオープンする	BufferedInputStream
hiFile.openBinaryFileW	バイナリファイルを書き出し用にオープンする	BufferedOutputStream

他にもObjectファイルのオープン、リソース上のファイルのオープンなども用意してあります。

テキストファイルに関してはオープンしてStringに全体を読み込むメソッド
text=hiFile.readTextAll(ファイル名)
なども用意されています。

hiSyncQue<T>

put(),get()とclear()のシンプルなAPIを持つ同期QUEUEです。

get()で待ち状態の時にclear()でget()をnullで起こすことができます。

hiJSON

利用者定義のクラスデータをJSONの形でエンコード/デコードできます。

辞書、配列、文字列といった汎用型での取り扱いメソッドも用意されています。

例えば次のデータ構造があり

// Sample.java
import java.util.*;
public class Sample {
   public String firstName;
   public String lastName;
   public int    age;
   public static class Address {
      public String streetAddress;
      public String city;
      public String state;
      public int    postalCode;
      };
   public Address address;
   public static class PhoneNumber{
      public String type;
      public String number;
      };
   public LinkedHashSet phoneNumbers;
   };

これに対する次のJSONデータ表現がファイル"Sample_data.json"上にあるとき

{
    "firstName":"John",
    "lastName":"Smith",
    "age":25,
    "address":{
        "streetAddress":"21 2nd Street",
        "city":"New York",
        "state":"NY",
        "postalCode":10021
    },
    "phoneNumbers":[
        {
            "type":"home",
            "number":"212 555-1234212 555-1234"
        },
        {
            "type":"fax",
            "number":"646 555-4567646 555-4567" 
        }
    ]
}

// http://www.oracle.com/technetwork/jp/articles/java/ja-topics/json-1973242-ja.htmlより

次の様にして解析しデータを取得することができます。

// Test01.java
import otsu.hiNote.*;
public class Test01{
   public static void main(String[] args_){
      try{
         String _json_text= hiFile.readTextAll("Sample_data.json");
         Sample _sample   = hiJSON.parseText(_json_text)
                                  .as(Sample.class);
         System.out.println("Sample_data="+hiU.str(_sample,hiU.WITH_INDENT));
         }
      catch(Exception _ex){
         _ex.printStackTrace(System.err);
         System.exit(1);
         }
      System.exit(0);
      }
   }

次の結果が得られます。

Sample_data={
   firstName="John",
   lastName="Smith",
   age=25,
   address={
      streetAddress="21 2nd Street",
      city="New York",
      state="NY",
      postalCode=10021},
   phoneNumbers=[
      {
         type="home",
         number="212 555-1234212 555-1234"},
      {
         type="fax",
         number="646 555-4567646 555-4567"}]}

拡張されたJSON構文を受け付け、コメントなども置けるようになっているため、システム設定記述などとしても使うことが出来ます。

利用者定義のジェネリック型や派生型、多型にも対応しています。

hiTime

時間関連の単純な手続きをまとめました。

現在時刻を文字列で得る。現在時刻をlongで得る。longを時刻表示にする。ラップタイムを得る。毎日指定時刻にタスクを実行するなどの機能を持ちます。

COMMAND

hiNote.jarには幾つかのコマンドが仕込まれています。

・java -jar hiNote.jar ur		:　UDP受信機
・java -jar hiNote.jar conv	-with pattern -in input	:　文字列変換

convはhiRegexの構造化正規表現パターンに従って文字列変換を行います。
実際に使用しているパターンを載せます。

javadoc記述内には直接'<'や'@'などの文字を置くことはできません。
これらをいちいち'<'や{@ @'などと書くのは現実的ではありません。

otsuライブラリは次のパターンを用い/**から*/の間で置き換えを行っています。
(REFとtableはエスケープとは別の追加変換です)

// ソースコード上のjavadoc部の特殊文字をエスケープする
${HTML_TAGS}=a|b|br|code|caption|center|div|input|ol|li|p|pre|span|table|ul|tr|td|blockquote|i
${JDOC_TAGS}=param|see|return|link|throws|exception|literal
param = {
   in=/\*\*[\s\S]*?\*/
   param={
      out=<!--[\s\S]*?-->
      param=[
        { // REFo{ref [text..]}
           regex=REFo\{(\w+)\s*(.*?)\}
           replace=<a class=A1 href="#o${1}">${2|1}</a>
           }
        { // REF{ref,text}
           regex=REF\{(?<ref>\S+?)\s+(?<text>.*?)\}
           replace=<a class=A1 href="../../otsu/hiNote/${ref}"><code>${text}</code></a>
           }
        { // <table>に<caption>&emsp;</caption>を付加する
           regex=<table[^>]*>(?!\s*<caption)
           replace=${0}<caption>&emsp;</caption>
           }
        {  // javadocの特殊パラメタ以外の@
           regex=@(?!(${JDOC_TAGS}))
           replace={@literal @}
           }
        { // &を&amp;に置き換える
           regex=&(?!([a-zA-Z]{2,6};))
           replace=&amp;
           }
        { // '<' と '>'の処理
           out=@param\s.*
           param={
              out={
                 regex=</?(${HTML_TAGS})(?=\W)[^>\n]*>
                 ignore_case
                 }
              param=[
                 {
                    regex=<
                    replace=&lt;
                    }
                 {
                    regex=>
                    replace=&gt;
                    }
                 ]
              }
           }
        ]
     }
  }

-----

otsuライブラリはver02からver03に変わって、機能を受け持つクラスが整理されました。
下のパターンはver02用のソースをver03用に変換するものです。完璧ではありませんがソースコード上の多くの部分を変換できます。

// otsuライブラリver02->ver03の基本変換
${HIU}  =(?<!\w)hiU\.
${FILE} =open|\w*Path|delete|canOpen|skipUTF
${TEXT} =trim|replace|tokens|divide|join|detab|just|length|fill|shorten^
|dbgStr|\w*Part|lastName|isAlphaNumeric|substring
${TIME} =sleep|currentMilliSec|dispTime|timeDiff|lapTime|currentTime
${TRACE}=print|setLogFile|setTraceFile|.*Printer|setTrace|setThreadTraceFormat
${HEX}  =halfByte|byteStr|encodeHex|getHexBytes|str2bytes
${BYTE} =getBinBytes|newBytes|bitOn|BitOff|bytes
param = [
   // ${HIU}にグループ{0}があるので追加グループは{1}からになる
   {  // hiU.openTextFileRなど⇒hiFile.openTextFileR
      regex  =${HIU}(${FILE})
      replace=hiFile.${1}
      }
   {
      regex  =${HIU}readLines\((.+),(.+)\);
      replace=hiFile.readTextAll(${1},${2});
      }
   {  // hiU.replaceAllなど⇒hiText.replaceAll
      regex  =${HIU}(${TEXT})
      replace=hiText.${1}
      }
   {  // hiU.trimLastなど⇒hiText.trimLast
      regex  =${HIU}(${TIME})
      replace=hiTime.${1}
      }
   {  // hiU.halfByteCharなど⇒hiHex.halfByteChar
      regex  =${HIU}(${HEX})
      replace=hiHex.${1}
      }
   {  // hiU.printなど⇒hiU.Trace.print
      regex  =${HIU}(${TRACE})
      replace=hiU.Trace.${1}
      }
   {  // hiU.args⇒hiArgs.args
      regex  =${HIU}args\(
      replace=hiArgs.args(
      }
   {  // hiU.hex⇒hiHex.str
      regex  =${HIU}hex\(
      replace=hiHex.str(
      }
   // 単純クラス名変換
   {
      regex  = hiUDPSocket
      replace= hiSocket.UDP
      }
   {
      regex  = hiBinarySocket
      replace= hiSocket.TCP
      }
   {
      regex  = hiTextSocket
      replace= hiSocket.TCP.ForText
      }
   // 個別変換
   {  // hiTextEdit.parseJson(a)⇒hiJSON.parseText(a).asObject()
      regex  =hiTextEdit.parseJson\((.+)\)
      replace=hiJSON.parseText(${1}).asObject()
      }
   ]

バージョン２⇒バージョン３

バージョン３は主にクラスの整理を行いました。

hiUの変更
`hiHex`へ移動
hiU.halfByteChar	⇒	hiHex.halfByteChar
hiU.halfByteCharSmall	⇒	hiHex.halfByteCharSmall
hiU.byteStr	⇒	hiHex.byteStr
hiU.byteStrSmall	⇒	hiHex.byteStrSmall
hiU.hex	⇒	hiHex.str
hiU.encodeHex	⇒	hiHex.encodeHex
hiU.parseHex	⇒	hiHex.parseHex
hiU.getHexBytes	⇒	hiHex.toBytes
hiU.str2bytes	⇒	hiHex.str2bytes
`hiBytes`へ移動
hiU.getBinBytes	⇒	hiBytes.getBinBytes
hiU.newBytes	⇒	hiBytes.newBytes
hiU.bitOff	⇒	hiBytes.bitOff
hiU.bitOn	⇒	hiBytes.bitOn
hiU.ints	⇒	hiBytes.ints
hiU.bytes	⇒	hiBytes.bytes
`hiText`へ移動
hiU.trim	⇒	hiText.trim
hiU.trimTop	⇒	hiText.trimTop
hiU.trimLast	⇒	hiText.trimLast
hiU.tokens	⇒	hiText.tokens
hiU.divide	⇒	hiText.divide
hiU.join	⇒	hiText.join
hiU.detab	⇒	hiText.detab
hiU.justSize	⇒	hiText.justSize
hiU.length2	⇒	hiText.length2
hiU.justSize2	⇒	hiText.justSize2
hiU.fill	⇒	hiText.fill
hiU.fill2	⇒	hiText.fill2
hiU.replace	⇒	hiText.replace
hiU.shorten	⇒	hiText.shorten
hiU.shortenTop	⇒	hiText.shortenTop
hiU.shortenLast	⇒	hiText.shortenLast
hiU.shortenLast2	⇒	hiText.shortenLast2
hiU.dbgStr	⇒	hiText.dbgStr
hiU.trimComment	⇒	hiText.trimComment
hiU.trimQuote	⇒	hiText.trimQuote
hiU.space	⇒	hiText.space
hiU.lastPart	⇒	hiText.lastPart
hiU.basePart	⇒	hiText.basePart
hiU.lastName	⇒	hiText.lastName
hiU.replaceUniCode	⇒	hiText.replaceUniCode
hiU.isAlphaNumeric	⇒	hiText.isAlphaNumeric
hiU.substring	⇒	hiText.substring
`hiFile`に移動
hiU.delete	⇒	hiFile.delete
hiU.asBufferedReader	⇒	hiFile.asBufferedReader
hiU.openPrintStream	⇒	hiFile.openPrintStream
hiU.canOpenFileR	⇒	hiFile.canOpenFileR
hiU.canOpenResFileR	⇒	hiFile.canOpenResFileR
hiU.openResTextFileR	⇒	hiFile.openResTextFileR
hiU.skipUTF8BOM	⇒	hiFile.skipUTF8BOM
hiU.readByte	⇒	hiFile.readBytes/td>
hiU.readBytes	⇒	hiFile.readBytes
hiU.tryReadBytes	⇒	hiFile.tryReadBytes
hiU.absolutePath	⇒	hiFile.absolutePath
hiU.parentPath	⇒	hiFile.parentPath
hiU.path	⇒	hiFile.path
hiU.readLines	⇒	hiFile.readTextAll hiFile.readTextLines
`hiTime`に移動
hiU.dispTime	⇒	hiTime.dispTime
hiU.timeDiff	⇒	hiTime.timeDiff
hiU.lapTime	⇒	hiTime.lapTime
hiU.currentMilliSec	⇒	hiTime.currentMilliSec
hiU.currentTime	⇒	hiTime.currentTime
hiU.sleep	⇒	hiTime.sleep
`hiArgs`に移動
hiU.args	⇒	hiArgs.args
`hiArray`に移動
hiU.parseInts	⇒	hiArrays.parseInts
hiU.intsToLong	⇒	hiArrays.intsToLong
hiU.shortsToInt	⇒	hiArrays.shortsToInt
hiU.intToShorts	⇒	hiArrays.intToShorts
hiU.atoa	⇒	hiArrays.atoa
hiU.toStrArrayList	⇒	hiArrays.toStrArrayList
hiU.toStrArray	⇒	hiArrays.toStrArray
hiU.toList	⇒	hiArrays.toList
hiU.lastOf	⇒	hiArrays.lastOf
hiU.get	⇒	hiArrays.get
hiU.shuffle	⇒	hiArrays.shuffled_ints
`hiStack`に移動
hiU.setTraceFold	⇒	hiStack.setTraceFold
hiU.getStackTrace	⇒	hiStack.getStackTrace
hiU.setTraceFormat	⇒	hiStack.setTraceFormat
`Trace`に移動
hiU.setLogFile	⇒	hiU.str,hiU.Trace.setLogFile
hiU.setTraceFile	⇒	hiU.str,hiU.Trace.setTraceFile
hiU.setPrinter	⇒	hiU.str,hiU.Trace.setPrinter
hiU.addPrinter	⇒	hiU.str,hiU.Trace.addPrinter
hiU.delPrinter	⇒	hiU.str,hiU.Trace.delPrinter
hiU.delPrinters	⇒	hiU.str,hiU.Trace.delPrinters
hiU.setTraceFormat	⇒	hiU.str,hiU.Trace.setTraceFormat
hiU.setTraceFold	⇒	hiU.str,hiU.Trace.setTraceFold
hiU.setThreadTraceFormat	⇒	hiU.str,hiU.Trace.setThreadTraceFormat
hiU.get_trace_format_expanded	⇒	hiU.str,hiU.Trace.get_trace_format_expanded
hiU内で統合
hiU.toString	⇒	hiU.str hiU.strs
hiU.parseInt	⇒	hiU.atoi
hiU.parseLong	⇒	hiU.atol
hiU.parseDouble	⇒	hiU.atod
hiU.parseBoolean	⇒	hiU.atob
型変更
System.out	:	(PrintStream)hiU.out (UTF-8)
System.err	:	(PrintStream)hiU.err (UTF-8)
System.out	:	(PrintWriter)hiU.out_pw(UTF-8)
System.err	:	(PrintWriter)hiU.err_pw(UTF-8)
hiU.out	⇒	PrintWriterからPrintStream(UTF-8)に変更
hiU.err	⇒	PrintWriterからPrintStream(UTF-8)に変更
hiU.out_utf8	⇒	hiU.out_pw
hiU.err_utf8	⇒	hiU.err_pw
クラス構成整理
hiSocket.udp	:	hiSocket.UdpIF
hiUDPSocket	:	hiSocket.UDP
hiMulticastSocket	:	hiSocket.UDP.Multicast
hiObjectSocket	:	hiSocket.TCP
hiTextSocket	:	hiSocket.TCP.ForText
hiObjectSocket	:	hiSocket.TCP.ForObject
hiValue	:	hiRef.V1
hiPair	:	hiRef.V2
hiTrio	:	hiRef.V3
hiLRegress(直線回帰)	:	hiRegress.Linear
hiQRegress(二次回帰)	:	hiRegress.Quad
hiLastValue	:	hiLastValue
hiLastIntValues	:	hiLastValues.Int
hiLastDoubleValues	:	hiLastValues.Dbl
hiGadgetパッケージへ移動
hiSyncDque	:	(hiGadget)hiSyncDque
hiSyncAque	:	(hiGadget)hiSyncAque
hiSyncCounter	:	(hiGadget)hiSyncCounter
hiJSONutl	:	(hiGadget)hiJSONutl
hiXML	:	(hiGadget)hiXML
hiDom	:	(hiGadget)hiDom
hiHTTP	:	(hiGadget)hiHTTP
hiLinesReader	:	(hiGadget)hiLinesReader
hiTextWriter	:	(hiGadget)hiTextWriter
hiTemplate	:	(hiGadget)hiTemplate
hiLinesReader	:	(hiGadget)hiLinesReader

アプリケーションのコンパイルと実行

hiNote,hiSwing,symphonieの３つのパッケージは次のjarファイルに纏められています。

jarファイル	含まれるパッケージ
hiNoteX_XX.jar	hiNoteのバージョンX_XX ＋ hiGadgetのバージョンX_XX
hiSwingX_XX.jar	hiSwingのバージョンX_XX 別途hiNoteが必要
symphonieX_XX.jar	symphonieのバージョンX_XX ＋ hiNoteのバージョンX_XX ＋ hiGadgetのバージョンX_XX

コンパイル時/実行時パス指定

otsu.hiNoteを利用するアプリケーションのコンパイル時はotsu.hiNoteを持つjarを指定する必要があります。
次のいずれかを行います。

環境変数のCLASSPATHに指定する

コンパイルオプション-classpathに指定する

標準のライブラリパス上にjarを置く

jarを自フォルダ上に展開(un-jar)する

ここでは単純に固定位置にインストールした場合のコンパイル法、実行法を述べます。

ANTのbuild.xml

仮にhiNote_3_14.jarをC:\jlibに置いたとしての antのbuild.xmlの例を示します。

<?xml version="1.0" encoding="UTF-8"?>
<project default="main">
   <property name ="classpath" value="C:/jlib/hiNote_3_14.jar"/>
   <target name="main" depends="make,run"/>
   <!-- javaコンパイルを行う -->
   <target name="make">
      <javac srcdir="."       includes="*.java"
             encoding="UTF-8" classpath=".;${classpath}" />
   </target>
   <!-- 試験プログラムを実行する -->
   <target name="run">
      <java classname="MyClass" classpath=".;${classpath}" fork="true">
         <arg value="6 4"/>
      </java>
   </target>
</project>
<!--　補足
antでプログラムを実行する場合fork="true"は必須です。
-->

Windowsのバッチ

コンパイルは次のように行います。

SET CLASSPATH=%CLASSPATH%;C:\jlib\hiNote_3_14.jar
javac  -Xlint:unchecked *.java

実行は次のように行います。

SET CLASSPATH=%CLASSPATH%;C:\jlib\hiNote_3_14.jar
java MyClass 6 4