Merge pull request #478 from shmpwk/warn-parse-args

Add warning for argparse.l when not calling :parse-args

Author: k-okada

doc/jlatex/jmanual.tex

@@ -169,6 +169,7 @@ \part{EusLisp 拡張}
 \input{jimage}
 \input{jmanipulator}
 \input{jmars-pre}
+\input{jmisc}
 %
 \begin{thebibliography}{99}
 \bibitem{Hirukawa:1991a}{T.Matsui H.Hirukawa and K.Takase. A general algorithm for derivation and analysis of constraint for motion of polyhedra in contact. In IEEE/RSJ International Workshop on Intelligent Robots and Systems'91, pages 38-43, 1991.}

doc/jlatex/jmisc.tex

@@ -0,0 +1,69 @@
+\section{その他の機能}
+
+\subsection{Argument Parser}
+
+\begin{refdesc}
+
+\classdesc{argument-parser}{propertied-object}{flaglst docstring parsed-p}{
+コマンドライン引数のパーサを定義する。}
+
+\methoddesc{:init}{\&key prog description epilog (add-help t)}{
+プログラム名，自動生成されるヘルプテキストの前後に表示するテキストから，
+オブジェクトを生成する。}
+
+\methoddesc{:add-argument}{flags \&key (action :store) const default choices check read required help dest}{
+コマンドライン引数を定義する。
+
+{\tt flag} は {\tt "--foo"} や {\tt  "-b"} の引数オプションを定義する。
+引数は{\tt '("--bar" "-b")}等のリストで与えることも可能である。
+
+{\tt action} はプログラムに引数が渡されたときの挙動を指定する。
+現在サポートされている{\tt action} は {\tt :store}, {\tt :store-true},
+{\tt :store-false}, {\tt :store-const}, {\tt :append}, そしてカスタム関数である。
+{\tt help} はヘルプドキュメントを指定する。
+ほとんどのパラメータはhttps://docs.python.org/3/library/argparse.htmlに習って設計されている。}
+
+\methoddesc{:parse-args}{}{
+{\tt lisp::*eustop-argument*} を用いてコマンドライン引数をパースする。
+このメソッドは{\tt argument-parser} インスタンスに引数オプション名メ
+ソッドを与える前に呼ばなければならない。}
+
+{\tt argument-parser}のサンプルプログラムを以下に示す。
+
+\begin{verbatim}
+(require :argparse "argparse.l")
+
+(defvar argparse (instance argparse:argument-parser :init
+                           :description "Program Description (optional)"))
+(send argparse :add-argument "--foo" :default 10 :read t
+      :help "the foo description")
+(send argparse :add-argument '("--bar" "-b") :action :store-true
+      :help "the bar description")
+
+(send argparse :parse-args)
+(format t "foo: ~A~%" (send argparse :foo))
+(format t "bar: ~A~%" (send argparse :bar))
+(exit)
+\end{verbatim}
+
+このサンプルプログラムを実行したときの出力は以下のようになる。
+
+\begin{verbatim}
+$ eus argparse-example.l
+foo: 10
+bar: t
+$ eus argparse-example.l --foo=100 --bar
+foo: 100
+bar: t
+$ eus argparse-example.l -h
+usage: [-h] [--foo=FOO] [-b]
+
+Program Description (optional)
+
+optional arguments:
+  -h, --help	show this help message and exit
+  --foo=FOO	the foo description (default: 10)
+  -b, --bar	the bar description
+\end{verbatim}
+
+\end{refdesc}

doc/latex/manual.tex

@@ -183,6 +183,7 @@ \part{EusLisp Extensions}
 \input{database}
 \input{http}
 % \input{sound}
+\input{misc}
 %
 \begin{thebibliography}{99}
 \bibitem{Hirukawa:1991a}{T.Matsui H.Hirukawa and K.Takase. A general algorithm for derivation and analysis of constraint for motion of polyhedra in contact. In IEEE/RSJ International Workshop on Intelligent Robots and Systems'91, pages 38-43, 1991.}

doc/latex/misc.tex

@@ -0,0 +1,70 @@
+\section{Miscellaneous}
+
+\subsection{Argument Parser}
+
+\begin{refdesc}
+
+\classdesc{argument-parser}{propertied-object}{flaglst docstring parsed-p}{
+command line argument parser.}
+
+\methoddesc{:init}{\&key prog description epilog (add-help t)}{
+instantiates argument-parser class object from the name of the program,
+description text to display before the argument help and text to
+display after them as an epilog.}
+
+\methoddesc{:add-argument}{flags \&key (action :store) const default choices check read required help dest}{
+defines the command-line argument to be parsed.
+
+{\tt flag} specify the options strings such as {\tt "--foo"} or {\tt
+  "-b"}. It also takes list values i.e. {\tt '("--bar" "-b")}.
+
+{\tt action} defines the behavior when this argument is passed to the
+program. Current supported actions are {\tt :store}, {\tt :store-true},
+{\tt :store-false}, {\tt :store-const}, {\tt :append}, and custom functions.
+{\tt help} defines the help document text.
+Most of the arguments are designed according to https://docs.python.org/3/library/argparse.html.}
+
+\methoddesc{:parse-args}{}{
+parses command line argument from {\tt lisp::*eustop-argument*}. This
+method must be called before sending an argument name method to {\tt
+ argument-parser} instance.}
+
+The following shows an example of {\tt argument-parser}.
+
+\begin{verbatim}
+(require :argparse "argparse.l")
+
+(defvar argparse (instance argparse:argument-parser :init
+                           :description "Program Description (optional)"))
+(send argparse :add-argument "--foo" :default 10 :read t
+      :help "the foo description")
+(send argparse :add-argument '("--bar" "-b") :action :store-true
+      :help "the bar description")
+
+(send argparse :parse-args)
+(format t "foo: ~A~%" (send argparse :foo))
+(format t "bar: ~A~%" (send argparse :bar))
+(exit)
+\end{verbatim}
+
+The following is an output of the example program above.
+
+\begin{verbatim}
+$ eus argparse-example.l
+foo: 10
+bar: t
+$ eus argparse-example.l --foo=100 --bar
+foo: 100
+bar: t
+$ eus argparse-example.l -h
+usage: [-h] [--foo=FOO] [-b]
+
+Program Description (optional)
+
+optional arguments:
+  -h, --help	show this help message and exit
+  --foo=FOO	the foo description (default: 10)
+  -b, --bar	the bar description
+\end{verbatim}
+
+\end{refdesc}

lib/llib/argparse.l

@@ -167,7 +167,7 @@
 
 (defclass argument-parser
   :super propertied-object
-  :slots (flaglst docstring))
+  :slots (flaglst docstring parsed-p))
 (defmethod argument-parser
   (:init (&key prog description epilog (add-help t))
     (setq docstring (instance argparse-docstring :init
@@ -209,7 +209,7 @@
                   ((not (argparse-argument-flagp arg)) name)))
       ;; add method
       (if (keywordp name)
-          (eval `(defmethod argument-parser (,name () (send (get self ,name) :value)))))
+          (eval `(defmethod argument-parser (,name () (if (not parsed-p) (warning-message 1 "Not parsed! Call :parse-args!~%")) (send (get self ,name) :value)))))
       ;; return name
       name))
   (:parse-args ()
@@ -248,4 +248,6 @@
                   (cli-error "Argument ~S not found!~%" flag)))))
         ;; check required arguments
         (when required-args
-          (cli-error "Argument ~A is required!" (caar (last required-args))))))))
+          (cli-error "Argument ~A is required!" (caar (last required-args))))))
+    ;; set parsed-p
+    (setq parsed-p t)))