Windows TIPS

［Scripting］

→ Windows TIPS TOPへ → Windows TIPS全リストへ → 内容別分類一覧へ WSHスクリプトでヘルプ・メッセージを表示する → 解説をスキップして操作方法を読む 山田 祥寛 2003/08/09 2012/06/21更新 　 対象OS Windows NT Windows 2000 Windows XP Windows Server 2003

■ WSHで作成したコードをエンド・ユーザーなどに配布する場合、いちいち使用マニュアルを配布するのは面倒である。 ■ そのような場合、「.wsf」ファイルに<runtime>要素を加えることで、コード中に簡単にオンライン・ヘルプを含めることができる。

　

解説

　この「Windows TIPS」コーナでもさまざまなWSH（Windows Scripting Host）のコードを紹介してきた。読者の方は、これらのコードをどのようにしてユーザーに配布しているだろうか。

　いちいち使用マニュアルを作成して、別に配布しているかもしれない。あるいは、ある程度対象ユーザーが限られていたり、自分だけのために作成したコードであるならば、そもそもマニュアルの作成などは考えたこともないかもしれない。だが、いかに個人用途であっても、しばらく経つと使い方などはきれいさっぱり忘れてしまうのが人の常であるし、「自分に限っては問題ない」という方でも、将来、配布すべき状況が起こってくることを考えれば、マニュアルや使い方のドキュメントを用意しておくべきだろう。

　だからといって、いちいち別にドキュメントを作成するのでは面倒臭くもなるし（面倒なことは、だいたい続かない）、ユーザーの側でもコードと離れていては紛失してしまう可能性が大きくなる。

　しかし、WSHのコメント機能を用いることで、コード中にオンライン・ヘルプを加えることができるようになる。コード中に追加されたヘルプは、実行時に適切な引数が渡されなかった場合のエラー・メッセージとして表示させることもできるし、また、コマンドプロンプトから「ファイル名 /?」の形式で呼び出して、表示させることも可能になる。

　コードと一体化させて管理しておけば、コードとそのドキュメントを配布するのが簡単になるだけでなく、コードのメンテナンスや機能追加などで変更が生じた場合でも、同時にヘルプ・メッセージを修正するだけでよいので、積極的に活用して欲しい。

操作方法

手順1―テキスト・エディタでスクリプトのコードを入力する

　ここでは、別稿の「TIPS―ファイルの文字コードを変換する」で扱ったkconv.wsfを例に、ヘルプ機能を追加してみることにする。赤文字で示した所が、前回からの追加部分である。なお、引用符（'）で始まる行はコードの概要を解説するためのコメント部分なので、省略しても構わない。

