Special commands

A set of special functions has been written for user convenience. They are provided as methods of the modules pysic, pygreg, ... if SIC is launched from Python, and also in every case as methods of an instance called Sic in the Python __main__ (see subsection 2.3.4):

• comm(string): takes a string as argument and sends it to the SIC interpreter, which will execute it. If SIC fails to interpret the command, or if the command itself returns an error, comm will raise an error in Python⁷. As usual in Python, it can be catched with the try and except couple of directives.

• setgdict(dictionary): define input dictionary as the area where Gildas variables will be imported, and automatically import these into the input dictionary. If a dictionary was already defined, it is first cleaned before filling the new one given in input.
  A call to this function is required if user wants to access the imported variables. This avoids polluting name areas because of uncontroled default. In interactive mode, the most common usage is to use the current name area, e.g. setgdict(globals()); print pi. In script mode, prefer using a custom dictionary, e.g. d = dict(); setgdict(d); print d['pi'], or even better the gdict container (see subsection 2.3.3).

• get([string[,integer[,boolean]]]): Takes a string as argument, which must be a valid SIC name (in SIC format, thus not case sensitive). Variable can be a scalar, an array, a structure, an header, a table, or an image. The second argument may be the level of the variable to be imported (0 = global, 1 = 1-local, and so on). It defaults to the current execution level. A third argument indicates if the function should be verbose (True, default), or not ( False).
  `get()' creates a SicVar or a SicStructure instance sharing its data with the corresponding variable in SIC. Its name is the original SIC name, but lowercased, and converted in respect with the Python name conventions (see table 1). '$' can not appear in Python names: it is converted to `_'. `%' (structures in SIC) has a special treatment and is converted to `.' (see subsection 2.4.3). All structures elements are linked to the corresponding SicStructure as SicVar (or SicStructure) attributes, and all header components of the images are linked to the corresponding SicVar as SicVar attributes.
  `get()' fails to import variable into Python when its converted name is a Python reserved keyword (such as ` def', `del', `import', `as', ...), or a built-in function name (such as `type', `range', `min', `max', ...).
  With no argument, `get()' imports all SIC variables by iteratively calling `get()' itself with their names as argument.

  
  

  
  

  Table 1: SIC to Python names conversion

  SIC	Python
  "ABC"	"abc"
  "ABC$DEF"	"abc_def"
  "ABC%DEF"	"abc.def"

  
  

• exa([var1[,var2[,...]]]): with one or more SicVar or SicStructure instances as argument, displays one line per instance with the corresponding SIC variable name, details on its type, dimensions,... With no argument, displays this line for the full list of the SIC variables. Example:

  >>> exa(pi)
  PI               is a        REAL*8, 0D            (GLOBAL,RO) -> pi
  

• define(string[,boolean]): takes one string as argument and defines one or more variables in both SIC and Python. First keyword must be the type (one of real, double, integer, character or structure, or a non-ambiguous truncated form of them), followed by one or more valid variable-creator SIC name (e.g. `A', `B*8', `C[2]', `D%E' or even `F%G*8[2,3]'). All variables created this way are read-and-write. By default they are local to the current execution level, but you can provide a second optional argument set to True to make the variables global. For images, give the command line you would give to the SIC interpreter, but without the define keyword. exa() is finally called on the newly created instance(s). Examples:

  >>> define('real a')
   A               is a        REAL*4, 0D            (GLOBAL,RW) -> a
  >>> define('double b c[2] d[2,3]')
   B               is a        REAL*8, 0D            (GLOBAL,RW) -> b
   C               is a        REAL*8, 1D (2x0x0x0)  (GLOBAL,RW) -> c
   D               is a        REAL*8, 2D (2x3x0x0)  (GLOBAL,RW) -> d
  >>> define('structure e')
   E               is a   <structure>, 0D            (GLOBAL,RW) -> e
  >>> define('character e%f e%g*6[2,3]')
   E%F             is a   CHARACTER*1, 0D            (GLOBAL,RW) -> e.f
   E%G             is a   CHARACTER*6, 2D (2x3x0x0)  (GLOBAL,RW) -> e.g
  >>> define('image h centaurus.gdf read')
   H               is a (image)REAL*4, 2D (512x512x1x1) (GLOBAL,RO) -> h
  

• delete(var1[,var2[,...]]): takes one or more SicVar or SicStructure instances as arguments. Tries to delete the corresponding variable in SIC. On success, also deletes the input instance.

• getlogical(string): takes one Python string as argument. The method translates a SIC logical and returns it as a Python string. Input name is case insensitive. An empty string is returned if no such SIC logical exists (no error is raised).