Syntax

From DavinciWiki
(Difference between revisions)
Jump to: navigation, search
m (Protected "Syntax" [edit=sysop:move=sysop])
 
(8 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
{{DavinciWiki_Glossary|
+
{{DavinciWiki_NavBar}}
 +
==Quick Reference==
 
   
 
   
−
+
====Pass-by-reference arguments====
−
'''Quick Reference'''
+
−
+
−
''Pass-by-reference arguments''
+
 
* Format: '''arg1 = TYPE'''
 
* Format: '''arg1 = TYPE'''
 
* Called either by explicitly declaring
 
* Called either by explicitly declaring
Line 10: Line 8:
 
** "b = function(a)"
 
** "b = function(a)"
 
   
 
   
−
''Pass-by-value arguments''
+
====Pass-by-value arguments====
 
* Format: '''arg1'''
 
* Format: '''arg1'''
 
* Called only by specifying a value to pass
 
* Called only by specifying a value to pass
−
** "b = function(a)
+
** "b = function(a)"
 
   
 
   
−
''Optional arguments''
+
====Optional arguments====
 
* Format: '''[arg1 = TYPE]'''
 
* Format: '''[arg1 = TYPE]'''
 
* Called only when needed
 
* Called only when needed
 
   
 
   
 
   
 
   
−
'''Detailed Description'''
+
==Detailed Description==
 
   
 
   
 
The single-line function usage statement is meant to be a quick reference on how to call a function.  Within the parentheses are listed the arguments (or inputs) needed to properly call the function. As not all arguments are passed to the function the same way, the syntax of the argument declaration tells the user how to pass it.
 
The single-line function usage statement is meant to be a quick reference on how to call a function.  Within the parentheses are listed the arguments (or inputs) needed to properly call the function. As not all arguments are passed to the function the same way, the syntax of the argument declaration tells the user how to pass it.
Line 26: Line 24:
 
Most inputs in davinci functions are davinci objects either stored in variables or created during the function call.  The function usage statement will sometimes contain a declaration telling the user what type of data is expected for a specific input (in the case of explicit pass-by-reference inputs).
 
Most inputs in davinci functions are davinci objects either stored in variables or created during the function call.  The function usage statement will sometimes contain a declaration telling the user what type of data is expected for a specific input (in the case of explicit pass-by-reference inputs).
 
   
 
   
−
'''Input Types:'''
+
==Input Types==
 
#BYTE    - values from 0 to 255   
 
#BYTE    - values from 0 to 255   
 
#SHORT    - values from -32768 to 32768
 
#SHORT    - values from -32768 to 32768
Line 38: Line 36:
 
   
 
   
 
   
 
   
−
Davinci objects, as arguments, may be passed by reference (explicit) or passed by value (inexplicit). Arguments passed by reference explicitly tell the user the name of the variable as it is called and manipulated within the function (ideally it is also intuitively descriptive) followed by an "=" sign and ended with the type of data (in capital letters) that should be passed (types 1 - 9) above.  
+
Davinci objects, as arguments, may be passed by reference (explicit) or passed by value (inexplicit).  
 +
 +
 +
==Pass by Reference==
 +
 +
Arguments passed by reference explicitly tell the user the name of the variable as it is called and manipulated within the function (ideally it is also intuitively descriptive) followed by an "=" sign and ended with the type of data (in capital letters) that should be passed (types 1 - 9) above.  
 
   
 
   
 
The format of a function usage statement with an explicit pass-by-reference argument looks like this:
 
The format of a function usage statement with an explicit pass-by-reference argument looks like this:
 
   
 
   
 
  function1(variable_name = TYPE)
 
  function1(variable_name = TYPE)
 +
 
   
 
   
 
An example of such a function usage statement is [[abs]]():
 
An example of such a function usage statement is [[abs]]():
 
   
 
   
 
  abs(obj = VAL)
 
  abs(obj = VAL)
 +
 
   
 
   
 
The function [[abs]]() returns the absolute value of the given numeric davinci object of any numeric type of any three dimensions.
 
The function [[abs]]() returns the absolute value of the given numeric davinci object of any numeric type of any three dimensions.
Line 57: Line 62:
 
  5x1x1 array of int, bsq format [20 bytes]
 
  5x1x1 array of int, bsq format [20 bytes]
 
  1      -6      -4      3      8
 
  1      -6      -4      3      8
 +
 
   
 
   
 
We can feed this array, held in the variable 'a', into [[abs]]() by explicitly typing out that we want the 'obj' variable inside the [[abs]]() function to be equal to our variable 'a' like so:
 
We can feed this array, held in the variable 'a', into [[abs]]() by explicitly typing out that we want the 'obj' variable inside the [[abs]]() function to be equal to our variable 'a' like so:
Line 63: Line 69:
 
  5x1x1 array of float, bsq format [20 bytes]
 
  5x1x1 array of float, bsq format [20 bytes]
 
  1.00000 6.00000 4.00000 3.00000 8.00000
 
  1.00000 6.00000 4.00000 3.00000 8.00000
 +
 
   
 
   
 
Alternatively, [[abs]]() is also capable of accepting the shorthand call:
 
Alternatively, [[abs]]() is also capable of accepting the shorthand call:
Line 69: Line 76:
 
  5x1x1 array of float, bsq format [20 bytes]
 
  5x1x1 array of float, bsq format [20 bytes]
 
  1.00000 6.00000 4.00000 3.00000 8.00000
 
  1.00000 6.00000 4.00000 3.00000 8.00000
 +
 
   
 
   
 
   
 
   
 +
==Pass by Value==
 +
 
 
Arguments passed by value simply state a descriptive name for the variable to indicate to the user what kind of data is required.  In this case, the name of the argument should not be explicitly declared when calling the function.  In general, arguments passed by value are simply ordered inputs with no labels.
 
Arguments passed by value simply state a descriptive name for the variable to indicate to the user what kind of data is required.  In this case, the name of the argument should not be explicitly declared when calling the function.  In general, arguments passed by value are simply ordered inputs with no labels.
 
   
 
   
Line 76: Line 86:
 
   
 
   
 
  function1(descriptive_name1, descriptive_name2)
 
  function1(descriptive_name1, descriptive_name2)
 +
 
   
 
   
 
And an example:
 
And an example:
  
 
  ctof(object)
 
  ctof(object)
 +
 
   
 
   
 
[[ctof]]() converts a numeric array containing temperatures in celsius to fahrenheit.  It doesn't have an internal variable called 'object' but rather the word 'object' attempts to describe to the user what to do.  This function can only be called one way:
 
[[ctof]]() converts a numeric array containing temperatures in celsius to fahrenheit.  It doesn't have an internal variable called 'object' but rather the word 'object' attempts to describe to the user what to do.  This function can only be called one way:
Line 91: Line 103:
 
  dv> ctof(124)
 
  dv> ctof(124)
 
  255.200
 
  255.200
 +
 
   
 
   
 
If the user attempts an explicit variable declaration Davinci returns an error:
 
If the user attempts an explicit variable declaration Davinci returns an error:
Line 96: Line 109:
 
  dv> ctof(object = a)
 
  dv> ctof(object = a)
 
  error: Unknown keyword to ufunc: ctof(... object= ...)
 
  error: Unknown keyword to ufunc: ctof(... object= ...)
 +
 
   
 
   
 
   
 
   
−
'''Optional Inputs:'''
+
==Optional Inputs==
  
 
By allowing some inputs to be optional, davinci has the ability to have preset values that the user doesn't need to enter for the function to work.  A good example of this usage is assuming an ignore value in functions like [[thm.deplaid]].
 
By allowing some inputs to be optional, davinci has the ability to have preset values that the user doesn't need to enter for the function to work.  A good example of this usage is assuming an ignore value in functions like [[thm.deplaid]].
Line 105: Line 119:
  
 
  For example:  
 
  For example:  
−
  function(obj = VAR, [ ignore = FLOAT ])
+
  function(obj = VAR [, ignore = FLOAT ])
−
  function($1 = VAR, [ $2 = FLOAT ])
+
  function($1 = VAR [, $2 = FLOAT ])
  
  
  
−
 
−
'''Definition of Inputs:'''
 
−
 
−
For all examples, [[thm.rectify]] will be used.  This is a special type of function where both explicit and non-explicit argument passing can be used.  There are several other functions like this special one but each of the individual cases is applicable to davinci functions where they apply.
 
−
 
−
In the explicit definition of inputs, the variable name will appear and be followed by the type of data it accepts.
 
−
 
−
For example:
 
−
function(obj = VAR, ignore = FLOAT )
 
−
 
−
dv> a
 
−
577x1852x10 array of float, bsq format [42,744,160 bytes]
 
−
dv> a = thm.rectify(obj = a, ignore = -32768)
 
−
struct, 4 elements
 
−
    data: 301x1883x10 array of float, bsq format [22,671,320 bytes]
 
−
    leftedge: 1x1883x1 array of int, bsq format [7,532 bytes]
 
−
    width: 577
 
−
    angle: 3.052882433
 
−
 
−
 
−
After the function definition, the meaning each input will be explained.
 
−
 
−
For example:
 
−
where
 
−
obj is the input data
 
−
ignore is the ignore value with default -32768
 
−
 
−
 
−
In the non-explicit definition of inputs, the argument number ($1, $2,...,$n) will be shown follwed by the type of data it accepts.
 
−
 
−
For example:
 
−
function($1 = VAR, $2 = FLOAT )
 
−
 
−
dv> a
 
−
577x1852x10 array of float, bsq format [42,744,160 bytes]
 
−
dv> a = thm.rectify(a, -32768)
 
−
struct, 4 elements
 
−
    data: 301x1883x10 array of float, bsq format [22,671,320 bytes]
 
−
    leftedge: 1x1883x1 array of int, bsq format [7,532 bytes]
 
−
    width: 577
 
−
    angle: 3.052882433
 
−
 
−
 
−
'''Optional Inputs:'''
 
−
 
−
By allowing some inputs to be optional, davinci has the ability to have preset values that the user doesn't need to enter for the function to work.  A good example of this usage is assuming an ignore value in functions like [[thm.deplaid]].
 
−
 
−
Optional inputs are enclosed by square brackets ( [  ] ) and defined as ususal.
 
−
 
−
For example:
 
−
function(obj = VAR, [ ignore = FLOAT ])
 
−
function($1 = VAR, [ $2 = FLOAT ])
 
−
 
−
}}
 
  
 
[[category:Glossary]]
 
[[category:Glossary]]

Latest revision as of 11:03, 25 June 2007

Contents

[edit] Quick Reference

[edit] Pass-by-reference arguments

  • Format: arg1 = TYPE
  • Called either by explicitly declaring
    • "b = function(a = INT)" or
    • "b = function(a)"

[edit] Pass-by-value arguments

  • Format: arg1
  • Called only by specifying a value to pass
    • "b = function(a)"

[edit] Optional arguments

  • Format: [arg1 = TYPE]
  • Called only when needed


[edit] Detailed Description

The single-line function usage statement is meant to be a quick reference on how to call a function. Within the parentheses are listed the arguments (or inputs) needed to properly call the function. As not all arguments are passed to the function the same way, the syntax of the argument declaration tells the user how to pass it.

Most inputs in davinci functions are davinci objects either stored in variables or created during the function call. The function usage statement will sometimes contain a declaration telling the user what type of data is expected for a specific input (in the case of explicit pass-by-reference inputs).

[edit] Input Types

  1. BYTE - values from 0 to 255
  2. SHORT - values from -32768 to 32768
  3. INT - values from -2,147,483,648 to +2,147,483,647
  4. FLOAT - values from -3.402822655e+38 to +3.402822655e+38
  5. DOUBLE - values from
  6. VAL - any type of numeric value (types 1 - 5 above)
  7. STRUCT - a davinci structure containing specified elements
  8. STRING - a arbitrary length object composed of characters
  9. TEXT - an array of strings


Davinci objects, as arguments, may be passed by reference (explicit) or passed by value (inexplicit).


[edit] Pass by Reference

Arguments passed by reference explicitly tell the user the name of the variable as it is called and manipulated within the function (ideally it is also intuitively descriptive) followed by an "=" sign and ended with the type of data (in capital letters) that should be passed (types 1 - 9) above.

The format of a function usage statement with an explicit pass-by-reference argument looks like this: 

function1(variable_name = TYPE)


An example of such a function usage statement is abs(): 

abs(obj = VAL)


The function abs() returns the absolute value of the given numeric davinci object of any numeric type of any three dimensions.

The user may call this function in a couple ways.

Let's take the small array of integer numbers 'a' defined below. 

dv> a
5x1x1 array of int, bsq format [20 bytes]
1       -6      -4      3       8


We can feed this array, held in the variable 'a', into abs() by explicitly typing out that we want the 'obj' variable inside the abs() function to be equal to our variable 'a' like so: 

dv> abs(obj = a)
5x1x1 array of float, bsq format [20 bytes]
1.00000 6.00000 4.00000 3.00000 8.00000


Alternatively, abs() is also capable of accepting the shorthand call: 

dv> abs(a)
5x1x1 array of float, bsq format [20 bytes]
1.00000 6.00000 4.00000 3.00000 8.00000


[edit] Pass by Value

Arguments passed by value simply state a descriptive name for the variable to indicate to the user what kind of data is required. In this case, the name of the argument should not be explicitly declared when calling the function. In general, arguments passed by value are simply ordered inputs with no labels.

The format of an inexplicit pass-by-value function usage statement looks like this: 

function1(descriptive_name1, descriptive_name2)


And an example: 

ctof(object)


ctof() converts a numeric array containing temperatures in celsius to fahrenheit. It doesn't have an internal variable called 'object' but rather the word 'object' attempts to describe to the user what to do. This function can only be called one way: 

dv> a
124

dv> ctof(a)
255.200

dv> ctof(124)
255.200


If the user attempts an explicit variable declaration Davinci returns an error: 

dv> ctof(object = a)
error: Unknown keyword to ufunc: ctof(... object= ...)


[edit] Optional Inputs

By allowing some inputs to be optional, davinci has the ability to have preset values that the user doesn't need to enter for the function to work. A good example of this usage is assuming an ignore value in functions like thm.deplaid.

Optional inputs are enclosed by square brackets ( [ ] ) and defined as ususal. 

For example: 
function(obj = VAR [, ignore = FLOAT ])
function($1 = VAR [, $2 = FLOAT ])
Retrieved from "https://davinci.mars.asu.edu/index.php?title=Syntax&oldid=5745"
Personal tools