<?xml version="1.0" encoding="Shift_JIS" standalone="yes" ?> <package> <job id="KConvert"> <?job error="True" debug="True" ?> <object id="objBsp" progid="Basp21" /> <object id="objFs"  progid="Scripting.FileSystemObject" /> <runtime>   <description>指定されたフォルダ配下の文字コードを変換する</description>   <unnamed name="folderPath" helpstring="フォルダの絶対パス"     many="False" required="1" />   <example>kconv.wsf sampleFolder</example> </runtime> <script language="VBScript"> <![CDATA[ Sub FileConvert(strPath)   Set objFld = objFs.GetFolder(strPath)   For Each objFl In objFld.Files     strTmp=objFl.Path     If objFl.Size>0 Then objBsp.KconvFile strTmp,strTmp & ".tmp",2,1     objFl.Delete     objFs.MoveFile strTmp & ".tmp",strTmp   Next   ' 現在のフォルダ配下に存在するファイル（objFld.Files）に対して、文字コード   ' の変換処理（Basp21#KconvFilesメソッド）を行う。ただし、対象のファイル   ' が空（0バイト）の場合には、KconvFileメソッドは失敗するので、あらかじめ   ' 取り除いておくものとする。   ' 変換後は元のファイルを削除し、KconvFileメソッドによって生成された「元の   ' ファイル名.tmp」を元のファイル名で保存し直す   For Each objSub In objFld.SubFolders     FileConvert objSub.Path   Next   ' 現在のフォルダ配下に存在するサブフォルダ（objFld.SubFolders）に対して   ' 再帰的にFileConvertプロシージャ（自分自身）を呼び出す。これによって、   ' 複数の階層フォルダに対しても、一度で変換処理が行える End Sub If WScript.Arguments.length<1 Then   WScript.Arguments.ShowUsage   WScript.Quit End If   ' 上で定義されたFileConvertプロシージャに、ドラッグ＆ドロップで渡された   ' フォルダのパスを引数として渡し、実行する FileConvert WScript.Arguments.Item(0) ]]> </script> </job> </package> ※赤字部分は、今回追加したコード。

• サンプル・ファイルのダウンロード
  （注：サンプルkconv.wsfをダウンロードするには、上のリンクを右クリックして、kconv.wsfというファイル名で保存してください）

　WSHの実行ファイルは拡張子「.wsf」（Windows Scripting host File）とする必要がある。ファイル名自体は何でもよいが、ここでは元の通り「kconv.wsf」という名前で保存しておく。

手順2―WSHのコードを実行する（1）

　kconv.wsfそのものに関する詳細な説明は、先の「TIPS―ファイルの文字コードを変換する」を参照して欲しい。ここでは、新たに追加されたコード部分（オンライン・ヘルプの表示）について、2つの方法で確認してみたい。

　最初の方法は、エクスプローラなどからkconv.wsfのアイコンをダブルクリックすることだ。kconv.wsfは1個の引数（パラメータ）を要求するので、引数を伴なわずに起動すると、オンライン・ヘルプをダイアログ表示して、実行を中止する。オンライン・ヘルプには、kconv.wsfの<runtime>要素以下で指定された一連の説明が、整形された形で表示される。

表示されたヘルプ・メッセージのダイアログ

引数を何も付けずに起動したり、コマンド・プロンプト上で「kconv /?」を実行するとこのようなダイアログが表示される。

手順2―WSHのコードを実行する（2）

　ヘルプを表示させる二つ目の方法は、コマンド・プロンプトから「/?」スイッチを付加して、kconv.wsfを呼び出すことだ。kconv.wsfが「C:\」に格納されているならば、コマンドプロンプトから以下のように入力すればよい。このようなヘルプの表示方法は、ほかの多くのコマンドでも使用されている一般的な方式なので、ユーザーにも分かりやすいだろう。

C:\>kconv.wsf /?

オンライン・ヘルプの定義方法について

　以上が簡単な表示方法の手順であるが、これだけではよく分からないと思うので、いくつか説明を追加しておきたい。

　オンライン・ヘルプを定義しているのは、kconv.wsf中の以下の部分だ。

<runtime>   <description>指定されたフォルダ配下の文字コードを変換する</description>   <unnamed name="folderPath" helpstring="フォルダの絶対パス"     many="False" required="1" />   <example>kconv.wsf sampleFolder</example> </runtime>

　<runtime>要素には、<description>、<named>、<unnamed>、<example>などの要素を含むことができる。

　<description>要素では簡単な「.wsf」ファイルの説明を、<example>要素では用例を記述する。属性は持たない。

　<named>、<unnamed>要素は引数に関する情報を記述する要素だ。その名の通り、<named>要素は名前付きの引数（つまり、「ファイル名 /パラメータ名:値」の形式で指定することができる）を、<unnamed>要素は名前なし引数（つまり、「ファイル名 値」の形式で指定することができる）を、それぞれ定義する。これら要素においては、以下のような属性を指定することができる。

属性名	概要
name	引数名。ただし<UNNAMED>要素ではヘルプで表示される以上の意味はない
helpstring	ヘルプの説明文
type	属性の型。string、boolean、simple（デフォルト）のいずれか。string、simpleの場合は「/パラメータ名:値」、booleanの場合は「/パラメータ名{+|-}」で指定する。<NAMED>要素でのみ指定可能
many	required属性で指定した回数以上の引数を指定可能か（True｜False）。つまり、many要素がTrueの場合、required属性で指定した数値以上のパラメータを指定できる。<UNNAMED>要素でのみ指定可能
required	パラメータが必須かどうか（True｜False）。ただし、<UNNAMED>要素では数値指定することで、登場可能な回数を指定することもできる。ヘルプで表示される以上の意味はない

　manyやrequired属性の指定はあくまでパラメータの情報を記述するのみであることに注意して欲しい。WSHはこの情報に基づいて、引数の妥当性チェックなどは行なわない。例にもあるように、引数の数や内容については、あくまで<script>要素の内部で自ら検証しなければならない。

　なお、<description>、<named>、<unnamed>、<example>要素の代替として、<usage>要素を指定することもできる。例えば次のようになる（もっと長いメッセージでもよい）。

<runtime>   <usage>指定されたフォルダ配下の文字コードを変換する...</usage> </runtime>

　<usage>要素を指定した場合、<runtime>要素配下の一切の要素は無視され、<usage>要素の内容だけがオンライン・ヘルプとして表示される。つまり、自由な形式でコードの説明を表示させたいという場合には、<usage>要素をそのほか要素の代替として使用することができる。

更新履歴

【2012/06/21】　属性名について解説している表の「概要」列にて、要素名「<UNNAMED>」と「<NAMED>」が複数個所で抜け落ちていました。お詫びして訂正させていただきます。

「Windows TIPS」

＠ITメールマガジン　新着情報やスタッフのコラムがメールで届きます（無料）