"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}
    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}
   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.
   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}
   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}.
   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}
   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.
   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}
   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.
   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.
  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.
  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}
  142 There is no ``type-casting'' as in C, but some automatic type
  143 conversions are possible (more on this later).
  145 Many commands can take more than one argument, as in
  146 \begin{code}
  147   set echo off
  148   set messages off
  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}.
  164 % There was a reference here to a {chap:settings}, but it has not
  165 % been written at this point
  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}
  182 \section{Manipulation of scalars}
  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}
  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.
  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.
  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).
  261 \section{Manipulation of strings}
  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.
  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}.
  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}
  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.}
  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}.
  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}.
  322 %%% Local Variables: 
  323 %%% mode: latex
  324 %%% TeX-master: "hansl-primer"
  325 %%% End: