--- loncom/html/adm/help/tex/Problem_LON-CAPA_Functions.tex 2003/06/27 14:20:01 1.3
+++ loncom/html/adm/help/tex/Problem_LON-CAPA_Functions.tex 2014/12/14 02:44:04 1.31
@@ -22,9 +22,9 @@
\&abs(\$x), \&sgn(\$x) & Abs takes the absolute value of x while sgn(x) returns 1, 0 or -1 depending on the value of x. For x$>$0, sgn(x) = 1, for x=0, sgn(x) = 0 and for x$<$0, sgn(x) = -1. \$x can be a pure number \\
\hline
-\&erf(\$x), \&erfc(\$x) & Error function. erf = 2/sqrt(pi) integral (0,x) et-sq and \emph{ erfx(x)}
- = 1.0 - \emph{erf(x)}
-. \$x can be a pure number \\
+\&erf(\$x), \&erfc(\$x) & Error function.
+erf = 2/sqrt(pi) integral (0,x) et-sq and \emph{ erfx(x)}
+ = 1.0 - \emph{erf(x)}. \$x can be a pure number \\
\hline
\&ceil(\$x), \&floor(\$x) & Ceil function returns an integer rounded up whereas floor function returns and integer rounded down. If x is an integer than it returns the value of the integer. \$x can be a pure number \\
@@ -45,18 +45,33 @@
\&asinh(\$x), \&acosh(\$x), \&atanh(\$x) & Inverse hyperbolic functions. \$x can be a pure number \\
\hline
-\&format(\$x,'nn') & Display or format \$x as nn where nn is nF or nE and n is an integer. Also supports the first character being a \$, it thjen will format the result with a call to \&dollarformat() described below. \\
+\&format(\$x,'nn') & Display or format \$x as nn where nn is nF or nE or nS and n is an integer. \\
\hline
-\&prettyprint(\$x,'nn') & Display or format \$x as nn where nn is nF or nE and n is an integer. Also supports the first character being a \$, it then will format the result with a a call to \&dollarformat() described below. In E mode it will attempt to generate a pretty x10\^{}3 rather than a E3 following the number \\
+\&prettyprint(\$x,'nn','optional target') & Note that that tag $<$num$>$ can be used to do the same thing. Display or format \$x as nn where nn is nF or nE or nS and n is an integer. Also supports the first character being a \$, it then will format the result with a a call to \&dollarformat() described below. If the first character is a , it will format it with commas grouping the thousands. In S mode it will fromat the number to the specified number of significant figures and display it in F mode. In E mode it will attempt to generate a pretty x10\^{}3 rather than a E3 following the number, the 'optional target' argument is optional but can be used to force \&prettyprint to generate either 'tex' output, or 'web' output, most people do not need to specify this argument and can leave it blank.\\
\hline
-\&dollarformat(\$x) & Reformats \$x to have a \$ (or $\backslash$\$ if in tex mode) and to have , grouping thousands. \\
+\&dollarformat(\$x,'optional target') & Reformats \$x to have a \$ (or $\backslash$\$ if in tex mode) and to have , grouping thousands. The 'optional target' argument is optional but can be used to force \&prettyprint to generate either 'tex' output, or 'web' output, most people do not need to specify this argument and can leave it blank.\\
\hline
-
+
+\parbox{6.49cm}{
+Option 1 - \$best = \&languages() \\
+Option 2 - @all = \&languages() \\
+Option 3 - \$best = \&languages($\backslash$@desired\_languages) \\
+Option 4 - @all = \&languages($\backslash$@desired\_languages) \\
+}& Returns the best language to use, in the first two options returns the languages codes in the preference order of the user. In the second two examples returns the best matches from a list of desired language possibilities. \\
+\hline
+
\&roundto(\$x,\$n) & Rounds a real number to n decimal points. \$x and \$n can be pure numbers \\
\hline
+\&cas(\$s,\$e,\$l)&Evaluates the expression \$e inside the symbolic algebra system \$s. Currently, the Maxima symbolic math system ('maxima') and the R statistical computing system ('R') are implemented.
+\$l is an optional comma-separated list of libraries. Example: \&cas('maxima','diff(sin(x)/cos(x),x,2)')\\
+\hline
+
+\&implicit\_multiplication(\$f)&Adds mathematical multiplication operators to the formula expression \$f where only implicit multiplication is used. Example: \&implicit\_multiplication('2(b+3c)') returns 2*(b+3*c) \\
+\hline
+
\&web(``a'',''b'',''c'') or \&web(\$a,\$b,\$c) & Returns either a, b or c depending on the output medium. a is for plain ASCII, b for tex output and c for html output \\
\hline
@@ -69,7 +84,7 @@
\&y0(\$x), \&y1(\$x), \&yn(\$m,\$x), \&yv(\$y,\$x) & Bessel functions of the second kind with orders 0, 1 and m respectively. For yn(m,x), m must be an integer whereas for yv(y,x), y is real. \$x can be a pure number. \$m must be an integer and can be a pure integer number. \$y can be a pure real number \\
\hline
-\&random(\$l,\$u,\$d) & Returns a uniformly distributed random number between the lower bound, l and upper bound, u in steps of d. \$l, \$u and \$d can be pure numbers \\
+\&random(\$l,\$u,\$d) & Returns a uniformly distributed random number between the lower bound, l and upper bound, u in steps of d. d is optional. If omitted, a step of 1 is used. \$l, \$u and \$d can be pure numbers. \\
\hline
\&choose(\$i,...) & Choose the ith item from the argument list. i must be an integer greater than 0 and the value of i should not exceed the number of items. \$i can be a pure integer \\
@@ -80,17 +95,19 @@ Option 1 - \&map(\$seed,[$\backslash$\$w
Option 2 - \&map(\$seed,$\backslash$@mappedArray,[\$a,\$b,\$c,\$d]) \\
Option 3 - @mappedArray = \&map(\$seed,[\$a,\$b,\$c,\$d]) \\
Option 4 - (\$w,\$x,\$y,\$z) = \&map(\$seed,$\backslash$@a) \\
+ Option 5 - @Z = \&map(\$seed,$\backslash$@a) \\
where \$a='A'\\
\$b='B'\\
\$c='B'\\
\$d='B'\\
- \$w, \$x, \$y, and \$z are variables } & Assigns to the variables \$w, \$x, \$y and \$z the values of the \$a, \$b, \$c and \$c (A, B, C and D). The precise value for \$w .. depends on the seed. (Option 1 of calling map). In option 2, the values of \$a, \$b .. are mapped into the array, @mappedArray. The two options illustrate the different grouping. Options 3 and 4 give a consistent way (with other functions) of mapping the items. For each option, the group can be passed as an array, for example, [\$a,\$b,\$c,\$d] =$>$ $\backslash$@a. \\
+ \$w, \$x, \$y, and \$z are variables } & Assigns to the variables \$w, \$x, \$y and \$z the values of the \$a, \$b, \$c and \$c (A, B, C and D). The precise value for \$w .. depends on the seed. (Option 1 of calling map). In option 2, the values of \$a, \$b .. are mapped into the array, @mappedArray. The two options illustrate the different grouping. Options 3 and 4 give a consistent way (with other functions) of mapping the items. For each option, the group can be passed as an array, for example, [\$a,\$b,\$c,\$d] =$>$ $\backslash$@a. And Option 5 is the same as option 4, where the array of results is saved into a single array rather than an array of scalar variables.\\
\hline
\parbox{6.49cm}{Option 1 - \&rmap(\$seed,[$\backslash$\$w,$\backslash$\$x,$\backslash$\$y,$\backslash$\$z],[\$a,\$b,\$c,\$d]) or \\
Option 2 - \&rmap(\$seed,$\backslash$@rmappedArray,[\$a,\$b,\$c,\$d]) \\
Option 3 - @rmapped\_array = \&rmap(\$seed,[\$a,\$b,\$c,\$d]) \\
Option 4 - (\$w,\$x,\$y,\$z) = \&rmap(\$seed,$\backslash$@a) \\
+ Option 5 - @Z = \&map(\$seed,$\backslash$@a) \\
where \$a='A'\\
\$b='B'\\
\$c='B'\\
@@ -98,7 +115,7 @@ Option 1 - \&map(\$seed,[$\backslash$\$w
\$w, \$x, \$y, and \$z are variables } & The rmap functions does the reverse action of map if the same seed is used in calling map and rmap. \\
\hline
-\$a=\&xmlparse(\$string) & Runs the internal parser over the argument parsing for display. \textbf{Warning}
+\$a=\&xmlparse(\$string) & You probably should use the tag $<$parse$>$ instead of this function. Runs the internal parser over the argument parsing for display. \textbf{Warning}
This will result in different strings in different targets. Don't use the results of this function as an answer. \\
\hline
@@ -111,20 +128,54 @@ Option 1 - \&map(\$seed,[$\backslash$\$w
\&to\_string(\$x), \&to\_string(\$x,\$y) & If x is an integer, returns a string. If x is real than the output is a string with format given by y. For example, if x = 12.3456, \&to\_string(x,''.3F'') = 12.345 and \&to\_string(x,''.3E'') = 1.234E+01. \\
\hline
-\&class(), \§ion() & Returns null string, class descriptive name, section number, set number and null string. \\
+\&class(), \&sec(), \&classid() & Returns null string, class descriptive name, section number, class id, set number and null string. \\
\hline
-\&name(), \&student\_number() & Return the full name in the following format: lastname, firstname initial. Student\_number returns the student 9-alphanumeric string. If undefined, the functions return null. \\
+\&name(), \&student\_number(), \&firstname(), \&middlename(), \&lastname() & Return the full name in the following format: lastname, firstname initial. Student\_number returns the student 9-alphanumeric string. The functions firstname, middlename, and lastname return just that part of the name. If undefined, the functions return null. \\
\hline
-
-\&open\_date(), \&due\_date(), \&answer\_date() & Problem open date, due date and answer date. The time is also included in 24-hr format. \\
+\&check\_status(\$partid) &Returns a number identifying the current status of a part. True values mean that a part is ``done'' (either unanswerable because of tries exhaustion, or correct) or a false value if a part can still be attempted. If \$part is unspecified, it will check either the current $<$part$>$'s status or if outside of a $<$part$>$, check the status of previous $<$part$>$. The full set of return codes are: 'undef' means it is unattempted, 0 means it is attempted and wrong but still has tries, 1 means it is marked correct, 2 means they have exceeded maximum number of tries, 3 means it is after the answer date.\\
+\hline
+\&open\_date(\$partid), \&due\_date(\$partid), \&answer\_date(\$partid) & Problem open date, due date and answer date in local human-readable format. Part 0 is chosen if \$partid is omitted.\\
+\hline
+\&open\_date\_epoch(\$partid), \&due\_date\_epoch((\$partid), \&answer\_date\_epoch((\$partid) & Problem open date, due date and answer date in seconds after the
+epoch (UTC), which can be used in calculations.\\
+\hline
+
+\&submission(\$partid,\$responseid,\$version,
+\$encode,\$cleanupnum,\$mapalias) & Returns what the student submitted for response \$responseid in part \$partid. You can get these IDs from the XML-code of the problem. Use 0 as \$partid for problems without parts. \$version is optional and returns the \$version-th submission of the student that was graded. If \$version is 0 or omitted, the latest submission is returned.
+\$encode is also optional and allows the author to explicitly encode the returned string. It's up to the author to take care of properly escaping all characters which might be interpreted by the browser.
+\$cleanupnum is also optional, and supports clean-up of the retrieved submission.
+It is a reference to a hash, with one or more of the following:
+exponent =$>$ 1,
+comma =$>$ 1,
+letterforzero =$>$ 1,
+spaces =$>$ 1,
+format =$>$ 'ns'
+(where n is an integer, i.e., number of significant digits). For example, to convert a student submission of
+11,300 to 11300 include \{ comma =$>$ 1, \} as the fifth arg.
+\$mapalias is also optional, and supports retrieval of the submission for a response item in a different problem in the course, for which a (unique) mapalias has been set.
+The default (mapalias not defined) is to retrieve the submission for the specified part and response IDs in the current problem.\\
+\hline
+
+\¶meter\_setting(\$name,\$partid) & Returns the parameter setting \$name. Partid is optional.\\
+\hline
+
+\&stored\_data(\$name,\$partid) & Returns the stored data \$name. Partid is optional.\\
+\hline
+\&wrong\_bubbles(\$correct,\$lower,\$upper,\$step,@given) & Returns an array that can be used for wrong answers in numerical responses. The first argument is the correct answer, the next arguments are the lower and upper boundaries for the bubbles, as well as the step size. The next argument is an
+optional array of wrong answers that should be included.\\
+\hline
+
+\¤tpart() &
+Returns the ID of the current part.\\
\hline
+
Not implemented & Get and set the random seed. \\
\hline
\&sub\_string(\$a,\$b,\$c)
-perl substr function. However, note the differences & Retrieve a portion of string a starting from b and length c. For example, \$a = ``Welcome to LON-CAPA''; \$result=\&sub\_string(\$a,4,4); then \$result is ``come'' \\
+perl substr function. However, note the differences & Retrieve a portion of string a starting from b and length c. For example, \$a = ``Welcome to LON-CAPA''; \$result=\&sub\_string(\$a,4,4); then \$result is ``come'' \\
\hline
@arrayname
@@ -134,7 +185,7 @@ Array is intrinsic in perl. To access a
@B=\&array\_moments(@A) & Evaluates the moments of an array A and place the result in array B[i] where i = 0 to 4. The contents of B are as follows: B[0] = number of elements, B[1] = mean, B[2] = variance, B[3] = skewness and B[4] = kurtosis. \\
\hline
-\&min(@Name), \&max(@Name) & In LON-CAPA to find the maximum value of an array, use \&max(@arrayname) and to find the minimum value of an array, use \&min(@arrayname) \\
+\&min(@Name), \&max(@Name) & In LON-CAPA to find the maximum value of an array, use \&max(@arrayname) and to find the minimum value of an array, use \&min(@arrayname) \\
\hline
undef @name & To destroy the contents of an array, use \\
@@ -202,3 +253,13 @@ undef @name & To destroy the contents o
NOTE: \$ne is rounded using int() and the result must be positive. \$p must be between 0 and 1 exclusive. & Generate an array of \$item\_cnt outcomes generated from negative binomial distribution with \$ne events and the probabilty of an event in each trial is \$p. \\
\hline
\end{longtable}
+
+The \&EXT() \index{\&EXT}external function is extremely powerful, and is used to access parameters
+and submission values. It can be
+used within scripts and also within cell formulas in the grading spreadsheet.
+Some examples can be found by browsing in the repository to /res/msu/albertel/test/ext\_examples.html.
+The \&EXT() function can be used to obtain values for the same parameters as are retrived by some of the other (newer) helper functions
+summarized in the table above, such as \&firstname() which is equivalent to \&EXT(`environment.firstname'),
+and \¶meter\_setting(\$name,\$partid) is equivalent to \&EXT(`resource.'.\$partid.`.'.\$name).
+In such cases the newer (specialized) functions are preferred to \&EXT() on the basis of ease of use.
+