"Fossies" - the Fresh Open Source Software Archive

Member "gretl-2019c/doc/tex/hp-output.tex" (24 Jul 2018, 10038 Bytes) of package /linux/misc/gretl-2019c.tar.xz:

As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) TeX and LaTeX source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

1 \chapter{Nice-looking output}
2 \label{chap:formatting}
3
4 \section{Formatted output}
5 \label{sec:printf}
6
7 A common occurrence when you're writing a script---particularly when
8 you intend for the script to be used by others, and you'd like the
9 output to be reasonably self-explanatory---is that you want to output
10 something along the following lines:
11 \begin{code}
12 The coefficient on X is Y, with standard error Z
13 \end{code}
14 where \texttt{X}, \texttt{Y} and \texttt{Z} are placeholders for
15 values not known at the time of writing the script; they will be
16 filled out as the values of variables or expressions when the script
17 is run. Let's say that at run time the replacements in the sentence
18 above should come from variables named \texttt{vname} (a string),
19 \texttt{b} (a scalar value) and \texttt{se} (also a scalar value),
20 respectively.
21
22 Across the spectrum of programming languages there are basically two
23 ways of arranging for this. One way originates in the \textsf{C}
24 language and goes under the name \texttt{printf}. In this approach we
25 (a) replace the generic placeholders \texttt{X}, \texttt{Y} and
27 (b) append the variables (or expressions) that are to be stuck into
28 the text, in order. Here's the hansl version:
29 \begin{code}
30 printf "The coefficient on %s is %g, with standard error %g\n", vname, b, se
31 \end{code}
32 The value of \texttt{vname} replaces the conversion specifier
33 \texttt{\%s},'' and the values of \texttt{b} and \texttt{se} replace
34 the two \texttt{\%g}'' specifiers, left to right. In relation to
35 hansl, here are the basic points you need to know: \texttt{\%s}''
36 pairs with a string argument, and \texttt{\%g}'' pairs with a
37 numeric argument.
38
39 The \textsf{C}-derived \texttt{printf} (either in the form of a
40 function, or in the form of a command as shown above) is present in
41 most serious'' programming languages. It is extremely versatile, and
42 in its advanced forms affords the programmer fine control over
43 the output.
44
45 In some scripting languages, however, \texttt{printf} is reckoned
46 too difficult'' for non-specialist users. In that case some sort of
47 substitute is typically offered. We're skeptical: simplified''
48 alternatives to \texttt{printf} can be quite confusing, and if at some
49 point you want fine control over the output, they either do not
50 support it, or support it only via some convoluted mechanism. A
51 typical alternative looks something like this (please note,
52 \texttt{display} is \textit{not} a hansl command, it's just
53 illustrative):
54 \begin{code}
55 display "The coefficient on ", vname, "is ", b, ", with standard error ", se, "\n"
56 \end{code}
57 That is, you break the string into pieces and intersperse the names of
58 the variables to be printed. The requirement to provide conversion
59 specifiers is replaced by a default automatic formatting of the
60 variables based on their type. By the same token, the command line
61 becomes peppered with mutiple commas and quotation marks. If this looks
62 preferable to you, you are welcome to join one of the gretl mailing
63 lists and argue for its provision!
64
65 Anyway, to be a bit more precise about \cmd{printf}, its syntax goes
66 like this:
67 \begin{flushleft}
68   \texttt{printf \emph{format}, \emph{arguments}}
69 \end{flushleft}
70 The \emph{format} is used to specify the precise way in which you want
71 the \emph{arguments} to be printed.
72
73 \subsection{The format string}
74 \label{sec:fmtstring}
75
76 In the general case the \cmd{printf} format must be an expression that
77 evaluates to a string, but in most cases will just be a \textit{string
78   literal} (an alphanumeric sequence surrounded by double
79 quotes). However, some character sequences in the format have a
80 special meaning. As illustrated above, those beginning with a
81 percent sign (\texttt{\%}) are interpreted as placeholders for the
82 items contained in the argument list. In addition, special characters
83 such as the newline character are represented via a combination
84 beginning with a backslash (\verb|\|).
85
86 For example,
87 \begin{code}
88 printf "The square root of %d is (roughly) %6.4f.\n", 5, sqrt(5)
89 \end{code}
90 will print
91 \begin{code}
92 The square root of 5 is (roughly) 2.2361.
93 \end{code}
94
95 Let's see how:
96 \begin{itemize}
97 \item The first special sequence is \verb|%d|: this indicates that we
98   want an integer at that place in the output; since it is the
99   leftmost percent'' expression, it is matched to the first
100   argument, that is 5.
101 \item The second special sequence is \verb|%6.4f|, which stands for a
102   decimal value with 4 digits after the decimal separator\footnote{The
103     decimal separator is the dot in English, but may be different in
104     other locales.} and at least 6 digits wide; this will be matched
105   to the second argument. Note that arguments are separated by
106   commas. Also note that the second argument is neither a scalar
107   constant nor a scalar variable, but an expression that evaluates to
108   a scalar.
109 \item The format string ends with the sequence \verb|\n|, which
110   inserts a newline.
111 \end{itemize}
112
113 The conversion specifiers in the square-root example are relatively
114 fancy, but as we noted earlier \texttt{\%g} will work fine for
115 almost all numerical values in hansl. So we could have used the
116 simpler form:
117 \begin{code}
118 printf "The square root of %g is (roughly) %g.\n", 5, sqrt(5)
119 \end{code}
120 The effect of \texttt{\%g} is to print a number using up to 6
121 significant digits (but dropping trailing zeros); it automatically
122 switches to scientific notation if the number is very large or very
123 small. So the result here is
124 \begin{code}
125 The square root of 5 is (roughly) 2.23607.
126 \end{code}
127
128 The escape sequences \verb|\n| (newline), \verb|\t| (tab), \verb|\v|
129 (vertical tab) and \verb|\\| (literal backslash) are recognized. To
130 print a literal percent sign, use \verb|%%|.
131
132 Apart from those shown in the above example, recognized numeric
133 formats are \verb|%e|, \verb|%E|, \verb|%f|, \verb|%g|, and \verb|%G|,
134 in each case with the various modifiers available in C. The format
135 \verb|%s| should be used for strings. As in C, numerical values that
136 form part of the format (width and or precision) may be given directly
137 as numbers, as in \verb|%10.4f|, or they may be given as variables. In
138 the latter case, one puts asterisks into the format string and
139 supplies corresponding arguments in order. For example,
140
141 \begin{code}
142   scalar width = 12
143   scalar precision = 6
144   printf "x = %*.*f\n", width, precision, x
145 \end{code}
146
147 If a matrix argument is given in association with a numeric format,
148 the entire matrix is printed using the specified format for each
149 element. A few more examples are given in table \ref{tab:printf-ex}.
150 \begin{table}[htbp]
151   \centering
152    {\small
153     \begin{tabular}{p{0.45\textwidth}p{0.3\textwidth}}
154       \textbf{Command} & \textbf{effect} \\
155       \hline
156       \verb|printf "%12.3f", $pi| & 3.142 \\ 157 \verb|printf "%12.7f",$pi| & 3.1415927 \\
158       \verb|printf "%6s%12.5f%12.5f %d\n", "alpha",| \\
159       \verb|   3.5, 9.1, 3| &
160       \verb| alpha     3.50000     9.10000 3| \\
161       \verb|printf "%6s%12.5f%12.5f\t%d\n", "beta",| \\
162       \verb|   1.2345, 1123.432, %11| &
163       \verb|  beta     1.23450  1123.43200 11| \\
164       \verb|printf "%d, %10d, %04d\n", 1,2,3| &
165       \verb|1,          2, 0003| \\
166       \verb|printf "%6.0f (%5.2f%%)\n", 32, 11.232| & \verb|32 (11.23%)| \\
167       \hline
168     \end{tabular}
169   }
170   \caption{Print format examples}
171   \label{tab:printf-ex}
172 \end{table}
173
174 \subsection{Output to a string}
175 \label{sec:sprintf}
176
177 A closely related effect can be achieved via the \cmd{sprintf}
178 function: instead of being printed directly the result is stored in a
179 named string variable, as in
180 \begin{code}
181   string G = sprintf("x = %*.*f\n", width, precision, x)
182 \end{code}
183 after which the variable \texttt{G} can be the object of further
184 processing.
185
186 \subsection{Output to a file}
187 \label{sec:outfile}
188
189 Hansl does not have a file or stream'' type as such, but the
190 \cmd{outfile} command can be used to divert output to a named text
191 file. To start such redirection you must give the name of a file; by
192 default a new file is created or an existing one overwritten but the
193 \option{append} can be used to append material to an existing file.
194 Only one file can be opened in this way at any given time. The
195 redirection of output continues until the command \cmd{end outfile} is
196 given; then output reverts to the default stream.
197
198 Here's an example of usage:
199 \begin{code}
200   printf "One!\n"
201   outfile "myfile.txt"
202     printf "Two!\n"
203   end outfile
204   printf "Three!\n"
205   outfile "myfile.txt" --append
206     printf "Four!\n"
207   end outfile
208   printf "Five!\n"
209 \end{code}
210 After execution of the above the file \texttt{myfile.txt} will contain
211 the lines
212 \begin{code}
213 Two!
214 Four!
215 \end{code}
216
217 Three special variants on the above are available. If you give the
218 keyword \texttt{null} in place of a real filename along with the write
219 option, the effect is to suppress all printed output until redirection
220 is ended. If either of the keywords \texttt{stdout} or \texttt{stderr}
221 are given in place of a regular filename the effect is to redirect
222 output to standard output or standard error output, respectively.
223
224 This command also supports a \option{quiet} option: its effect is to
225 turn off the echoing of commands and the printing of auxiliary
226 messages while output is redirected. It is equivalent to doing
227 \begin{code}
228   set echo off
229   set messages off
230 \end{code}
231 before invoking \cmd{outfile}, except that when redirection is ended
232 the prior values of the \texttt{echo} and \texttt{messages} state
233 variables are restored.
234
235 \section{Graphics}
236
237 The primary graphing command in hansl is \texttt{gnuplot} which, as
238 the name suggests, in fact provides an interface to the
239 \textsf{gnuplot} program. It is used for plotting series in a dataset
240 (see part~\ref{part:hp-data}) or columns in a matrix. For an account
241 of this command (and some other more specialized ones, such as
242 \texttt{boxplot} and \texttt{qqplot}), see the \GCR.
243
244 %%% Local Variables:
245 %%% mode: latex
246 %%% TeX-master: "hansl-primer"
247 %%% End: