"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
   26 \texttt{Z} with more informative \textit{conversion specifiers}, 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: