Commit cb23809a authored by thomas.forbriger's avatar thomas.forbriger
Browse files

[WP][API][!!!][ERR] (libstfinv): implement new end-user usage functions

Implement a new set and hierarchy of end-user usage functions:
- engines: prints a list of available procedures
- help: prints the list of procedures together with a brief usage summary
- usage: prints the detailed description for the selected procedure

Function declarations are provided. onlinehelp.cc addresses these new
functions. Function bodies, however, are not yet implemented.

Next:
- implement bodies of usage and classusage functions.
- adjust bodies of implemented classhelp functions.
- new bodies must make use of character strings created automatically
  from *usage.txt files
parent 6abb6224
......@@ -31,11 +31,12 @@
* - 30/09/2011 V1.1 implemented handling of additional time series pairs
* - 05/10/2011 V1.2 correction: initstfinvenginewithpairs was named
* incorrectly initstfinvenginepairs
* - 14/10/2015 V1.3 new end-user usage functions
*
* ============================================================================
*/
#define STFINV_STFINV_C_VERSION \
"STFINV_STFINV_C V1.2"
"STFINV_STFINV_C V1.3"
#include <stfinv/stfinv.h>
#include <stfinv/error.h>
......@@ -164,18 +165,24 @@ void freestfinvengine()
/*----------------------------------------------------------------------*/
void printengines()
{
stfinv::engines();
} // void printengines()
/*----------------------------------------------------------------------*/
void printhelp()
{
stfinv::STFEngine::help();
stfinv::help();
} // void printhelp()
/*----------------------------------------------------------------------*/
void printusage(const std::string& id)
void printusage(char* id)
{
stfinv::STFEngine::help();
stfinv::help();
} // void printhelp()
std::string selectid(id);
stfinv::usage(selectid);
} // void printhelp(age(char* id)
/* ----- END OF stfinv.cc ----- */
......@@ -33,6 +33,7 @@
* - 28/06/2011 V1.1 requires extern declaration for C++ since binary
* code is compiled by C++ compiler, not C compiler
* - 30/09/2011 V1.2 implemented handling of additional time series pairs
* - 14/10/2015 V1.3 new end-user usage functions
*
* ============================================================================
*/
......@@ -41,7 +42,7 @@
#ifndef STFINV_STFINV__H_VERSION
#define STFINV_STFINV__H_VERSION \
"STFINV_STFINV__H V1.2"
"STFINV_STFINV__H V1.3"
#include <stfinv/waveformheader.h>
......@@ -275,6 +276,12 @@ void runstfinvengine();
*/
void freestfinvengine();
/*! \brief List procedures (engines) on stdout
*
* \ingroup cinterface
*/
void printengines();
/*! \brief Print usage summary to stdout
*
* \ingroup cinterface
......
......@@ -31,17 +31,20 @@
* - 06/05/2011 V1.0 Thomas Forbriger
* - 30/09/2011 V1.1 implemented handling of additional time series pairs
* - 04/10/2011 V1.2 renamed Fourier domain least squares engine
* - 14/10/2015 V1.3 new end-user usage functions
*
* ============================================================================
*/
#define STFINV_STFINVANY_CC_VERSION \
"STFINV_STFINVANY_CC V1.1"
"STFINV_STFINVANY_CC V1.3"
#include <stfinv/stfinvany.h>
#include <stfinv/stfinvfdleastsquares.h>
#include <stfinv/stfinvfixedstf.h>
#include <stfinv/stfinvidentity.h>
#include <stfinv/parameterhandler.h>
#include <stfinv/stfinvany_summary_usage.h>
#include <stfinv/stfinvany_description_usage.h>
#include <stfinv/error.h>
namespace stfinv {
......@@ -125,10 +128,10 @@ namespace stfinv {
/*----------------------------------------------------------------------*/
void STFEngine::help(std::ostream& os)
void STFEngine::engines(std::ostream& os)
{
os << "Currently the following engines are available:" << std::endl;
os << "---------------------------------------------" << std::endl;
os << "The following procedures are available:" << std::endl;
os << "---------------------------------------" << std::endl;
os << std::endl;
const int width1=10;
/*----------------------------------------------------------------------*/
......@@ -150,61 +153,58 @@ namespace stfinv {
os << ": " << STFEngineFDLeastSquares::description << std::endl;
} // void STFEngine::help(std::ostream& os=std::cout)
/*======================================================================*/
/*----------------------------------------------------------------------*/
void help(std::ostream& os)
void STFEngine::help(std::ostream& os)
{
os << "Details descriptions of available engines:" << std::endl;
os << "------------------------------------------" << std::endl;
STFEngine::engines(os);
os << std::endl;
STFEngineIdentity::classhelp(os);
/*
os << std::endl;
STFEngineFixedWavelet::classhelp(os);
*/
os << std::endl;
STFEngineFDLeastSquares::classhelp(os);
STFFourierDomainEngine::classhelp(os);
STFBaseEngine::classhelp(os);
os << std::endl;
os << stfinvany_summary_usage;
} // void STFEngine::help(std::ostream& os=std::cout)
// parameter strings
os << "\n";
os << "How to construct parameter strings" << std::endl;
os << "----------------------------------" << std::endl;
os << "A specific engine is selected by passing a parameter string.\n"
<< "This parameter string may further contain parameters to control\n"
<< "the execution mode of the engine.\n";
os << "The parameter string starts with an ID-sequence identifying\n"
<< "the desired engine. See the list below for available engines.\n"
<< "In the parameter string the ID-sequence is terminated by a\n"
<< "colon (:).\n";
os << "After selecting the desired engine, the interface function\n"
<< "strips of the ID-sequence as well as the colon from the\n"
<< "parameter string and initializes the engine and passes the\n"
<< "remainder of the parameter string to the engine. This\n"
<< "remainder may consist of several control parameters being\n"
<< "separated by colons (:). Each control parameter may just be\n"
<< "a flag (switch to turn an option on) or may come along with\n"
<< "a parameter value. The value of the parameter is separated\n"
<< "by an equal sign (=).\n";
os << "\n";
os << "Examples:\n";
os << "- To select Fourier domain least squares and shift\n"
<< " the returned source correction filter wavelet by 0.4s and\n"
<< " switch on verbose mode, pass the following parameter string:\n";
os << " fdlsq:tshift=0.4:verbose\n";
os << "- To select the identity engine and to switch on debug level 4:\n";
os << " ident:DEBUG=4\n";
os << "- To select Fourier domain least squares, apply offset\n"
<< " dependent weights and use a power of two to speed up the FFT:\n";
os << " fdlsq:pow2:exp=1.4\n";
/*----------------------------------------------------------------------*/
void STFEngine::usage(const std::string& id, std::ostream& os)
{
if (id == std::string(stfinv::STFEngineIdentity::ID))
{
stfinv::STFEngineIdentity::classusage(os);
}
else if ((id == std::string(stfinv::STFEngineFDLeastSquares::ID)))
{
stfinv::STFEngineFDLeastSquares::classusage(os);
}
else
{
std::cerr << "ERROR: engine ID " << id << " is unkown!" << std::endl;
STFINV_abort("aborting since engine ID is not recognized");
}
os << std::endl;
os << stfinvany_description_usage;
} // void STFEngine::help(std::ostream& os=std::cout)
/*======================================================================*/
void engines(std::ostream& os)
{
STFEngine::engines(os);
} // void engines(std::ostream& os)
void help(std::ostream& os)
{
STFEngine::help(os);
} // void help(std::ostream& os=std::cout)
void usage(const std::string& id, std::ostream& os)
{
STFEngine::usage(id, os);
} // void usage(const std::string& id, std::ostream& os)
} // namespace stfinv
/* ----- END OF stfinvany.cc ----- */
......@@ -30,6 +30,7 @@
* REVISIONS and CHANGES
* - 06/05/2011 V1.0 Thomas Forbriger
* - 30/09/2011 V1.1 implemented handling of additional time series pairs
* - 14/10/2015 V1.2 new end-user usage functions
*
* ============================================================================
*/
......@@ -38,7 +39,7 @@
#ifndef STFINV_STFINVANY_H_VERSION
#define STFINV_STFINVANY_H_VERSION \
"STFINV_STFINVANY_H V1.1"
"STFINV_STFINVANY_H V1.2"
#include<stfinv/stfinvbase.h>
......@@ -119,8 +120,16 @@ namespace stfinv {
stfinv::STFBaseEngine& STFBaseEngine() { return (*Mengine); }
//! \brief Start engine and return source correction filter.
stfinv::Waveform run() { return(Mengine->run()); }
//! \brief List engines currently recognized
//! \brief List procedures (engines) currently recognized
static void engines(std::ostream& os=std::cout);
//! \brief List engines currently recognized and print summary
static void help(std::ostream& os=std::cout);
/*! \brief Print detailed usage description.
*
* \param id ID of procedure (engine) to be described.
* \param os stream to send output to
*/
static void usage(const std::string& id, std::ostream& os=std::cout);
private:
//! \brief initialize engine.
void initialize(const stfinv::Tvectoroftriples& triples,
......@@ -133,11 +142,27 @@ namespace stfinv {
/*----------------------------------------------------------------------*/
/*! print online help of the whole implemented system of engines
/*! print list available procedures (engines)
* \ingroup cxxinterface
*
* Just delegates to STFEngine::engines()
*/
void engines(std::ostream& os=std::cout);
/*! print print usage summary
* \ingroup cxxinterface
*
* Just delegates to STFEngine::help()
*/
void help(std::ostream& os=std::cout);
/*! print print detailed description for selected engine
* \ingroup cxxinterface
*
* Just delegates to STFEngine::usage()
*/
void usage(const std::string& id, std::ostream& os=std::cout);
} // namespace stfinv
#endif // STFINV_STFINVANY_H_VERSION (includeguard)
......
......@@ -30,11 +30,12 @@
* REVISIONS and CHANGES
* - 06/05/2011 V1.0 Thomas Forbriger
* - 30/09/2011 V1.1 implemented handling of additional time series pairs
* - 14/10/2015 V1.2 new end-user usage functions
*
* ============================================================================
*/
#define STFINV_STFINVBASE_CC_VERSION \
"STFINV_STFINVBASE_CC V1.1"
"STFINV_STFINVBASE_CC V1.2"
#include <sstream>
#include <cmath>
......
......@@ -30,6 +30,7 @@
* REVISIONS and CHANGES
* - 06/05/2011 V1.0 Thomas Forbriger
* - 30/09/2011 V1.1 implemented handling of additional time series pairs
* - 14/10/2015 V1.2 new end-user usage functions
*
* ============================================================================
*/
......@@ -38,7 +39,7 @@
#ifndef STFINV_STFINVBASE_H_VERSION
#define STFINV_STFINVBASE_H_VERSION \
"STFINV_STFINVBASE_H V1.1"
"STFINV_STFINVBASE_H V1.2"
#include<stfinv/waveformheader.h>
#include<stfinv/parameterhandler.h>
......@@ -238,10 +239,14 @@ namespace stfinv {
}
//! \brief print online help
virtual void help(std::ostream& os=std::cout) const;
//! \brief print online help
virtual void usage(std::ostream& os=std::cout) const;
//! \brief return name of engine
virtual const char* name() const;
//! \brief print online help
static void classhelp(std::ostream& os=std::cout);
//! \brief print online help
static void classusage(std::ostream& os=std::cout);
//@}
/*! \name Shape query functions
......
......@@ -30,11 +30,12 @@
* REVISIONS and CHANGES
* - 06/05/2011 V1.0 Thomas Forbriger
* - 04/10/2011 V1.1 renamed engine
* - 14/10/2015 V1.2 new end-user usage functions
*
* ============================================================================
*/
#define STFINV_STFINVFDLEASTSQUARES_CC_VERSION \
"STFINV_STFINVFDLEASTSQUARES_CC V1.1"
"STFINV_STFINVFDLEASTSQUARES_CC V1.2"
#include <iostream>
#include <aff/functions/sqrsum.h>
......
......@@ -31,6 +31,7 @@
* - 06/05/2011 V1.0 Thomas Forbriger
* - 30/09/2011 V1.1 implemented handling of additional time series pairs
* - 04/10/2011 V1.2 renamed engine
* - 14/10/2015 V1.3 new end-user usage functions
*
* ============================================================================
*/
......@@ -39,7 +40,7 @@
#ifndef STFINV_STFINVFDLEASTSQUARES_H_VERSION
#define STFINV_STFINVFDLEASTSQUARES_H_VERSION \
"STFINV_STFINVFDLEASTSQUARES_H V1.2"
"STFINV_STFINVFDLEASTSQUARES_H V1.3"
#include<stfinv/stfinvfourier.h>
......@@ -246,6 +247,10 @@ namespace stfinv {
virtual void help(std::ostream& os=std::cout) const;
//! \brief print online help
static void classhelp(std::ostream& os=std::cout);
//! \brief print online help
virtual void usage(std::ostream& os=std::cout) const;
//! \brief print online help
static void classusage(std::ostream& os=std::cout);
//! \brief return name of engine
virtual const char* name() const;
private:
......
......@@ -31,11 +31,12 @@
* - 08/05/2011 V1.0 Thomas Forbriger
* - 30/09/2011 V1.1 implemented handling of additional time series pairs
* - 04/10/2011 V1.2 correction in debug message
* - 14/10/2015 V1.3 new end-user usage functions
*
* ============================================================================
*/
#define STFINV_STFINVFOURIER_CC_VERSION \
"STFINV_STFINVFOURIER_CC V1.2"
"STFINV_STFINVFOURIER_CC V1.3"
#include <sstream>
#include <stfinv/stfinvfourier.h>
......
......@@ -29,6 +29,7 @@
* REVISIONS and CHANGES
* - 08/05/2011 V1.0 Thomas Forbriger
* - 30/09/2011 V1.1 implemented handling of additional time series pairs
* - 14/10/2015 V1.2 new end-user usage functions
*
* ============================================================================
*/
......@@ -37,7 +38,7 @@
#ifndef STFINV_STFINVFOURIER_H_VERSION
#define STFINV_STFINVFOURIER_H_VERSION \
"STFINV_STFINVFOURIER_H V1.1"
"STFINV_STFINVFOURIER_H V1.2"
#include <stfinv/stfinvbase.h>
#include <aff/array.h>
......@@ -111,6 +112,10 @@ namespace stfinv {
virtual void help(std::ostream& os=std::cout) const;
//! \brief print online help
static void classhelp(std::ostream& os=std::cout);
//! \brief print online help
virtual void usage(std::ostream& os=std::cout) const;
//! \brief print online help
static void classusage(std::ostream& os=std::cout);
//! \brief return name of engine
virtual const char* name() const;
protected:
......
......@@ -29,12 +29,13 @@
*
* REVISIONS and CHANGES
* - 07/05/2011 V1.0 Thomas Forbriger (thof)
* - 21/02/2014 thof: implemented scaling to average weighted energy
* - 21/02/2014 V1.1 implemented scaling to average weighted energy
* - 14/10/2015 V1.2 new end-user usage functions
*
* ============================================================================
*/
#define STFINV_STFINVIDENTITY_CC_VERSION \
"STFINV_STFINVIDENTITY_CC 2014-02-21"
"STFINV_STFINVIDENTITY_CC V1.2"
#include <stfinv/stfinvidentity.h>
#include <aff/functions/sqrsum.h>
......
......@@ -29,6 +29,7 @@
*
* REVISIONS and CHANGES
* - 07/05/2011 V1.0 Thomas Forbriger
* - 14/10/2015 V1.1 new end-user usage functions
*
* ============================================================================
*/
......@@ -37,7 +38,7 @@
#ifndef STFINV_STFINVIDENTITY_H_VERSION
#define STFINV_STFINVIDENTITY_H_VERSION \
"STFINV_STFINVIDENTITY_H V1.0"
"STFINV_STFINVIDENTITY_H V1.1"
#include<stfinv/stfinvbase.h>
......@@ -85,6 +86,10 @@ namespace stfinv {
virtual void help(std::ostream& os=std::cout) const;
//! \brief print online help
static void classhelp(std::ostream& os=std::cout);
//! \brief print online help
virtual void usage(std::ostream& os=std::cout) const;
//! \brief print online help
static void classusage(std::ostream& os=std::cout);
//! \brief return name of engine
virtual const char* name() const;
private:
......
......@@ -29,11 +29,12 @@
*
* REVISIONS and CHANGES
* - 09/05/2011 V1.0 Thomas Forbriger
* - 14/10/2015 V1.1 address new end-user usage functions
*
* ============================================================================
*/
#define ONLINEHELP_VERSION \
"ONLINEHELP V1.0 print online help"
"ONLINEHELP V1.1 print online help"
#include <iostream>
#include <tfxx/commandline.h>
......@@ -43,6 +44,9 @@ using std::cout;
using std::cerr;
using std::endl;
bool selectprocedure;
std::string procedure_id;
int main(int iargc, char* argv[])
{
......@@ -50,7 +54,7 @@ int main(int iargc, char* argv[])
char usage_text[]=
{
ONLINEHELP_VERSION "\n"
"usage: onlinehelp" "\n"
"usage: onlinehelp [-procedure p]" "\n"
" or: onlinehelp --help|-h" "\n"
};
......@@ -68,6 +72,8 @@ int main(int iargc, char* argv[])
{"help",arg_no,"-"},
// 1: verbose mode
{"v",arg_no,"-"},
// 2: verbose mode
{"procedure",arg_yes,"-"},
{NULL}
};
......@@ -75,7 +81,6 @@ int main(int iargc, char* argv[])
if (iargc<2)
{
cerr << usage_text << endl;
stfinv::STFEngine::help(cerr);
exit(0);
}
......@@ -87,32 +92,21 @@ int main(int iargc, char* argv[])
{
cerr << usage_text << endl;
cerr << help_text << endl;
stfinv::STFEngine::help(cerr);
stfinv::help(cerr);
stfinv::engines(cout);
exit(0);
}
// dummy operation: print option settings
for (int iopt=0; iopt<2; iopt++)
selectprocedure=cmdline.optset(2);
procedure_id=cmdline.string_arg(2);
if (selectprocedure)
{
cout << "option: '" << options[iopt].opt_string << "'" << endl;
if (cmdline.optset(iopt)) { cout << " option was set"; }
else { cout << "option was not set"; }
cout << endl;
cout << " argument (string): '" << cmdline.string_arg(iopt) << "'" << endl;
cout << " argument (int): '" << cmdline.int_arg(iopt) << "'" << endl;
cout << " argument (long): '" << cmdline.long_arg(iopt) << "'" << endl;
cout << " argument (float): '" << cmdline.float_arg(iopt) << "'" << endl;
cout << " argument (double): '" << cmdline.double_arg(iopt) << "'" << endl;
cout << " argument (bool): '";
if (cmdline.bool_arg(iopt))
{ cout << "true"; } else { cout << "false"; }
cout << "'" << endl;
stfinv::usage(procedure_id, cout);
}
else
{
stfinv::help(cout);
}
while (cmdline.extra()) { cout << cmdline.next() << endl; }
// dummy operation: print rest of command line
while (cmdline.extra()) { cout << cmdline.next() << endl; }
}
/* ----- END OF onlinehelp.cc ----- */
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment