srecord 1.65.0
 
Loading...
Searching...
No Matches
file.h
Go to the documentation of this file.
1//
2// srecord - manipulate eprom load files
3// Copyright (C) 1998-2008, 2010-2013 Peter Miller
4//
5// This program is free software; you can redistribute it and/or modify it
6// under the terms of the GNU Lesser General Public License as published by
7// the Free Software Foundation; either version 3 of the License, or (at your
8// option) any later version.
9//
10// This program 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 Lesser General Public
13// License for more details.
14//
15// You should have received a copy of the GNU Lesser General Public License
16// along with this program. If not, see <http://www.gnu.org/licenses/>.
17//
18
19#ifndef SRECORD_INPUT_FILE_H
20#define SRECORD_INPUT_FILE_H
21
22#include <string>
23
24#include <srecord/input.h>
25
26namespace srecord {
27
28class arglex; // forward
29
30/**
31 * The srecord::input_file class is used to represent an generic input
32 * file. It provides many helper methods common to most file input
33 * classes.
34 */
36 public input
37{
38public:
39 typedef std::shared_ptr<input_file> pointer;
40
41 /**
42 * The destructor.
43 */
44 virtual ~input_file();
45
46 /**
47 * The guess class method is used to open a file of an unknown
48 * type. It attempts all of the know formats one after the other.
49 *
50 * @param file_name
51 * The name of the file to be opened.
52 * @param cmdln
53 * The command line for context
54 */
55 static pointer guess(const std::string &file_name, arglex &cmdln);
56
57 /**
58 * The ignore_all_checksums method is used to set the global
59 * ignore checksums flag. This is usually the result of an
60 * --ignore-checksums command line option.
61 */
62 static void ignore_all_checksums(void) { ignore_checksums_default = true; }
63
64 /**
65 * The format_option_number method is used to obtain the option number,
66 * which can then be turned into text via the arglex::token_name method.
67 */
68 virtual int format_option_number(void) const = 0;
69
70protected:
71 // See base class for documentation.
72 virtual std::string filename(void) const;
73
74 // See base class for documentation.
75 virtual std::string filename_and_line(void) const;
76
77 // See base class for documentation.
79
80protected:
81 /**
82 * The constructor. The input will be taken from the named file
83 * (or the standard input if the filename is "-").
84 *
85 * Only derived classes may use this constructor.
86 *
87 * @param file_name
88 * The name of the file to be read.
89 */
90 input_file(const std::string &file_name);
91
92 /**
93 * The get_char method is used to fetch a character from
94 * the input. Usually, this is sufficient, however derived
95 * classes may over-ride it if they have a special case.
96 * Over-ride with caution, as it affects many other methods.
97 *
98 * The line_number instance variable is maintained, so that the
99 * filename_and_line method may report the current file location.
100 * This makes for more informative error messages.
101 */
102 virtual int get_char(void);
103
104 /**
105 * The get_char_undo method is used to return a character to
106 * the input. (a later get_char or peak_char method will see
107 * it again). Only one character may be pushed back.
108 */
109 virtual void get_char_undo(int);
110
111 /**
112 * The peek_char method is used to look at the next character
113 * of input, without actually consuming it (a later get_char
114 * or peak_char method will still see it).
115 */
116 int peek_char(void);
117
118 /**
119 * The get_nibble_value class method is used to translate a
120 * character into its hexadecimal value.
121 *
122 * @param c
123 * The character to translate
124 * @returns
125 * int; 0..9 for '0'..'9', 10..15 for 'a'..'f',
126 * 10..15 for 'A-Z', and -1 for everything else.
127 */
128 static int get_nibble_value(int c);
129
130 /**
131 * The get_nibble method is used to fetch one hexadecimal digit
132 * from the input, via the get_char method. It is not case
133 * sensitive. It returns a value for 0 to 15. Characters which
134 * are not hexadecimal digits will result in a fatal error,
135 * and the method call will not return.
136 */
137 virtual int get_nibble(void);
138
139 /**
140 * The get_byte method is used to fetch a byte value from the
141 * input. The default implementation is to call the get_nibble
142 * method twice, and assemble them big-endian (most significant
143 * nibble first).
144 *
145 * The value of the byte will be added to the running checksum,
146 * via the checksum_add method.
147 *
148 * Usually, this get_byte method implementation is sufficient for
149 * most input classes, however derived classes may over-ride
150 * it if they have a special case. Over-ride with caution,
151 * as it affects many other methods.
152 */
153 virtual int get_byte(void);
154
155 /**
156 * The get_word_be method is used to fetch a 16-bit value from the
157 * input. The get_byte method is called twice, and the two byte
158 * values are assembled big-endian (most significant byte first).
159 */
160 unsigned get_word_be(void);
161
162 /**
163 * The get_word_le method is used to fetch a 16-bit value from
164 * the input. The get_byte method is called twice, and the two
165 * byte values are assembled little-endian (least significant byte
166 * first).
167 */
168 unsigned get_word_le(void);
169
170 /**
171 * The get_3bytes_be method is used to fetch a 24-bit value from
172 * the input. The get_byte method is called three times,
173 * and the three byte values are assembles big-endian (most
174 * significant byte first).
175 */
176 unsigned long get_3bytes_be(void);
177
178 /**
179 * The get_3bytes_le method is used to fetch a 24-bit value from
180 * the input. The get_byte method is called three times, and the
181 * three byte values are assembled little-endian (least significant
182 * byte first).
183 */
184 unsigned long get_3bytes_le(void);
185
186 /**
187 * The get_4bytes_be method is used to fetch a 32-bit value from
188 * the input. The get_byte method is called four times,
189 * and the four byte values are assembled big-endian (most
190 * significant byte first).
191 */
192 unsigned long get_4bytes_be(void);
193
194 /**
195 * The get_4bytes_le method is used to fetch a 32-bit value from
196 * the input. The get_byte method is called four times, and the
197 * four byte values are assembled little-endian (least significant
198 * byte first).
199 */
200 unsigned long get_4bytes_le(void);
201
202 /**
203 * The checksum_get method is used to get the current value of
204 * the running checksum (added to by the checksum_add method,
205 * usually called by the get_byte method). Only the lower 8
206 * bits of the sum are returned.
207 */
208 int checksum_get(void) const;
209
210 /**
211 * The checksum_get16 method is used to get the current value of
212 * the running checksum (added to by the checksum_add method,
213 * usually called by the get_byte method). Only the lower 16
214 * bits of the sum are returned.
215 */
216 int checksum_get16(void) const;
217
218 /**
219 * The checksum_add method is used to add another 8-bit value
220 * to the running checksum.
221 */
222 virtual void checksum_add(unsigned char n);
223
224 /**
225 * The checksum_rest method is used to set the running checksum
226 * to zero.
227 */
228 void checksum_reset(void);
229
230 /**
231 * The seek_to_end method is used to move the input position
232 * to the end of the file.
233 */
234 void seek_to_end(void);
235
236 /**
237 * The is_binary method is used to to determine whether or not
238 * a file format is binary (true) of text (false). The default
239 * implementation always returns false (text).
240 */
241 virtual bool is_binary(void) const;
242
243private:
244 /**
245 * The file_name instance variable is used by the filename
246 * and filename_and_line methods to report the name of the
247 * input file. This makes for informative error messages.
248 */
249 std::string file_name;
250
251 /**
252 * The line_number instance variable is used by the get_char
253 * method to remember the current line number. It us used by the
254 * filename_and_line method to report the current file location.
255 */
256 int line_number;
257
258 /**
259 * The prev_was_newline instance variable is used by the
260 * get_char method to know when to increment the line number.
261 * It is not done when a newline is seen, but rather on reading
262 * the first character after a newline. In this way, the error
263 * messages refer to the correct line, when if (when) it was
264 * the the error message must be issued only when the whole
265 * line has bean read in, including the newline. error message.
266 */
267 bool prev_was_newline;
268
269 /**
270 * The vfp instance variable is used by the get_fp method to
271 * remember the file pointer. You need to cast it to FILE* before
272 * you use it. Never access this instance variable directly,
273 * always go via the get_fp method. This ensures the file has
274 * been opened first!
275 */
276 void *vfp;
277
278protected:
279 /**
280 * The checksum instance variable is used record the running
281 * checksum. NEVER access this variable directly. Always use
282 * the #checksum_reset method to set it mack to its initial state.
283 * Always use the checksum_add method to add a byte to it.
284 * Always use the #checksum_get or #checksum_get16 methods to
285 * read its value.
286 */
288
289 /**
290 * The use_checksums method is used to determine whether or not to
291 * validate checksums when data is read.
292 *
293 * @returns
294 * bool; true if need to check checksums, false to ignore checksums.
295 */
296 bool use_checksums(void) const { return !ignore_checksums; }
297
298private:
299 /**
300 * The ignore_checksums instance variable is used to remember
301 * whether or not checksums should be ignored (true) or validated
302 * (false).
303 */
304 bool ignore_checksums;
305
306 /**
307 * The ignore_checksums_default class variable is used to remember
308 * the default checksum validation. Defaults to false.
309 */
310 static bool ignore_checksums_default;
311
312 /**
313 * The get_fp method is used to get the stdio file pointer
314 * associated with this input file. (By avoiding a FILE*
315 * declaration, we avoid having to include <stdio.h> for no
316 * particularly good reason. Take care when casting.)
317 *
318 * If the file has not been opened yet, it will be opened by
319 * this method.
320 */
321 void *get_fp(void);
322
323 /**
324 * The default constructor. Do not use.
325 */
326 input_file();
327
328 /**
329 * The copy constructor. Do not use.
330 */
331 input_file(const input_file &);
332
333 /**
334 * the assignment operator. Do not use.
335 */
336 input_file &operator=(const input_file &);
337};
338
339};
340
341// vim: set ts=8 sw=4 et :
342#endif // SRECORD_INPUT_FILE_H
The arglex class is used to implement a lexical analizer for command line arguments.
Definition arglex.h:39
The srecord::input_file class is used to represent an generic input file.
Definition file.h:37
unsigned get_word_be(void)
The get_word_be method is used to fetch a 16-bit value from the input.
virtual std::string filename(void) const
The filename method is used to get the name of the input file being processed.
static void ignore_all_checksums(void)
The ignore_all_checksums method is used to set the global ignore checksums flag.
Definition file.h:62
virtual void checksum_add(unsigned char n)
The checksum_add method is used to add another 8-bit value to the running checksum.
unsigned long get_3bytes_be(void)
The get_3bytes_be method is used to fetch a 24-bit value from the input.
virtual int get_char(void)
The get_char method is used to fetch a character from the input.
void disable_checksum_validation(void)
The disable_checksum_validation method is used to have this input stream ignore checksum errors.
void seek_to_end(void)
The seek_to_end method is used to move the input position to the end of the file.
virtual bool is_binary(void) const
The is_binary method is used to to determine whether or not a file format is binary (true) of text (f...
input_file(const std::string &file_name)
The constructor.
bool use_checksums(void) const
The use_checksums method is used to determine whether or not to validate checksums when data is read.
Definition file.h:296
virtual void get_char_undo(int)
The get_char_undo method is used to return a character to the input.
int checksum_get(void) const
The checksum_get method is used to get the current value of the running checksum (added to by the che...
int peek_char(void)
The peek_char method is used to look at the next character of input, without actually consuming it (a...
unsigned long get_3bytes_le(void)
The get_3bytes_le method is used to fetch a 24-bit value from the input.
virtual std::string filename_and_line(void) const
The filename_and_line method is used to get the name and current line number within the file.
virtual int get_nibble(void)
The get_nibble method is used to fetch one hexadecimal digit from the input, via the get_char method.
unsigned long get_4bytes_le(void)
The get_4bytes_le method is used to fetch a 32-bit value from the input.
static pointer guess(const std::string &file_name, arglex &cmdln)
The guess class method is used to open a file of an unknown type.
static int get_nibble_value(int c)
The get_nibble_value class method is used to translate a character into its hexadecimal value.
unsigned long get_4bytes_be(void)
The get_4bytes_be method is used to fetch a 32-bit value from the input.
virtual int format_option_number(void) const =0
The format_option_number method is used to obtain the option number, which can then be turned into te...
int checksum
The checksum instance variable is used record the running checksum.
Definition file.h:287
int checksum_get16(void) const
The checksum_get16 method is used to get the current value of the running checksum (added to by the c...
unsigned get_word_le(void)
The get_word_le method is used to fetch a 16-bit value from the input.
virtual int get_byte(void)
The get_byte method is used to fetch a byte value from the input.
void checksum_reset(void)
The checksum_rest method is used to set the running checksum to zero.
std::shared_ptr< input_file > pointer
Definition file.h:39
virtual ~input_file()
The destructor.
input()
The default constructor.