Yorick Cookbook

This page is still in construction. It contains down-to-earth guidelines on how to perform simple, and less simple tasks with yorick. It is to be viewed as a complement to the user manual, the refcard, and the FAQ. This cookbook is definitely not an exhaustive list of all the ways to do thing: instead, we are trying to present things in an easy way, give "recipes", geared to yorick beginners.

Go to:

Installing yorick

There are two ways to install yorick: from sources or from binaries. If you have a C compiler and a make system (gnumake), you can install from source.

From sources on a *nix system

  1. download the latest yorick source tarfile from here
  2. move the tarfile to your root directory
  3. gunzip and untar: gunzip -c yorick???.tgz | tar xvf -
  4. cd to the newly created yorick directory (let's call it yorick-2.1)
  5. type:
    make config
    make
    make check
    make install
  6. Yorick should be installed in yorick-2.1/Your_platform/bin (e.g. yorick-2.1/Linuxi386/bin)
  7. That's it. Now if you want the confort of being able to start yorick by typing "yorick", you have to put the install bin directory in your path, or more likely, you want to put a link to the executable somewhere in your path, e.g.:
    cd ~/bin
    ln -s /your/home/directory/yorick-2.1/Linuxi386/bin/yorick yorick
    
    providing of course ~/bin in in your path... If you don't understand this last point, that's OK, you can still start yorick by writing up the whole path: /path/to/yorick/platform/bin/yorick
  8. The location of the yorick libraries and include files is compiled in. So you can move the yorick executable wherever you want, but you can't move the yorick directory tree.

from binaries

  1. download the last binaries from here (let's call it yorick-2.1 for this exercise).
  2. move the file to your root directory
  3. gunzip and untar: gunzip -c yorick-2.1-01.macosx.tgz | tar xvf - (replace by the equivalent utility on a windows system)
  4. the yorick executable is in the yorick-2.1-01/bin
  5. yorick finds its libraries and include file relative to the executable location, so you can not move the executable w.r.t the yorick directory tree

Running Yorick: Basics

Once you are done with installation and yorick is in your path, start yorick with:
% yorick
 Copyright (c) 1996.  The Regents of the University of California.
 All rights reserved.  Yorick 2.1.01 ready.  For help type 'help'
> 

Now let's do simple things. Below, all of the stuff after "//" are comments I have added:

  1. Assignments:
    > a=1        // assign 1 to the variable "a". a is a scalar.
    > a=[1,2,3]  // a is a vector
    > print,a
    [1,2,3]
    > a
    [1,2,3]      // default action is print to stdout
    
  2. above, as in yorick, the double slash "//" starts a comment ( also "/* comment */")
  3. White space usually do not matter: a=1 is equivalent to a = 1. Except in statements like func, return, for, if, ...
  4. Single statements are separated by semi-colon:
    > a=1; b=2; print,a+b;
    3
    
  5. Short hand statements as below are understood by yorick:
    > a=b=c=3.; a+=2; b*=c; print,a,b,c;
    5   // this is a
    9   // this is b
    3   // this is c
    
    For those who are not familiar with it: a+=2 is a short hand for a=a+2.
  6. You can do operations on arrays without looping on their elements (in fact, you should, this is all the beauty and power of yorick):
    > a=[1,2,3]; b=[6,7,8]; a+b
    [7,9,11]
    
  7. the info function describe the type of variable/entity one is dealing with:
    > a = [1,2,3]
    > info,a
     array(long,3)
    > info,[1.,2,3]
     array(double,3)
    > info,random
    builtin random()   // "Builtin" function (compiled, yorick core)
    > info,dist    
    func dist(dim,xc=,yc=)  // interpreted function
    
  8. The help function prints out the "manpage" for the given function:
    > help,quit
     /* DOCUMENT quit
          Exit YMainLoop when current task finishes.
          Normally this terminates the program.
      */
     defined at:  LINE: 185  FILE: /Users/frigaut/yorick-2.1/i0/std.i
    
  9. and much much more, but I will not cover it yet. Refer to the yorick manual or refcard for more about array syntax, indices, etc...
  10. "quit" exits the yorick session.

Writing a function

In yorick, you can write your own functions. Nothing is easier:
  1. Open your favorite text editor (not word, but something that processes and writes out simple ascii, like emacs, vi, nedit, notepad, ...)
  2. Type in. A function looks like
    func myfunc(parameters, keywords)
    {
      instructions;
      return result;
    }
    
    where the keywords and return statements are optional, depending on what you want to do. Heck, even the parameters and instructions are optional (although I don't see the purpose of the function is there are no instructions).
  3. Example:
    func add_arrays(a,b)
    {
      c = a+b;
      return c;
    }
    
    note that the semi-colons are important. Yorick uses this to separate statements that otherwise can span more than one line (I advise however to use the line continuation "\" character when writing multi-line statements). The brace {} are also important, as they define the limit of a group of statements. The spaces and indentations are optional and just here for ease of readability.
  4. Save the function in, say, "myfunc.i"
  5. Include it in yorick:
    > #include "myfunc.i"
    
  6. Now the function add_arrays is available.
    > print,add_arrays(2,3)
    5
    
  7. There are no pre-requisite for the carriage returns in the function as defined above. You could have written:
    func add_arrays(a,b){c=a+b;return c;}
    and in fact, you can define this function on the fly at the yorick prompt:
    > func add_arrays(a,b){c=a+b;return c;}
    > print,add_arrays(2,3)
    5
    > a = array(21,[2,4,4]); print,add_arrays(4.5,a)
    [[25.5,25.5,25.5,25.5],[25.5,25.5,25.5,25.5],[25.5,25.5,25.5,25.5],[25.5,25.5,
    25.5,25.5]]
    > 
    
  8. There is only one form of function/subroutine/procedure: a "function". If you want the "function" to do something but you don't need any return, just omit the "return" statement at the end. Return statement can only return one entity. It can be a scalar, an array, a structure or a pointer, but you can't return multiple entities (like return a,b; for instance)
  9. When you call a function, you can call it as a function:
    c = add_arrays(a,b)
    
    or as a "subroutine":
    add_arrays,a,b
    
    in the last case, yorick knows that it should not execute the return statement (there is nothing to put the return variable in!). Of course in this example it doesn't make sense to not return the result, as otherwise the function does absolutely nothing, but you see the picture.
  10. Keywords: You can pass keywords to your function, as in
    func add_arrays(a,b,scale=)
    {
      c = (a+b)*scale;
      return c;
    }
    
    and the you call the function as:
    c = add_arrays(a,b,scale=4.56)
    
    Usually, keywords are used to pass optional parameters. So in this example it would not work. Indeed, if you call c = add_arrays(a,b) yorick will complain about an undefined variable when it comes to the c =(a+b)*scale line. To solve this problem, test if "scale" is known and set a default value:
    func add_arrays(a,b,scale=)
    {
      if (scale==[]) scale=1.;
      c = (a+b)*scale;
      return c;
    }
    This way, if scale is not defined, it will take the value 1 ( the open-close square bracket stands for a NULL -undefined- entity).
  11. Sometime, you may want to pass variables to a function and have them modified, on top of the function return value. In that case you should explicitly let yorick know that an input variable has to be "returned" modified by putting a "&" sign in front of the variable name in the function header:
    > func add_arrays_plus_one(a,&b){ a+=1; b+=1; return a+b;}   
    > a=2;b=2;r=add_arrays_plus_one(a,b)
    > r
    6
    > a
    2
    > b
    3
    
    Did you follow? In this example, although a and b were added "1" in the function, only b was actually changed at the main level because we asked for the b value affected by the function to be returned by pre-pending the &.