"Fossies" - the Fresh Open Source Software Archive

Member "gretl-2020e/doc/tex/hp-hello.tex" (29 Aug 2019, 13645 Bytes) of package /linux/misc/gretl-2020e.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{Hello, world!}
2 \label{chap:hello}
3
4 We begin with the time-honored Hello, world'' program, the
5 obligatory first step in any programming language. It's actually very
6 simple in hansl:
7 \begin{code}
8   # First example
9   print "Hello, world!"
10 \end{code}
11
12 There are several ways to run the above example: you can put it in a
13 text file \texttt{first\_ex.inp} and have gretl execute it from the
14 command line through the command
15 \begin{code}
16   gretlcli -b first_ex.inp
17 \end{code}
18 or you could just copy its contents in the editor window of a GUI
19 gretl session and click on the gears'' icon. It's up to you; use
20 whatever you like best.
21
22 From a syntactical point of view, allow us to draw attention on
23 the following points:
24 \begin{enumerate}
25 \item The line that begins with a hash mark (\texttt{\#}) is a
26   comment: if a hash mark is encountered, everything from that point
27   to the end of the current line is treated as a comment, and ignored
28   by the interpreter.
29 \item The next line contains a \emph{command} (\cmd{print}) followed
30   by an \emph{argument}; this is fairly typical of hansl: many jobs
31   are carried out by calling commands.
32 \item Hansl does not have an explicit command terminator such as the
33   \texttt{;}'' character in the C language family (C++, Java, C\#,
34   \ldots) or GAUSS; instead it uses the newline character as an
35   implicit terminator. So at the end of a command, you \emph{must}
36   insert a newline; conversely, you \emph{can't} put a newline in the
37   middle of a command---or not without taking special measures. If you
38   need to break a command over more than one line for the sake of
39   legibility you can use the \textbackslash'' (backslash) character,
40   which causes gretl to ignore the following line break.
41 \end{enumerate}
42
43 Note also that the \cmd{print} command automatically appends a line
44 break, and does not recognize escape'' sequences such as
45 \verb|\n|''; such sequences are just printed literally. The
46 \cmd{printf} command can be used for greater control over output; see
47 chapter \ref{chap:formatting}.
48
49 Let's now examine a simple variant of the above:
50 \begin{code}
51   /*
52     Second example
53   */
54   string foo = "Hello, world"
55   print foo
56 \end{code}
57
58 In this example, the comment is written using the convention adopted
59 in the C programming language: everything between \verb|/*|'' and
60 \verb|*/|'' is ignored.\footnote{Each type of comment can be masked
61   by the other:
62 \begin{itemize}
63 \item If \texttt{/*} follows \texttt{\#} on a given line which does
64   not already start in ignore mode, then there's nothing special about
65   \texttt{/*}, it's just part of a \texttt{\#}-style comment.
66 \item If \texttt{\#} occurs when we're already in comment mode, it is
67   just part of a comment.
68 \end{itemize}} Comments of this type cannot be nested.
69
70 Then we have the line
71 \begin{code}
72   string foo = "Hello, world"
73 \end{code}
74 In this line, we assign the value \texttt{Hello, world}'' to the
75 variable named \texttt{foo}. Note that
76 \begin{enumerate}
77 \item The assignment operator is the equals sign (\texttt{=}).
78 \item The name of the variable (its \emph{identifier}) must follow the
79   following convention: identifiers can be at most 31 characters long
80   and must be plain ASCII. They must start with a letter, and can
81   contain only letters, numbers and the underscore
82   character.\footnote{Actually one exception to this rule is
83     supported: identifiers taking the form of a single Greek
84     letter. See chapter~\ref{chap:greeks} for details.} Identifiers in
85   hansl are case-sensitive, so \texttt{foo}, \texttt{Foo} and
86   \texttt{FOO} are three distinct names. Of course, some words are
87   reserved and can't be used as identifiers (however, nearly all
88   reserved words only contain lowercase characters).
89 \item The string delimiter is the double quote (\verb|"|).
90 \end{enumerate}
91
92 In hansl, a variable has to be of one of these types: \texttt{scalar},
93 \texttt{series}, \texttt{matrix}, \texttt{list}, \texttt{string},
94 \texttt{bundle} or \texttt{array}. As we've just seen, string
95 variables are used to hold sequences of alphanumeric characters. We'll
96 introduce the other ones gradually; for example, the \texttt{matrix}
97 type will be the object of the next chapter.
98
99 The reader may have noticed that the line
100 \begin{code}
101   string foo = "Hello, world"
102 \end{code}
103 implicitly performs two tasks: it \emph{declares} \texttt{foo} as a
104 variable of type \texttt{string} and, at the same time, \emph{assigns}
105 a value to \texttt{foo}. The declaration component is not strictly
106 required. In most cases gretl is able to figure out by itself what
107 type a newly introduced variable should have, and the line
108 \verb|foo = "Hello, world"| (without a type specifier) would have
109 worked just fine.  However, it is more elegant (and leads to more
110 legible and maintainable code) to use a type specifier at least the
111 first time you introduce a variable.
112
113 In the next example, we will use a variable of the \texttt{scalar}
114 type:
115 \begin{code}
116   scalar x = 42
117   print x
118 \end{code}
119 A \texttt{scalar} is a double-precision floating point number, so
120 \texttt{42} is the same as \texttt{42.0} or \texttt{4.20000E+01}. Note
121 that hansl doesn't have a separate variable type for integers or
122 complex numbers.
123
124 An important detail to note is that, contrary to most other
125 matrix-oriented languages in use in the econometrics community, hansl
126 is \emph{strongly typed}. That is, you cannot assign a value of one
127 type to a variable that has already been declared as having a
128 different type. For example, this will return an error:
129 \begin{code}
130   string a = "zoo"
131   a = 3.14 # no, no, no!
132 \end{code}
133 If you try running the example above, an error will be
134 flagged. However, it is acceptable to destroy the original variable,
135 via the \cmd{delete} command, and then re-declare it, as in
136 \begin{code}
137   scalar X = 3.1415
138   delete X
139   string X = "apple pie"
140 \end{code}
141
142 There is no type-casting'' as in C, but some automatic type
143 conversions are possible (more on this later).
144
145 Many commands can take more than one argument, as in
146 \begin{code}
147   set echo off
148   set messages off
149
150   scalar x = 42
151   string foo = "not bad"
152   print x foo
153 \end{code}
154 In this example, one \texttt{print} is used to print the values of two
155 variables; more generally, \texttt{print} can be followed by as many
156 arguments as desired. The other difference with respect to the
157 previous code examples is in the use of the two \texttt{set}
158 commands. Describing the \texttt{set} command in detail would lead us
159 to an overly long diversion; suffice it to say that this command is
160 used to set the values of various state variables'' that influence
161 the behavior of the program; here it is used as a way to silence
162 unwanted output. See the \GCR{} for more on \texttt{set}.
163
164 % There was a reference here to a {chap:settings}, but it has not
165 % been written at this point
166
167 The \cmd{eval} command is useful when you want to look at the result
168 of an expression without assigning it to a variable; for example
169 \begin{code}
170   eval 2+3*4
171 \end{code}
172 will print the number 14. This is most useful when running gretl
173 interactively, like a calculator, but it is usable in a hansl script
174 for checking purposes, as in the following (rather silly) example:
175 \begin{code}
176   scalar a = 1
177   scalar b = -1
178   # this ought to be 0
179   eval a+b
180 \end{code}
181
182 \section{Manipulation of scalars}
183
184 Algebraic operations work in the obvious way, with the classic
185 algebraic operators having their traditional precedence rules: the
186 caret (\verb|^|) is used for exponentiation. For example,
187 \begin{code}
188   scalar phi = exp(-0.5 * (x-m)^2 / s2) / sqrt(2 * $pi * s2) 189 \end{code} 190 %$
191 in which we assume that \texttt{x}, \texttt{m} and \texttt{s2} are
192 pre-existing scalars. The example above contains two noteworthy
193 points:
194 \begin{itemize}
195 \item The usage of the \cmd{exp} (exponential) and \cmd{sqrt} (square
196   root) functions; it goes without saying that hansl possesses a
197   reasonably wide repertoire of such functions. See the \GCR{} for the
198   complete list.
199 \item The usage of \verb|$pi| for the constant$\pi$. While 200 user-specified identifiers must begin with a letter, built-in 201 identifiers for internal objects typically have a dollar'' prefix; 202 these are known as \emph{accessors} (basically, read-only 203 variables). Most accessors are defined in the context of an open 204 dataset (see part~\ref{part:hp-data}), but some represent 205 pre-defined constants, such as$\pi\$. Again, see the \GCR{} for a
206   comprehensive list.
207 \end{itemize}
208
209 Hansl does not possess a specific Boolean type, but scalars can be
210 used for holding true/false values. It follows that you can also use
211 the logical operators \emph{and} (\verb|&&|), \emph{or} (\verb+||+),
212 and \emph{not} (\verb|!|) with scalars, as in the following example:
213 \begin{code}
214   a = 1
215   b = 0
216   c = !(a && b)
217 \end{code}
218 In the example above, \texttt{c} will equal 1 (true), since
219 \verb|(a && b)| is false, and the exclamation mark is the negation
220 operator.  Note that 0 evaluates to false, and anything else (not
221 necessarily 1) evaluates to true.
222
223 A few constructs are taken from the C language family: one is the
224 postfix increment operator:
225 \begin{code}
226   a = 5
227   b = a++
228   print a b
229 \end{code}
230 the second line is equivalent to \texttt{b = a}, followed by
231 \texttt{a++}, which in turn is shorthand for \texttt{a = a+1}, so
232 running the code above will result in \texttt{b} containing 5 and
233 \texttt{a} containing 6. Postfix subtraction is also supported; prefix
234 operators, however, are not supported. Another C borrowing is
235 inflected assignment, as in \texttt{a += b}, which is equivalent to
236 \texttt{a = a + b}; several other similar operators are available,
237 such as \texttt{-=}, \texttt{*=} and more. See the \GCR{} for details.
238
239 The internal representation for a missing value is \texttt{NaN} (not
240 a number''), as defined by the IEEE 754 floating point standard.  This
241 is what you get if you try to compute quantities like the square root
242 or the logarithm of a negative number. You can also set a value to
243 missing'' directly using the keyword \texttt{NA}.  The complementary
244 functions \cmd{missing} and \cmd{ok} can be used to determine whether
245 a scalar is \texttt{NA}. In the following example a value of zero is
246 assigned to the variable named \texttt{test}:
247 \begin{code}
248   scalar not_really = NA
249   scalar test = ok(not_really)
250 \end{code}
251 Note that you cannot test for equality to \texttt{NA}, as in
252 \begin{code}
253   if x == NA ... # wrong!
254 \end{code}
255 because a missing value is taken as indeterminate and hence not equal
256 to anything. This last example, despite being wrong, illustrates a
257 point worth noting: the test-for-equality operator in hansl is the
258 double equals sign, \texttt{==}'' (as opposed to plain
259 \texttt{=}'' which indicates assignment).
260
261 \section{Manipulation of strings}
262
263 Most of the previous section applies, with obvious modifications, to
264 strings: you may manipulate strings via operators and/or
265 functions. Hansl's repertoire of functions for manipulating strings
266 offers all the standard capabilities one would expect, such as
267 \cmd{toupper}, \cmd{tolower}, \cmd{strlen}, etc., plus some more
268 specialized ones. Again, see the \GCR\ for a complete list.
269
270 In order to access part of a string, you may use the \cmd{substr}
271 function,\footnote{Actually, there is a cooler method, which uses the
272   same syntax as matrix slicing (see chapter \ref{chap:matrices}):
273   \cmd{substr(s, 3, 5)} is functionally equivalent to \cmd{s[3:5]}.} as in
274 \begin{code}
275   string s = "endogenous"
276   string pet = substr(s, 3, 5)
277 \end{code}
278 which would result to assigning the value \texttt{dog} to the variable
279 \texttt{pet}.
280
281 The following are useful operators for strings:
282 \begin{itemize}
283 \item the \verb|~| operator, to join two or more strings, as
284   in\footnote{On some national keyboards, you don't have the tilde
285     (\texttt{\~}) character. In gretl's script editor, this can be
286     obtained via its Unicode representation: type Ctrl-Shift-U,
287     followed by \texttt{7e}.}
288   \begin{code}
289     string s1 = "sweet"
290     string s2 = "Home, " ~ s1 ~ " home."
291   \end{code}
292 \item the closely related \verb|~=| operator, which acts as an
293   inflected assignment operator (so \verb|a ~= "_ij"| is equivalent to
294   \verb|a = a ~ "_ij"|);
295 \item the offset operator \texttt{+}, which yields a substring of the
296   preceding element, starting at the given character offset.  An empty
297   string is returned if the offset is greater than the length of the
298   string in question.
299 \end{itemize}
300
301 A noteworthy point: strings may be (almost) arbitrarily long;
302 moreover, they can contain special characters such as line breaks and
303 tabs. It is therefore possible to use hansl for performing rather
304 complex operations on text files by loading them into memory as a very
305 long string and then operating on that; interested readers should take
306 a look at the \cmd{readfile}, \cmd{getline}, \cmd{strsub} and
307 \cmd{regsub} functions in the \GCR.\footnote{We are not claiming that
308   hansl would be the tool of choice for text processing in
309   general. Nonetheless the functions mentioned here can be very useful
310   for tasks such as pre-processing plain text data files that do not
311   meet the requirements for direct importation into gretl.}
312
313 For \emph{creating} complex strings, the most flexible tool is the
314 \cmd{sprintf} function. Its usage is illustrated in
315 Chapter~\ref{chap:formatting}.
316
317 % Finally, it is quite common to use \emph{string
318 %   substitution} in hansl sripts; however, this is another topic that
319 % deserves special treatment so we defer its description to section
320 % \ref{sec:stringsub}.
321
322 %%% Local Variables:
323 %%% mode: latex
324 %%% TeX-master: "hansl-primer"
325 %%% End: