casacore
FITSHistoryUtil.h
Go to the documentation of this file.
1//# FITSHistoryUtil.h: Class of static functions to help with FITS History cards.
2//# Copyright (C) 2002
3//# Associated Universities, Inc. Washington DC, USA.
4//#
5//# This library is free software; you can redistribute it and/or modify it
6//# under the terms of the GNU Library General Public License as published by
7//# the Free Software Foundation; either version 2 of the License, or (at your
8//# option) any later version.
9//#
10//# This library is distributed in the hope that it will be useful, but WITHOUT
11//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12//# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13//# License for more details.
14//#
15//# You should have received a copy of the GNU Library General Public License
16//# along with this library; if not, write to the Free Software Foundation,
17//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18//#
19//# Correspondence concerning AIPS++ should be addressed as follows:
20//# Internet email: aips2-request@nrao.edu.
21//# Postal address: AIPS++ Project Office
22//# National Radio Astronomy Observatory
23//# 520 Edgemont Road
24//# Charlottesville, VA 22903-2475 USA
25//#
26//#
27//# $Id$
28
29
30#ifndef FITS_FITSHISTORYUTIL_H
31#define FITS_FITSHISTORYUTIL_H
32
33#include <casacore/casa/aips.h>
34#include <casacore/casa/Arrays/ArrayFwd.h>
35#include <vector>
36
37namespace casacore { //# NAMESPACE CASACORE - BEGIN
38
39class ConstFitsKeywordList;
40class FitsKeywordList;
41class String;
42class LoggerHolder;
43
44// <summary>
45// A class with static functions to help deal with FITS History cards.
46// </summary>
47
48// <use visibility=export>
49
50// <reviewed reviewer="Eric Sessoms" date="2002/08/19" tests="tFITSHistoryUtil.cc">
51// </reviewed>
52
53// <prerequisite>
54// <li> General knowledge of FITS, and particularly FITS keywords, is
55// assumed.
56// <li> Presumably you are using this class in conjunction
57// with the "native"
58// <linkto class=FitsKeywordList>FitsKeywordList</linkto>
59// </prerequisite>
60//
61// <etymology>
62// This is a collection of static utility functions for use with FITS
63// HISTORY keywords.
64// </etymology>
65//
66// <synopsis>
67// Manipulate HISTORY information. FITS HISTORY cards are interconverted with
68// String as follows:
69// <ul>
70// <li> 'HISTORY ' and trailing blanks are removed from each card.
71// <li> Continuation cards are CARDS that have '>' in the first line.
72// <li> A string is made by concatenating the leading card and all continuation
73// cards.
74// </ul>
75// For example:
76// <srcblock>
77// HISTORY Every good
78// HISTORY > boy deserves
79// HISTORY >fudge.
80// </srcblock>
81// Becomes the C++ String: "Every good boy deservesfudge." Note the lack of
82// a space between deserves and fudge.
83//
84// History cards are broken into groups. A group is delimited by
85// <srcblock>
86// HISTORY AIPS++ START TYPE
87// HISTORY AIPS++ END [TYPE]
88// </srcblock>
89// Where type might be, e.g., LOGTABLE. HISTORY cards not enclosed between
90// START/END pairs are implicitly of type "" (i.e. the empty string).
91// The TYPE is optional on the END statement. It is essentially a comment.
92//
93// At present, START/END pairs cannot be nested, although this would be an
94// obvious extension.
95// </synopsis>
96//
97// <motivation>
98// The FitsKeywordList class can be somewhat tedious to use, as it deals with,
99// e.g., char* pointers rather than Strings. This class makes it easy to
100// interconvert between the HISTORY keywords and a Vector of related history
101// information.
102// </motivation>
103//
104
106{
107public:
108 // Get the strings in the next keyword group. Returns the number of
109 // strings found (0 when no history remains). If necessary, strings will be
110 // resized larger. in must be set to the first card before the first call to
111 // getHistoryGroup, and should not be reset until all history is extracted
112 // (otherwise the same history will be extracted more than once). This method
113 // can be used as follows:
114 // <srcBlock>
115 // uInt n;
116 // Vector<String> group;
117 // String type;
118 // ConstFITSKeywordList keys(...);
119 // ...
120 // keys.first();
121 // while ((n = FITSHistoryUtil::getHistoryGroup(group, type, keys)) != 0) {
122 // ... process this history group
123 // }
124 // </srcBlock>
125 // strings will have no embedded newlines. strings is not resized if it is more
126 // than large enough to hold the number of history cards in the group (i.e. there
127 // may be values at the end of strings which are not part of the requested group.
128 static uInt getHistoryGroup(Vector<String> &strings, String &groupType,
130
131 // Add history strings of the specified groupType to an existing FitsKeywordList.
132 // This function will split long strings across HISTORY cards and set
133 // up the group START/END keywords if necessary. nstrings must be specified
134 // because strings might have come from something like getHistoryGroup, i.e.
135 // it might have garbage entries at the end. The strings may have embedded
136 // newlines, but they must have no other non-printable characters.
138 const std::vector<String> &strings,
139 uInt nstrings, const String &groupType);
140
141 // Some functions to help convert between log tables and FITS HISTORY cards.
142 // It is intended that these functions will only be used by the functions in
143 // classes like ImageFITSConverter.
144 //
145 // Table rows are in Casacore format if they have a valid time and priority,
146 // otherwise they are in the standard FITS HISTORY format. The history lines
147 // are processed by contiguous groups where all lines in that group are
148 // either in Casacore or HISTORY format. Note that history.nelements() might
149 // be greater than nstrings for efficiency (i.e. the history vector will
150 // not be shrunk unnecessarily).
151 //
152 // Note that these functions are in a separate .cc file so that if they
153 // are not used the table function is not linked in if other functions in
154 // this class are used.
155 //
156 // The strings are assumed to be from or going to the get/addHistoryGroup
157 // functions, i.e. strings that span multiple lines are joined,
158 // AIPS++ START/END cards are stripped, etc.
159 //
160 // The Casacore format is: the first line DATE PRIORITY [SRCCODE='xxx']
161 // [OBJID='xxx'] and the second lins is the message. These entries are in
162 // an AIPS++ START LOGTABLE history sequence.
163 // <group>
164 static void fromHISTORY(LoggerHolder& logSink,
165 const Vector<String>& history,
166 uInt nstrings, Bool aipsppFormat);
167
168 // toHistory signals that it is done by setting nstrings to 0.
169 // The returned value is firstLine + n_lines_read, i.e. use
170 // it as firstLine in your next call.
171 static uInt toHISTORY(std::vector<String>& history, Bool& aipsppFormat,
172 uInt& nstrings, uInt firstLine,
173 const LoggerHolder& logSink);
174 // </group>
175
176};
177
178
179} //# NAMESPACE CASACORE - END
180
181#endif
list of read-only FITS keywords
Definition: fits.h:951
static void fromHISTORY(LoggerHolder &logSink, const Vector< String > &history, uInt nstrings, Bool aipsppFormat)
Some functions to help convert between log tables and FITS HISTORY cards.
static void addHistoryGroup(FitsKeywordList &out, const std::vector< String > &strings, uInt nstrings, const String &groupType)
Add history strings of the specified groupType to an existing FitsKeywordList.
static uInt toHISTORY(std::vector< String > &history, Bool &aipsppFormat, uInt &nstrings, uInt firstLine, const LoggerHolder &logSink)
toHistory signals that it is done by setting nstrings to 0.
static uInt getHistoryGroup(Vector< String > &strings, String &groupType, ConstFitsKeywordList &in)
Get the strings in the next keyword group.
linked list of FITS keywords
Definition: fits.h:737
String: the storage and methods of handling collections of characters.
Definition: String.h:225
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:51
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42