source: trunk/FACT++/src/Description.cc @ 10381

Last change on this file since 10381 was 10381, checked in by tbretz, 9 years ago
Turned comment and unit in constructor, added a function to return a html formatted list.
File size: 5.5 KB
Line 
1// **************************************************************************
2/** @struct Description
3
4@brief A struct which stores a name, a unit and a comment
5
6To have proper descriptions of commands and services in the network
7(and later proper informations in the FITS files) this struct provides
8a simple storage for a name, a unit and a comment.
9
10Assume you want to write a descriptive string for a command with three arguments.
11It could look like this:
12
13   COMMAND=Description|int[addr]:Address range (from - to)|val[byte]:Value to be set
14
15Description is a general description of the command or service itself,
16int and val are the names of the arguments (e.g. names of FITS columns),
17addr and byte have the meaning of a unit (e.g. unit of FITS column)
18and the text after the colon is a description of the arguments
19(e.g. comment of a FITS column). The description must not contain a
20line-break character \n.
21
22Such a string can then be converted with SplitDescription into a vector
23of Description objects, each containing the name, the unit and a
24comment indivdually. The first object will contain COMMAND as name and
25Description as comment. The unit will remain empty.
26
27You can omit either the name, the unit or the comment or any
28combination of them. The descriptions of the individual format strings
29are separated by a vertical line. If you want to enclose the name into
30[]-braces (e.g. marking an optional argument in a dim command), you
31have add empty brackets for the units.
32
33For a suggestion for rules for the names please have a look at:
34http://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/ofwg_recomm/r15.html
35
36For units please see:
37http://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/general/ogip_93_001/ogip_93_001.html
38
39*/
40// **************************************************************************
41#include "Description.h"
42
43#include <sstream>
44
45#include "tools.h"
46
47using namespace std;
48
49// --------------------------------------------------------------------------
50//
51//! Construct a Description object
52//!
53//! @param n
54//!     Name of the Description, e.g. "temp"
55//!
56//! @param c
57//!     Descriptive text of the Description, e.g. "Temperature of the moon"
58//!
59//! @param u
60//!     Unit of the Description, e.g. "K"
61//
62Description::Description(const string &n, const string &c, const string &u)
63    : name(Trim(n)), comment(Trim(c)), unit(Trim(u))
64{
65}
66
67// --------------------------------------------------------------------------
68//
69//! This function breaks down a descriptive string into its components.
70//! For details see class reference.
71//!
72//! @param buffer
73//!     string which should be broekn into pieces
74//!
75//! @returns
76//!     A vector<Description> containing all the descriptions found.
77//!     The first entry contains the Description members name and comment,
78//!     corresponding to the service or command name the Description
79//!     list is for and its corresponding description.
80//
81vector<Description> Description::SplitDescription(const string &buffer)
82{
83    const size_t p0 = buffer.find_first_of('=');
84
85    const string svc  = buffer.substr(0, p0);
86    const string desc = buffer.substr(p0+1);
87
88    const size_t p = desc.find_first_of('|');
89
90    // Extract a general description
91    const string d = Trim(desc.substr(0, p));
92
93    vector<Description> vec;
94    vec.push_back(Description(svc, d));
95
96    if (p==string::npos)
97        return vec;
98
99    string buf;
100    stringstream stream(desc.substr(p+1));
101    while (getline(stream, buf, '|'))
102    {
103        if (buf.empty())
104            continue;
105
106        const size_t p1 = buf.find_first_of(':');
107
108        const string comment = p1==string::npos ? "" : buf.substr(p1+1);
109        if (p1!=string::npos)
110            buf.erase(p1);
111
112        const size_t p2 = buf.find_last_of('[');
113        const size_t p3 = buf.find_last_of(']');
114
115        const bool hasunit = p2<p3 && p2!=string::npos;
116
117        const string unit = hasunit ? buf.substr(p2+1, p3-p2-1) : "";
118        const string name = hasunit ? buf.substr(0, p2) : buf;
119
120        vec.push_back(Description(name, comment, unit));
121    }
122
123    return vec;
124}
125
126
127// --------------------------------------------------------------------------
128//
129//! Returns a string with an html formatted text containing the descriptions
130//! as returned by SplitDescription
131//!
132//! @param vec
133//!     vector of Description for the individual arguments. First
134//!     element is the global description of the command or service.
135//!
136//! @returns
137//!     string with html formatted text
138//
139string Description::GetHtmlDescription(const vector<Description> &vec)
140{
141    stringstream str;
142    str << '|';
143
144    str << "<H3>" << vec[0].name << "</H3>";
145
146    str << "Usage:";
147    for (vector<Description>::const_iterator i=vec.begin()+1; i!=vec.end(); i++)
148        str << "&nbsp;<font color='maroon'>&lt;" << i->name <<    "&gt;</font>";
149
150    if (vec.size()==1)
151        str << " &lt;no arguments&gt;";
152
153    str << "<P>" << vec[0].comment << "<P>";
154
155    str << "<table>";
156
157    for (vector<Description>::const_iterator i=vec.begin()+1; i!=vec.end(); i++)
158    {
159        str << "<tr>"
160            "<td><font color='maroon'>" << i->name <<     "</font>";
161
162        if (i->unit.empty() && !i->comment.empty() && !i->name.empty())
163            str << ':';
164
165        str << "</td>";
166
167        if (!i->unit.empty())
168            str << "<td><font color='green'>[" << i->unit <<    "]</font>";
169
170        if (!i->unit.empty() && !i->comment.empty())
171            str << ':';
172
173        str <<
174            "</td>"
175            "<td><font color='navy'>"   << i->comment <<  "</font></td>"
176            "</tr>";
177    }
178
179    str << "</table>";
180
181    return str.str();
182}
Note: See TracBrowser for help on using the repository browser.