home *** CD-ROM | disk | FTP | other *** search
/ Chip 2004 March / CMCD0304.ISO / Software / Freeware / Programare / nullsoft / nsis20.exe / Contrib / Math / Math.txt < prev    next >
Text File  |  2003-09-22  |  10KB  |  199 lines
  1. Math::Script NSIS plugin.
  2.  
  3. C-like style scripting (operators at least).
  4. Tip1: plugin watches the case of the letters.
  5. Tip2: plugin makes almost no error checks. So YOU should check your script
  6. twice before run :)
  7.  
  8. New HOW TO USE: run the MathTest.Exe, and try yourself. After spending 
  9. some minutes your should be able to write your script by yourself.
  10. To include it to your NSIS script just insert that (don't forget /NOUNLOAD
  11. in case of multiple calls): 
  12.         Math::Script /NOUNLOAD "YourScript1"
  13.         Math::Script /NOUNLOAD "YourScript2"
  14.         Math::Script "YourScriptFinal"
  15.  
  16. How to use it? Simple:
  17.         Strcpy $0 "Brainsucker"
  18.         Math::Script "a = 'Math'; B = 'Script'; r0 += ' wants to use ' + a + '::' + b +'!'"
  19.         DetailPrint "$0"
  20. That string will fill r0 with some shit. 
  21.  
  22. Here are some other samples:
  23.         10! (factorial, r0 will contain '10! = 362880'):
  24.                 r0 = '10! = ' + (1*2*3*4*5*6*7*8*9)
  25.         the same:
  26.                 a = b = 1; #{++a <= 10, b = b*a}; r0 = (a-1) + '! = ' + b
  27.         Some floating point:
  28.                 Strcpy $R0 "1e1"
  29.                 Math::Script "pi = 3.14159; R1 = 2*pi*R0; r0 = 'Length of circle with radius ' + R0 + ' is equal to ' + R1 + '.'"
  30.                 Detailprint "$0"        
  31.  
  32. Ok. Variables. 
  33. NSIS: r0-r9 -> $0-$9. R0-R9 -> $R0-$R9. 
  34. Also CL ($CMDLINE), ID ($INSTDIR), OD ($OUTDIR), LG ($LANG), ED ($EXEDIR).
  35. User definable: name starting from character, up to 28 letters long.
  36.  
  37. Stacks. Two stacks are supported: NSIS stack and plugin's own stack. I see no 
  38. reasons for using plugin stack, but if you will, remember - the plugin stores
  39. variables used at function to that stack before function execution, and restores
  40. after execution. Even less I recommend you to use NSIS stack. You should use it
  41. only for input/output.
  42. How to use? It's variable styled. Plugins stack is associated with S variable,
  43. and NSIS stack associated with NS variable. To push to stack just do "S=0" or
  44. "NS=0", to pop from stack "a=S" or "b=NS". Combined operations supported too: 
  45. "S += 1.5" will increment value at the top of stack by 1.5.
  46.  
  47. Supported types: int (in fact that is __int64), float (double in fact),
  48. string.
  49. Int: just numbers, may include sign.
  50. Float: -123.456, 123.456e-78, 123e-45
  51. String: something in quotes ("", '', ``).
  52.  
  53. There is also an array type. It is actually a reference type, so if b is array
  54. and you will perform "a=b", the a and b will reference a single array.
  55. To create a copy of array, use ca func: dest = ca(source). Btw - you couldn't
  56. control dimensions of arrays - they are autosized.
  57. To declare array:
  58. a = {};
  59. To declare array and initialize some items with values:
  60. {"Hello!", "Use", "mixed types", 1.01e23, "like that" ,1234};
  61. To access array:
  62. a[index] = "Cool";
  63.  
  64. Also [] operation could be used to strings. str[x] gives you a single char with
  65. index x (zero-based) as new string. str[-x] - the same, but x counts from the
  66. string end (so the last char is -1). str[x,y] gives you characters in range x-y
  67. (inclusive), both x and y could be <0 - in this case they counted from the end
  68. of the string.
  69.  
  70. The function could be useful - is conversion of arrays to strings and back.
  71. Example:
  72. a = a("Hello"); str = s(a);
  73. After running such script array a will contain 6 integers (chars and last zero 
  74. - end of string), and str will contain your string back.
  75.  
  76. Operators (some binary, some unary):
  77. >>= <<= -= += /= *= |= &= ^= %= -- ++ >> << && || <= =< >= => != ==
  78. = + - * / % < > & | ^ ~ !
  79. Only some are applicable to float (logic & arithmetic) and string (+ and logic) 
  80. of course. 
  81. Additional case: reference/de-reference operators (& and *). & will
  82. give you the reference to argument which should be a variable (NSIS, user, array
  83. item, stack), and * will convert it back to original variable. For example 
  84. (a=&b; *a=10) will set b to 10. Expression (*&a) is equal to simple (a).
  85.  
  86. Script is set of expressions (mathematical in general) delimeted with ';'.
  87. Processing is mathematicaly right (2+2*2 will give 6), operations are performed
  88. in a C like order (precedence).
  89.  
  90. Flow control:
  91.         if-then-else like:      #[if-expression, then-expr, else-expr]
  92.                 example:
  93.                         #[a==0, b=1; c=2, b *= (--c); c/=10]               
  94.                 C eq:
  95.                         if (a==0) { b=1; c=2;} else { b*=(c++);c-=10; }
  96.         while (expr) do; like   #{expr, do}
  97.                 example:
  98.                         #{(c<1.1e25)&&(b < 10), b++; c*=1.23}
  99.                 C eq:
  100.                         while ((c<1.1e25)&&(b<10)) { b++; c*=1.23; }
  101.  
  102. WATCH OUT! Comma (,) separates if-expr, then-expr, and else-expr from each 
  103. other. All sub-expressions separated by (;) are the part of one expression,
  104. and the result of the last one of these sub-exprs gives you the result of 
  105. expression.
  106.  
  107. All the shit (like variables and functions) will be saved between calls if 
  108. you'll use /NOUNLOAD or setpluginunload alwaysoff.
  109.  
  110. Functions:
  111.         type conversions:
  112.                 l(string)       returns the length of string or array argument
  113.                 s(source)       converts source to string type
  114.                 i(source)       converts source to int type
  115.                 f(source)       converts source to float type
  116.                 c(source)       if source is string, returns int value of first
  117.                         char, if source is int, returns string which consists
  118.                         of a single char (source) (+0 terminator).
  119.                 a(source)       converts source to array (only string supported)
  120.                 ff(float, format)       converts float to string, with format
  121.                                         options.
  122.                         options = precision + flags.
  123.                         Precision shows how many digits after decimal point
  124.                         will be shown. Flags:
  125.                                 16 (or 0x10) - No Exponential View 
  126.                                         (number will be shown as 123.123)
  127.                                 32 (or 0x20) - Only exponential view
  128.                                         (number will be shown as 123.12e123)
  129.                                 64 (or 0x40) - use 'E' character instead of 'e' 
  130.                         By default the plugin decides itself how to show your
  131.                         number.
  132.  
  133.         math (description of all these functions is available at MSDN, use the
  134.             second given name for search):
  135.                 sin(x),         sin     Sine of argument
  136.                 cos(x),         cos     Cosine of argument
  137.                 cel(x),         ceil    Ceil of argument (no fract. part) 
  138.                 csh(x),         cosh    Hyperbolic Cosine of Argument        
  139.                 exp(x),         exp     Exponential
  140.                 abs(x),         abs     Absolute value (warning: float)
  141.                 flr(x),         floor   Floor of argument (no fract. part) 
  142.                 asn(x),         asin    ArcSine of argument
  143.                 acs(x),         acos    ArcCosine of argument
  144.                 atn(x),         atan    ArcTangent of argument
  145.                 ln(x),          log     Exponential Logarithm
  146.                 log(x),         log10   Decimal logarithm
  147.                 snh(x),         sinh    Hyperbolic Sine of Argument
  148.                 sqt(x),         sqrt    Square root of argument
  149.                 tan(x),         tan     Tangent of argument
  150.                 tnh(x),         tanh    Hyperbolic tangent  of argument
  151.  
  152.           functions taking two arguments
  153.                 at2(x, y)       atan2    Arctangent of the value (y/x)
  154.                 pow(x, y)       pow      power, x^y
  155.                 fmd(x, y)       fmod     floating point remainder
  156.                 fex(x, o)       frexp    Gets the mantissa (result = r) 
  157.                                         and exponent (o) of floating-point 
  158.                                         number (x): x = r*(2^o)
  159.                 mdf(x, o)       modf    Splits a floating-point value into 
  160.                                         fractional and integer parts.
  161.  
  162. User-defined functions.
  163. It's very simple. Example:
  164.         test(a,b) (a+b);
  165. After that test(1,2) will give you 3. 
  166.         test2(a,b) (a=a+b; b *= a);
  167. The result of function is always the result of last expression.
  168. As said before it better not to use stack (S) in between function calls.
  169. It will be better to develop variable-safe functions, i.e. functions which will
  170. not corrupt variables. For this you should either push/pop them to stack, or
  171. declare as additional arguments, which will never be used. Example:
  172.         test3(a,b,c) (c=10; #{--c > 0, a=sqrt(a*b)}; a)
  173. No matter how many arguments will be passed to function, the values of all three 
  174. vars (a,b,c) will be saved. 
  175. Such variable-safe functions could be recursive:
  176.         Math::Script /NOUNLOAD 'rec(a) (#[a > 0, rec(a-1), 0]+a);'
  177.         Math::Script 'R1 = rec(10)'
  178. will set R1 to right result 55.
  179. Sometimes functions will need to return more than one value, in this case you
  180. could declare argument as referent (b at example):
  181.         test4(a, &b) (*b = a*a; a*a*a)
  182. In this case test4 will return a^3, and if we will call it like that test4(a,c),
  183. it will place a^2 to c. BUT! Note: you should use de-referencer (*) with variable,
  184. at example *b. CAUTION: never use the same variable as function internal reference
  185. variable and external argument variable (for example test4(a,b)). It will surely 
  186. fail. Also: if you declared argument as reference - you should never supply
  187. a constant expression to it. It could be either array item (array[1]), NSIS
  188. register R0, any of the user variables (beside the variable with the same name:), 
  189. but never the constant.
  190.  
  191. Another may-be-useful posibility is to redeclare the function (the usual 
  192. declaration at the time when function already defined will simply call that
  193. function). For such task you could use "#name", like "func()(1); #func()(2);".
  194. But beware, function declaration occurs at time of parsing, so it's not possible
  195. to perform flow controlled declaration. 
  196. SUCH IS NOT POSSIBLE: "#[a<0, #func()(1), #func()(2)]"
  197. IT WILL SIMPLY DEFINE #func as (2), as the latest variant.
  198.         
  199. (c) Nik Medved (brainsucker)