1 /*
2 * $Id: std.i,v 1.46 2010-09-13 03:05:58 dhmunro Exp $
3 * Declarations of standard Yorick functions.
4 */
5 /* Copyright (c) 2005, The Regents of the University of California.
6 * All rights reserved.
7 * This file is part of yorick (http://yorick.sourceforge.net).
8 * Read the accompanying LICENSE file for details.
9 */
10
11 /*
12 The Codger automatic code generator program uses this file to
13 generate appropriate C code to initialize the various built-in
14 functions declared here.
15 This file is also used as online documentation for these functions
16 by Yorick's help mechanism.
17
18 The "extern" declaration of each function or variable is a no-op,
19 but causes Yorick to place the variable in the sourceList for this
20 include file, making it available for online help. The DOCUMENT
21 comment is provided in a standard format to simplify manipulation
22 of such comments by programs other than Yorick; it should immediately
23 follow the corresponding "extern" so that it will be visible when
24 the page containing the "extern" is displayed.
25
26 The Codger code generator finds each "extern" line and creates
27 initialization code binding the associated Yorick variable to
28 either a BuiltIn function (see ydata.h) Y_variable, or, if a
29 "reshape, variable, ..." declaration is found, to a global
30 compiled variable y_variable with the compiled data type
31 corresponding to the Yorick data type mentioned in the "reshape"
32 command. Codger can generate certain simple Y_variable wrapper
33 routines if further information is provided in a PROTOTYPE comment.
34 */
35 /*= SECTION(info) help and information =====================================*/
36
37 extern help;
38 /* DOCUMENT help, topic
39 or help
40 Prints DOCUMENT comment from include file in which the variable
41 TOPIC was defined, followed by the line number and filename.
42 By opening the file with a text editor, you may be able to find
43 out more, especially if no DOCUMENT comment was found.
44 Examples:
45 help, set_path
46 prints the documentation for the set_path function.
47 help
48 prints the DOCUMENT comment you are reading.
49
50 This copy of Yorick was launched from the directory:
51 **** Y_LAUNCH (computed at runtime) ****
52 Yorick's "site directory" at this site is:
53 **** Y_SITE (computed at runtime) ****
54 You can find out a great deal more about Yorick by browsing
55 through these directories. Begin with the site directory,
56 and pay careful attention to the subdirectories doc/ (which
57 contains documentation relating to Yorick), and i/ and
58 contrib/ (which contain many examples of Yorick programs).
59 Look for files called README (or something similar) in any
60 of these directories -- they are intended to assist browsers.
61 The site directory itself contains std.i and graph.i, which
62 are worth reading.
63
64 Type:
65 help, dbexit
66 for help on debug mode. If your prompt is "dbug>" instead of
67 ">", dbexit will return you to normal mode.
68
69 Type:
70 quit
71 to quit Yorick.
72
73 SEE ALSO: about, quit, info, print, copyright, warranty, legal
74 */
75
76 local copyright, warranty;
77 /* DOCUMENT copyright, (no) warranty
78
79 Copyright (c) 2005. The Regents of the University of California.
80 All rights reserved.
81
82 Yorick is provided "as is" without any warranty, either expressed or
83 implied. For a complete statement, type:
84
85 legal
86
87 at the Yorick prompt.
88
89 SEE ALSO: legal
90 */
91
legal(void)92 func legal(void)
93 /* DOCUMENT legal
94 Prints the legal details of Yorick's copyright, licensing,
95 and lack of warranty.
96 SEE ALSO: copyright, warranty
97 */
98 {
99 f = open(Y_HOME+"LICENSE.md", "r", 1);
100 if (!f) error, "missing LICENSE file, yorick improperly installed";
101 f = rdline(f, 1000);
102 write, format="%s\n", f(where(f));
103 }
104
105 func help_worker
106 /* xxDOCUMENT help_worker (Not for interactive use -- called by help.)
107 */
108 {
109 /* help_worker task is pushed by help function -- topic and file
110 arguments are left in help_topic and help_file variables */
111 topic= help_topic; help_topic= [];
112 file= help_file; help_file= [];
113
114 if (file) {
115 mark= bookmark(file);
116 line= rdline(file);
117
118 if (typeof(topic)!="struct_definition") {
119 /* non-struct looks for DOCUMENT comment before any blank lines */
120 n= 10; /* read at most 10 lines looking for DOCUMENT comment */
121 while (strtok(line)(1) && n--) {
122 if (strmatch(line, "/* DOCUMENT")) break;
123 line= rdline(file);
124 }
125 if (strmatch(line, "/* DOCUMENT")) {
126 do {
127 if (strmatch(line, "**** Y_LAUNCH (computed at runtime) ****"))
128 write, " "+Y_LAUNCH;
129 else if (strmatch(line, "**** Y_SITE (computed at runtime) ****"))
130 write, " "+Y_SITE;
131 else
132 write, line;
133 line= rdline(file);
134 if (!line) break;
135 } while (!strmatch(line, "*/"));
136 write, line;
137 } else {
138 write, "<DOCUMENT comment not found>";
139 }
140
141 } else {
142 /* struct just prints definition */
143 gotopen= 0;
144 do {
145 if (!gotopen) gotopen= strmatch(line, "{");
146 write, line;
147 if (gotopen && strmatch(line, "}")) break;
148 } while (line= rdline(file));
149 }
150
151 mark= print(mark)(2:0);
152 line= "";
153 for (i=1 ; i<numberof(mark) ; i++) line+= strpart(mark(i),1:-1);
154 line+= mark(i);
155 write, "defined at:"+line;
156
157 } else if (is_func(topic) == 3) {
158 /* autoloaded function */
159 buf = print(topic);
160 n = numberof(buf);
161 str = buf(1);
162 escape = "\134"; /* must be octal code to not kill codger */
163 newline = "\n";
164 for (i=2;i<=n;++i) {
165 if (strpart(str, 0:0) == escape) {
166 str = strpart(str, 1:-1) + buf(i);
167 } else {
168 str += newline + buf(i);
169 }
170 }
171 topic_name = file_name = string();
172 if (sread(str, format="autoload of: %s from: %[^\n]",
173 topic_name, file_name) == 2) {
174 include, file_name, 1;
175 help_topic = topic_name;
176 after, 0.0, _help_auto;
177 } else {
178 info, topic;
179 }
180 } else {
181 write, "<not defined in an include file, running info function>";
182 info, topic;
183 }
184 }
185
186 func _help_auto
187 /* xxDOCUMENT _help_auto (Not for interactive use -- called by help_worker
188 * for autoloaded function.) */
189 {
190 topic = help_topic;
191 help_topic = [];
192 if (structof(topic) == string) topic = symbol_def(topic);
193 help, topic;
194 }
195
info(args)196 func info(args)
197 /* DOCUMENT info, expr [, expr2, expr3, ...]
198 prints the data type and array dimensions of EXPR. Multiple
199 expressions result in multiple descriptions. You can also
200 invoke info as a function to return a string or array of strings
201 instead of printing the result.
202 SEE ALSO: about, help, print
203 */
204 {
205 /* void = use_origins(1); // either worthless or wrong? */
206 r = args("_depth");
207 prefix = r? string(&array(' ',r+r)) : "";
208 value = [];
209 s = am_subroutine();
210 for (j=1 ; j<=args(0) ; ++j) {
211 if (r) line = prefix + args("_name") + " = ";
212 else if (args(0)>1) line = (args(-,j)? args(-,j) : "<expr>") + " = ";
213 else line = "";
214 if (is_array(args(j,:))) {
215 line += "array(" + nameof(structof(args(j,:)));
216 dims = dimsof(args(j,:));
217 orgs = orgsof(args(j,:));
218 ndims = dims(1)+1;
219 for (i=2 ; i<=ndims ; i++) {
220 line += ",";
221 if (orgs(i)!=1)
222 line += print(orgs(i))(1)+":"+print(orgs(i)+dims(i)-1)(1);
223 else
224 line += print(dims(i))(1);
225 }
226 line = swrite(line + ")");
227 } else if (is_stream(args(j)) || !is_obj(args(j))) {
228 x = print(args(j));
229 x(1) = line + x(1);
230 line = swrite(format=" %s", x);
231 } else {
232 o = args(j);
233 n = o(*);
234 nm = o(*,);
235 line = swrite(format=" %sobject with %ld members:", line, n);
236 n = min(n, 99);
237 for (i=1 ; i<=n ; ++i) {
238 k = _name = nm(i);
239 if (!k) {
240 _name = swrite(format="<%ld>", i);
241 k = i;
242 }
243 grow, line, info(o(noop(k)), _depth=(r?r+1:1), _name=_name);
244 }
245 n = o(*);
246 if (i <= n)
247 grow, line, swrite(format=" %s <%ld more>...", prefix, n-i+1);
248 }
249 if (s) write, format="%s\n", line;
250 else grow, value, line;
251 }
252 return value;
253 }
254 wrap_args, info;
255
256 /* need strange variable names to avoid matches with help topic pattern! */
about(____n____,____a____)257 func about(____n____, ____a____)
258 /* DOCUMENT about, pattern;
259 or about, pattern, 1;
260 Search and display documentation about functions (or all symbols if
261 second argument is true) matching regular expression PATTERN. If
262 multiple matches are found, the user is prompted to select a subject.
263 PATTERN may be a string, or a function or structure definition. If
264 PATTERN is a string with a trailing "/i", the other part of the
265 regular expression is interpreted so as to ignore case.
266
267 Set
268 about_glob = strglob;
269 to use UNIX shell style matching (e.g.- ls command line) to match
270 PATTERN instead of grep style matching. The default about_glob
271 function is strgrepm.
272
273 SEE ALSO: help, info, strgrep, strglob
274 */
275 {
276 if (structof(____n____) != string) {
277 ____n____ = nameof(____n____);
278 if (structof(____n____) != string)
279 error, "expecting a string, a function, or a structure definition";
280 }
281 /* first get list of all symbol names matching the pattern */
282 ____c____ = strpart(____n____, -1:0) == "/i";
283 if (____c____) ____n____ = strpart(____n____, 1:-2);
284 ____b____ = save(*)(*,);
285 ____b____ = ____b____(where(about_glob(____n____,____b____,case=____c____)));
286 if (!____a____) {
287 /* by default remove all matches which are not functions */
288 for (____a____=1 ; ____a____<=numberof(____b____) ; ++____a____)
289 if (!is_func(symbol_def(____b____(____a____))))
290 ____b____(____a____) = string(0);
291 }
292 ____a____ = ____b____(where(____b____));
293 if (!numberof(____a____)) {
294 write, " Sorry no match found.";
295 return;
296 }
297 if (numberof(____a____) == 1)
298 ____a____ = ____a____(1);
299 else
300 ____a____ = select_name(____a____(sort(____a____)), bol=" ",
301 prompt=" Choose one subject: ");
302 if (numberof(____a____)) {
303 /* Explicitly filter range operators which have a built-in
304 * function counterpart to avoid ambiguity in yorick. */
305 if (____a____ == "sum") {
306 write, format="%s\n%s\n%s\n%s\n",
307 "/* DOCUMENT sum(x)",
308 " Returns sum of values in array X.",
309 " Can also be used as a range operator.",
310 " SEE ALSO: avg, max, min. */";
311 } else if (____a____ == "avg") {
312 write, format="%s\n%s\n%s\n%s\n",
313 "/* DOCUMENT avg(x)",
314 " Returns average of values in array X.",
315 " Can also be used as a range operator.",
316 " SEE ALSO: max, min, sum. */";
317 } else if (____a____ == "min") {
318 write, format="%s\n%s\n%s\n%s\n",
319 "/* DOCUMENT min(x)",
320 " Returns minimum value in array X.",
321 " Can also be used as a range operator.",
322 " SEE ALSO: avg, max, sum. */";
323 } else if (____a____ == "max") {
324 write, format="%s\n%s\n%s\n%s\n",
325 "/* DOCUMENT max(x)",
326 " Returns maximum value in array X.",
327 " Can also be used as a range operator.",
328 " SEE ALSO: avg, min, sum. */";
329 } else {
330 include, ["help, "+____a____];
331 }
332 }
333 }
334
library(void)335 func library(void)
336 /* DOCUMENT library
337 print the Y_SITE/i/README file at the terminal.
338 */
339 {
340 f= open(Y_SITE+"i/README");
341 while ((line= rdline(f))) write, line;
342 }
343
344 extern get_pkgnames;
345 /* DOCUMENT get_pkgnames(all)
346 returns list of package names, ALL non-zero means to return both
347 statically and dynamically loaded packages, otherwise just the
348 initial statically loaded packages.
349 SEE ALSO: get_path
350 */
351
352 extern symbol_def;
353 /* DOCUMENT symbol_def(func_name)(arglist)
354 or symbol_def(var_name)
355 invokes the function FUNC_NAME with the specified ARGLIST,
356 returning the return value. ARGLIST may be zero or more arguments.
357 In fact, symbol_def("fname")(arg1, arg2, arg3) is equivalent to
358 fname(arg1, arg2, arg3), so that "fname" can be the name of any
359 variable for which the latter syntax is meaningful -- interpreted
360 function, built-in function, or array.
361
362 Without an argument list, symbol_def("varname") is equivalent to
363 varname, which allows you to get the value of a variable whose name
364 you must compute.
365
366 DO NOT OVERUSE THIS FUNCTION. It works around a specific deficiency
367 of the Yorick language -- the lack of pointers to functions -- and
368 should be used for such purposes as hook lists (see openb).
369
370 SEE ALSO: symbol_set, symbol_exists
371 */
372
373 extern symbol_set;
374 /* DOCUMENT symbol_set, var_name, value
375 is equivalent to the redefinition
376 varname= value
377 except that var_name="varname" is a string which must be computed.
378
379 DO NOT OVERUSE THIS FUNCTION. It works around a specific deficiency
380 of the Yorick language -- the lack of pointers to functions, streams,
381 bookmarks, and other special non-array data types.
382
383 SEE ALSO: symbol_def, symbol_exists
384 */
385
386 extern symbol_exists;
387 /* DOCUMENT symbol_exists(name)
388 Check whether variable/function named NAME exists. This routine can be
389 used prior to symbol_def to check existence of a symbol since symbol_def
390 raise an error for non-existing symbol.
391
392 SEE ALSO: symbol_def, symbol_names, symbol_set.
393 */
394
395 extern symbol_names;
396 /* DOCUMENT symbol_names()
397 or symbol_names(flags)
398 Return an array of strings with the names of all symbols of given
399 type(s) found in global symbol table. To select the type of symbol,
400 FLAGS is be the bitwise-or of one or more of the following bits:
401 1 - basic array symbols
402 2 - structure instance symbols
403 4 - range symbols
404 8 - nil symbols (i.e. symbols undefined at current scope level)
405 16 - interpreted function symbols
406 32 - builtin function symbols
407 64 - structure definition symbols
408 128 - file stream symbols
409 256 - opaque symbols (other than the ones below)
410 512 - list objects
411 1024 - auto-loaded functions
412
413 The special value FLAGS = -1 can be used to get all names found in
414 global symbol table. The default (if FLAGS is nil or omitted) is to
415 return the names of all symbols but the nil ones. Beware that lists,
416 hash tables and auto-loaded functions are also opaque symbols (use
417 0xffffff7f to get *all* opaque symbols).
418
419 SEE ALSO: symbol_def, symbol_exists, symbol_set.
420 */
421
split_path(path)422 func split_path(path)
423 /* DOCUMENT split_path(path)
424 splits PATH, a colon or semi-colon delimited list of directories
425 as returned by get_path, into a string array with one directory
426 per element.
427 SEE ALSO: set_path, get_pkgnames
428 */
429 {
430 if (numberof(path) > 1) path = sum(";"+path);
431 path = strchar(path);
432 list = where(path == ';');
433 if (numberof(list)) path(list) = '\0';
434 list = where(path == ':');
435 if (numberof(list)) {
436 for (i=j=1 ; j<=numberof(list) ; ++j) {
437 for (; i<list(j) ; ++i) if (path(i)) break;
438 if ((i==list(j)-1) && ((c=path(i)|'\x20')>='a') && (c<='z')) {
439 list(j) = 0;
440 if (++j > numberof(list)) break;
441 }
442 i = list(j) + 1;
443 }
444 list = list(where(list));
445 if (numberof(list)) path(list) = '\0';
446 }
447 return strchar(path);
448 }
449
450 /*= SECTION(advanced) performance and interface optimizations ==============*/
451
452 extern eq_nocopy;
453 /* DOCUMENT eq_nocopy, y, x
454 is the same as
455 y= x
456 except that if x is an array, it is not copied, even if it is
457 not a temporary (i.e.- an expression). Having multiple variables
458 reference the same data can be confusing, which is why the default
459 = operation copies the array. The most important use of eq_nocopy
460 involves pointers or lists:
461 y= *py
462 z= _car(list)
463 always causes the data pointed to by py to be copied, while
464 eq_nocopy, y, *py
465 eq_nocopy, z, _car(list)
466 does not copy the data - often more nearly what you wanted.
467 Note that scalar int, long, and double variables are always copied,
468 so you cannot count on eq_nocopy setting up an "equivalence"
469 between variables.
470
471 SEE ALSO: swap, unref.
472 */
473
474 extern swap;
475 /* DOCUMENT swap, a, b;
476 Exchanges the contents of variables A and B without requiring any
477 temporary copy. The result of the call is identical to:
478 tmp = a; a = b; b = tmp;
479 which makes a copy of A and then a copy of B. Another possibility which
480 avoids any copy of A nor B is:
481 local tmp;
482 eq_nocopy, tmp, a; eq_nocopy, a, b; eq_nocopy, b, tmp;
483
484 SEE ALSO: eq_nocopy, unref.
485 */
486
487 extern unref;
488 /* DOCUMENT unref(x)
489 Returns X, destroying X in the process if it is an array (useful to
490 deal with temporary big arrays).
491
492 SEE ALSO: eq_nocopy, swap.
493 */
494
495 extern wrap_args;
496 /* DOCUMENT wrap_args, interpreted_function
497 converts INTERPRETED_FUNCTION to a wrapped_func object,
498 which will accept an arbitrary argument list, then invoke
499 INTERPRETED_FUNCTION with a single wrapped_args object as
500 its argument. The INTERPRETED_FUNCTION must be declared as:
501
502 func INTERPRETED_FUNCTION(args)
503 {
504 ...use args object to retrieve actual arguments...
505 }
506 wrap_args, INTEPRETED_FUNCTION;
507
508 After wrapping, you invoke the function as usual:
509
510 result = INTERPRETED_FUNCTION(arg1, key1=ka1, arg2, ...);
511
512 Unlike an ordinary interpreted function, a wrapped function
513 will accept any number of arguments, and keyword arguments
514 of any name. Furthermore, unlike an ordinary function, you
515 can determine the number of arguments passed to the function,
516 the names of any simple variable references passed to the
517 function, and other useful information about the arguments.
518 You can set the external value of any simple variable passed
519 as an argument, as if it had been declared func f(..., &x, ...).
520
521 A wrapped_func function call is less efficient and requires
522 less transparent coding than an ordinary function call; the
523 advantage is that you can write a wrapped function which has
524 non-standard semantics, for example, like the save and restore
525 built-in functions (which use the names of the arguments passed
526 to them), or other special effects, like accepting arbitrary
527 keyword names.
528
529 The ARGS object, the single argument actually passed to
530 your INTEPRETED_FUNCTION, is a wrapped_args object, which has
531 the following Eval methods:
532
533 ARGS(-) returns [keyname1, keyname2, keyname3, ...]
534 the actual names of the keyword arguments passed
535 or nil [] if no keywords were passed
536 ARGS(*,) is a synonym for ARGS(-) to resemble
537 the object syntax (see help,oxy), although the
538 analogy is not exact.
539 ARGS(0) returns the number of positional arguments passed
540 ARGS(*) is a synonym for ARGS(0) to resemble
541 the object syntax (see help,oxy), although the
542 analogy is not exact.
543 ARGS(i) returns the i-th positional argument
544 i can also be a string to return a keyword argument,
545 or a negative number to return the -i-th keyword
546 ARGS, i, value
547 sets the value of argument i, as if it were
548 an output variable declared as func f(..., &x, ...)
549 ARGS(-,i) returns the name of argument i if it was
550 passed as a simple variable reference
551 ARGS(*,i) is a synonym for ARGS(-,i) to resemble
552 the object syntax (see help,oxy), although the
553 analogy is not exact.
554 ARGS(0,i) returns a flag describing the argument:
555 0 if argument is a simple variable reference (set value works)
556 1 if argument is an expression (set value will be discarded)
557 2 if argument does not exist (as opposed to simply nil)
558 For obscure situations, there is also:
559 ARGS(i,:) same as ARGS(i), except if the argument is an lvalue,
560 it is not fetched.
561 This rather arcane feature permits you to pass an argument of the
562 form f.x, where f is a file handle, to functions like dimsof or
563 structof without triggering a read of the file. Do not assign
564 the result to a variable; use it only as an argument to another
565 function. The first time you call ARGS(i) for argument i, the
566 lvalue is fetched, and ARGS(i,:) will do nothing special.
567 SEE ALSO: errs2caller
568 */
569
570 extern errs2caller;
571 /* DOCUMENT errs2caller, f1, f2, ...
572 makes function F1 (and optionally F2, ...) pass control for dbug
573 mode to its caller if a fault occurs inside F1. This makes F1
574 behave more like a compiled function for its caller. For example,
575 if you are writing a mathematical function, you can raise an
576 error in its caller rather than in the function itself -- which
577 is appropriate if the only errors your function raises are, for
578 example, domain errors. Your function will then respond to a
579 domain error in the same way as, for example, asin(1.5).
580 If you want to wrap arguments of such a function, you need to call
581 errs2caller before wrap_args.
582 SEE ALSO: wrap_args
583 */
584
585 /*= SECTION(query) finding out variable type and properties ================*/
586
587 extern structof;
588 /* DOCUMENT structof(object)
589 returns the data type of OBJECT, or nil for non-array OBJECTs.
590 Use typeof(object) to get the ASCII name of a the data type.
591 SEE ALSO: typeof, dimsof, numberof, sizeof, nameof
592 */
593
594 extern dimsof;
595 /* DOCUMENT dimsof(object)
596 or dimsof(object1, object2, ...)
597 returns a vector of integers describing the dimensions of OBJECT.
598 The format of the vector is [number of dims, length1, length2, ...].
599 The orgsof function returns the origin of each dimension (normally 1).
600 If more than one argument is given, dimsof returns the dimension
601 list of the result of binary operations between all the objects,
602 or nil if the objects are not conformable.
603 SEE ALSO: typeof, structof, numberof, sizeof, orgsof
604 */
605
606 extern orgsof;
607 /* DOCUMENT orgsof(object)
608 returns a vector of integers describing the dimensions of OBJECT.
609 The format of the vector is [number of dims, origin1, origin2, ...].
610 By default, dimension origins are ignored, but use_origins changes
611 this. The dimsof function returns the length of each dimension.
612 *** NOTE NOTE NOTE ***
613 Unless use_origins(1) is in effect, orgsof will always return
614 1 for all of the originI in the list. Thus, whether use_origins(1)
615 is in effect or not, you are guaranteed that x(orgsof(x)(2)) is the
616 first element of x.
617
618 *** DEPRECATED ***
619 Do not use index origins. Your brain will explode sooner or later.
620
621 SEE ALSO: dimsof, typeof, structof, numberof, sizeof, use_origins
622 */
623
624 extern use_origins;
625 /* DOCUMENT dummy= use_origins(dont_force)
626 Yorick array dimensions have an origin as well as a length.
627 By default, this origin is 1 (like FORTRAN arrays, unlike C
628 arrays). However, the array function and the pseudo-index (-)
629 can be used to produce arrays with other origins.
630
631 Initially, the origin of an array index is ignored by Yorick; the
632 first element of any array has index 1. You can change this
633 default behavior by calling use_origins with non-zero DONT_FORCE,
634 and restore the default behavior by calling use_origins(0).
635
636 When the returned object DUMMY is destroyed, either by return from
637 the function in which it is a local variable, or by explicit
638 redefintion of the last reference to it, the treatment of array
639 index origins reverts to the behavior prior to the call to
640 use_origins. Thus, you can call use_origins at the top of a
641 function and not worry about restoring the external behavior
642 before every possible return (including errors).
643
644 *** DEPRECATED ***
645 Do not use index origins. Your brain will explode sooner or later.
646
647 SEE ALSO: array, dimsof, orgsof
648 */
649
650 extern sizeof;
651 /* DOCUMENT sizeof(object)
652 returns the size of the object in bytes, or 0 for non-array objects.
653 sizeof(structure_definition) returns the number of bytes per instance.
654 sizeof(binary_file) returns the file size in bytes.
655 SEE ALSO: dimsof, typeof, structof, numberof
656 */
657
658 extern numberof;
659 /* DOCUMENT numberof(object)
660 returns the number of elements if object is an array, or 0 if not.
661 SEE ALSO: sizeof, dimsof, typeof, structof
662 */
663
664 extern typeof;
665 /* DOCUMENT typeof(object)
666 returns a string describing the type of object. For the basic
667 data types, these are "char", "short", "int", "long", "float",
668 "double", "complex", "string", "pointer", "struct_instance",
669 "void", "range", "struct_definition", "function", "builtin",
670 "stream" (for a binary stream), and "text_stream".
671 SEE ALSO: structof, dimsof, sizeof, numberof, nameof
672 */
673
674 extern nameof;
675 /* DOCUMENT nameof(object)
676 If OBJECT is a function or a structure definition, returns the
677 name of the func or struct as it was defined (not necessarily
678 the name of the variable passed to the nameof function).
679 SEE ALSO: typeof
680 */
681
682 extern is_array;
683 /* DOCUMENT is_array(object)
684 returns 1 if OBJECT is an array data type (as opposed to a function,
685 structure definition, index range, I/O stream, etc.), else 0.
686 An array OBJECT can be written to or read from a binary file;
687 non-array Yorick data types cannot.
688 SEE ALSO: is_func, is_void, is_range, is_struct, is_stream, is_scalar
689 */
690
691 extern is_func;
692 /* DOCUMENT is_func(object)
693 returns 1 if OBJECT is a Yorick interpreted function, 2 if OBJECT
694 is a built-in (that is, compiled) function, 3 if OBJECT is an
695 autoload, 4 if object is a wrap_args function, 5 if object
696 is a closure function, else 0.
697 SEE ALSO: is_array, is_void, is_range, is_struct, is_stream, autoload,
698 closure
699 */
700
701 extern is_void;
702 /* DOCUMENT is_void(object)
703 returns 1 if OBJECT is nil (the one instance of the void data type),
704 else 0.
705 SEE ALSO: is_array, is_func, is_range, is_struct, is_stream
706 */
707
708 extern is_range;
709 /* DOCUMENT is_range(object)
710 returns 1 if OBJECT is an index range (e.g.- 3:5 or 11:31:2),
711 else 0.
712 SEE ALSO: rangeof, is_array, is_func, is_void, is_struct, is_stream
713 */
714
715 extern rangeof;
716 /* DOCUMENT rangeof(range)
717 rangeof(list)
718 converts index range RANGE into array of 4 longs, or array of 4 longs
719 LIST into an index range. The LIST is:
720 [min, max, inc, flags]
721 flags: 1-bit min nil, 2-bit max nil,
722 plus 4 times:
723 1-4 - .. * where(0)
724 5-12 min max ptp sum avg rms mnx mxx
725 13-18 psum dif zcen pcen uncp cum
726 SEE ALSO: is_range
727 */
728
729 extern is_struct;
730 /* DOCUMENT is_struct(object)
731 returns 1 if OBJECT is the definition of a Yorick struct, else 0.
732 Thus, is_struct(double) returns 1, but is_struct(1.0) returns 0.
733 SEE ALSO: is_array, is_func, is_void, is_range, is_stream
734 */
735
736 extern is_stream;
737 /* DOCUMENT is_stream(object)
738 returns 1 if OBJECT is a binary I/O stream (usually a file), else 0.
739 The _read and _write functions work on object if and only if
740 is_stream returns non-zero. Note that is_stream returns 0 for a
741 text stream -- you need the typeof function to test for those.
742 SEE ALSO: is_array, is_func, is_void, is_range, is_struct
743 */
744
745 extern is_list;
746 /* DOCUMENT is_list(object)
747 returns 1 if OBJECT is a list or nil, else 0 (see _lst).
748 SEE ALSO: is_array, is_func, is_void, is_range, is_struct, _lst
749 */
750
751 extern is_scalar;
752 extern is_vector;
753 extern is_matrix;
754 /* DOCUMENT is_scalar(x)
755 or is_vector(x)
756 or is_matrix(x)
757 These functions return true if X is (respectively) a scalar, a vector
758 (i.e., a 1-D array), or a matrix (i.e., a 2-D array).
759
760 SEE ALSO: dimsof,
761 is_array, is_func, is_hash, is_integer, is_list, is_range,
762 is_stream, is_struct, is_void.
763 */
764
765 extern is_integer;
766 extern is_real;
767 extern is_complex;
768 extern is_numerical;
769 extern is_string;
770 extern is_pointer;
771 /* DOCUMENT is_integer(x)
772 or is_real(x)
773 or is_complex(x)
774 or is_numerical(x)
775 or is_string(x)
776 or is_pointer(x)
777 These functions return true if X is an array of type: integer, real
778 (i.e. double or float), complex, numerical (i.e. integer, real or
779 complex), string, or pointer.
780
781 SEE ALSO: structof, dimsof,
782 is_array, is_func, is_hash, is_list, is_range, is_scalar,
783 is_stream, is_struct, is_void.
784 */
785
786 extern identof;
787 local Y_CHAR, Y_SHORT, Y_INT, Y_LONG;
788 local Y_FLOAT, Y_DOUBLE, Y_COMPLEX;
789 local Y_STRING, Y_POINTER, Y_STRUCT;
790 local Y_RANGE, Y_LVALUE, Y_VOID;
791 local Y_FUNCTION, Y_BUILTIN;
792 local Y_STRUCTDEF, Y_STREAM, Y_OPAQUE;
793 /* DOCUMENT identof(object)
794 Returns type identifier of OBJECT as a long integer:
795 0 (Y_CHAR) for an array of char('s)
796 1 (Y_SHORT) for an array of short('s)
797 2 (Y_INT) for an array of int('s)
798 3 (Y_LONG) for an array of long('s)
799 4 (Y_FLOAT) for an array of float('s)
800 5 (Y_DOUBLE) for an array of double('s)
801 6 (Y_COMPLEX) for an array of complex('s)
802 7 (Y_STRING) for an array of string('s)
803 8 (Y_POINTER) for an array of pointer('s)
804 9 (Y_STRUCT) for a structure object
805 10 (Y_RANGE) for a range object
806 11 (Y_LVALUE) for a lvalue
807 12 (Y_VOID) for a void (undefined) object
808 13 (Y_FUNCTION) for a function array
809 14 (Y_BUILTIN) for a builtin array
810 15 (Y_STRUCTDEF) for a data type or structure definition
811 16 (Y_STREAM) for a file stream
812 17 (Y_OPAQUE) for an opaque object
813
814 SEE ALSO: typeof, structof.
815 */
816 Y_CHAR = 0;
817 Y_SHORT = 1;
818 Y_INT = 2;
819 Y_LONG = 3;
820 Y_FLOAT = 4;
821 Y_DOUBLE = 5;
822 Y_COMPLEX = 6;
823 Y_STRING = 7;
824 Y_POINTER = 8;
825 Y_STRUCT = 9;
826 Y_RANGE = 10;
827 Y_LVALUE = 11;
828 Y_VOID = 12;
829 Y_FUNCTION = 13;
830 Y_BUILTIN = 14;
831 Y_STRUCTDEF = 15;
832 Y_STREAM = 16;
833 Y_OPAQUE = 17;
834
835 extern am_subroutine;
836 /* DOCUMENT am_subroutine()
837 returns 1 if the current Yorick function was invoked as a subroutine,
838 else 0. If am_subroutine() returns true, the result of the current
839 function will not be used, and need not be computed (the function
840 has been called for its side effects only).
841 */
842
843 /*= SECTION(math) simple mathematical functions ============================*/
844
845 extern sin;
846 extern cos;
847 extern tan;
848 /* DOCUMENT sin(x)
849 cos(x)
850 tan(x)
851 returns the sine, cosine, or tangent of its argument,
852 which is in radians.
853 SEE ALSO: asin, acos, atan
854 */
855
856 extern asin;
857 /* DOCUMENT asin(x)
858 returns the inverse sine of its argument, range [-pi/2, pi/2].
859 SEE ALSO: sin, cos, tan, asin, acos, atan
860 */
861
862 extern acos;
863 /* DOCUMENT acos(x)
864 returns the inverse cosine of its argument, range [0, pi].
865 SEE ALSO: sin, cos, tan, asin, acos, atan
866 */
867
868 extern atan;
869 /* DOCUMENT atan(x)
870 or atan(y, x)
871 returns the inverse tangent of its argument, range [-pi/2, pi/2].
872 In the two argument form, returns the angle from (1, 0) to (x, y),
873 in the range (-pi, pi], with atan(1, 0)==pi/2. (If x>=0, this is
874 the same as atan(y/x).)
875 SEE ALSO: sin, cos, tan, asin, acos, atan
876 */
877
878 local pi;
879 /* DOCUMENT pi
880 roughly 3.14159265358979323846264338327950288
881 */
882 pi= 4.0*atan(1.0); /* to double precision on this machine */
883
884 extern sinh;
885 extern cosh;
886 extern tanh;
887 /* DOCUMENT sinh(x)
888 cosh(x)
889 tanh(x)
890 returns the hyperbolic sine, cosine, or tangent of its argument.
891 SEE ALSO: sech, csch, asinh, acosh, atanh
892 */
893
sech(x)894 func sech(x) { x = exp(_neg_re(x)); return (x+x)/(1.+x*x); }
csch(x)895 func csch(x) { y = _neg_re(x,x); return (4.*x-2.)*exp(y)/expm1(y+y); }
896 /* DOCUMENT sech(x)
897 csch(x)
898 returns the hyperbolic secant (1/cosh) or cosecant (1/sinh) of
899 its argument, without overflowing for large x.
900 SEE ALSO: sinh, cosh, tanh, asinh, acosh, atanh
901 */
902 func _neg_re(x,&m) { m = double(double(x)<0.); return m*x - (1.-m)*x; }
903
904 /* note: factorization in acosh prevents possible overflow
905 * asinh = log(x+sqrt(x*x+1.0)) has both overflow problem
906 * and small x problem */
asinh(x)907 func asinh(x) { y=-_neg_re(x,x); return (1.-2.*x)*log1p(y+_sqrt_x2p1m1(y)); }
acosh(x)908 func acosh(x) { return log(x+sqrt(x+1.)*sqrt(x-1.)); }
atanh(x)909 func atanh(x) { y=_neg_re(x,x); return (x-0.5)*log1p((y+y)/(1.0-y)); }
910 /* DOCUMENT asinh(x)
911 acosh(x)
912 atanh(x)
913 returns the inverse hyperbolic sine, cosine, or tangent of
914 its argument. The range of real acosh is >=0.0.
915 SEE ALSO: sinh, cosh, tanh, sech, csch
916 */
_sqrt_x2p1m1(x)917 func _sqrt_x2p1m1(x)
918 {
919 mask = abs(x) > 1.e18;
920 b = x(where(mask));
921 if (numberof(b)) { /* avoid overflow for big x */
922 s = 1./b;
923 b *= sqrt(1.+s*s);
924 b = -(_neg_re(b)+1.);
925 }
926 s = x(where(!mask));
927 if (numberof(s)) { /* avoid rounding error for small x */
928 s *= s;
929 s /= (sqrt(1.+s) + 1.);
930 }
931 return merge(b, s, mask);
932 }
933
934 extern exp;
935 /* DOCUMENT exp(x)
936 returns the exponential function of its argument (inverse of log).
937 SEE ALSO: expm1, log, log10, sinh, cosh, tanh, sech, csch
938 */
939
940 extern log;
941 /* DOCUMENT log(x)
942 returns the natural logarithm of its argument (inverse of exp).
943 SEE ALSO: log1p, log10, exp, asinh, acosh, atanh
944 */
945
946 extern log10;
947 /* DOCUMENT log10(x)
948 returns the base 10 logarithm of its argument (inverse of 10^x).
949 SEE ALSO: log, exp, asinh, acosh, atanh
950 */
951
952 func expm1(x, &ex)
953 /* DOCUMENT expm1(x)
954 or expm1(x, ex)
955 return exp(X)-1 accurate to machine precision (even for X<<1)
956 in the second form, returns exp(x) to EX
957 SEE ALSO: exp, log1p
958 */
959 {
960 ex = exp(x);
961 return (ex-1.) + (x-log(ex+!ex))*ex;
962 }
963
log1p(x)964 func log1p(x)
965 /* DOCUMENT log1p(x)
966 return log(1+X) accurate to machine precision (even for X<<1)
967 from Goldberg, ACM Computing Surveys, Vol 23, No 1, March 1991,
968 apparently originally from HP-15C Advanced Functions Handbook
969 SEE ALSO: expm1, log1p
970 */
971 {
972 y = 1.+x; z = double(y == 1.);
973 return x * (log(y)+z)/(y-1.+z);
974 }
975
976 errs2caller, sech, csch, asinh, acosh, atanh, expm1, log1p;
977
978 extern sqrt;
979 /* DOCUMENT sqrt(x)
980 returns the square root of its argument.
981 SEE ALSO: abs
982 */
983
984 extern poly;
985 /* DOCUMENT poly(x, a0, a1, a2, ..., aN)
986 returns the polynomial A0 + A1*x + A2*x^2 + ... + AN*X^N
987 The data type and dimensions of the result, and conformability rules
988 for the inputs are identical to those for the expression.
989 */
990
991 extern ceil;
992 /* DOCUMENT ceil(x)
993 returns the smallest integer not less than x (no-op on integers).
994 SEE ALSO: floor, round
995 */
996
997 extern floor;
998 /* DOCUMENT floor(x)
999 returns the largest integer not greater than x (no-op on integers).
1000 SEE ALSO: ceil, round
1001 */
1002
1003 extern lround;
1004 extern round;
1005 /* DOCUMENT round(x);
1006 lround(x);
1007 These functions return X rounded to the nearest integer. The result of
1008 round(X) is a floating point value, while that of lround(X) is a long
1009 integer. They are respectively equivalent to: floor(X+0.5) and
1010 long(floor(X+0.5)).
1011 SEE ALSO: floor, ceil
1012 */
1013
1014 extern abs;
1015 /* DOCUMENT abs(x)
1016 or abs(x, y, z, ...)
1017 returns the absolute value of its argument.
1018 In the multi-argument form, returns sqrt(x^2+y^2+z^2+...).
1019 SEE ALSO: sign, sqrt
1020 */
1021
1022 extern sign;
1023 /* DOCUMENT sign(x)
1024 returns algebraic sign of it argument, or closest point on the
1025 unit circle for complex x. Guaranteed that x==sign(x)*abs(x).
1026 sign(0)==+1.
1027 SEE ALSO: abs
1028 */
1029
1030 extern conj;
1031 /* DOCUMENT conj(z)
1032 returns the complex conjugate of its argument.
1033 */
1034
1035 local re_part;
1036 /* DOCUMENT re_part(z)
1037 returns the real part of its argument. (Same as double(z).)
1038 Unlike z.re, works if z is not complex.
1039 */
1040 re_part= double;
1041
im_part(z)1042 func im_part(z)
1043 /* DOCUMENT im_part(z)
1044 returns the imaginary part of its argument.
1045 Unlike z.im, works if z is not complex (returns zero).
1046 */
1047 {
1048 return (structof(z)==complex)? z.im : array(0.0, dimsof(z));
1049 }
1050
1051 extern random;
1052 extern random_seed;
1053 /* DOCUMENT random(dimension_list)
1054 random_seed, seed
1055 returns an array of random double values with the given
1056 DIMENSION_LIST (nil for a scalar result), uniformly distributed
1057 on the interval from 0.0 to 1.0.
1058 The algorithm is from Press and Teukolsky, Computers in Physics,
1059 vol. 6, no. 5, Sep/Oct 1992 (ran2). They offer a reward of $1000
1060 to anyone who can exhibit a statistical test that this random
1061 number generator fails in a "non-trivial" way.
1062 The random_seed call reinitializes the random number sequence;
1063 SEED should be between 0.0 and 1.0 non-inclusive; if SEED is
1064 omitted, nil, or out of range, the sequence is reinitialized as
1065 when Yorick starts.
1066 The numbers are actually at the centers of 2147483562 equal width
1067 bins on the interval [0,1]. Although only these 2 billion numbers
1068 are possible, the period of the generator is roughly 2.3e18.
1069
1070 SEE ALSO: randomize
1071 */
1072
randomize(void)1073 func randomize(void)
1074 /* DOCUMENT randomize
1075 randomize()
1076 set the seed for random "randomly" (based on the timer clock
1077 and the current state of random). As a function, returns the
1078 value of the seed passed to random_seed.
1079
1080 SEE ALSO: random, random_seed
1081 */
1082 {
1083 seed= array(0., 3);
1084 timer, seed;
1085 seed= pi*sum(abs(seed));
1086 while (seed > 0.9) seed*= 0.1;
1087 seed+= 0.05;
1088 random_seed, seed;
1089 return seed;
1090 }
1091
1092 /*= SECTION(array) building and manipulating arrays ========================*/
1093
1094 extern array;
1095 /* DOCUMENT array(value, dimension_list)
1096 or array(type, dimension_list)
1097 returns an object of the same type as VALUE, consisting of copies
1098 of VALUE, with the given DIMENSION_LIST appended to the dimensions
1099 of VALUE. Hence, array(1.5, 3, 1) is the same as [[1.5, 1.5, 1.5]].
1100 In the second form, the VALUE is taken as scalar zero of the TYPE.
1101 Hence, array(short, 2, 3) is the same as [[0s,0s],[0s,0s],[0s,0s]].
1102 A DIMENSION_LIST is a list of arguments, each of which may be
1103 any of the following:
1104 (1) A positive scalar integer expression,
1105 (2) An index range with no step field (e.g.- 1:10), or
1106 (3) A vector of integers [number of dims, length1, length2, ...]
1107 (that is, the format returned by the dimsof function).
1108 SEE ALSO: reshape, is_array, dimsof, numberof, grow, span, use_origins,
1109 _lst
1110 */
1111
1112 extern allof;
1113 extern anyof;
1114 extern noneof;
1115 extern nallof;
1116 /* DOCUMENT allof(x)
1117 anyof(x)
1118 nallof(x)
1119 noneof(x)
1120 Respectively:
1121 returns 1 if every element of the array x is non-zero, else 0.
1122 returns 1 if at least one element of the array x is non-zero, else 0.
1123 returns 1 if at least one element of the array x is zero, else 0.
1124 returns 1 if every element of the array x is zero, else 0.
1125 SEE ALSO: allof, anyof, noneof, nallof, where, where2
1126 */
1127
1128 extern where;
1129 /* DOCUMENT where(x)
1130 returns the vector of longs which is the index list of non-zero
1131 values in the array x. Thus, where([[0,1,3],[2,0,4]]) would
1132 return [2,3,4,6]. If noneof(x), where(x) is a special range
1133 function which will return a nil value if used to index an array;
1134 hence, if noneof(x), then x(where(x)) is nil.
1135 If x is a non-zero scalar, then where(x) returns a scalar value.
1136 The rather recondite behavior for scalars and noneof(x) provides
1137 maximum performance when the merge function to be used with the
1138 where function.
1139 SEE ALSO: where2, merge, merge2 allof, anyof, noneof, nallof, sort
1140 */
1141
where2(x)1142 func where2(x)
1143 /* DOCUMENT where2(x)
1144 like where(x), but the returned list is decomposed into indices
1145 according to the dimensions of x. The returned list is always
1146 2 dimensional, with the second dimension the same as the dimension
1147 of where(x). The first dimension has length corresponding to the
1148 number of dimensions of x. Thus, where2([[0,1,3],[2,0,4]]) would
1149 return [[2,1],[3,1],[1,2],[3,2]].
1150 If noneof(x), where2 returns [] (i.e.- nil).
1151 SEE ALSO: where, merge, merge2, allof, anyof, noneof, nallof, sort
1152 */
1153 {
1154 w= where(x);
1155 /* Since the result of where2 cannot be used as an index list, the
1156 case noneof(x) can be disposed of more easily than with where. */
1157 if (!is_array(w)) return [];
1158 d= dimsof(x);
1159 n= d(1);
1160 if (!n) return w; /* catcall for passing a scalar */
1161 d= d(2:);
1162 o= orgsof(x)(2:);
1163 w2= w(-:1:n,);
1164 w-= o(1);
1165 for (i=1 ; i<=n ; i++) {
1166 w2(i,)= w%d(i) + o(i);
1167 w/= d(i);
1168 }
1169 return w2;
1170 }
1171
1172 extern merge;
1173 /* DOCUMENT merge(true_expr, false_expr, condition)
1174 returns the values TRUE_EXPR or FALSE_EXPR where CONDITION is
1175 non-zero or zero, respectively. The result has the data type of
1176 TRUE_EXPR or FALSE_EXPR, promoted to the higher arithmetic type
1177 if necessary. The result has the dimensions of CONDITION.
1178 The number of elements in TRUE_EXPR must match the number of
1179 non-zero elements of CONDITION, and the number of elements in
1180 FALSE_EXPR must match the number of zero elements of CONDITION.
1181 (TRUE_EXPR or FALSE_EXPR should be nil if there are no such
1182 elements of CONDITION. Normally, TRUE_EXPR and FALSE_EXPR should
1183 be 1-D arrays if they are not nil.)
1184 This function is intended for vectorizing a function whose
1185 domain is divided into two or more parts, as in:
1186 func f(x) {
1187 big= (x>=threshhold);
1188 wb= where(big);
1189 ws= where(!big);
1190 if (is_array(wb)) {
1191 xx= x(wb);
1192 fb= <function of xx>
1193 }
1194 if (is_array(ws)) {
1195 xx= x(ws);
1196 fs= <function of xx>
1197 }
1198 return merge(fb, fs, big);
1199 }
1200 SEE ALSO: mergef, merge2, where
1201 */
1202
merge2(t,f,c)1203 func merge2(t, f, c)
1204 /* DOCUMENT merge2(true_expr, false_expr, condition)
1205 returns the values TRUE_EXPR or FALSE_EXPR where CONDITION is
1206 non-zero or zero, respectively. The result has the data type of
1207 TRUE_EXPR or FALSE_EXPR, promoted to the higher arithmetic type
1208 if necessary. Unlike the merge function, TRUE_EXPR and FALSE_EXPR
1209 must be conformable with each other, and with the CONDITION.
1210 SEE ALSO: merge, where, mergef
1211 */
1212 {
1213 dims= dimsof(t, f, c);
1214 if (dims(1)) {
1215 c+= array(structof(c), dims);
1216 tt= array(structof(t), dims); tt(..)= t;
1217 ff= array(structof(f), dims); ff(..)= f;
1218 } else {
1219 tt= t;
1220 ff= f;
1221 }
1222 return merge(tt(where(c)), ff(where(!c)), c);
1223 }
1224
mergei(__x,..)1225 func mergei(__x, ..)
1226 /* DOCUMENT y = mergei(x, f0, x1, f1, x2, ... xN, fN)
1227 * Evaluate F1 where X<X1, F2 where X1<=X<X2, ..., FN where X>=XN,
1228 * and merge all the results back into an array Y with the
1229 * same dimensions as X.
1230 *
1231 * During the evaluation of Fi, all of the local variables of
1232 * the caller of mergei are available. The Fi are called in
1233 * order, skipping any for which no X is in the specified interval.
1234 * Each Fi must return a value with the same dimensions as
1235 * its input.
1236 *
1237 * Additional input and output variables can be constructed using
1238 * the mergel index list employed by mergei, and using the mergeg
1239 * function. For example, let w be an additional input to and z be
1240 * an additional output from the function:
1241 * func myfunc(x, w, &z) {
1242 * z = array(0.0, dimsof(x, w));
1243 * x += z;
1244 * w += z;
1245 * return mergei(x, _myfunc_lo, 1.234, _myfunc_hi);
1246 * }
1247 * func _myfunc_lo(x) {
1248 * wp = w(mergel); // part of w for this function
1249 * z = mergeg(z, <expression using x and wp>);
1250 * return <expression using x and wp>;
1251 * }
1252 * func _myfunc_hi(x) {
1253 * wp = w(mergel); // part of w for this function
1254 * z = mergeg(z, <expression using x and wp>);
1255 * return <expression using x and wp>;
1256 * }
1257 *
1258 * SEE ALSO: mergef, merge
1259 */
1260 {
1261 /**/ local __r;
1262 _1_ = !dimsof(__x)(1);
1263 __n = dimsof(__x)(1)? indgen(numberof(__x)) : 1;
1264 while (numberof(__x)) {
1265 __f = next_arg();
1266 __m = next_arg();
1267 __m = is_void(__m)? (__n>0) : (__x < __m);
1268 __l = where(__m);
1269 if (numberof(__l)) {
1270 __m = where(!__m);
1271 mergel = __n(__l);
1272 if (_1_) return __f(__x);
1273 __f = __f(__x(__l));
1274 if (is_void(__r)) __r = array(structof(__f), dimsof(__x));
1275 __r(mergel) = __f;
1276 __x = __x(__m);
1277 __n = __n(__m);
1278 }
1279 }
1280 return __r;
1281 }
1282
mergef(__x,..)1283 func mergef(__x, ..)
1284 /* DOCUMENT y = mergef(x, f1, cond1, f2, cond2, ... felse)
1285 * Evaluate F1(X(where(COND1))), F2(X(where(COND2))),
1286 * and so on, until FELSE(X(where(!(COND1 | COND2 | ...))))
1287 * and merge all the results back into an array Y with the
1288 * same dimensions as X. Each of the CONDi must have the
1289 * same dimensions as X, and they must be mutally exclusive.
1290 *
1291 * During the evaluation of Fi, all of the local variables of
1292 * the caller of mergei are available. The Fi are called in
1293 * order, skipping any for which no X is in the specified interval.
1294 * Each Fi must return a double value with the same dimensions as
1295 * its input.
1296 *
1297 * Additional input and output variables can be constructed using
1298 * the mergel index list employed by mergei, and using the mergeg
1299 * function. For example, let w be an additional input to and z be
1300 * an additional output from the function:
1301 * func myfunc(x, w, &z) {
1302 * z = array(0.0, dimsof(x, w));
1303 * x += z;
1304 * w += z;
1305 * return mergef(x, _myfunc_lo, x<1.234, _myfunc_hi);
1306 * }
1307 * func _myfunc_lo(x) {
1308 * wp = w(mergel); // part of w for this function
1309 * z = mergeg(z, <expression using x and wp>);
1310 * return <expression using x and wp>;
1311 * }
1312 * func _myfunc_hi(x) {
1313 * wp = w(mergel); // part of w for this function
1314 * z = mergeg(z, <expression using x and wp>);
1315 * return <expression using x and wp>;
1316 * }
1317 *
1318 * SEE ALSO: mergei, merge
1319 */
1320 {
1321 /**/ local __r;
1322 _1_ = !dimsof(__x)(1);
1323 __n = dimsof(__x)(1)? indgen(numberof(__x)) : 1;
1324 while (numberof(__x)) {
1325 __f = next_arg();
1326 __m = next_arg();
1327 __m = is_void(__m)? (__n>0) : __m(__n);
1328 __l = where(__m);
1329 if (numberof(__l)) {
1330 __m = where(!__m);
1331 mergel = __n(__l);
1332 if (_1_) return __f(__x);
1333 __f = __f(__x(__l));
1334 if (is_void(__r)) __r = array(structof(__f), dimsof(__x));
1335 __r(mergel) = __f;
1336 __x = __x(__m);
1337 __n = __n(__m);
1338 }
1339 }
1340 return __r;
1341 }
1342
1343 func mergeg(&z, value)
1344 /* DOCUMENT z = mergeg(z, value)
1345 * or z = mergeg(z)
1346 * If secondary results are to be returned from a mergef, besides
1347 * its return value, the Fi may construct them using mergeg.
1348 * z = mergeg(z, value)
1349 * where z is a variable in the original caller of mergef,
1350 * and value is its value.
1351 *
1352 * z = []; or z = <something with shape of x>;
1353 * y = mergef(x, f1, cond, f2);
1354 * z = mergeg(z); // this can now be omitted, but does no harm
1355 * ...
1356 * func f1(x) { <exprz(x) computes z(x), expry(x) computes y(x)>
1357 * z = mergeg(z, exprz(x));
1358 * return expry(x);
1359 * }
1360 * func f2(x) { <exprz(x) computes z(x), expry(x) computes y(x)>
1361 * z = mergeg(z, exprz(x));
1362 * return expry(x);
1363 * }
1364 *
1365 * SEE ALSO: mergef, merge
1366 */
1367 {
1368 if (is_void(value)) {
1369 return z; /* for backward compatibility */
1370 } else {
1371 /* void z case for backward compatibility */
1372 if (is_void(z)) z = array(structof(value), dimsof(__x));
1373 if (_1_) z = value;
1374 z(mergel) = value;
1375 return z;
1376 }
1377 }
1378
1379 extern grow;
1380 extern _;
1381 /* DOCUMENT grow, x, xnext1, xnext2, ...
1382 or grow(x, xnext1, xnext2, ...)
1383 or _(x, xnext1, xnext2, ...)
1384 lengthens the array X by appending XNEXT1, XNEXT2, etc. to its
1385 final dimension. If X is nil, X is first redefined to the first
1386 non-nil XNEXT, and the remainder of the XNEXT list is processed
1387 normally. Each XNEXT is considered to have the same number of
1388 dimensions as X, by appending unit-length dimensions if necessary.
1389 All but this final dimension of each XNEXT must be right-conformable
1390 (that is, conformable in the sense of the right hand side of an
1391 assignment statement) with all but the final dimension of X.
1392 The result has a final dimension which is the sum of the final
1393 dimension of X and all the final dimensions of the XNEXT. Nil
1394 XNEXT are ignored. The value of the result is obtained by
1395 concatenating all the XNEXT to X, after any required broadcasts.
1396
1397 If invoked as a function, grow returns the new value of X; in
1398 this case, X may be an expression. X must be a simple variable
1399 reference for the subroutine form of grow; otherwise there is
1400 nowhere to return the result. The subroutine form is slightly
1401 more efficient than the function form for the common usage:
1402 x= grow(x, xnext1, xnext2) is the same as
1403 grow, x, xnext1, xnext2 the preferred form
1404
1405 The _ function is a synonym for grow, for people who want this
1406 operator to look like punctuation in their source code, on analogy
1407 with the array building operator [a, b, c, ...].
1408
1409 The _cat function is sometimes more appropriate than grow.
1410
1411 Usage note:
1412 Never do this:
1413 while (more_data) grow, result, datum;
1414 The time to complete this loop scales as the SQUARE of the number
1415 of passes! Instead, do this:
1416 for (i=1,result=array(things,n_init) ; more_data ; i++) {
1417 if (i>numberof(result)) grow, result, result;
1418 result(i) = datum;
1419 }
1420 result = result(1:i-1);
1421 The time to complete this loop scales as n*log(n), because the
1422 grow operation doubles the length of the result each time.
1423
1424 SEE ALSO: _cat, array
1425 */
1426
1427 extern indgen;
1428 /* DOCUMENT indgen(n)
1429 or indgen(start:stop)
1430 or indgen(start:stop:step)
1431 returns "index generator" list -- an array of longs running from
1432 1 to N, inclusive. In the second and third forms, the index
1433 values specified by the index range are returned.
1434 SEE ALSO: span, spanl, array
1435 */
1436
1437 extern span;
1438 /* DOCUMENT span(start, stop, n)
1439 or span(start, stop, n, which)
1440 returns array of N doubles equally spaced from START to STOP.
1441 The START and STOP arguments may themselves be arrays, as long as
1442 they are conformable. In this case, the result will have one
1443 dimension of length N in addition to dimsof(START, STOP).
1444 By default, the result will be N-by-dimsof(START, STOP), but
1445 if WHICH is specified, the new one of length N will be the
1446 WHICHth. WHICH may be non-positive to position the new
1447 dimension relative to the end of dimsof(START, STOP); in
1448 particular WHICH of 0 produces a result with dimensions
1449 dimsof(START, STOP)-by-N.
1450 SEE ALSO: spanl, indgen, array
1451 */
1452
spanl(start,stop,n,which)1453 func spanl(start, stop, n, which)
1454 /* DOCUMENT spanl(start, stop, n)
1455 or spanl(start, stop, n, which)
1456 similar to the span function, but the result array have N points
1457 spaced at equal ratios from START to STOP (that is, equally
1458 spaced logarithmically). See span for discussion of WHICH argument.
1459 START and STOP must have the same algebraic sign for this to make
1460 any sense.
1461 SEE ALSO: span, indgen, array
1462 */
1463 {
1464 if (is_void(which)) which = 1;
1465 s = sign(start+0*stop);
1466 return exp(span(log(abs(start)), log(abs(stop)), n, which)) *
1467 span(s,s,n,which);
1468 }
1469 errs2caller, spanl;
1470
1471 extern digitize;
1472 /* DOCUMENT digitize(x, bins)
1473 returns an array of longs with dimsof(X), and values i such that
1474 BINS(i-1) <= X < BINS(i) if BINS is monotonically increasing, or
1475 BINS(i-1) > X >= BINS(i) if BINS is monotonically decreasing.
1476 Beyond the bounds of BINS, returns either i=1 or i=numberof(BINS)+1
1477 as appropriate.
1478 SEE ALSO: histogram, interp, integ, sort, where, where2
1479 */
1480
1481 extern histogram;
1482 /* DOCUMENT histogram(list)
1483 or histogram(list, weight)
1484 returns an array hist which counts the number of occurrences of each
1485 element of the input index LIST, which must consist of positive
1486 integers (1-origin index values into the result array):
1487 histogram(list)(i) = number of occurrences of i in LIST
1488
1489 A second argument WEIGHT must have the same shape as LIST; the result
1490 will be the sum of WEIGHT:
1491 histogram(list)(i) = sum of all WEIGHT(j) where LIST(j)==i
1492
1493 The result of the single argument call will be of type long; the
1494 result of the two argument call will be of type double (WEIGHT is
1495 promoted to that type). The input argument(s) may have any number
1496 of dimensions; the result is always 1-D.
1497
1498 KEYWORD: top=max_list_value
1499 By default, the length of the result is max(LIST). You may
1500 specify that the result have a larger length by means of the TOP
1501 keyword. (Elements beyond max(LIST) will be 0, of course.)
1502
1503 SEE ALSO: digitize, sort, histinv
1504 */
1505
histinv(hist)1506 func histinv(hist)
1507 /* DOCUMENT list = histinv(hist)
1508 returns a list whose histogram is HIST, hist = histogram(list),
1509 that is, hist(1) 1's followed by hist(2) 2's, followed by hist(3)
1510 3's, and so on. The total number of elements in the returned
1511 list is sum(hist). All values in HIST must be non-negative;
1512 if sum(hist)==0, histinv returns []. The input HIST array may
1513 have any number of dimensions; the result will always be either
1514 nil or a 1D array.
1515
1516 SEE ALSO: histogram
1517 */
1518 {
1519 if (anyof(hist < 0)) error, "histinv argument must be non-negative";
1520 hist = hist(*)(psum);
1521 return hist(0)? histogram(hist+1)(psum:1:-1) + 1 : [];
1522 }
1523
1524 extern reshape;
1525 /* DOCUMENT reshape, reference, address, type, dimension_list
1526 or reshape, reference, type, dimension_list
1527 or reshape, reference
1528 The REFERENCE must be an unadorned variable, not an expression;
1529 reshape sets this variable to an LValue at the specified ADDRESS
1530 with the specified TYPE and DIMENSION_LIST. (See the array
1531 function documentation for acceptable DIMENSION_LIST formats.)
1532 If ADDRESS is an integer (e.g.- a long), the programmer is
1533 responsible for assuring that the data at ADDRESS is valid.
1534 If ADDRESS is a (Yorick) pointer, Yorick will assure that the
1535 data pointed to will not be discarded, and the reshape will
1536 fail if TYPE and DIMENSION_LIST extend beyond the pointee
1537 bounds. In the second form, ADDRESS is taken to be &REFERENCE;
1538 that is, the TYPE and DIMENSION_LIST of the variable are changed
1539 without doing any type conversion. In the third form, REFERENCE
1540 is set to nil ([]). (Simple redefinition will not work on a
1541 variable defined using reshape.)
1542 WARNING: There are almost no situations for which reshape is
1543 the correct operation. Use reform instead.
1544 SEE ALSO: reform, array, dimsof, numberof, is_array, eq_nocopy
1545 */
1546
reform(x,..)1547 func reform(x, ..)
1548 /* DOCUMENT reform(x, dimlist)
1549 * returns array X reshaped according to dimension list DIMLIST.
1550 * SEE ALSO: array, dimsof, accum_dimlist
1551 */
1552 {
1553 dims = [0];
1554 while (more_args()) accum_dimlist, dims, next_arg();
1555 if (dims(1)) {
1556 y = array(structof(x), dims);
1557 y(*) = x(*); /* will blow up if lengths differ */
1558 } else {
1559 if (numberof(x)>1) error, "X longer than specified DIMLIST";
1560 y = x(1);
1561 }
1562 return y;
1563 }
1564
1565 func accum_dimlist(&dims, d)
1566 /* DOCUMENT accum_dimlist, dims, d
1567 accumulate a dimension argument D onto a dimension list DIMS.
1568 This can be used to emulate the dimension lists supplied to the
1569 array function. For example:
1570 func myfunc(arg1, arg2, ..) {
1571 local dims;
1572 while (more_args()) accum_dimlist, dims, next_arg();
1573 ...
1574 }
1575 SEE ALSO: array, reform
1576 */
1577 {
1578 if (is_void(d)) return;
1579 if (is_range(d)) { /* yuck */
1580 mn = mx = 0;
1581 if (sread(print(d)(1),format="%ld:%ld",mn,mx) != 2)
1582 error, "only min:max ranges allowed in dimension list";
1583 d = mx - mn + 1;
1584 }
1585 r = dimsof(d)(1);
1586 if (!r) d = [++r, d];
1587 if (is_void(dims)) {
1588 dims = d;
1589 } else if (r && d(1)) {
1590 grow, dims, d(2:1+d(1));
1591 dims(1) += d(1);
1592 }
1593 }
1594
1595 extern interp;
1596 /* DOCUMENT interp(y, x, xp)
1597 or interp(y, x, xp, which)
1598 returns yp such that (XP, yp) lies on the piecewise linear curve
1599 (X(i), Y(i)) (i=1, ..., numberof(X)). Points beyond X(1) are set
1600 to Y(1); points beyond X(0) are set to Y(0). The array X must be
1601 one dimensional, have numberof(X)>=2, and be either monotonically
1602 increasing or monotonically decreasing. The array Y may have more
1603 than one dimension, but dimension WHICH must be the same length as
1604 X. WHICH defaults to 1, the first dimension of Y. WHICH may be
1605 non-positive to count dimensions from the end of Y; a WHICH of 0
1606 means the final dimension of Y. The result yp has dimsof(XP)
1607 in place of the WHICH dimension of Y (if XP is scalar, the WHICH
1608 dimension is not present). (The dimensions of the result are the
1609 same as if an index list with dimsof(XP) were placed in slot
1610 WHICH of Y.)
1611 SEE ALSO: integ, digitize, span
1612 */
1613
1614 extern integ;
1615 /* DOCUMENT integ(y, x, xp)
1616 or integ(y, x, xp, which)
1617 See the interp function for an explanation of the meanings of the
1618 arguments. The integ function returns ypi which is the integral
1619 of the piecewise linear curve (X(i), Y(i)) (i=1, ..., numberof(X))
1620 from X(1) to XP. The curve (X, Y) is regarded as constant outside
1621 the bounds of X. Note that X must be monotonically increasing or
1622 SEE ALSO: interp, digitize, span
1623 */
1624
1625 extern sort;
1626 /* DOCUMENT sort(x)
1627 or sort(x, which)
1628 returns an array of longs with dimsof(X) containing index values
1629 such that X(sort(X)) is a monotonically increasing array. X can
1630 contain integer, real, or string values. If X has more than one
1631 dimension, WHICH determines the dimension to be sorted. The
1632 default WHICH is 1, corresponding to the first dimension of X.
1633 WHICH can be non-positive to count dimensions from the end of X;
1634 in particular a WHICH of 0 will sort the final dimension of X.
1635
1636 WARNING: The sort function is non-deterministic if some of the
1637 values of X are equal, because the Quick Sort algorithm
1638 involves a random selection of a partition element.
1639
1640 For information on sorting with multiple keys (and on making
1641 sort deterministic), type the following: help, msort
1642
1643 SEE ALSO: median, digitize, interp, integ, histogram
1644 */
1645
1646 extern min;
1647 /* DOCUMENT min(x)
1648 or min(x, y, z, ...)
1649 returns the scalar minimum value of its array argument, or, if
1650 more than one argument is supplied, returns an array of the
1651 minimum value for each array element among the several arguments.
1652 In the multi-argument case, the arguments must be conformable.
1653 SEE ALSO: max, sum, avg
1654 */
1655
1656 extern max;
1657 /* DOCUMENT max(x)
1658 or max(x, y, z, ...)
1659 returns the scalar maximum value of its array argument, or, if
1660 more than one argument is supplied, returns an array of the
1661 maximum value for each array element among the several arguments.
1662 In the multi-argument case, the arguments must be conformable.
1663 SEE ALSO: min, sum, avg
1664 */
1665
1666 extern sum;
1667 /* DOCUMENT sum(x)
1668 returns the scalar sum of all elements of its array argument.
1669 If X is a string, concatenates all elements.
1670 SEE ALSO: avg, min, max
1671 */
1672
1673 extern avg;
1674 /* DOCUMENT avg(x)
1675 returns the scalar average of all elements of its array argument.
1676 SEE ALSO: sum, min, max
1677 */
1678
median(x,which)1679 func median(x, which)
1680 /* DOCUMENT median(x)
1681 or median(x, which)
1682 returns the median of the array X. The search for the median takes
1683 place along the dimension of X specified by WHICH. WHICH defaults
1684 to 1, meaning the first index of X. The median function returns an
1685 array with one fewer dimension than its argument X (the WHICH
1686 dimension of X is missing in the result), in exact analogy with
1687 rank reducing index range functions. If dimsof(X)(WHICH) is
1688 odd, the result will have the same data type as X; if even, the
1689 result will be a float or a double, since the median is defined
1690 as the arithmetic mean between the two central values in that
1691 case.
1692 SEE ALSO: sort
1693 */
1694 {
1695 if (is_void(which)) which= 1;
1696 list= sort(x, which);
1697 dims= dimsof(x);
1698 if (which<1) which= dims(1)-which;
1699 n= dims(1+which);
1700 odd= n%2;
1701 n/= 2; /* index with half above, half below... */
1702 n+= 1; /* ...corrected for 1-origin */
1703 stride= 1;
1704 for (i=1 ; i<which ; i++) stride*= dims(1+i);
1705 ldims= dims(1)-which+1;
1706 /**/ local l;
1707 reshape, l, &list, long, stride, grow(ldims, dims(1+which:));
1708 lm= l(,n,..);
1709 if (which<dims(1)) dims(1+which:-1)= dims(2+which:0);
1710 --dims(1);
1711 reshape, lm, long, dims;
1712 xm= x(lm);
1713 if (!odd) { /* even length dimensions have more complicated median */
1714 reshape, lm; /* undefine the LValue lm so following define works */
1715 lm= l(,n-1,..);
1716 reshape, lm, long, dims;
1717 xm= 0.5f*(xm+x(lm));
1718 }
1719 return xm;
1720 }
1721
1722 extern transpose;
1723 /* DOCUMENT transpose(x)
1724 or transpose(x, permutation1, permutation2, ...)
1725 transpose the first and last dimensions of array X. In the second
1726 form, each PERMUTATION specifies a simple permutation of the
1727 dimensions of X. These permutations are compounded left to right
1728 to determine the final permutation to be applied to the dimensions
1729 of X. Each PERMUTATION is either an integer or a 1D array of
1730 integers. A 1D array specifies a cyclic permutation of the
1731 dimensions as follows: [3, 5, 2] moves the 3rd dimension to the
1732 5th dimension, the 5th dimension to the 2nd dimension, and the 2nd
1733 dimension to the 3rd dimension. Non-positive numbers count from the
1734 end of the dimension list of X, so that 0 is the final dimension,
1735 -1 in the next to last, etc. A scalar PERMUTATION is a shorthand
1736 for a cyclic permutation of all of the dimensions of X. The value
1737 of the scalar is the dimension to which the 1st dimension will move.
1738
1739 Examples: Let x have dimsof(x) equal [6, 1,2,3,4,5,6] in order
1740 to be able to easily identify a dimension by its length. Then:
1741 dimsof(x) == [6, 1,2,3,4,5,6]
1742 dimsof(transpose(x)) == [6, 6,2,3,4,5,1]
1743 dimsof(transpose(x,[1,2])) == [6, 2,1,3,4,5,6]
1744 dimsof(transpose(x,[1,0])) == [6, 6,2,3,4,5,1]
1745 dimsof(transpose(x,2)) == [6, 6,1,2,3,4,5]
1746 dimsof(transpose(x,0)) == [6, 2,3,4,5,6,1]
1747 dimsof(transpose(x,3)) == [6, 5,6,1,2,3,4]
1748 dimsof(transpose(x,[4,6,3],[2,5])) == [6, 1,5,6,3,2,4]
1749 */
1750
1751 /*= SECTION(string) string manipulation ====================================*/
1752 /*
1753 * yorick string manipulation functions
1754 *
1755 * Inspired by the regexp package of Francois Rigaut 2004/Oct/6.
1756 * This API designed by David Munro January, 2005.
1757 *
1758 * compiled regular expression engine from Henry Spencer (Univ. of Toronto)
1759 * see yregexp.c source
1760 * ftp://ftp.zoo.toronto.edu/pub/regex.shar
1761 * compiled globbing engine from Guido van Rossum (for Univ. of California)
1762 * see yfnmatch.c source
1763 * http://www.freebsd.org/cgi/cvsweb.cgi/src/sys/libkern/fnmatch.c
1764 * http://www.openbsd.org/cgi-bin/cvsweb/src/lib/libc/gen/fnmatch.c
1765 */
1766
1767 local string;
1768 /* DOCUMENT string
1769 *
1770 * The yorick string datatype is a character string, e.g.- "Hello, world!".
1771 * Internally, strings are stored as 0-terminated sequences of characters,
1772 * which are 8-bit bytes, the same as the char datatype..
1773 *
1774 * Like numeric datatypes, string behaves as a function to convert objects
1775 * to the string datatype. There are only two interesting conversions:
1776 * string(0) is the nil string, like a 0 pointer
1777 * This is the only string which is "false" in an if test.
1778 * string(pc) where pc is an array of type pointer where each pointer
1779 * is either 0 or points to an array of type char, copies the chars
1780 * into an array of strings, adding a trailing '\0' if necessary
1781 * pointer(sa) where sa is an array of stringa is the inverse
1782 * conversion, copying each string to an array of char (including the
1783 * terminal '\0') and returning an array of pointers to them
1784 * The strchar() function may be a more convenient way to convert from
1785 * string to char and back.
1786 *
1787 * Yorick provides the following means of manipulating string variables:
1788 *
1789 * s+t when s and t are strings, + means concatentation
1790 * (this is not perfect nomenclature, since t+s != s+t)
1791 * s(,sum,..) the sum index range concatentates along a dimension of
1792 * an array of strings
1793 * sum(s) concatenates all the strings in an array (in storage order)
1794 *
1795 * strlen(s) returns length(s) of string(s) s
1796 * strcase(upper, s) converts s to upper or lower case
1797 * strchar(s_or_c) converts between string and char arrays
1798 * (quick and dirty alternative to string<->pointer)
1799 * strpart(s, m:n)
1800 * strpart(s, sel) extracts substrings (sel is a [start,end] list)
1801 * string search functions:
1802 * strglob(pat, s) shell-like wildcard pattern match, returns 0 or 1
1803 * strword(s, delim) parses s into word(s), returns a sel
1804 * strfind(pat, s) simple pattern match, returns a sel
1805 * strgrep(pat, s) regular expression pattern match, returns a sel
1806 * streplace(s, sel, t) replaces sel in s by t
1807 *
1808 * strtrim trims leading and/or trailing blanks (based on strword)
1809 * strmatch is a wrapper for strfind that simply returns whether there
1810 * was a match or not rather than its exact offset
1811 * strtok is a variant of strword that calls strpart in order to
1812 * return the substrings rather than an sel index list
1813 *
1814 * The strword, strfind, and strgrep functions produce a sel, that is,
1815 * a list of [start,end] offsets into an array of strings.
1816 * These sel indicate portions of a string to be operated on for the
1817 * strpart and streplace functions.
1818 *
1819 * The sread, swrite, and print functions operate on or produce strings.
1820 * The rdline, rdfile, read, and write functions perform I/O on strings
1821 * to text files.
1822 */
1823 {}
1824 /* (previous line is kludge to halt help,string interactive printout) */
1825
1826 extern strlen;
1827 /* DOCUMENT strlen(string_array)
1828 returns an long array with dimsof(STRING_ARRAY) containing the
1829 lengths of the strings. Both string(0) and "" have length 0.
1830 SEE ALSO: string, strchar, strcase, strpart, strfind, strword
1831 */
1832
1833 extern strchar;
1834 /* DOCUMENT strchar(string_array)
1835 or strchar(char_array)
1836 converts STRING_ARRAY to an array of characters, or CHAR_ARRAY
1837 to an array of strings. The return value is always a 1D array,
1838 except in the second form if CHAR_ARRAY contains only a single
1839 string, the result will be a scalar string. Each string is
1840 stored in sequence including its trailing '\0' character, with
1841 any string(0) elements treated as if they were "". Going in
1842 the opposite direction, a '\0' before any non-'\0' characters
1843 produces string(0), so that "" can never be an element of
1844 the result, and if the final char (of the leading dimension)
1845 is not '\0', an implicit '\0' is assumed beyond the end of the
1846 input char array. For example,
1847 strchar(["a","b","c"]) --> ['a','\0','b','\0','c','\0']
1848 strchar([['a','\0','b'],['c','\0','\0']]) --> ["a","b","c",string(0)]
1849 The string and pointer data types themselves also convert between
1850 string and char data, avoiding the quirks of strchar.
1851 SEE ALSO: string, strpart, strword, strfind
1852 */
1853
1854 extern strpart;
1855 /* DOCUMENT strpart(string_array, m:n)
1856 or strpart(string_array, start_end)
1857 or strpart, string_array, start_end
1858 returns another string array with the same dimensions as
1859 STRING_ARRAY which consists of characters M through N of
1860 the original strings. M and N are 1-origin indices; if
1861 M is omitted, the default is 1; if N is omitted, the default
1862 is the end of the string. If M or N is non-positive, it is
1863 interpreted as an index relative to the end of the string,
1864 with 0 being the last character, -1 next to last, etc.
1865 Finally, the returned string will be shorter than N-M+1
1866 characters if the original doesn't have an Mth or Nth
1867 character, with "" (note that this is otherwise impossible)
1868 if neither an Mth nor an Nth character exists. A 0
1869 is returned for any string which was 0 on input.
1870
1871 In the second form, START_END is an array of [start,end] indices.
1872 A single pair [start,end] is equivalent to the range start+1:end,
1873 that is, start is the index of the character immediately before
1874 the substring (which is to say start is the number of characters
1875 skipped at the beginning of the string). If end<start, or if
1876 either start or end are <0 or >length, or if the original string
1877 is string(0), strpart returns string(0); otherwise, if end==start,
1878 strpart returns "".
1879
1880 However, the START_END array may have any additional dimensions
1881 (beyond the leading dimension of length 2) which are conformable
1882 with the dimensions of the STRING_ARRAY. The result will be a
1883 string array with dimensions dimsof(STRING_ARRAY,START_END(1,..)).
1884 Furthermore, the leading dimension of START_END may have any
1885 even length, say 2*n, in which case the leading dimension of
1886 the result will be n. For example,
1887 strpart(a, [s1,e1,s2,e2,s3,e3,s4,e4])
1888 is equivalent to (or shorthand for)
1889 strpart(a(-,..), [[s1,e1],[s2,e2],[s3,e3],[s4,e4]])(1,..)
1890
1891 In the third form, called a subroutine, strpart operates on
1892 STRING_ARRAY in place. In this case START_END must have
1893 leading dimension of length 2, although it may have trailing
1894 dimensions as usual.
1895
1896 Examples:
1897 strpart("Hello, world!", 4:6) --> "lo,"
1898 strpart("Hello, world!", [3,6]) --> "lo,"
1899 -it may help to think of [start,end] as the 0-origin offset
1900 of a "cursor" between the characters of the string
1901 strpart("Hello, world!", [3,3]) --> ""
1902 strpart("Hello, world!", [3,2]) --> string(0)
1903 strpart("Hello, world!", [3,20]) --> string(0)
1904 strpart("Hello, world!", [3,6,7,9]) --> ["lo,","wo"]
1905 strpart(["one","two"], [[1,2],[0,1]]) --> ["n","t"]
1906 strpart(["one","two"], [1,2,0,1]) --> [["n","o"],["w","t"]]
1907
1908 SEE ALSO: string, strcase, strlen, strfind, strword
1909 */
1910
1911 extern strcase;
1912 /* DOCUMENT strcase(upper, string_array)
1913 or strcase, upper, string_array
1914 returns STRING_ARRAY with all strings converted to upper case
1915 if UPPER is non-zero. If UPPER is zero, result is lower case.
1916 (For characters >=0x80, the case conversion assumes the ISO8859-1
1917 character set.)
1918 Called as a subroutine, strcase converts STRING_ARRAY in place.
1919 SEE ALSO: string, strlen, strpart, strglob, strfind, strgrep, strword
1920 */
1921
1922 extern strword;
1923 /* DOCUMENT strword(string_array)
1924 or strword(string_array, delim)
1925 or strword(string_array, delim, n)
1926 or strword(string_array, off, delim, n)
1927 scans to the first character in STRING_ARRAY which is not in
1928 the DELIM list. DELIM defaults to " \t\n", that is, whitespace.
1929 The return value is a [start,end] offset pair, with trailing
1930 dimensions matching the dimensions of the given STRING_ARRAY.
1931 Note that this return value is suitable for use in the strpart
1932 or streplace functions.
1933
1934 If the first character of DELIM is "^", the sense is reversed;
1935 strword scans to the first character in DELIM. (Except that
1936 if DELIM is the single character "^", it has its usual meaning.)
1937 Also, a "-" which is not the first (or second after "^") or last
1938 character of DELIM indicates a range of characters. Finally,
1939 if DELIM is "" or string(0), the scan stops immediately, since
1940 the first character (no matter what it is) is not in DELIM.
1941
1942 Furthermore, DELIM can be a list of delimiter sets, where each
1943 element of the list delimits a new word, so the return value will
1944 be [start1,end1, ..., startN,endN], where N=numberof(DELIM),
1945 and start1 is the offset of the first character not in DELIM(1),
1946 characters with offset between end1 and start2 are in DELIM(2),
1947 characters with offset between end2 and start3 are in DELIM(3),
1948 and so on. If endM is the length of the string for some M<N,
1949 then all subsequent start,end pairs will be endM,-1. Note that
1950 endN is always the length of the string.
1951
1952 If N is specified, the final DELIM will be repeated N times, so
1953 the leading dimension of the result is 2*(numberof(DELIM)+N-1).
1954 Thus, instead of DELIM = [d1,d2,d3,d3,d3,d3,d3], you may specify
1955 DELIM = [d1,d2,d3] and N = 5. (By default, N=1.)
1956
1957 If OFF is supplied (it is distinguished from DELIM by the
1958 fact that DELIM is a string or [], while OFF is an integer),
1959 it represents the offset (0-origin character index) in
1960 STRING_ARRAY at which the word search is to begin. (DELIM
1961 or N may be omitted to get their default values.) The OFF
1962 may be a scalar or an array conformable with STRING_ARRAY.
1963 The returned offsets include OFF; you do not need to add OFF
1964 to the return value to get the offsets into STRING_ARRAY.
1965
1966 The action of strword can be described as follows: If d1 is
1967 the first delimiter, d2 is the second delimiter, and so on,
1968 then the input element of STRING_ARRAY looks like this:
1969 d1 word1 d2 word2 d3 word3 d4 word4 ...
1970 The offset array returned by strword will select word1, word2,
1971 word3, etc., if used in strpart. One defect of this system is
1972 that the final word has no trailing delimiter - it always
1973 extends to the end of the string.
1974
1975 To remedy this defect, N<0 is interpreted as follows: It is
1976 the same as abs(N), except that the final [start,end] pair is
1977 supressed; that is, if you have specified N delimiters, only
1978 N-1 words will be returned.
1979
1980 As a second special case, N=0 forces the final delimeter to be
1981 at the end of the string, rather than as soon after the previous
1982 endM as possible. Like N<0, this reduces the number of start,end
1983 pairs by one. (N=0 is useful, for example, in order to trim
1984 trailing blanks.)
1985
1986 Examples:
1987 strword(" Hello, world!") --> [2,15]
1988 strword("Hello, world!") --> [0,13]
1989 strword("Hello, world!", , 2) --> [0,6,7,13]
1990 strword("Hello, world!", , -2) --> [0,6]
1991 strword("Hello, world!", ".!, \t\n", -2) --> [0,5]
1992 strword("Hello, world!", [string(0), ".!, \t\n"], 0) --> [0,12]
1993 strword("Hello, world!", "A-Za-z", 2) --> [5,7,12,13]
1994 strword("Hello, world!", "^A-Za-z", 2) --> [0,5,7,13]
1995 strword("Hello, world!", "^A-Za-z", 3) --> [0,5,7,12,13,-1]
1996 strword(" Hello, world!", [" \t\n",".!, \t\n"]) --> [2,7,9,15]
1997 strword(" Hello, world!", [" \t\n",".!, \t\n"], 2) --> [2,7,9,14,15,-1]
1998
1999 SEE ALSO: string, strlen, strpart, strfind, strtok, strtrim
2000 */
2001
2002 func strtrim(s, which, blank=)
2003 /* DOCUMENT strtrim(string_array)
2004 or strtrim(string_array, which)
2005 or strtrim, string_array, which
2006 returns STRING without leading and/or trailing blanks. WHICH=1
2007 means to trim leading blanks only, WHICH=2 trims trailing blanks
2008 only, while WHICH=3 (the default) trims both leading and trailing
2009 blanks. Called as a subroutine, strtrim performs this operation
2010 in place.
2011 The blank= keyword, if present, is a list of characters to be
2012 considered "blanks". Use blank=[lead_delim,trail_delim] to get
2013 different leading and trailing "blanks" definitions. By default,
2014 blank=" \t\n". (See strword for more about delim syntax.)
2015 SEE ALSO: string, strpart, strword
2016 */
2017 {
2018 which = is_void(which)? 3 : (which&3);
2019 if (!which) return s;
2020 if (which == 1) {
2021 if (numberof(blank)>1) blank = blank(1);
2022 b = strword(s, blank);
2023 } else {
2024 if (which == 2) {
2025 if (!numberof(blank)) blank = [string(0), " \t\n"];
2026 else blank = [string(0), blank(numberof(blank))];
2027 } else {
2028 if (!numberof(blank)) blank = [" \t\n", " \t\n"];
2029 else blank = [blank(1), blank(numberof(blank))];
2030 }
2031 b = strword(s, blank, 0);
2032 }
2033 if (am_subroutine()) strpart, s, b;
2034 else return strpart(s, b);
2035 }
2036
strtok(s,delim,n)2037 func strtok(s, delim, n)
2038 /* DOCUMENT strtok(string_array, delim)
2039 or strtok(string_array)
2040 or strtok(string_array, delim, n)
2041 strips the first token off of each string in STRING_ARRAY.
2042 A token is delimited by any of the characters in the string
2043 DELIM. If DELIM is blank, nil, or not given, the
2044 default DELIM is " \t\n" (blanks, tabs, or newlines).
2045 The result is a string array ts with dimensions
2046 2-by-dimsof(STRING_ARRAY); ts(1,) is the first token, and
2047 ts(2,) is the remainder of the string (the character which
2048 terminated the first token will be in neither of these parts).
2049 The ts(2,) part will be 0 (i.e.- the null string) if no more
2050 characters remain after ts(1,); the ts(1,) part will be 0 if
2051 no token was present. A STRING_ARRAY element may be 0, in
2052 which case (0, 0) is returned for that element.
2053
2054 With yorick-1.6, strtok has been extended to accept multiple
2055 delimiter sets DELIM for successive words, and a repeat count
2056 N for the final DELIM set. The operation is the same as for
2057 strword, except that the N<=0 special cases are illegal, and
2058 if DELIM consists of only a single set, N=2 is the default
2059 rather than N=1. The dimensions of the return value are thus
2060 min(2,numberof(DELIM)+N-1)-by-dimsof(STRING_ARRAY).
2061
2062 SEE ALSO: string, strword, strmatch, strpart, strlen
2063 */
2064 {
2065 return strpart(s, (is_void(n)?_strtok(s, delim):_strtok(s, delim, n)));
2066 }
2067
2068 extern _strtok; /* worker for strtok, a variant on strword */
2069
2070 extern strglob;
2071 /* DOCUMENT strglob(pat, string_array)
2072 or strglob(pat, string_array, off)
2073 test if pattern PAT matches STRING_ARRAY. Optional OFF is an integer
2074 array conformable with STRING_ARRAY or 0-origin offset(s) within
2075 the string(s) at which to begin the search(es). The return value
2076 is an int with the same dimensions as STRING_ARRAY, 1 for a match,
2077 and 0 for no match.
2078
2079 PAT can contain UNIX shell wildcard or "globbing" characters:
2080 * matches any number of characters
2081 ? matches any single character
2082 [abcd] matches any single character in the list, which may
2083 contain ranges such as [a-z0-9A-Z]
2084 \c matches the character c (useful for c= a special character)
2085 (note that this is "\\c" in a yorick string)
2086
2087 The strglob function is mostly intended for matching lists of
2088 file names. Note, in particular, that unlike strfind or strgrep,
2089 the entire string must match PAT.
2090
2091 Keywords:
2092 case= (default 1) zero for case-insensitive search
2093 path= (default 0) 1 bit set means / must be matched by /
2094 2 bit set means leading . must be matched by .
2095 esc= (default 1) zero means \ is not treated as an escape
2096
2097 The underlying compiled routine is based on the BSD fnmatch
2098 function, contributed by Guido van Rossum.
2099
2100 Examples:
2101 return all files in current directory with .pdb extension:
2102 d=lsdir("."); d(where(strglob("*.pdb", d)));
2103 return all subdirectories of the form "hackNN", case insensitive:
2104 d=lsdir(".",1);
2105 d(where(strglob("hack[0-9][0-9]", d, case=0)));
2106
2107 SEE ALSO: string, strfind, strgrep, strword, strpart, streplace
2108 */
2109
2110 extern strfind;
2111 /* DOCUMENT strfind(pat, string_array)
2112 or strfind(pat, string_array, off)
2113 finds pattern PAT in STRING_ARRAY. Optional OFF is an integer
2114 array conformable with STRING_ARRAY or 0-origin offset(s) within
2115 the string(s) at which to begin the search(es). The return value
2116 is a [start,end] offset pair specifying the beginning and end
2117 of the first match, or [len,-1] if none, with trailing dimensions
2118 the same as the dimensions of STRING_ARRAY. This return value
2119 is suitable as an input to the strpart or streplace functions.
2120
2121 The strfind function is the simpler string pattern matcher:
2122 strfind - just finds a literal pattern (possibly case insensitive)
2123 strgrep - matches a pattern containing complex regular expressions
2124 Additionally, the strglob function does filename wildcard matching.
2125
2126 Keywords:
2127 n= (default 1) returns list of first n matches, so leading
2128 dimension of result will be 2*n
2129 case= (default 1) zero for case-insensitive search
2130 back= (default 0) non-zero for backwards search
2131 If back!=0 and n>1, the last match is listed as the
2132 last start-end pair, so the output pairs still appear
2133 in increasing order, and the first few may be 0,-1
2134 to indicate no match.
2135
2136 Examples:
2137 s = ["one two three", "four five six"]
2138 strfind("o",s) --> [[0,1], [1,2]]
2139 strfind(" t",s) --> [[3,5], [13,-1]]
2140 strfind(" t",s,n=2) --> [[3,5,7,9], [13,-1,13,-1]]
2141 strfind("e",s,n=2,back=1) --> [[11,12,12,13], [0,-1,8,9]]
2142
2143 SEE ALSO: string, strglob, strgrep, strword, strpart, streplace
2144 */
2145
2146 extern strgrep;
2147 /* DOCUMENT strgrep(pat, string_array)
2148 or strgrep(pat, string_array, off)
2149 finds pattern PAT in STRING_ARRAY. Optional OFF is an integer
2150 array conformable with STRING_ARRAY or 0-origin offset(s) within
2151 the string(s) at which to begin the search(es). The return value
2152 is a [start,end] offset pair specifying the beginning and end
2153 of the first match, or [len,-1] if none, with trailing dimensions
2154 the same as the dimensions of STRING_ARRAY. This return value
2155 is suitable as an input to the strpart or streplace functions.
2156
2157 The underlying compiled routine is based on the regexp package
2158 written by Henry Spencer (copyright University of Toronto 1986),
2159 slightly modified for yorick.
2160
2161 PAT is a regular expression, simliar to the UNIX grep utility.
2162 Every "regular expression" syntax is slightly different; here is
2163 the syntax supported by strgrep:
2164
2165 The following characters in PAT have special meanings:
2166
2167 '[' followed by any sequence of characters followed by ']' is a
2168 "range", which matches any single one of those characters
2169 '^' first means to match any character NOT one in the sequence
2170 '-' in such a sequence indicates a range of characters
2171 (e.g.- "[A-Za-z0-9_]" matches any alphanumeric character
2172 or underscore, while "[^A-Za-z0-9_]" matches anything else)
2173 to include ']' in the sequence, place it first,
2174 to include '-' in the sequence, place it first or last
2175 (or first after a leading '^' in either case)
2176 Note that the following special characters lose their special
2177 meanings inside a range.
2178 '.' matches any single character
2179 '^' matches the beginning of the string (but no characters)
2180 '$' matches the end of the string (but no characters)
2181 (that is, ^ and $ serve to anchor a search so that it will
2182 only find a match at the beginning or end of the string)
2183 '\' (that is, a single backslash, which can only be entered
2184 into a yorick string by a double backslash "\\")
2185 followed by any single character eliminates any special
2186 meaning for that character, for example "\\." matches
2187 period, rather than any single character (its special meaning)
2188 '(' followed by a regular expression followed by ')' matches the
2189 regular expression, creating a sub-pattern, which is a type
2190 of atom (see below)
2191 '|' means "or"; it separates branches in a regular expression
2192 '*' after an atom matches 0 or more matches of the atom
2193 '+' after an atom matches 1 or more matches of the atom
2194 '?' after an atom matches 0 or 1 matches of the atom
2195
2196 The definitions of "atom", "branch", and "regular expression" are:
2197
2198 A "regular expression" (which is what PAT is) consists of zero
2199 or more "branches" separated by '|'; it matches anything that
2200 matches one of the branches.
2201
2202 A "branch" consists of zero or more "pieces", concatenated; it
2203 matches a match for the first followed by a match for the second,
2204 etc.
2205
2206 A "piece" is an "atom", optionally followed by '*', '+', or '?';
2207 it matches the atom, or zero or more repetitions of the atom, as
2208 specified by the optional suffix.
2209
2210 Finally, an "atom" is an ordinary single character, or a
2211 '\'-escaped single character (matching that character), or
2212 one of the special characters '.', '^', or '$', or a
2213 []-delimited range (matching any single character in the range),
2214 or a sub-pattern enclosed in () (matching the sub-pattern).
2215
2216 A maximum of nine sub-patterns is allowed in PAT; these are
2217 numbered 1 through 9, in order of their opening '(' in PAT.
2218
2219 This recursive definition of regular expressions often leads to
2220 ambiguities, both subtle and glaring. Here is Henry Spencer's
2221 synopsis of how his routines behave:
2222
2223 -------------------------------------------------------------------
2224 If a regular expression could match two different parts of the
2225 input string, it will match the one which begins earliest. If both
2226 begin in the same place but match different lengths, or match the
2227 same length in different ways, life gets messier, as follows.
2228
2229 In general, the possibilities in a list of branches are considered
2230 in left-to-right order, the possibilities for `*', `+', and `?' are
2231 considered longest-first, nested constructs are considered from the
2232 outermost in, and concatenated constructs are considered leftmost-
2233 first. The match that will be chosen is the one that uses the
2234 earliest possibility in the first choice that has to be made. If
2235 there is more than one choice, the next will be made in the same
2236 manner (earliest possibility) subject to the decision on the first
2237 choice. And so forth.
2238
2239 For example, `(ab|a)b*c' could match `abc' in one of two ways. The
2240 first choice is between `ab' and `a'; since `ab' is earlier, and
2241 does lead to a successful overall match, it is chosen. Since the
2242 `b' is already spoken for, the `b*' must match its last possibility
2243 -the empty string- since it must respect the earlier choice.
2244
2245 In the particular case where no `|'s are present and there is only
2246 one `*', `+', or `?', the net effect is that the longest possible
2247 match will be chosen. So `ab*', presented with `xabbbby', will
2248 match `abbbb'. Note that if `ab*' is tried against `xabyabbbz', it
2249 will match `ab' just after `x', due to the begins-earliest rule.
2250 (In effect, the decision on where to start the match is the first
2251 choice to be made, hence subsequent choices must respect it even if
2252 this leads them to less-preferred alternatives.)
2253 -------------------------------------------------------------------
2254
2255 When PAT contains parenthesized sub-patterns, strgrep returns
2256 the [start,end] of the entire match by default, but you can
2257 also get the [start,end] of any or all of the sub-patterns
2258 using the sub= keyword (see below).
2259
2260 If PAT does not contain any regular expression constructs, you
2261 should use the strfind function instead of strgrep. The strglob
2262 function, if appropriate, will also be faster than strgrep.
2263
2264 Keywords:
2265 n= (default 1) returns list of first n matches, so leading
2266 dimension of result will be 2*n
2267 sub=[n1,n2,...] is a list of the sub-pattern [start,end] pairs
2268 to be returned. Thus 0 is the whole PAT, 1 is the first
2269 parenthesized sub-pattern, and so on. The leading
2270 dimension of the result will be 2*numberof(sub)*n. The
2271 sequence n1,n2,... must strictly increase: n1<n2<...
2272 The default is sub=0, which returns only the whole match.
2273
2274 Examples:
2275 s = "Hello, world!"
2276 strgrep("(Hello|Goodbye), *([a-zA-Z]+)!", s)
2277 --> [0,13]
2278 strgrep("(Hello|Goodbye), *([a-z]*|[A-Z]*)!", s, sub=[1,2])
2279 --> [0,5,7,12]
2280 strgrep("(Hello|Goodbye), *([a-z]*|[A-Z]*)!", s, sub=[0,2])
2281 --> [0,13,7,12]
2282 strgrep("(Hello|Goodbye), *(([A-Z]*)|([a-z]*))!", s, sub=[0,2,3,4])
2283 --> [0,13,7,12,13,-1,7,12]
2284
2285 SEE ALSO: string, strglob, strfind, strword, strpart, streplace,
2286 strgrepm
2287 */
2288
2289 func strgrepm(pat, x, off, case=)
2290 /* DOCUMENT strgrepm(pat, string_array)
2291 * or strgrepm(pat, string_array, off)
2292 * call strgrep, but simply return mask of same dimensions as STRING_ARRAY
2293 * set to 1 where it matches the PAT, and 0 where it does not match.
2294 * The strgrepm function does not accept any of the strgrep keywords,
2295 * but it does accept the strglob case= keyword to indicate a case
2296 * insensitive search.
2297 * SEE ALSO: strglob, strgrep
2298 */
2299 {
2300 if (case) {
2301 pat = strcase(0, pat);
2302 x = strcase(0, x);
2303 }
2304 return strgrep(pat, x, off)(2,..) >= 0;
2305 }
2306
2307 about_glob = strgrepm;
2308
strmatch(s,pat,case)2309 func strmatch(s, pat, case)
2310 /* DOCUMENT strmatch(string_array, pattern)
2311 or strmatch(string_array, pattern, case_fold)
2312 or strmatch(string_array, pattern, case_fold)
2313 returns an int array with dimsof(STRING_ARRAY) with 0 where
2314 PATTERN was not found in STRING_ARRAY and 1 where it was found.
2315 If CASE_FOLD is specified and non-0, the pattern match is
2316 insensitive to case, that is, an upper case letter will match
2317 the same lower case letter and vice-versa.
2318 (Consider using strfind directly.)
2319 SEE ALSO: string, strfind, strpart, strlen
2320 */
2321 {
2322 if (is_void(case)) i = strfind(pat, s);
2323 else i = strfind(pat, s, case=(case==0));
2324 return i(2,..) >= 0;
2325 }
2326
2327 extern streplace;
2328 /* DOCUMENT streplace(string_array, start_end, to_string)
2329 replaces the part(s) START_END of STRING_ARRAY by TO_STRING.
2330 The leading dimension of START_END must be a multiple of 2,
2331 while any trailing dimensions must be conformable with the
2332 dimensions of STRING_ARRAY. The TO_STRING must be conformable
2333 with STRING_ARRAY if the leading dimension of START_END is 2.
2334 An element of START_END may represent "no match" (for example,
2335 when end<start), in which case streplace silently skips the
2336 replacement. Note that when start==end, streplace functions
2337 as text insertion.
2338
2339 However, if the leading dimension of START_END = 2*n > 2, then
2340 TO_STRING must have a leading dimension conformable with n
2341 (that is, of length either 1 or n). In this case, streplace
2342 performs multiple replacements within each string. In order
2343 for multiple replacements to be meaningful, the START_END
2344 must be disjoint and sorted, as returned by strfind or
2345 strgrep with a repeat count, or by strword. In other words,
2346 the first dimension of START_END should be non-decreasing,
2347 except where end<start indicates no replacement.
2348
2349 Invoked as a subroutine, streplace operates on STRING_ARRAY
2350 in place.
2351
2352 Examples:
2353 s = "Hello, world!"
2354 streplace(s,[0,5], "Goodbye")
2355 --> "Goodbye, world!"
2356 streplace(s,[0,5,7,7], ["Goodbye","cruel "])
2357 --> "Goodbye, cruel world!"
2358 streplace(s,[0,5,7,7,12,13], ["Goodbye","cruel ","?"])
2359 --> "Goodbye, cruel world?"
2360 streplace(s,[0,5,0,-1,12,13], ["Goodbye","cruel ","?"])
2361 --> "Goodbye, world?"
2362 streplace([s,s],[0,5], ["Goodbye", "Good bye"])
2363 --> ["Goodbye, world!", "Good bye, world!"]
2364 streplace([s,s],[0,5,7,7], [["Goodbye","cruel "], ["Good bye",""]])
2365 --> ["Goodbye, cruel world!", "Good bye, world!"]
2366
2367 SEE ALSO: string, strfind, strgrep, strword, strpart
2368 */
2369
2370 /*= SECTION(fileio) generic file i/o =======================================*/
2371
2372 extern open;
2373 /* DOCUMENT f= open(filename)
2374 or f= open(filename, filemode)
2375 or f= open(filename, filemode, errmode)
2376 opens the file FILENAME according to FILEMODE (both are strings).
2377 If ERRMODE is non-nil and non-zero, fail by returning nil F,
2378 otherwise failure to open or create the file is a runtime error.
2379
2380 To use ERRMODE to check for the existence of a file:
2381 if (open(filename,"r",1)) file_exists;
2382 else file_does_not_exist;
2383
2384 The return value F is an IOStream (or just stream for short). When
2385 the last reference to this return value is discarded, the file will
2386 be closed. The file can also be explicitly closed with the close
2387 function. The FILEMODE determines whether the file is to be
2388 opened in read, write, or update mode, and whether writes are
2389 restricted to the end-of-file (append mode). FILEMODE also
2390 determines whether the file is opened as a text file or as a
2391 binary file. FILEMODE can have the following values, which are
2392 the same as for the ANSI standard fopen function:
2393 "r" - read only
2394 "w" - write only, random access, existing file overwritten
2395 "a" - write only, forced to end-of-file,
2396 existing file preserved
2397 "r+" - read/write, random access, existing file preserved
2398 "w+" - read/write, random access, existing file overwritten
2399 "a+" - read/write, reads random access,
2400 writes forced to end-of-file, existing file preserved
2401 "rb" "wb" "ab" "r+b" "rb+" "w+b" "wb+" "a+b" "ab+"
2402 without b means text file, with b means binary file
2403 The default FILEMODE is "r" -- open an existing text file for
2404 reading.
2405
2406 The read and write functions perform I/O on text files.
2407 I/O to binary files may be performed explicitly using the save
2408 and restore functions, or implicitly by using the stream variable
2409 F as if it were a data structure instance (e.g.- f.x refers to
2410 variable x in the binary file f).
2411 SEE ALSO: create, close, read, write, rdline, bookmark, backup, popen
2412 vopen, rename, remove, save, restore, socket, fd_read
2413 */
2414
2415 extern vopen;
2416 /* DOCUMENT f = vopen(source)
2417 or f = vopen(source, 1)
2418 opens SOURCE, which can be a string or char array, as if it were a
2419 file, returning a file handle. The file handle will be a text file
2420 unless the optional second argument is non-nil and non-zero, as in
2421 the second form. For the case of a binary file, SOURCE must be a
2422 char array. Any dimensions of a char array are ignored in either
2423 case. For a text file, if SOURCE is a string array, each array element
2424 is treated as one line of text. For a text file char array, "\n",
2425 "\r", "\r\n", or "\0" are all recognized as newline markers. These
2426 are read only files.
2427
2428 If SOURCE is nil, the file handle will be read-write. After writing
2429 the in-memory file, you can retrieve the finished array with the
2430 vclose function. If the file is text, the array will be an array of
2431 strings, one per line. If the file is binary, the array will be an
2432 array of char.
2433
2434 SEE ALSO: vsave, vclose, open, system
2435 */
2436
2437 extern vclose;
2438 /* DOCUMENT contents = vclose(handle)
2439 closes a file handle opened with vopen, returning the contents as
2440 an array. As a side effect, the handle is set to nil [], as in
2441 close. For a read-only handle, the contents will be the same as
2442 the array passed to the vopen call which returned the handle.
2443 For a read-write handle, vclose is the only way to get back what
2444 you have written to the file; if you close such a file using the
2445 ordinary close function, you will lose what you have written.
2446 SEE ALSO: vsave, vopen, close
2447 */
2448
vsave(args)2449 func vsave(args)
2450 /* DOCUMENT c = vsave(var1, var2, ...);
2451 or c = vsave(var1, ..., string(namea), vara, ...);
2452 or vfile = createb(char);
2453 vsave, vfile, var1, var2, ...;
2454 vsave, vfile, var3, var4, ...;
2455 ...
2456 c = vsave(vfile);
2457 save the array variables VAR1, VAR2, ..., in the char array that is
2458 returned. Any of the variables may instead be a string expression
2459 NAMEA followed by the value VARA of the variable. The NAMEA argument
2460 is recognized as the name of the following argument by being an
2461 expression; arguments that are to be stored in f must be simple
2462 variable references. You can achieve this as shown by placing the
2463 argument inside a call to string(), or by adding "", or simply by
2464 passing a constant string value like "myvarname".
2465
2466 If you wish to build up a char array over several calls to vsave,
2467 pass the first argument VFILE, which you create with createb(char).
2468 A final call with no variables returns the char array and closes
2469 VFILE.
2470
2471 You can pass the returned char array to openb, f=openb(c), to get
2472 an in-memory file handle f like any other binary file handle,
2473 allowing you to use the restore function, or the f.var1 syntax,
2474 or the get_member function.
2475
2476 You can set the internal primitives using the prims= keyword; see
2477 createb for details.
2478 SEE ALSO: openb, vopen, vpack, restore, get_member, wrap_args
2479 */
2480 {
2481 /**/ local a, name;
2482 prims = args(-);
2483 if (numberof(prims)) {
2484 if (numberof(prims)!=1 || prims(1)!="prims")
2485 error, "unrecognized keyword argument";
2486 eq_nocopy, prims, args(-1);
2487 }
2488 eq_nocopy, a, args(1);
2489 handle = is_stream(a);
2490 if (handle) f = a;
2491 else f = createb(char, prims);
2492 n = args(0);
2493 if (handle && n==1) {
2494 a = vclose(f);
2495 args, 1, f;
2496 return a;
2497 }
2498 handle = (handle || is_range(a));
2499 for (i=1+handle ; i<=n ; ++i) {
2500 eq_nocopy, a, args(i);
2501 name = args(-,i);
2502 if (!name) {
2503 eq_nocopy, name, a;
2504 eq_nocopy, a, args(++i);
2505 }
2506 add_variable, f, -1, name, structof(a), dimsof(a);
2507 get_member(f, name) = a;
2508 }
2509 return handle? f : vclose(f);
2510 }
2511 wrap_args, vsave;
2512
vpack(args)2513 func vpack(args)
2514 /* DOCUMENT bytes = vpack(var1, var2, ...);
2515 or vfile = vopen(,1);
2516 vpack, vfile, var1, var2, ...;
2517 vpack, vfile, var3, var4, ...;
2518 ...
2519 bytes = vpack(vfile);
2520 pack variables into a byte stream, preserving data types and dimensions.
2521 If the first argument is an in-memory file created by vopen(,1), then
2522 vpack appends the variables to the file; to close the file, supply
2523 no new variables to pack. The VARi must be arrays, and may not be
2524 pointers or struct instances. If you want to store pointers or struct
2525 instances and preserve variable names, use vsave.
2526 The returned byte stream contains the primitive data formats (as
2527 returned by get_primitives), so it can be used on a platform other
2528 than the one on which vpack was run.
2529 SEE ALSO: vunpack, vsave
2530 */
2531 {
2532 if (numberof(args(-)))
2533 error, "unexpected keyword argument";
2534 narg = args(0);
2535 iarg = 1;
2536 var = args(iarg);
2537 if (is_stream(var)) {
2538 f = var;
2539 if (narg == 1) {
2540 var = vclose(f);
2541 args, 1, f;
2542 return var;
2543 }
2544 var = args(++iarg);
2545 handle = 1;
2546 } else if (is_range(var)) {
2547 f = vopen(,1);
2548 var = args(++iarg);
2549 handle = 1;
2550 } else {
2551 f = vopen(,1);
2552 }
2553
2554 addr = sizeof(f);
2555 prims = get_primitives(f);
2556 sz = prims(1:22:3);
2557 sz(7:8) = [2*sz(6), 1];
2558 if (!addr) {
2559 p = array(char, 4, 32);
2560 for (i=0 ; i<4 ; ++i) p(i+1,) = (prims >> (8*i)) & 0xff;
2561 _write, f, 0, p; /* first 128 bytes are primitive formats */
2562 p = array(char, 8); /* leave 8 bytes of scratch space at byte 128 */
2563 _write, f, 128, p;
2564 addr = 136;
2565 save, f, complex;
2566 }
2567
2568 for (;;) {
2569 s = structof(var);
2570 d = dimsof(var);
2571 if (is_void(s)) s = 0;
2572 else if (s == char) s = 1;
2573 else if (s == short) s = 2;
2574 else if (s == int) s = 3;
2575 else if (s == long) s = 4;
2576 else if (s == float) s = 5;
2577 else if (s == double) s = 6;
2578 else if (s == complex) s = 7;
2579 else if (s == string) s = 8;
2580 else error, "vpack supports only string and numeric arrays";
2581
2582 _write, f, addr, s+16*numberof(d);
2583 addr += sz(4);
2584 if (s) {
2585 _write, f, addr, d;
2586 addr += sz(4)*numberof(d);
2587 if (s == 8) {
2588 list = where(var == "");
2589 if (numberof(list)) { /* strchar does not handle "" properly */
2590 var = grow(array(string, dimsof(var)), var);
2591 var(list) = ".";
2592 }
2593 var = strchar(var);
2594 _write, f, addr, numberof(var);
2595 addr += sz(4);
2596 }
2597 _write, f, addr, var;
2598 addr += sz(s)*numberof(var);
2599 }
2600
2601 if (iarg >= narg) break;
2602 var = args(++iarg);
2603 }
2604
2605 if (handle) return f;
2606 return vclose(f);
2607 }
2608 wrap_args, vpack;
2609
vunpack(args)2610 func vunpack(args)
2611 /* DOCUMENT eof = vunpack(bytes, var1, var2, ...);
2612 or nextvar = vunpack(bytes,-);
2613 or vunpack, bytes;
2614 unpack variables VAR1, VAR2, ... from a byte stream BYTES created
2615 with vpack. The vunpack call modifies BYTES to save the number of
2616 variables which have already been unpacked, so you can perform the
2617 unpack operation with multiple calls. Calling vunpack as a
2618 subroutine with no VARi arguments resets this information, restoring
2619 BYTES to its original value (that is, as vpack returned it).
2620 Called as a function, vunpack returns 1 if more variables remain
2621 to be unpacked, or 0 if no more variables remain.
2622 For example, if BYTES contains 5 variables:
2623 bytes = vpack(var1, var2, var3, var4, var5);
2624 You can retrieve the variables by a single call to vunpack:
2625 vunpack, bytes, var1, var2, var3, var4, var5;
2626 Or by a sequence of calls to vunpack:
2627 vunpack, bytes, var1, var2;
2628 vunpack, bytes, var3, var4, var5;
2629 SEE ALSO: vunpack, vsave
2630 */
2631 {
2632 if (numberof(args(-)))
2633 error, "unexpected keyword argument";
2634 bytes = args(1);
2635 if (structof(bytes)!=char || numberof(bytes)<136)
2636 error, "first argument must be byte stream from vpack to unpack";
2637 n = args(0);
2638 p = array(char, 4, 32);
2639 p(*) = bytes(1:128);
2640 prims = array(0, 32);
2641 for (i=3 ; i>=0 ; --i) prims = (prims<<8) | (p(i+1,) & 0xff);
2642 if (sizeof(long) > 4) {
2643 list = where(prims(3:18:3) & 0x80000000);
2644 if (numberof(list)) prims(3*list) |= ~0xffffffff;
2645 }
2646 sz = prims(1:22:3);
2647 sz(7:8) = [2*sz(6), 1];
2648 p = bytes(129:136);
2649 addr = 0;
2650 for (i=7 ; i>=0 ; --i) addr = (addr<<8) | (p(i+1) & 0xff);
2651 if (addr == 0) addr = 136;
2652 if (n > 1) {
2653 f = vopen(bytes, 1);
2654 set_primitives, f, prims;
2655 save, f, complex;
2656 flag = (n==2 && args(0,2)==1);
2657 }
2658 for (i=2 ; i<=n ; ++i) {
2659 var = [];
2660 if (addr < sizeof(f)) {
2661 s = 0;
2662 _read, f, addr, s;
2663 addr += sz(4);
2664 if (s > 0) {
2665 d = array(0, s/16);
2666 s = s%16;
2667 _read, f, addr, d;
2668 addr += sz(4)*numberof(d);
2669 if (s == 1) var = array(char, d);
2670 else if (s == 2) var = array(short, d);
2671 else if (s == 3) var = array(int, d);
2672 else if (s == 4) var = array(long, d);
2673 else if (s == 5) var = array(float, d);
2674 else if (s == 6) var = array(double, d);
2675 else if (s == 7) var = array(complex, d);
2676 else if (s == 8) {
2677 nn = 0;
2678 _read, f, addr, nn;
2679 addr += sz(4);
2680 var = array(char, nn);
2681 }
2682 _read, f, addr, var;
2683 addr += sz(s)*numberof(var);
2684 if (s == 8) {
2685 eq_nocopy, nn, var;
2686 var = array(string, d);
2687 nn = strchar(nn);
2688 if (numberof(nn) == 2*numberof(var)) {
2689 list = where(nn(1:numberof(var)));
2690 nn = nn(numberof(var)+1:0);
2691 nn(list) = "";
2692 }
2693 var(*) = nn;
2694 }
2695 }
2696 }
2697 if (!flag) args, i, var;
2698 }
2699 close, f; /* harmless if f never opened */
2700 p = array(char, 8);
2701 if (n>1 || !am_subroutine())
2702 for (i=0 ; i<sizeof(addr) ; ++i) p(i+1) = (addr >> (8*i)) & 0xff;
2703 bytes(129:136) = p;
2704 args, 1, bytes;
2705 if (flag) return var;
2706 else if (!am_subroutine()) return addr >= numberof(bytes);
2707 }
2708 wrap_args, vunpack;
2709
2710 extern popen;
2711 /* DOCUMENT f= popen(command, mode)
2712 opens a pipe to COMMAND, which is executed as with the system
2713 function. If MODE is 0, the returned file handle is open for
2714 reading, and you are reading the stdout produced by COMMAND.
2715 If MODE is 1, f is opened for writing and you are writing to
2716 the stdin read by COMMAND.
2717 SEE ALSO: open, system
2718 */
2719
2720 extern fflush;
2721 /* DOCUMENT fflush, file
2722 flush the I/O buffers for the text file FILE. (Binary files are
2723 flushed at the proper times automatically.) You should only need
2724 this after a write, especially to a pipe.
2725 SEE ALSO: write, popen
2726 */
2727
create(filename)2728 func create(filename)
2729 /* DOCUMENT f= create(filename)
2730 is a synonym for f= open(filename, "w")
2731 Creates a new text file FILENAME, destroying any existing file of
2732 that name. Use the write function to write into the file F.
2733 SEE ALSO: write, close, open
2734 */
2735 { return open(filename, "w"); }
2736 errs2caller, create;
2737
2738 extern close;
2739 /* DOCUMENT close, f
2740 closes the I/O stream F (returned earlier by the open function).
2741 If F is a simple variable reference (as opposed to an expression),
2742 the close function will set F to nil. If F is the only reference
2743 to the I/O stream, then "close, f" is equivalent to "f= []".
2744 Otherwise, "close, f" will close the file (so that subsequent
2745 I/O operations will fail) and print a warning message about the
2746 outstanding ("stale") references.
2747 SEE ALSO: open, read, write, rdline, bookmark, backup, save, restore,
2748 rename, remove
2749 */
2750
2751 extern filepath;
2752 /* DOCUMENT filepath(file);
2753 Return full path name of file(s). Argument FILE can be either an open
2754 binary/text file or an array of file names (in the latter case tilde
2755 expansion is performed and the result will have the same shape as the
2756 input).
2757
2758 SEE ALSO: cd, lsdir, mkdir, open.
2759 */
2760
2761 extern rename;
2762 extern remove;
2763 /* DOCUMENT rename, old_filename, new_filename
2764 remove filename
2765 rename or remove a file.
2766 SEE ALSO: open, close, openb
2767 */
2768
2769 /*= SECTION(filetxt) text i/o to terminal, file, or string =================*/
2770
2771 extern print;
2772 /* DOCUMENT print, object1, object2, object3, ...
2773 or print(object1, object2, object3, ...)
2774 prints an ASCII representation of the OBJECTs, in roughly the format
2775 they could appear in Yorick source code. When invoked as a subroutine
2776 (in the first form), output is to the terminal. When invoked as a
2777 function (int the second form), the output is stored as a vector of
2778 strings, one string per line that would have been output.
2779 Printing a structure definition prints the structure definition;
2780 printing a function prints its "func" definition; printing files,
2781 bookmarks, and other objects generally provides some sort of
2782 useful description of the object.
2783 SEE ALSO: totxt, pr1, print_format, write, exit, error, nameof, typeof
2784 */
2785
pr1(x)2786 func pr1(x)
2787 /* DOCUMENT pr1(x)
2788 returns text representing expression X, equivalent to print(X)(1).
2789 SEE ALSO: print, swrite, totxt
2790 */
2791 { return print(x)(1); }
2792
2793 extern print_format;
2794 /* DOCUMENT print_format, line_length, max_lines, char=, short=, int=,
2795 float=, double=, complex=, pointer=
2796 sets the format string the print function will use for each of
2797 the basic data types. Yorick format strings are the same as the
2798 format strings for the printf function defined in the ANSI C standard.
2799 The default strings may be restored individually by setting the
2800 associated format string to ""; all defaults are restored if
2801 print_format is invoked with no arguments. The default format strings
2802 are: "0x%02x", "%d", "%d", "%ld", "%g", "%g", and "%g+%gi".
2803 Note that char and short values are converted to int before being
2804 passed to printf, and that float is converted to double.
2805 If present, an integer positional argument is taken as the line
2806 length; <=0 restores the default line length of 80 characters,
2807 while nil [] leaves the line length unchanged.
2808 A second positional argument, if present, becomes the maximum number
2809 of lines to output; <=0 restores the default of 5000 lines. A single
2810 print command will not produce more than this many lines of output;
2811 output simply stops without any additional messages.
2812 SEE ALSO: print, write, totxt, nameof, typeof
2813 */
2814
totxt(x,fmt)2815 func totxt(x, fmt)
2816 /* DOCUMENT totxt(x)
2817 or totxt(x, fmt)
2818 returns text representing expression X. If X is not numeric,
2819 then totxt(x) is the same as print(x). If X is numeric, then
2820 totxt returns an array of strings with the same dimensions as X.
2821 Integers get %d format, while reals get %g format, unless you
2822 specify FMT. FMT can be a single numeric format, or just a
2823 number with the following interpretation:
2824 FMT = integer w means %wd for integers or %wf for reals
2825 FMT = real w.p means %wd for integers or %w.pf for reals
2826 In either case, a negative value -w or -w.p switches to hex
2827 format for integers %wx or exponential format %w.pe for reals.
2828 SEE ALSO: print, swrite, tonum
2829 */
2830 {
2831 i = identof(x);
2832 if (i > 6) return print(x);
2833 if (is_void(fmt)) {
2834 fmt = (i>3)? "%g" : ((i==3)? "%ld" : "%d");
2835 } else if (structof(fmt) != string) {
2836 a = fmt<0;
2837 fmt = abs(fmt);
2838 w = long(fmt);
2839 p = long(100.*(fmt-w)+1.e-6);
2840 if (!(p%10)) p /= 10;
2841 w = w? print(w)(1) : "";
2842 if ((identof(fmt)>3) && (i>3)) p = "."+print(p)(1);
2843 else p = "";
2844 if (i > 3) a = a? "e" : "f";
2845 else if (i == 3) a = a? "lx" : "ld";
2846 else a = a? "x" : "d";
2847 fmt = "%"+w+p+a;
2848 }
2849 if (i < 6) return swrite(format=fmt, x);
2850 return swrite(format=fmt, x.re)+"+"+swrite(format=fmt, x.im)+"i";
2851 }
2852
2853 extern read;
2854 extern sread;
2855 /* DOCUMENT n= read(f, format=fstring, obj1, obj2, ...)
2856 or n= read(prompt= pstring, format=fstring, obj1, obj2, ...)
2857 or n= sread(source, format=fstring, obj1, obj2, ...)
2858 reads text from I/O stream F (1st form), or from the keyboard (2nd
2859 form), or from the string or string array SOURCE (3rd form),
2860 interprets it according to the optional FSTRING, and uses that
2861 interpretation to assign values to OBJ1, OBJ2, ... If the input
2862 is taken from the keyboard, the optional prompt PSTRING (default
2863 "read> ") is printed before each line is read. The Yorick write
2864 function does not interact with the read function -- writes are
2865 always to end-of-file, and do not affect the sequence of lines
2866 returned by read. The backup (and bookmark) function is the
2867 only way to change the sequence of lines returned by read.
2868
2869 There must be one non-supressed conversion specifier (see below)
2870 in FSTRING for each OBJ to be read; the type of the conversion
2871 specifier must generally match the type of the OBJ. That is,
2872 an integer OBJ requires an integer specifier (d, i, o, u, or x)
2873 in FSTRING, a real OBJ requires a real specifier (e, f, or g),
2874 and a string OBJ requires a string specifier (s or []). An OBJ
2875 may not be complex, a pointer, a structure instance, or any non-
2876 array Yorick object. If FSTRING is not supplied, or if it has
2877 fewer conversion specifiers than the number of OBJ arguments,
2878 then Yorick supplies default specifiers ("%ld" for integers,
2879 "%lg" for reals, and "%s" for strings). If FSTRING contains more
2880 specifiers than there are OBJ arguments, the part of FSTRING
2881 beginning with the first specifier with no OBJ is ignored.
2882
2883 The OBJ may be scalar or arrays, but the dimensions of every OBJ
2884 must be identical. If the OBJ are arrays, Yorick behaves as
2885 if the read were called in a loop numberof(OBJ1) times, filling
2886 one array element of each of the OBJ according to FSTRING on
2887 each pass through the loop. (Note that this behavior includes
2888 the case of reading columns of numbers by a single call to read.)
2889
2890 The return value N is the total number of scalar assignments
2891 which were made as a result of this call. (If there were 4
2892 OBJ arguments, and each was an array with 17 elements, a return
2893 value of N==35 would mean the following: The first 8 elements
2894 of OBJ1, OBJ2, OBJ3, and OBJ4 were read, and the 9th element of
2895 OBJ1, OBJ2, and OBJ3 was read.) The read function sets any
2896 elements of the OBJ which were not read to zero -- hence,
2897 independent of the returned N, the all of the old data in the
2898 OBJ arguments is overwritten.
2899
2900 The read or sread functions continue reading until either:
2901 (1) all elements of all OBJ have been filled, or (2) end-of-file
2902 (or end of SOURCE for sread) is reached ("input failure"), or
2903 (3) part of FSTRING or a conversion specifier supplied by
2904 default fails to match the source text ("matching failure").
2905
2906 The FSTRING is composed of a series of "directives" which are
2907 (1) whitespace -- means to skip any amount of whitespace in the
2908 source text
2909 (2) characters other than whitespace and % -- must match the
2910 characters in the source text exactly, or matching failure
2911 occurs and the read operation stops
2912 (3) conversion specifiers beginning with % and ending with a
2913 character specifying the type of conversion -- optionally
2914 skip whitespace, then convert as many characters as
2915 continue to "look like" the conversion type, possibly
2916 producing a matching failure
2917 The conversion specifier is of the form %*WSC, where:
2918 * is either the character '*' or not present
2919 A specifier beginning with %* does not correspond to any of
2920 the OBJ; the converted value will be discarded.
2921 W is either a positive decimal integer specifying the maximum
2922 field width (not including any skipped leading whitespace),
2923 or not present if any number of characters up to end-of-line
2924 is acceptable.
2925 S is either one of the characters 'h', 'l', or 'L', or not
2926 present. Yorick allows this for compatibility with the C
2927 library functions, but ignores it.
2928 C is a character specifying the type of conversion:
2929 d - decimal integer
2930 i - decimal, octal (leading 0), or hex (leading 0x) integer
2931 o - octal integer
2932 u - unsigned decimal integer (same as d for Yorick)
2933 x, X - hex integer
2934 e, f, g, E, G - floating point real
2935 s - string of non-whitespace characters
2936 [xxx] - (xxx is any sequence of characters) longest string
2937 of characters matching those in the list
2938 [^xxx] - longest string of characters NOT matching those in
2939 the list (this is how you can extend %s to be
2940 delimited by something other than whitespace)
2941 % - the ordinary % character; complete conversion
2942 specification must be "%%"
2943
2944 The read function is modeled on the ANSI standard C library
2945 fscanf and sscanf functions, but differs in several respects:
2946 (1) Yorick's read cannot handle the %c, %p, or %n conversion
2947 specifiers in FSTRING.
2948 (2) Yorick's read never results in a portion of a line
2949 being read -- any unused part of a line is simply discarded
2950 (end FSTRING with "%[^\n]" if you want to save the trailing
2951 part of an input line).
2952 (3) As a side effect of (2), there are some differences between
2953 fscanf and Yorick's read in how whitespace extending across
2954 newlines is handled.
2955 SEE ALSO: rdline, write, open, close, bookmark, backup, save, restore,
2956 read_n, tonum
2957 */
2958
2959 extern rdline;
2960 /* DOCUMENT rdline(f)
2961 or rdline(f, n, prompt= pstring)
2962 returns next line from stream F (stdin if F nil). If N is non-nil,
2963 returns a string array containing the next N lines of F. If
2964 end-of-file occurs, rdline returns nil strings. If F is nil,
2965 uses the PSTRING to prompt for input (default "read> ").
2966 SEE ALSO: read, open, close, bookmark, backup, read_n, rdfile
2967 */
2968
rdfile(f,nmax)2969 func rdfile(f, nmax)
2970 /* DOCUMENT rdfile(f)
2971 or rdfile(f, nmax)
2972 reads all remaining lines (or at most NMAX lines) from file F.
2973 If NMAX is omitted, it defaults to 2^20 lines (about a million).
2974 The result is an array of strings, one per line of F.
2975 SEE ALSO: rdline
2976 */
2977 {
2978 if (structof(f)==string) f = open(f);
2979 if (is_void(f)) error, "use rdline to read from stdin";
2980 if (is_void(nmax) || nmax<=0) nmax = 1048576;
2981 n = min(4096, nmax);
2982 s = rdline(f, n);
2983 while (s(0) && n<nmax) {
2984 grow, s, rdline(f, min(nmax-n, n));
2985 n = numberof(s);
2986 }
2987 if (!s(0)) s = s(where(s));
2988 return s;
2989 }
2990
2991 autoload, "readn.i", read_n;
2992 local read_n;
2993 /* DOCUMENT read_n, f, n0, n1, n2, ...
2994 grabs the next numbers N0, N1, N2, ... from file F, skipping over
2995 any whitespace, comma, semicolon, or colon delimited tokens which
2996 are not numbers. (Actually, only the first and last characters of
2997 the token have to look like a number -- 4xxx3 would be read as 4.)
2998 ***WARNING*** at most ten Ns are allowed
2999 The Ns can be arrays, provided all have the same dimensions.
3000 SEE ALSO: read, rdline
3001 */
3002
3003 func tonum(s, &mask, nan=)
3004 /* DOCUMENT tonum(s)
3005 or tonum(s, mask)
3006 returns array of numbers corresponding to given array of strings S.
3007 For each element of S which consists of a single number (either a
3008 decimal integer or floating point number), tonum returns the numeric
3009 value. The return value is type double and the same dimensions as S.
3010 Any elements of S which cannot be interpreted as single numeric
3011 values will have the value -1.0e99 in the result array. You can
3012 specify a different value for "not a number" with the nan= keyword.
3013 The optional MASK is an output of type int of the same dimensions
3014 as S, which is 1 where S is a floating point number (with decimal
3015 point and/or exponent), 3 where S is an integer, and 0 where S is
3016 not a number.
3017 SEE ALSO: sread, totxt, strgrep
3018 */
3019 {
3020 if (is_void(nan)) nan = -1.e99;
3021 x = array(nan, dimsof(s));
3022 i = strgrep("^[ \t]*[+-]?[0-9]+[ \t]*$", s);
3023 r = "[+-]?(\\.?[0-9]+|[0-9]+\\.[0-9]*)([dDeE][+-]?[0-9]+)?";
3024 r = strgrep("^[ \t]*"+r+"[ \t]*$", s);
3025 mask = (r(2,..)>0) | ((i(2,..)>0)<<1);
3026 list = where(mask);
3027 n = numberof(list);
3028 if (n) {
3029 y = array(0., n);
3030 if (sread(s(list)+" ",y) != n) error, "(BUG) number not a number??";
3031 x(list) = y;
3032 }
3033 return x;
3034 }
3035
3036 extern write;
3037 extern swrite;
3038 /* DOCUMENT n= write(f, format=fstring, linesize=l, obj1, obj2, ...)
3039 n= write(format=fstring, linesize=l, obj1, obj2, ...)
3040 or strings= swrite(format=fstring, linesize=l, obj1, obj2, ...)
3041 writes text to I/O stream F (1st form), or to the terminal (2nd
3042 form), or to the STRINGS string array (3rd form), representing
3043 arrays OBJ1, OBJ2, ..., according to the optional FSTRING. The
3044 optional linesize L defaults to 80 characters, and helps restrict
3045 line lengths when FSTRING is not given, or does not contain
3046 newline directives. The write function always appends to the
3047 end of a text file; the position for a sequence of reads is
3048 not affected by intervening writes.
3049
3050 There must be one conversion specifier (see below) in FSTRING for
3051 each OBJ to be written; the type of the conversion specifier must
3052 generally match the type of the OBJ. That is, an integer OBJ
3053 requires an integer specifier (d, i, o, u, x, or c) in FSTRING,
3054 a real OBJ requires a real specifier (e, f, or g), a string OBJ
3055 requires the string specifier (s), and a pointer OBJ requires a
3056 the pointer specifier (p). An OBJ may not be complex, a structure
3057 instance, or any non-array Yorick object. If FSTRING is not
3058 supplied, or if it has fewer conversion specifiers than the
3059 number of OBJ arguments, then Yorick supplies default specifiers
3060 (" %8ld" for integers, " %14.6lg" for reals, " %s" for strings, and
3061 " %8p" for pointers). If FSTRING contains more specifiers than
3062 there are OBJ arguments, the part of FSTRING beginning with the
3063 first specifier with no OBJ is ignored.
3064
3065 The OBJ may be scalar or arrays, but the dimensions of the OBJ
3066 must be conformable. If the OBJ are arrays, Yorick behaves as
3067 if he write were called in a loop dimsof(OBJ1, OBJ2, ...) times,
3068 writing one array element of each of the OBJ according to FSTRING
3069 on each pass through the loop. The swrite function returns a
3070 string array with dimensions dimsof(OBJ1, OBJ2, ...). The write
3071 function inserts a newline between passes through the array if
3072 the line produced by the previous pass did not end with a
3073 newline, and if the total number of characters output since the
3074 previous inserted newline, plus the number of characters about
3075 to be written on the current pass, would exceed L characters
3076 (L defaults to 80). The write function returns the total
3077 number of characters output.
3078
3079 The FSTRING is composed of a series of "directives" which are
3080 (1) characters other than % -- copied directly to output
3081 (2) conversion specifiers beginning with % and ending with a
3082 character specifying the type of conversion -- specify
3083 how to convert an OBJ into characters for output
3084 The conversion specifier is of the form %FW.PSC, where:
3085 F is zero or more optional flags:
3086 - left justify in field width
3087 + signed conversion will begin with either + or -
3088 (space) signed conversion will begin with either space or -
3089 # alternate form (see description of each type below)
3090 0 pad field width with leading 0s instead of leading spaces
3091 W is either a decimal integer specifying the minimum field width
3092 (padded as specified by flags), or not present to use the
3093 minimum number of characters required.
3094 .P is either a decimal integer specifying the precision of the
3095 result, or not present to get the default. For integers, this
3096 is the number of digits to be printed (possibly forcing leading
3097 zeroes), and defaults to 1. For reals, this is the number of
3098 digits after the decimal point, and defaults to 6. For strings,
3099 this is the maximum number of characters to print, and defaults
3100 to infinity.
3101 S is either one of the characters 'h', 'l', or 'L', or not
3102 present. Yorick allows this for compatibility with the C
3103 library functions, but ignores it.
3104 C is a character specifying the type of conversion:
3105 d, i - decimal integer
3106 o - octal integer (# forces leading 0)
3107 u - unsigned decimal integer (same as d for Yorick)
3108 x, X - hex integer (# forces leading 0x)
3109 f - floating point real in fixed point notation
3110 (# forces decimal)
3111 e, E - floating point real in scientific notation
3112 g, G - floating point real in fixed or scientific notation
3113 depending on the value converted (# forces decimal)
3114 s - string of ASCII characters
3115 c - integer printed as corresponding ASCII character
3116 p - pointer
3117 % - the ordinary % character; complete conversion
3118 specification must be "%%"
3119
3120 The write function is modeled on the ANSI standard C library
3121 fprintf and sprintf functions, but differs in several respects:
3122 (1) Yorick's write cannot handle the %n conversion specifier
3123 in FSTRING.
3124 (2) Yorick's write may insert additional newlines if the OBJ
3125 are arrays, to avoid extremely long output lines.
3126 SEE ALSO: print, exit, error, read, rdline, open, close, save, restore
3127 */
3128
3129 extern bookmark;
3130 extern backup;
3131 /* DOCUMENT backup, f
3132 or bmark= bookmark(f)
3133 ...
3134 backup, f, bmark
3135 back up the text stream F, so that the next call to the read
3136 function returns the same line as the previous call to read
3137 (note that you can only back up one line). If the optional
3138 second argument BMARK is supplied, restores the state of the
3139 file F to its state at the time the bookmark function was
3140 called.
3141 After a matching failure in read, use the single argument form
3142 of backup to reread the line containing the matching failure.
3143 SEE ALSO: read, rdline, open, close
3144 */
3145
3146 func select_name(list, index=, prompt=, forever=,
3147 label=, width=, sep=, eol=, bol=, maxcols=)
3148 /* DOCUMENT select_name(list)
3149 Print out array of strings LIST (using print_columns) and
3150 interactively ask the user a number/item in the list and return the
3151 selected item. If keyword INDEX is true, the item number is returned
3152 rather than its value. The prompt string can be set with keyword PROMPT
3153 (default is " Select one item: "). If keyword FOREVER is true the user
3154 is prompted until a valid choice is made.
3155
3156 Other keywords are passed to print_columns: LABEL (as
3157 LABEL), WIDTH, SEP, EOL, BOL and MAXCOLS.
3158
3159 SEE ALSO: print_columns. */
3160 {
3161 number = numberof(list);
3162 print_columns, list, label=(is_void(label) ? " - " : label),
3163 width=width, sep=sep, eol=eol, bol=bol, maxcols=maxcols;
3164 if (is_void(prompt)) prompt=" Select one item: ";
3165 for (;;) {
3166 t = string(0);
3167 k = 0;
3168 s = rdline(prompt=prompt);
3169 if (sread(s, format="%d %s", k, t) == 1 && k >= 1 && k <= number) break;
3170 if (numberof((k = where(list == s))) == 1) {
3171 k = k(1);
3172 break;
3173 }
3174 if (! forever) return;
3175 }
3176 return (index ? k : list(k));
3177 }
3178
3179 func select_file(dir, prompt=, width=, forever=, all=, pattern=)
3180 /* DOCUMENT select_file()
3181 or select_file(dir)
3182 Interactively select name of an existing file starting at current working
3183 directory or at last selected directory or at DIR if this argument is
3184 specified. The function returns full path of selected file or nil [] if
3185 no valid selection is made. If keyword FOREVER is true, a file must be
3186 selected for the function to return.
3187
3188 If keyword ALL is true, then all files and directories get displayed --
3189 even the "hidden" ones which name start with a dot. In any cases, the
3190 current and parent directories ("." and "..") get displayed to allow the
3191 user to re-scan the current directory or to go into the parent directory.
3192
3193 Keyword PATTERN can be set to a regular expression to select only files
3194 that match PATTERN. For instance, PATTERN="\\.(tgz|tar\\.gz)$" would
3195 match any files with suffix ".tgz" or ".tar.gz".
3196
3197 Keyword WIDTH can be used to specify a different text width than the
3198 default of 79 characters.
3199
3200 Keyword PROMPT can be set to change the default prompt:
3201 " Select file/directory: "
3202
3203 SEE ALSO: lsdir, regmatch, print_columns. */
3204 {
3205 /* fool codger */ extern __select_file_dir; local dir_list;
3206 if (is_void(width)) width = 79;
3207 if (is_void(prompt)) prompt=" Select file/directory: ";
3208 if (! is_void(pattern) && ! (is_string(pattern) && is_scalar(pattern))) {
3209 error, "value of keyword PATTERN must be nil or a scalar string";
3210 }
3211 cwd = get_cwd();
3212 if (! is_void(dir)) __select_file_dir = dir;
3213 if (structof(__select_file_dir) != string) {
3214 __select_file_dir = cwd;
3215 } else {
3216 __select_file_dir = cd(__select_file_dir);
3217 }
3218
3219 hline = "-------------------------------------";
3220 for (;;) {
3221 file_list = lsdir(__select_file_dir, dir_list);
3222 if (! all) {
3223 if ((n = numberof(file_list)) > 0) {
3224 i = where(strpart(file_list, 1:1) != ".");
3225 if (numberof(i) != n) file_list = file_list(i);
3226 }
3227 if ((n = numberof(dir_list)) > 0) {
3228 i = where(strpart(dir_list, 1:1) != ".");
3229 if (numberof(i) != n) dir_list = dir_list(i);
3230 }
3231 }
3232 if (pattern && (n = numberof(file_list)) > 0) {
3233 i = where(strgrep(pattern, file_list)(2,..) >= 0);
3234 if (numberof(i) != n) file_list = file_list(i);
3235 }
3236 grow, dir_list, ".", ".."; /* use . to allow reading directory again */
3237 dir_list = dir_list(sort(dir_list));
3238 list = dir_list + "/";
3239 if (is_array(file_list)) {
3240 grow, list, file_list(sort(file_list));
3241 file_list = [];
3242 }
3243 ndirs = numberof(dir_list);
3244 number = numberof(list);
3245
3246 /* Print out directory list. */
3247 text = print_columns(list, label=": ", width=width,
3248 sep=, eol=" ", bol="| ", maxcols=);
3249 text_len = strlen(text(1))+1;
3250 len = max(width, text_len);
3251 while (strlen(hline) < len) hline += hline;
3252 head_line = "[" + __select_file_dir + "]";
3253 n = (len - strlen(head_line) - 2)/2;
3254 if (n > 0) head_line = strpart(hline, 1:n)+head_line;
3255 n = len - strlen(head_line) - 2;
3256 if (n > 0) head_line += strpart(hline, 1:n);
3257 write, format=",%s.\n", head_line;
3258 write, format=swrite(format="%%-%ds|\n", len-1), text;
3259 write, format="`%s'\n", strpart(hline, 1:len-2);
3260 for (;;) {
3261 t = string(0);
3262 k = 0;
3263 s = rdline(prompt=prompt);
3264 if (sread(s, format="%d %s", k, t) == 1 && k >= 1 && k <= number) break;
3265 if (numberof((k = where(list == s))) == 1) {
3266 k = k(1);
3267 break;
3268 }
3269 if (numberof((k = where(dir_list == s))) == 1) {
3270 k = k(1);
3271 break;
3272 }
3273 if (! forever) {
3274 cd, cwd;
3275 return;
3276 }
3277 }
3278 if (k > ndirs) {
3279 cd, cwd;
3280 return __select_file_dir + list(k);
3281 }
3282 __select_file_dir = cd(__select_file_dir + dir_list(k));
3283 }
3284 }
3285
3286 func print_columns(list, label=, width=, start=, sep=, eol=, bol=, maxcols=)
3287 /* DOCUMENT print_columns, list;
3288 or print_columns(list);
3289 Write array of strings LIST in columns. In subroutine form, the result
3290 is printed to standard output; otherwise, the function returns an array
3291 of formatted strings (one per row).
3292
3293 The maximum width (in number of characters) of each row can be specified
3294 with keyword WIDTH (default 79). But actual width may be larger, since
3295 at least one column is produced.
3296
3297 The maximum number of columns may be limited by using keyword MAXCOLS (by
3298 default, there is no limit).
3299
3300 Keywords BOL, SEP and EOL, can be set to scalar strings to use at begin
3301 of line, between each column, at end of line respectively. SEP can also
3302 be the number of spaces to insert between columns. The default are:
3303 BOL="", SEP=5 (five spaces) and EOL=string(0).
3304
3305 Keyword LABEL can be used to number items. LABEL must be a scalar string.
3306 If LABEL contains a "%d", it is used to format the index; otherwise,
3307 LABEL is the string to use as separator between indices and items. For
3308 instance:
3309 label="[%d] " yields: "[1] first_item [2] second_item ..."
3310 label=" - " yields: "1 - first_item 2 - second_item ..."
3311
3312 Keyword START can be used to specify the starting index for numbering
3313 items (default START=1).
3314
3315
3316 SEE ALSO: swrite, select_name, select_file. */
3317 {
3318 number = numberof(list);
3319 if (is_scalar(label) && is_string(label)) {
3320 if (is_void(start)) start = 1;
3321 index = indgen(start:start+number-1);
3322 if (strmatch(label, "%d")) {
3323 index = swrite(format=label, index);
3324 } else {
3325 index = swrite(format="%d", index) + label;
3326 }
3327 len = strlen(index);
3328 if (max(len) != min(len)) {
3329 /* Justify index list. */
3330 index = swrite(format=swrite(format="%%%ds", max(len)), index);
3331 }
3332 list = index + list(*);
3333 } else if (is_void(label)) {
3334 list = list(*);
3335 } else {
3336 error, "value of keyword LABEL must be nil or a scalar string";
3337 }
3338
3339 if (is_void(bol)) bol = "";
3340 if (is_void(eol)) eol = string(0);
3341 if (is_void(width)) width = 79;
3342 if (structof(sep) != string) {
3343 /* Convert margin separator into spaces. */
3344 if (is_void(sep)) sep = 5;
3345 sep = swrite(format=swrite(format="%%%ds", sep), "");
3346 }
3347 len = max(strlen(list));
3348 slen = strlen(sep);
3349 ncols = (width + slen - strlen(bol) - strlen(eol))/(len + slen);
3350 if (! is_void(maxcols) && ncols > maxcols) ncols = maxcols;
3351 if (ncols < 1) ncols = 1;
3352 nrows = (number+ncols-1)/ncols;
3353
3354 (tmp = array(string, nrows, ncols))(1:number) = unref(list);
3355 if (ncols > 1) {
3356 fmt = swrite(format="%%-%ds%s", len, sep);
3357 for (j=1 ; j<ncols ; ++j) bol += swrite(format=fmt, tmp(,j));
3358 }
3359 fmt = (eol ? swrite(format="%%-%ds%s", len, eol) : "%s");
3360 bol += swrite(format=fmt, tmp(,ncols));
3361 if (! am_subroutine()) return bol;
3362 write, format="%s\n", bol;
3363 }
3364
3365 /*= SECTION(include) including files and parsing strings ===================*/
3366
3367 extern include;
3368 extern require;
3369 /* DOCUMENT #include "yorick_source.i"
3370 require, source
3371 include, source
3372 or include, source, now
3373
3374 The SOURCE argument can be a scalar string, interpreted as a
3375 filename like "yorick_source.i", the text in a char array, or
3376 the text in a 1D array of strings (as returned by a two argument
3377 call to rdline). This is the low level interface for executing
3378 text as yorick code. Use the exec function for a higher level
3379 interface. In particular, with NOW=1, a function with a catch
3380 call in the call tree of SOURCE will not work properly with
3381 include, but it will work with exec.
3382
3383 #include is a parser directive, not a Yorick statement. Use it
3384 to read Yorick source code which you have saved in a file; the
3385 file yorick_source.i will be read one line at a time, exactly as
3386 if you had typed those lines at the keyboard. The following
3387 directories are searched (in this order) to find yorick_source.i:
3388
3389 . (current working directory)
3390 ~/yorick (your personal directory of Yorick functions)
3391 ~/Yorick (your personal directory of Yorick functions)
3392 Y_SITE/i (Yorick distribution library)
3393 Y_SITE/contrib (contributed source at your site)
3394 Y_SITE/i0 (Yorick startup and package include files)
3395 Y_HOME/lib (Yorick architecture dependent include files)
3396
3397 To find out what is available in the Y_SITE/i directory,
3398 type:
3399 library
3400 You can also type
3401 Y_SITE
3402 to find the name of the site directory at your site, go to the
3403 include or contrib subdirectory, and browse through the *.i files.
3404 This is a good way to learn how to write a Yorick program. Be
3405 alert for files like README as well.
3406
3407 The require function checks to see whether FILENAME has already
3408 been included (actually whether any file with the same final
3409 path component has been included). If so, require is a no-op,
3410 otherwise, the action is the same as the include function with
3411 NOW == 1.
3412
3413 The include function causes Yorick to parse and execute FILENAME
3414 immediately. The effect is similar to the #include parser
3415 directive, except the finding, parsing, and execution of FILENAME
3416 occurs at runtime. The NOW argument has the following meanings:
3417 NOW == -1 filename pushed onto stack, popped and parsed
3418 when all pending input is exhausted
3419 NOW == 0 (or nil, default) parsed just before next input
3420 line would be parsed
3421 NOW == 1 parsed immediately, resuming current interpreted
3422 program when finished (like require)
3423 NOW == 2 like 0, except no error if filename does not exist
3424 NOW == 3 like 1, except no error if filename does not exist
3425
3426 SEE ALSO: set_path, Y_SITE, plug_in, autoload, include_all, funcdef
3427 include1, exec
3428 */
3429
3430 extern include1;
3431 /* DOCUMENT function = include1(source)
3432 is similar to include, but parses SOURCE only until the first
3433 executable *main* program, which it returns as an interpreted
3434 function rather than executing immediately.
3435
3436 The SOURCE argument can be a scalar string, interpreted as a
3437 filename like "yorick_source.i", the text in a char array, or
3438 the text in a 1D array of strings (as returned by a two argument
3439 call to rdline).
3440
3441 SEE ALSO: include, funcdef
3442 */
3443
exec(_exec_code_)3444 func exec(_exec_code_)
3445 /* DOCUMENT exec, yorick_code
3446 or value = exec(yorick_expr)
3447 Parse and execute the string or string array YORICK_CODE. If a
3448 string or string array YORICK_EXPR represents a single yorick
3449 expression, and exec is invoked as a function, it will return the
3450 value of the expression. If YORICK_EXPR does not contain the
3451 pattern "return", "return " will be prepended.
3452 SEE ALSO: include
3453 */
3454 {
3455 local _exec_func_;
3456 if (am_subroutine()) { /* invoke code as subroutine */
3457 include, grow("func _exec_func_ {", _exec_code_, "}"), 1;
3458 _exec_func_;
3459 } else { /* evaluate code as an expression, returning its value */
3460 _exec_code_ = _exec_code_;
3461 if (noneof(strmatch(_exec_code_, "return")))
3462 _exec_code_(1) = "return " + _exec_code_(1);
3463 include, grow("func _exec_func_(_exec_code_) {", _exec_code_, "}"), 1;
3464 return _exec_func_();
3465 }
3466 }
3467
3468 extern current_include;
3469 /* DOCUMENT current_include()
3470 If Yorick is parsing a file, this function returns the absolute path
3471 of this file; otherwise, this function returns nil.
3472
3473 SEE ALSO: include, require.
3474 */
3475
3476 extern get_includes;
3477 /* DOCUMENT get_includes()
3478 Returns an array of strings with the names of all included files so
3479 far.
3480
3481 SEE ALSO: set_path, current_include, include, require.
3482 */
3483
include_all(dir,..)3484 func include_all(dir, ..)
3485 /* DOCUMENT include_all, dir1, dir2, ...
3486 include all files in directories DIR1, DIR2, ..., with names
3487 ending in the ".i" extension. (This is mostly for use to load
3488 the i-start directories when yorick starts; see i0/stdx.i.)
3489 If any of the DIRi do not exist, or are empty, they are
3490 silently skipped. Filenames beginning with "." are also skipped,
3491 even if they end in ".i". The files are included in alphabetical
3492 order, DIR1 first, then DIR2, and so on.
3493
3494 SEE ALSO: include, include1, autoload
3495 */
3496 {
3497 if (is_void(dir)) return;
3498 dir = array(dir, more_args()+1);
3499 for (i=2 ; i<=numberof(dir) ; ++i) dir(i) = next_arg();
3500 /* provide hook for mpy to prevent all ranks from calling lsdir */
3501 files = _include_all_hook(dir);
3502 for (i=1 ; i<=numberof(files) ; ++i) include, files(i), 3;
3503 }
include_all_ls(dir)3504 func include_all_ls(dir)
3505 {
3506 /**/ local files;
3507 for (i=1 ; i<=numberof(dir) ; ++i) {
3508 list = lsdir(dir(i));
3509 if (structof(list) != string) continue;
3510 list = list(where((strpart(list,1:1)!=".")&(strpart(list,-1:0)==".i")));
3511 if (!numberof(list)) continue;
3512 list = list(sort(list));
3513 if (strpart(dir(i),0:0) != "/") dir(i) += "/";
3514 grow, files, dir(i)+list;
3515 }
3516 return files;
3517 }
3518 _include_all_hook = include_all_ls;
3519
3520 func istart_include
3521 {
3522 dir = istart_places(Y_SITE);
3523 if (Y_HOME!=Y_SITE) grow, dir, istart_places(Y_HOME);
3524 if (Y_HOME_PKG && (Y_HOME_PKG!=Y_SITE)) grow, dir, istart_places(Y_HOME_PKG);
3525 if (!_istart_hook()) grow, dir, [Y_USER+"i-start"];
3526 files = _include_all_hook(dir);
3527 for (i=1 ; i<=numberof(files) ; ++i) include, files(i), 3;
3528 }
3529 _istart_hook = batch;
3530
istart_places(dir)3531 func istart_places(dir)
3532 {
3533 i = strfind("/",dir, n=1024);
3534 i = i(1 : min(where(i<0))-1);
3535 parts = strpart(dir, grow([0],i));
3536 if (numberof(parts) < 2) return dir+"i-start";
3537 if (parts(0) == "") parts = parts(1:-1);
3538 list = where(strmatch(parts,"yorick",1));
3539 if (numberof(list)) {
3540 i = list(1);
3541 } else {
3542 list = where((parts=="lib") | (parts=="share"));
3543 if (numberof(list)) i = max(list(0)+1,i);
3544 else i = numberof(parts);
3545 }
3546 parts += "/";
3547 dir = array(sum(parts(1:i)), numberof(parts)-i+1);
3548 parts = (i<numberof(parts))? parts(i+1:0) : [];
3549 for (i=1 ; i<=numberof(parts) ; ++i) dir(i+1:0) += parts(i);
3550 parts = array("site-i", numberof(dir));
3551 parts(1) = "i-start";
3552 return dir(::-1) + parts;
3553 }
3554
3555 func customize { if (!_istart_hook()) include, "custom.i"; }
3556
3557 extern autoload;
3558 /* DOCUMENT autoload, ifile, var1, var2, ...
3559 or autoload, ifile
3560 causes IFILE to be included when any of the variables VAR1, VAR2, ...
3561 is referenced as a function or subroutine. Multiple autoload
3562 calls may refer to a single IFILE; the effect is cumulative. Note
3563 that any reference to a single one of the VARi causes all of them
3564 to be replaced (when IFILE is included).
3565 The semantics of this process are complicated, but should work
3566 as expected in most cases: After the call to autoload, the VARi
3567 may not be redefined (e.g.- VARi=something or func VARi) without
3568 generating a warning message, and causing all the VARi for the
3569 same IFILE to become undefined. The semantic subtlety arises
3570 from the yorick variable scoping rules; if any of the VARi has local
3571 scope for any function in the calling chain when the inclusion of
3572 IFILE is actually triggered, only those local values will be
3573 replaced. (The autoload function is no different than the require
3574 or include functions in this regard.)
3575 The second form, with no VARi, cancels the autoload, without giving
3576 any warning; all the VARi become undefined.
3577
3578 Before IFILE is included, the VARi behave like [] (nil) variables
3579 as far as their response to the is_void function, and the ! and ?
3580 operators. (You can use is_func to discover whether a variable is
3581 an autoload.) Only their actual use in a function or subroutine call
3582 will trigger the autoload. While the IFILE may define the VARi
3583 as any type of object, the autoload feature only works as intended
3584 if the VARi are defined as interpreted or built-in functions. The
3585 only way it makes sense for a VARi to be a built-in function, is
3586 if the IFILE executes a plug_in command to dynamically load an
3587 associated compiled library.
3588
3589 If IFILE (or a file with the same name) has already been included,
3590 autoload is a silent no-op. This is exactly analogous to the
3591 behavior of the require function; it does not harm to call either
3592 require or autoload if the IFILE has already been included. Note
3593 that you may want to place a require at the beginning of a file
3594 you expect to be autoloaded, in preference to providing separate
3595 autoloads for the second file.
3596
3597 SEE ALSO: include, require, plug_in, is_func
3598 */
3599
3600 extern funcdef;
3601 /* DOCUMENT function = funcdef(command_line)
3602 creates an anonymous interpreted function from the input
3603 COMMAND_LINE, equivalent to
3604 func function {
3605 command_line;
3606 }
3607 The COMMAND_LINE string is restricted to the following
3608 format:
3609 "funcname arg1 arg2 ..."
3610 where each of the arguments is one of
3611 (a) a symbol (that is, a yorick variable name)
3612 (b) a decimal integer
3613 (c) a real number
3614 (d) a quoted string
3615 The quoted string is enclosed in double quotes, and a
3616 backslash can be used to escape a double quote or a
3617 backslash (but the other backslash escape sequences are
3618 not recognized and unnecessary - just insert the ascii code).
3619
3620 Note that funcdef merely creates the function; if you want
3621 to execute it and discard it, use the following statement:
3622 funcdef(command_line);
3623
3624 The huge advantage of funcdef over the full yorick parser
3625 is that it is stateless, which means you can invoke it to
3626 generate actions for event callbacks. The extreme simplicity
3627 of the permitted COMMAND_LINE is not a limitation for this
3628 application, because you are free to invoke an arbitrarily
3629 complex "funcname", and to provide it with arbitrary inputs.
3630
3631 The intent with funcdef is not to permit you to create an
3632 arbitrary toolkit of interpreted functions, but merely to
3633 allow you to invoke such a toolkit; the toolkit itself is
3634 supposed to be parsed by the ordinary include, require, or
3635 autoload mechanisms. Generally, you will have to design
3636 an interpreted toolkit somewhat differently if it is to be
3637 invoked by funcdef. For example, funcdef does not allow
3638 you to set variables as in x=value, but you can use the
3639 funcset (or similarly designed) function to set variables
3640 like this:
3641 funcdef("funcset x value")
3642
3643 Do not attempt to use funcdef to input vast amounts of data.
3644 As a rule of thumb, if your funcdef strings have more than a
3645 couple of dozen tokens, you probably haven't thought hard
3646 enough about what you are doing.
3647
3648 SEE ALSO: include, spawn, funcset
3649 */
3650
3651 func funcset(&v1,x1,&v2,x2,&v3,x3,&v4,x4,&v5,x5,&v6,x6,&v7,x7,&v8,x8)
3652 /* DOCUMENT funcset var1 val1 var2 val2 ...
3653
3654 Equivalent to
3655 var1=val1; var2=val2; ...
3656
3657 This function it is not useful for yorick programs. It is intended
3658 to be used to create functions with funcdef that set variable values.
3659
3660 Handles at most 8 var/val pairs.
3661 As a special case, if given an odd number of arguments, funcset
3662 sets the final var to [], e.g.-
3663 funcset var1 12.34 var2
3664 is equivalent to
3665 var1=12.34; var2=[];
3666
3667 SEE ALSO: funcdef
3668 */
3669 {
3670 v1 = x1;
3671 if (is_void(x1)) return; else v2 = x2;
3672 if (is_void(x2)) return; else v3 = x3;
3673 if (is_void(x3)) return; else v4 = x4;
3674 if (is_void(x4)) return; else v5 = x5;
3675 if (is_void(x5)) return; else v6 = x6;
3676 if (is_void(x6)) return; else v7 = x7;
3677 if (is_void(x7)) return; else v8 = x8;
3678 }
3679
3680 /*= SECTION(plugin) loading plugins ========================================*/
3681
3682 extern plug_in;
3683 /* DOCUMENT plug_in, "pkgname"
3684
3685 Dynamically link to yorick package "pkgname". The compiled
3686 functions of the package are in a shared object file; these
3687 files have a naming convention which differs slightly on different
3688 platforms. On most UNIX systems (including Mac OS X), the
3689 binary file is named pkgname.so. On MS Windows systems, the
3690 binary file is named pkgname.dll. On HPUX systems, the name is
3691 pkgname.sl. The "pkgname" argument to plug_in does not include
3692 this platform-dependent file extension, so that the yorick code
3693 containing the plug_in command will be portable.
3694
3695 After dynamically linking the compiled routines in the pkgname
3696 shared object binary, yorick runs the function (which must be
3697 present) yk_pkgname in order to initialize the package. At
3698 minimum yk_pkgname returns lists of the new compiled (builtin)
3699 functions defined by the package and the names by which they
3700 may be invoked by interpreted code.
3701
3702 Additionally, yk_pkgname returns a list of files to be included
3703 containing interpreted wrapper functions for the compiled routines
3704 and DOCUMENT comments for the help system. Conventionally, these
3705 include files are located in the Y_SITE/i0 or Y_HOME/lib directories,
3706 and the name (of one) of the file(s) is pkgname.i. If the package
3707 has been statically linked (i.e.- not by plug_in), these .i files
3708 are automatically included when yorick starts. However, if the
3709 package is loaded dynamically by plug_in, you must arrange to
3710 include one or all of these .i files as you would any interpreted
3711 package (e.g.- by the autoload or require functions, or manually).
3712
3713 The upshot of all this is that the plug_in function is designed
3714 to be placed at the top of the .i files associated with the
3715 package. You are not supposed to call plug_in manually, rather
3716 when you #include (or autoload) a .i file which needs compiled
3717 functions, that .i file invokes plug_in to perform any required
3718 dynamic linking to compiled code. Thus, the end user does not
3719 do anything differently for a package that uses dynamically loaded
3720 compiled code, than for a purely interpreted package.
3721
3722 Yorick dynamic library support solves a distribution problem. For
3723 debugging and creating compiled packages for your own use, you want
3724 to build special versions of yorick with your compiled routines
3725 statically linked. In order to support platforms on which there
3726 is no dynamic linking, if you call the plug_in function for a
3727 package that is statically linked (e.g.- plug_in,"yor"), the
3728 function will silently become a no-op when it notices that the
3729 "pkgname" package was already loaded at startup.
3730
3731 SEE ALSO: plug_dir, include, require, autoload
3732 */
3733
3734 extern plug_dir;
3735 /* DOCUMENT old_dirs = plug_dir(dirname)
3736 or plug_dir
3737 or current_dirs = plug_dir()
3738 causes plug_in to look in DIRNAME for dynamic library files, in
3739 addition to Y_HOME/lib. DIRNAME may be an array of strings to
3740 search multiple directories. The return value is the previous
3741 list of directories searched by plug_in. No checks are made
3742 for repeats, so be careful not to grow the list indiscriminately.
3743 In the second form (or called as a subroutine with DIRNAME []),
3744 empties the plug_in search path; in the third form does not
3745 alter the current search path. Note that Y_HOME/lib is omitted
3746 from the end of the return value, even though it is searched.
3747 SEE ALSO: plug_in
3748 */
3749
3750 /*= SECTION(filebin) save and restore binary data ==========================*/
3751
3752 func openb(filename, clogfile, update, open102=, one=)
3753 /* DOCUMENT file = openb(filename)
3754 or file = openb(filename, clogfile)
3755 open the existing file FILENAME for read-only binary I/O.
3756 (Use updateb or createb, respectively, to open an existing file
3757 with read-write access or to create a new file.)
3758 If the CLOGFILE argument is supplied, it represents the structure
3759 of FILENAME in the Clog binary data description language.
3760 After an openb, the file variable may be used to extract variables
3761 from the file as if it were a structure instance. That is, the
3762 expression "file.var" refers to the variable "var" in file "file".
3763 A complete list of the variable names present in the file may
3764 be obtained using the get_vars function. If the file contains
3765 history records, the jt and jc functions may be used to set the
3766 current record -- initially, the first record is current.
3767 The restore function may be used to make memory copies of data
3768 in the file; this will be faster than a large number of
3769 references to "file.var".
3770 The openb function will recognize families of PDB or netCDF files
3771 by their sequential names and open all files subsequent to FILENAME
3772 in such a family as well as FILENAME itself. You can use the one=1
3773 keyword to suppress this behavior and open only FILENAME.
3774 FILENAME may be a file handle to skip the initial open operation.
3775 This feature is intended to enable in-memory files created with
3776 vopen to be opened:
3777 file = openb(vopen(char_array,1));
3778 FILENAME may also be char_array directly, as returned by vsave.
3779 SEE ALSO: updateb, createb, open, vopen, cd
3780 show, jt, jc, restore
3781 get_vars, get_times, get_ncycs, get_member, has_records
3782 set_blocksize, dump_clog, read_clog, recover_file
3783 openb_hooks, open102, close102, get_addrs
3784 */
3785 {
3786 if (is_stream(filename)) f = filename;
3787 else if (structof(filename)==char) f = vopen(filename, 1);
3788 else f = open(filename, (update? update : "rb"));
3789 if (!is_void(clogfile)) return read_clog(f, clogfile);
3790 if (!is_void(open102)) yPDBopen= ((open102&3)|(at_pdb_open&~3));
3791 else yPDBopen= at_pdb_open;
3792 _openb_one = (one || (structof(filename)!=string));
3793 for (hooks=openb_hooks ; hooks ; hooks=_cdr(hooks)) {
3794 if (_car(hooks)(f)) continue;
3795 if (has_records(f)) edit_times, f; /* force increasing times */
3796 return f;
3797 }
3798 return [];
3799 }
3800 errs2caller, openb;
3801
3802 autoload, "show.i", show;
3803 local show;
3804 /* DOCUMENT show, f
3805 or show, f, pat
3806 or show, f, 1
3807 prints a summary of the variables contained in binary file F.
3808 If there are too many variables, use the second form to select
3809 only those variables whose first few characters match PAT.
3810 In the third form, continues the previous show command where it
3811 left off -- this may be necessary for files with large numbers of
3812 variables.
3813 The variables are printed in alphabetical order down the columns.
3814 The print function can be used to obtain other information about F.
3815 SEE ALSO: openb, jt, jc
3816 */
3817
3818 autoload, "collec.i", collect;
3819 local collect;
3820 /* DOCUMENT result= collect(f, name_string)
3821 scans through all records of the history file F accumulating the
3822 variable NAME_STRING into a single array with one additional
3823 index varying from 1 to the number of records.
3824
3825 NAME_STRING can be either a simple variable name, or a name
3826 followed by up to four simple indices which are either nil, an
3827 integer, or an index range with constant limits. (Note that
3828 0 or negative indices count from the end of a dimension.)
3829
3830 Examples:
3831 collect(f, "xle") -- collects the variable f.xle
3832 collect(f, "tr(2,2:)") -- collects f.tr(2,2:)
3833 collect(f, "akap(2,-1:0,)") -- collects f.akap(2,-1:0,)
3834 (i.e.- akap in the last two values of its
3835 second index)
3836
3837 SEE ALSO: get_times
3838 */
3839
3840 extern get_member;
3841 /* DOCUMENT get_member(f_or_s, member_name)
3842 returns F_OR_S member MEMBER_NAME, like F_OR_S.MEMBER_NAME syntax,
3843 but MEMBER_NAME can be a computed string. The F_OR_S may be a
3844 binary file or a structure instance.
3845 SEE ALSO: openb
3846 */
3847
3848 extern read_clog;
3849 /* DOCUMENT file= read_clog(file, clog_name)
3850 raw routine to set the binary data structure of FILE according
3851 to the text description in the Contents Log file CLOG_NAME.
3852 */
3853
recover_file(filename,clogfile)3854 func recover_file(filename, clogfile)
3855 /* DOCUMENT recover_file, filename
3856 or recover_file, filename, clogfile
3857 writes the descriptive information at the end of a corrupted
3858 binary file FILENAME from its Contents Log file CLOGFILE, which
3859 is FILENAME+"L" by default.
3860 */
3861 {
3862 if (is_void(clogfile)) clogfile= filename+"L";
3863 if (clogfile==filename+"L") { /* open clobbers this one */
3864 changed= 1;
3865 rename, clogfile, filename+"M";
3866 clogfile= filename+"M";
3867 } else {
3868 changed= 0;
3869 }
3870 f= open(filename, "r+b");
3871 i= array(char, 12);
3872 _read, f, 0, i;
3873 read_clog, f, clogfile;
3874 if (string(&i)=="!<<PDB:II>>!") _set_pdb, f, at_pdb_close;
3875 else _init_clog, f;
3876 close, f;
3877 if (changed) remove, clogfile;
3878 }
3879
3880 extern _not_pdb;
3881 /* DOCUMENT _not_pdb(file, familyOK)
3882 returns 1 if FILE is not a PDB file, otherwise returns 0 after
3883 setting the structure and data tables, and cataloguing any
3884 history records. Used to open an existing file. Also detects
3885 a file with an appended Clog description.
3886 Before calling _not_pdb, set the variable yPDBopen to the value
3887 of at_pdb_open you want to be in force. (For historical reasons
3888 -- in order to allow for the open102 keyword to openb -- _not_pdb
3889 looks at the value of the variable yPDBopen, rather than at_pdb_open
3890 directly.)
3891 */
3892
3893 local close102, open102, close102_default;
3894 /* DOCUMENT close102 is a keyword for createb or updateb,
3895 open102 is a keyword for openb or updateb
3896 close102_default is a global variable (initially 0)
3897 ***Do not use close102_default -- use at_pdb_close
3898 -- this is for backward compatibility only***
3899
3900 close102=1 means to close the PDB file "Major-Order:102"
3901 close102=0 means close it "Major-Order:101"
3902 if not specified, uses 1 if close102_default non-zero,
3903 otherwise the value specified in at_pdb_close
3904
3905 open102=1 means to ignore what the PDB file says internally,
3906 and open it as if it were "Major-Order:102"
3907 open102=0 (the default) means to assume the PDB file is
3908 correctly writen
3909 open102=2 means to assume that the file is incorrectly
3910 written, whichever way it is marked
3911 open102=3 means to ignore what the PDB file says internally,
3912 and open it as if it were "Major-Order:101"
3913
3914 The PDB file format comes in two styles, "Major-Order:101", and
3915 "Major-Order:102". Yorick interprets these correctly by default,
3916 but other codes may ignore them, or write them incorrectly.
3917
3918 Unlike Yorick, not all codes are able to correctly read both
3919 styles. If you are writing a file which needs to be read by
3920 a "102 style" code, create it with the close102=1 keyword.
3921
3922 If you notice that a file you though was a history file isn't, or
3923 that the dimensions of multi-dimensional variables are transposed
3924 from the order you expected, the code which wrote the file probably
3925 blew it. Try openb("filename", open102=2). The choices 1 and 3
3926 are for cases in which you know the writing code was supposed to
3927 write the file one way or the other, and you don't want to be
3928 bothered.
3929
3930 The open102 and close102 keywords, if present, override the
3931 defaults in the variables at_pdb_open and at_pdb_close.
3932
3933 SEE ALSO: at_pdb_open, at_pdb_close
3934 */
3935 close102_default= [];
3936
3937 local at_pdb_open, at_pdb_close;
3938 /* DOCUMENT at_pdb_open
3939 at_pdb_close
3940 bits for optional behavior when a PDB file is opened or closed:
3941
3942 at_pdb_open:
3943 000 Major-Order: value specified in file is correct
3944 001 Major-Order:102 always
3945 002 Major-Order: opposite from what file says
3946 003 Major-Order:101 always
3947
3948 004 Strip Basis @... suffices from variable names (when possible)
3949 Danger! If you do this and open a file for update, the variable
3950 names will be stripped when you close the file!
3951 010 Use Basis @history convention on input
3952
3953 The 001 and 002 bits may be overridden by the open102 keyword.
3954 The default value of at_pdb_open is 010.
3955
3956 at_pdb_close (the value at the time the file is opened or created
3957 is remembered):
3958 001 Write Major-Order 102 PDB file
3959 002 Write PDB style history data
3960 The following are no-ops unless bit 002 is set:
3961 004 Use Basis @history convention on output
3962 010 Do NOT pack all history record variables into
3963 a single structure instance.
3964
3965 The 001 bit may be overridden by the close102 keyword or if
3966 close102_default is non-zero.
3967 The default value of at_pdb_close is 007.
3968
3969 SEE ALSO: close102_default
3970 */
3971 at_pdb_open= 010;
3972 at_pdb_close= 007;
3973
_not_pdbf(f)3974 func _not_pdbf(f) { return _not_pdb(f, !_openb_one); }
3975
3976 extern _init_pdb;
3977 extern _set_pdb;
3978 /* DOCUMENT _init_pdb, file, at_pdb_close
3979 _set_pdb, file, at_pdb_close
3980 initializes a PDB binary file. Used after creating a new file --
3981 must be called AFTER the primitive data formats have been set.
3982 The _set_pdb call only sets the CloseHook, on the assumption that
3983 the file header has already been written (as in recover_file).
3984 SEE ALSO: createb, recover_file, at_pdb_close
3985 */
3986
3987 extern _init_clog;
3988 /* DOCUMENT _init_clog, file
3989 initializes a Clog binary file. Used after creating a new file --
3990 must be called AFTER the primitive data formats have been set.
3991 */
3992
3993 extern dump_clog;
3994 /* DOCUMENT dump_clog, file, clog_name
3995 dumps a Contents Log of the binary file FILE into the text file
3996 CLOG_NAME. Any previous file named CLOG_NAME is overwritten.
3997 SEE ALSO: openb
3998 */
3999
_not_cdf(file)4000 func _not_cdf(file)
4001 /* DOCUMENT _not_cdf(file)
4002 is like _not_pdb, but for netCDF files.
4003 */
4004 {
4005 i= array(char, 4);
4006 _read, file, 0, i;
4007 if (string(&i)!="CDF\001") return 1; /* test magic number */
4008 require, "netcdf.i";
4009 if (_openb_one) _nc_open_filename = [filename];
4010 return raw_not_cdf(file);
4011 }
4012
4013 local openb_hooks;
4014 /* DOCUMENT openb_hooks
4015 list of functions to be tried by openb if the file to be
4016 opened is not a PDB file. By default,
4017 openb_hooks= _lst(_not_pdbf, _not_cdf).
4018 The hook functions will be called with the file as argument
4019 (e.g.- _not_cdf(file)), beginning with _car(openb_hooks), until
4020 one of them returns 0. Note that a hook should return 0 if it
4021 "recognizes" the file as one that it should be able to open, but
4022 finds that the file is misformatted (alternatively, it could call
4023 error to abort the whole process).
4024 */
4025 openb_hooks= _lst(_not_pdbf, _not_cdf);
4026
4027 func createb(filename, primitives, close102=, clog=)
4028 /* DOCUMENT file= createb(filename)
4029 or file= createb(filename, primitives)
4030 creates FILENAME as a PDB file in "w+b" mode, destroying any
4031 existing file by that name. If the PRIMITIVES argument is
4032 supplied, it must be the name of a procedure that sets the
4033 primitive data types for the file. The default is to create
4034 a file with the native primitive types of the machine on which
4035 Yorick is running. The following PRIMITIVES functions are
4036 predefined:
4037 sun_primitives -- appropriate for Sun, HP, IBM, and
4038 most other workstations
4039 sun3_primitives -- appropriate for old Sun-2 or Sun-3
4040 dec_primitives -- appropriate for DEC (MIPS) workstations, Windows
4041 alpha_primitives -- appropriate for DEC alpha workstations
4042 sgi64_primitives -- appropriate for 64 bit SGI workstations
4043 cray_primitives -- appropriate for Cray 1, XMP, and YMP
4044 mac_primitives -- appropriate for MacIntosh
4045 macl_primitives -- appropriate for MacIntosh, 12-byte double
4046 i86_primitives -- appropriate for Linux i86 machines
4047 pc_primitives -- appropriate for IBM PC
4048 vax_primitives -- appropriate for VAXen only (H doubles)
4049 vaxg_primitives -- appropriate for VAXen only (G doubles)
4050 xdr_primitives -- appropriate for XDR files
4051
4052 FILENAME may also be char (that is, the char datatype) in order to
4053 create an in-memory binary file using vopen. Such a file must be
4054 closed with vclose or everything written to it will be lost.
4055
4056 SEE ALSO: openb, updateb, vopen, vsave, cd
4057 save, add_record, set_filesize, set_blocksize
4058 close102, close102_default, at_pdb_open, at_pdb_close
4059 */
4060 {
4061 file = (filename==char)? vopen(,1) : open(filename, "w+b"+(clog?"c":""));
4062 if (!is_void(primitives)) primitives, file;
4063 if (!is_void(close102)) yPDBclose= ((close102&1)|(at_pdb_close&~1));
4064 else if (is_void(close102_default)) yPDBclose= at_pdb_close;
4065 else yPDBclose= ((close102_default&1)|(at_pdb_close&~1));
4066 _init_pdb, file, yPDBclose;
4067 return file;
4068 }
4069 errs2caller, createb;
4070
sun_primitives(file)4071 func sun_primitives(file)
4072 /* DOCUMENT sun_primitives, file
4073 sets FILE primitive data types to be native to Sun, HP, IBM, etc.
4074 */
4075 {
4076 set_primitives, file, __sun;
4077 }
4078
sun3_primitives(file)4079 func sun3_primitives(file)
4080 /* DOCUMENT sun3_primitives, file
4081 sets FILE primitive data types to be native to Sun-2 or Sun-3.
4082 */
4083 {
4084 set_primitives, file, __sun3;
4085 }
4086
dec_primitives(file)4087 func dec_primitives(file)
4088 /* DOCUMENT dec_primitives, file
4089 sets FILE primitive data types to be native to DEC (MIPS) workstations.
4090 */
4091 {
4092 set_primitives, file, __dec;
4093 }
4094
alpha_primitives(file)4095 func alpha_primitives(file)
4096 /* DOCUMENT alpha_primitives, file
4097 sets FILE primitive data types to be native to DEC alpha workstations.
4098 */
4099 {
4100 set_primitives, file, __alpha;
4101 }
4102
sgi64_primitives(file)4103 func sgi64_primitives(file)
4104 /* DOCUMENT sgi64_primitives, file
4105 sets FILE primitive data types to be native to 64-bit SGI workstations.
4106 */
4107 {
4108 set_primitives, file, __sgi64;
4109 }
4110
cray_primitives(file)4111 func cray_primitives(file)
4112 /* DOCUMENT cray_primitives, file
4113 sets FILE primitive data types to be native to Cray 1, XMP, and YMP.
4114 */
4115 {
4116 set_primitives, file, __cray;
4117 }
4118
mac_primitives(file)4119 func mac_primitives(file)
4120 /* DOCUMENT mac_primitives, file
4121 sets FILE primitive data types to be native to MacIntosh, 8 byte double.
4122 */
4123 {
4124 set_primitives, file, __mac;
4125 }
4126
macl_primitives(file)4127 func macl_primitives(file)
4128 /* DOCUMENT macl_primitives, file
4129 sets FILE primitive data types to be native to MacIntosh, long double.
4130 */
4131 {
4132 set_primitives, file, __macl;
4133 }
4134
i86_primitives(file)4135 func i86_primitives(file)
4136 /* DOCUMENT i86_primitives, file
4137 sets FILE primitive data types to be native to Linux i86 machines.
4138 */
4139 {
4140 set_primitives, file, __i86;
4141 }
4142
pc_primitives(file)4143 func pc_primitives(file)
4144 /* DOCUMENT pc_primitives, file
4145 sets FILE primitive data types to be native to IBM PC.
4146 */
4147 {
4148 set_primitives, file, __ibmpc;
4149 }
4150
vax_primitives(file)4151 func vax_primitives(file)
4152 /* DOCUMENT vax_primitives, file
4153 sets FILE primitive data types to be native to VAXen, H-double, only.
4154 */
4155 {
4156 set_primitives, file, __vax;
4157 }
4158
vaxg_primitives(file)4159 func vaxg_primitives(file)
4160 /* DOCUMENT vaxg_primitives, file
4161 sets FILE primitive data types to be native to VAXen, G-double, only.
4162 */
4163 {
4164 set_primitives, file, __vaxg;
4165 }
4166
xdr_primitives(file)4167 func xdr_primitives(file)
4168 /* DOCUMENT xdr_primitives, file
4169 sets FILE primitive data types to be XDR (external data representation).
4170 */
4171 {
4172 set_primitives, file, __xdr;
4173 }
4174
4175 extern get_primitives;
4176 /* DOCUMENT prims = get_primitives(file)
4177 Return the primitive data types for FILE as an array of 32
4178 integers. The format is described under set_primitives.
4179 SEE ALSO: set_primitives, __xdr, __i86
4180 */
4181
set_primitives(file,p)4182 func set_primitives(file, p)
4183 /* DOCUMENT set_primitives, file, prims
4184 Return the primitive data types for FILE as an array of 32
4185 integers. Versions for particular machines are defined in
4186 prmtyp.i, and can be accessed using functions like
4187 sun_primitives or i86_primitives. See __xdr for a complete
4188 list. The format is:
4189 [size, align, order] repeated 6 times for char, short, int,
4190 long, float, and double, except that char align is always 1,
4191 so result(2) is the structure alignment (see struct_align).
4192 [sign_address, exponent_address, exponent_bits,
4193 mantissa_address, mantissa_bits,
4194 mantissa_normalization, exponent_bias] repeated twice for
4195 float and double. See the comment at the top of prmtyp.i
4196 for an explanation of these fields.
4197 the total number of items is thus 3*6+7*2=32.
4198 SEE ALSO: get_primitives, createb, __xdr, __i86
4199 */
4200 {
4201 install_struct, file, "char", 1, 1, p(3);
4202 install_struct, file, "short", p(4),p(5),p(6);
4203 install_struct, file, "int", p(7),p(8),p(9);
4204 install_struct, file, "long", p(10),p(11),p(12);
4205 install_struct, file, "float", p(13),p(14),p(15), p(19:25);
4206 install_struct, file, "double", p(16),p(17),p(18), p(26:32);
4207 struct_align, file, p(2);
4208 }
4209
4210 local __xdr;
4211 local __vaxg;
4212 local __vax;
4213 local __ibmpc;
4214 local __i86;
4215 local __macl;
4216 local __mac;
4217 local __cray;
4218 local __sgi64;
4219 local __alpha;
4220 local __dec;
4221 local __sun;
4222 local __sun3;
4223 /* DOCUMENT primitive data types for various machines:
4224 little-endians
4225 __i86 Intel x86 Linux
4226 __ibmpc IBM PC (2 byte int)
4227 __alpha Compaq alpha
4228 __dec DEC workstation (MIPS), Intel x86 Windows
4229 __vax DEC VAX (H-double)
4230 __vaxg DEC VAX (G-double)
4231 big-endians
4232 __xdr External Data Representation
4233 __sun Sun, HP, SGI, IBM-RS6000, MIPS 32 bit
4234 __sun3 Sun-2 or Sun-3 (old)
4235 __sgi64 SGI, Sun, HP, IBM-RS6000 64 bit
4236 __mac MacIntosh 68000 (power Mac, Gx are __sun)
4237 __macl MacIntosh 68000 (12 byte double)
4238 __cray Cray XMP, YMP
4239 SEE ALSO: set_primitives
4240 */
4241 __xdr = __i86 =
4242 /* sizeof, alignment, order
4243 * char short int long float double */
4244 [ 1, 1, 1, 2, 2, 1, 4, 4, 1, 4, 4, 1, 4, 4, 1, 8, 4, 1,
4245 /* sign addr, exp addr, exp len, man addr, man len, man norm, exp bias
4246 * float double */
4247 0, 1,8, 9,23, 0, 0x7f, 0, 1,11, 12,52, 0, 0x3ff];
4248 __i86(3:18:3) = -1;
4249 __ibmpc = __alpha = __dec = __i86;
4250 __ibmpc([7,8,11,14,17]) = 2;
4251 __alpha([10,11,17]) = 8;
4252 __dec(17) = 8;
4253 __sun = __sun3 = __sgi64 = __mac = __xdr;
4254 __sun(17) = 8;
4255 __sun3(5:17:3) = 2;
4256 __sgi64([10,11,17]) = 8;
4257 __mac([7,8,11,14,17]) = 2;
4258 __macl = __mac;
4259 __macl(16) = 12;
4260 __macl(26:32) = [0, 1,15, 32,64, 1, 0x3ffe];
4261 __cray =
4262 [ 1, 1, 1, 8, 8, 1, 8, 8, 1, 8, 8, 1, 8, 8, 1, 8, 8, 1,
4263 0, 1,15, 16,48, 1, 0x4000, 0, 1,15, 16,48, 1, 0x4000];
4264 __vax = __vaxg =
4265 [ 1, 1, -1, 2, 1, -1, 4, 1, -1, 4, 1, -1, 4, 1, 2, 8, 1, 2,
4266 0, 1,8, 9,23, 0, 0x81, 0, 1,8, 9,55, 0, 0x81];
4267 __vaxg(26:32) = [0, 1,11, 12,52, 0, 0x401];
4268
4269 func updateb(filename, primitives, close102=, open102=, clog=)
4270 /* DOCUMENT file= updateb(filename)
4271 or file= updateb(filename, primitives)
4272 open a binary data file FILENAME for update (mode "r+b").
4273 The optional PRIMITIVES argument is as for the createb function.
4274 If the file exists, it is opened as if by openb(filename),
4275 otherwise a new PDB file is created as if by createb(filename).
4276 SEE ALSO: openb, createb, cd, save, restore, get_vars, get_addrs
4277 close102, close102_default, open102, at_pdb_open, at_pdb_close
4278 */
4279 {
4280 if (is_void(open(filename, "r", 1))) /* "rb" does much more work */
4281 return createb(filename, primitives, close102=close102, clog=clog);
4282 else
4283 return openb(filename,,(clog?"r+bc":"r+b"), open102=open102);
4284 }
4285 errs2caller, updateb;
4286
4287 extern save;
4288 extern restore;
4289 /* DOCUMENT save, obj, var1, var2, ...
4290 restore, obj, var1, var2, ...
4291 grp = save(var1, var2, ...)
4292 grp = restore(var1, var2, ...)
4293 saves the variables VAR1, VAR2, etc. in the object OBJ, or restores
4294 them from that object. An object can be a binary file handle, in which
4295 case there may be restrictions on the type of the VARi; in particular,
4296 the VARi will need to be arrays or structure definitions. In general,
4297 the kind of object OBJ determines what kinds of variables can be
4298 saved in it.
4299
4300 Called as functions, save and restore return a grp object, a very
4301 light weight in-memory container that can hold any kind of yorick
4302 variable. In the case of save, the grp contains the the specified
4303 variables VARi. For group objects (not necessarily other objects),
4304 the saved items are not copies, but references. However, if you
4305 redefine a VARi after a save to a group object, the group member
4306 corresponding to that VARi does not change. Hence, groups are a
4307 way to maintain "namespaces" in yorick. The return value from
4308 save is simply a group object containing the VARi. The return
4309 value from restore is more interesting: it is a group object containing
4310 the values of the VARi before they were restored. This enables you to
4311 put things back the way they were before a restore, after you are
4312 finished using the restored variables.
4313
4314 Special cases of save:
4315 grp = save(); // return an empty group object
4316 obj = save(*); // return the entire global symbol table as an object
4317 save, obj; // saves entire global symbol table in OBJ, silently
4318 skipping any variables whose data type OBJ does not support
4319 Other special cases:
4320 restore, obj; // restores all named variables in OBJ
4321 save, use, var1, var2, ...;
4322 restore, use, var1, var2, ...;
4323 save and restore to the current context object (see help,use).
4324 Normally you should use the use function, not these special forms.
4325
4326 Each VARi may be a simple variable reference, in which case the name
4327 of the VARi specifies which member of the object. (In the case of
4328 save, a VARi whose name matches no current object member will create
4329 a new object member of that name.) However, any of the VARi may
4330 instead be be a pair of arguments instead of a single argument:
4331 VARi --> MEMBSPECi, VALi
4332 where MEMBSPECi is an expression (but NOT a simple variable reference)
4333 whose value specifies which object member, and the VALi argument is
4334 the external value. In the case of save, VALi may also be an
4335 expression; in the case of restore, VALi must be the simple variable
4336 reference for the variable which restore will set to the specified
4337 object member. For example:
4338 var2 = 3*x+7;
4339 save, obj, var1, var2, var3;
4340 save, obj, var1, "var2", 3*x+7, var3;
4341 save, obj, var1, swrite(format="var%ld",8/4), 3*x+7, var3;
4342 All three save calls do the same thing. The corresponding restore
4343 works by name; the order need not be the same as the save:
4344 restore, obj, var2, var3, var1;
4345 puts the saved values back where they started, while:
4346 restore, obj, var2, swrite(format="var%ld",1), x;
4347 puts var2 back to its saved value, but sets x to the value saved
4348 as var1. You can use the noop() function to make an expression out
4349 of a variable holding a MEMBSPEC. For example, if varname="var1", then
4350 restore, obj, noop(varname), x; // or
4351 restore, obj, varname+"", x;
4352 will set x to the value saved as var1, while
4353 restore, obj, varname, x; // error!
4354 attempts to restore two variables named "varname" and "x" from obj.
4355
4356 For the save function, each VARi may also be a keyword argument:
4357 VARi --> member=VALi
4358 which behaves exactly the same as:
4359 VARi --> "member",VALi
4360 but is slightly more efficient, since it avoids the string argument.
4361 You can also omit the "save" in a subroutine call if all arguments
4362 are keywords:
4363 save, obj, m1=val1, m2=val2, ...;
4364 is the same thing as:
4365 obj, m1=val1, m2=val2, ...;
4366
4367 Some kinds of objects (including the group objects, but usually not
4368 binary file handles) support anonymous members. For such objects,
4369 the order in which the members were saved is significant, and member
4370 names are optional. You can create anonymous members by passing
4371 string(0) to save as the MEMBSPEC. Unlike ordinary names, each save
4372 with string(0) as the name creates a new member (rather than overwriting
4373 the existing member with that name). All members (named as well as
4374 anonymous) are numbered starting from 1 for the first member, in the
4375 order in which they are created. For objects supporting anonymous
4376 members, MEMBSPEC may also be an integer, which is the member index.
4377
4378 In fact, MEMBSPECi can be any of the following:
4379 scalar string - member name, string(0) on save creates anonymous member
4380 scalar index - member index
4381 string array - VALi a group with those members (string(0) on save OK)
4382 index array - VALi a group with those members
4383 min:max:step - VALi a group with those members
4384 nil [] - save only: if VALi is not an object, same as string(0),
4385 if VALi is an object, merge with OBJ, that is members of VALi become
4386 members of OBJ, creating or overwriting named members and always
4387 appending anonymous members.
4388 MEMBSPEC indices and index ranges accept zero or negative values with
4389 the same meaning as for array indices, namely 0 represents the last
4390 member, -1 the second to the last, and so on. Unlike array indices,
4391 the non-positive index values also work in index array MEMBSPECs.
4392
4393 See help,oxy (object extension to yorick) for more on objects.
4394
4395 As a final remark, notice that you can use save and restore to
4396 construct group objects without having any side effects -- that is,
4397 without "damaging" the state of any other variables. For example,
4398 suppose we want to create an object bump consisting of three
4399 variables x, y, and z, that need to be computed. In order to do
4400 that without clobbering existing values of x, y, and z, or anything
4401 else, we can do this:
4402 bump = save(x, y, z); // save current values of x, y, z
4403 scratch = save(scratch, xy); // save scratch variables (xy and scratch)
4404 xy = span(-4, 4, 250);
4405 x = xy(,-:1:250);
4406 y = xy(-:1:250,);
4407 z = sqrt(0.5/pi)*exp(-0.5*abs(x,y)^2);
4408 bump = restore(bump); // put back old x,y,z, set bump to new
4409 restore, scratch; // restore xy and scratch itself
4410
4411 SEE ALSO: oxy, is_obj, openb, createb, use, noop, gaccess
4412 */
4413
jt(file,time)4414 func jt(file, time)
4415 /* DOCUMENT jt, time
4416 or jt, file, time
4417 or jt, file
4418 or jt, file, -
4419 jump to the record nearest the specified TIME. If no FILE is
4420 specified, the current record of all open binary files containing
4421 records is shifted.
4422 If both FILE and TIME are specified and jt is called as a function,
4423 it returns the actual time of the new current record.
4424
4425 N.B.: "jt, file" and "jt, file, -" are obsolete. Use the jr function to
4426 step through a file one record at a time.
4427
4428 If only the FILE is specified, increment the current record of that
4429 FILE by one. If the TIME argument is - (the pseudo-index range
4430 function), decrement the current record of FILE by one.
4431 If the current record is the last, "jt, file" unsets the current record
4432 so that record variables will be inaccessible until another jt or jc.
4433 The same thing happens with "jt, file, -" if the current record was the
4434 first.
4435 If only FILE is specified, jt returns 1 if there is a new current
4436 record, 0 if the call resulted in no current record. Thus "jt(file)"
4437 and "jt(file,-)" may be used as the condition in a while loop to step
4438 through every record in a file:
4439 file= openb("example.pdb");
4440 do {
4441 restore, file, interesting_record_variables;
4442 ...calculations...
4443 } while (jt(file));
4444
4445 SEE ALSO: jc, _jt, edit_times, show, jr
4446 */
4447 {
4448 return is_void(time)? _jt(file) : _jt(file, time);
4449 }
4450
jc(file,ncyc)4451 func jc(file, ncyc)
4452 /* DOCUMENT jc, file, ncyc
4453 jump to the record of FILE nearest the specified NCYC.
4454 SEE ALSO: jt, _jc, edit_times, show, jr
4455 */
4456 {
4457 return _jc(file, ncyc);
4458 }
4459
4460 extern _jr;
4461 extern _jt;
4462 extern _jc;
4463 /* DOCUMENT _jt, file, time
4464 _jc, file, ncyc
4465 _jr, file
4466 are raw versions of jt and jc provided to simplify redefining
4467 the default jt and jc functions to add additional features.
4468 For example, you could redefine jt to jump to a time, then
4469 plot something. The new jt can pass its arguments along to
4470 _jt, then call the appropriate plotting functions.
4471 There is a raw version of jr as well.
4472 */
4473
jr(file,i)4474 func jr(file, i)
4475 /* DOCUMENT jr, file, i
4476 or _jr(file, i)
4477 Jump to a particular record number I (from 1 to n_records) in a
4478 binary file FILE. The function returns 1 if such a record exists,
4479 0 if there is no such record. In the latter case, no action is
4480 taken; the program halts with an error only if jr was invoked
4481 as a subroutine. Record numbering wraps like array indices; use
4482 jr, file, 0 to jump to the last record, -1 to next to last, etc.
4483 SEE ALSO: jt, jc, edit_times, show
4484 */
4485 {
4486 return _jr(file, i);
4487 }
4488
4489 extern add_record;
4490 /* DOCUMENT add_record, file, time, ncyc
4491 or add_record, file, time, ncyc, address
4492 or add_record, file
4493 adds a new record to FILE corresponding to the specified TIME and
4494 NCYC (respectively a double and a long). Either or both TIME
4495 and NCYC may be nil or omitted, but the existence of TIME and
4496 NCYC must be the same for every record added to one FILE.
4497 If present, ADDRESS specifies the disk address of the new record,
4498 which is assumed to be in the current file. Without ADDRESS, or
4499 if ADDRESS<0, the next available address is used; this may create
4500 a new file in the family (see the set_filesize function).
4501 The add_record function leaves the new record current
4502 for subsequent save commands to actually write the data.
4503
4504 The TIME, NCYC, and ADDRESS arguments may be equal length vectors
4505 to add several records at once; in this case, the first of the
4506 newly added records is the current one. If all three of TIME,
4507 NCYC, and ADDRESS are nil or omitted, no new records are added,
4508 but the file becomes a record file if it was not already, and in
4509 any case, no record will be the current record after such an
4510 add_record call.
4511
4512 After the first add_record call (even if no records were added),
4513 subsequent add_variable commands will create record variables.
4514 After the first record has been added, subsequent save commands
4515 will create any new variables as record variables.
4516 After a second record has been added using add_record, neither
4517 save commands nor add_variable commands may be used to introduce
4518 any new record variables.
4519 SEE ALSO: save, createb, updateb, openb, set_filesize, set_blocksize
4520 add_variable
4521 */
4522
4523 extern add_variable;
4524 /* DOCUMENT add_variable, file, address, name, type, dimlist
4525 adds a variable NAME to FILE at the specified ADDRESS, with the
4526 specified TYPE and dimensions given by DIMLIST. The DIMLIST may
4527 be zero or more arguments, as for the "array" function. If the
4528 ADDRESS is <0, the next available address is used. Note that,
4529 unlike the save command, add_variable does not actually write any
4530 data -- it merely changes Yorick's description of the contents of
4531 FILE.
4532 After the first add_record call, add_variable adds a variable to
4533 the record instead of a non-record variable. See add_record.
4534 SEE ALSO: save, openb, createb, updateb, add_record,
4535 add_member, install_struct, data_align
4536 */
4537
4538 extern set_blocksize;
4539 /* DOCUMENT set_blocksize, file, blocksize
4540 or set_blocksize, blocksize
4541 sets smallest cache block size for FILE to BLOCKSIZE. BLOCKSIZE
4542 is rounded to the next larger number of the form 4096*2^n if
4543 necessary; cache blocks for this file will be multiples of
4544 BLOCKSIZE bytes long. The default BLOCKSIZE is 0x4000 (16 KB)
4545 initially. The second form, with no FILE argument, sets the
4546 default BLOCKSIZE.
4547 SEE ALSO: openb, updateb, createb, save, restore, _read, _write,
4548 set_cachesize
4549 */
4550
4551 extern set_cachesize;
4552 /* DOCUMENT set_cachesize, maxBlockSize, totalCacheSize
4553 Sets largest cache block size to MAXBLOCKSIZE. MAXBLOCKSIZE
4554 is rounded to the next larger number of the form 4096*2^n if
4555 necessary.
4556 Sets the total cache size to TOTALCACHESIZE. TOTALCACHESIZE
4557 will be set to 4*MAXBLOCKSIZE if it is smaller than that.
4558 The default MAXBLOCKSIZE is 0x080000 (512k) and the default
4559 TOTALCACHESIZE is 0x140000 (1.25 Mbytes).
4560 SEE ALSO: set_blocksize, openb, updateb, createb
4561 */
4562
4563 extern set_filesize;
4564 /* DOCUMENT set_filesize, file, filesize
4565 sets the new family member threshhold for FILE to FILESIZE.
4566 Whenever a new record is added (see add_record), if the current file
4567 in the FILE family has at least one record and the new record would
4568 cause the current file to exceed FILESIZE bytes, a new family
4569 member will be created to hold the new record.
4570 Note that set_filesize must be called after the first call to
4571 add_record.
4572 The default FILESIZE is 0x800000 (8 MB).
4573 SEE ALSO: openb, updateb, createb, add_record
4574 */
4575
4576 extern get_vars;
4577 /* DOCUMENT name_lists= get_vars(file)
4578 returns the lists of non-record and record variable names in the
4579 binary FILE. The return value is an array of two pointers to
4580 arrays of type string; *name_lists(1) is the array of non-record
4581 variable names (or nil if there are none), *name_lists(2) is the
4582 array of record variable names.
4583 The get_addrs function returns corresponding lists of disk
4584 addresses; the get_member function can be used in conjunction
4585 with the dimsof, structof, and typeof functions to determine
4586 the other properties of a variable.
4587 SEE ALSO: openb, updateb, restore, jt, jc, has_records, get_addrs,
4588 set_vars
4589 */
4590
4591 extern set_vars;
4592 /* DOCUMENT set_vars, file, names
4593 or set_vars, file, nonrec_names, rec_names
4594 Change the names of the variables in FILE to NAMES. If the
4595 file has record variables, you can use the second form to change
4596 the record variable names. Either of the two lists may be nil
4597 to leave those names unchanged, but if either is not nil, it must
4598 be a 1D array of strings whose length exactly matches the number
4599 of that type of variable actually present in the file.
4600 SEE ALSO: openb, updateb, has_records, get_vars
4601 */
4602
4603 extern get_addrs;
4604 /* DOCUMENT addr_lists= get_addrs(file)
4605 returns the byte addresses of the non-record and record variables
4606 in the binary file FILE, and lists of the record addresses, file
4607 indices, and filenames for file families with history records.
4608 *addr_lists(1) absolute addresses of non-record variables
4609 *addr_lists(2) relative addresses of record variables
4610 (add record address to get absolute address)
4611 The order of these two address lists matches the
4612 corresponding lists of names returned by get_vars.
4613 *addr_lists(3) absolute addresses of records
4614 *addr_lists(4) list of file indices corresponding to
4615 addr_lists(3); indices are into addr_lists(5)
4616 *addr_lists(5) list of filenames in the family
4617 SEE ALSO: openb, updateb, restore, jt, jc, has_records, get_vars
4618 */
4619
has_records(file)4620 func has_records(file)
4621 /* DOCUMENT has_records(file)
4622 returns 1 if FILE has history records, 0 if it does not.
4623 */
4624 {
4625 return get_vars(file)(2)? 1n : 0n;
4626 }
4627
4628 extern get_times;
4629 extern get_ncycs;
4630 /* DOCUMENT times= get_times(file)
4631 ncycs= get_ncycs(file)
4632 returns the list of time or ncyc values associated with the records
4633 if FILE, or nil if there are none. The time values are not guaranteed
4634 to be precise (but they should be good to at least 6 digits or so);
4635 the precise time associated with each record may be stored as a record
4636 variable.
4637 SEE ALSO: collect, openb, updateb, restore, jt, jc, edit_times
4638 */
4639
4640 extern edit_times;
4641 /* DOCUMENT edit_times, file
4642 or edit_times, file, keep_list
4643 or edit_times, file, keep_list, new_times, new_ncycs
4644 edits the records for FILE. The KEEP_LIST is a 0-origin index list
4645 of records to be kept, or nil to keep all records. The NEW_TIMES
4646 array is the list of new time values for the (kept) records, and
4647 the NEW_NCYCS array is the list of new cycle number values for the
4648 (kept) records. Either NEW_TIMES, or NEW_NCYCS, or both, may be
4649 nil to leave the corresponding values unchanged. If non-nil,
4650 NEW_TIMES and NEW_NCYCS must have the same length as KEEP_LIST,
4651 or, if KEEP_LIST is nil, as the original number of records in
4652 the file. If KEEP_LIST, NEW_TIME, and NEW_NCYCS are all omitted
4653 or nil, then edit_times removes records as necessary to ensure
4654 that the remaining records have monotonically increasing times,
4655 or, if no times are present, monotonically increasing ncycs.
4656 (The latest record at any given time/ncyc is retained, and earlier
4657 records are removed.)
4658 In no case does edit_times change the FILE itself; only Yorick's
4659 in-memory model of the file is altered.
4660 SEE ALSO: get_times, get_ncycs, jt, jc
4661 */
4662
4663 extern _read;
4664 extern _write;
4665 /* DOCUMENT _write, file, address, expression
4666 _read, file, address, variable
4667 or nbytes= _read(file, address, variable);
4668 are low level read and write functions which do not "see" the
4669 symbol table for the binary FILE. The ADDRESS is the byte address
4670 at which to begin the write or read operation. The type and number
4671 of objects of the EXPRESSION or VARIABLE determines how much data
4672 to read, and what format conversion operations to apply. In the
4673 case of type char, no conversion operations are ever applied, and
4674 _read will return the actual number of bytes read, which may be
4675 fewer than the number implied by VARIABLE in this one case.
4676 (In all other cases, _read returns numberof(VARIABLE).)
4677 If the FILE has records, the ADDRESS is understood to be in the
4678 file family member in which the current record resides.
4679 SEE ALSO: openb, createb, updateb, save, restore, sizeof
4680 */
4681
4682 extern fd_read;
4683 extern fd_write;
4684 extern fd_close;
4685 /* DOCUMENT fd_read, fd, variable
4686 fd_write, fd, expression
4687 fd_close, fd
4688 read or write array data (pointer, string, or struct instance not
4689 allowed) directly to fiel descriptor FD. With fd_close, you may
4690 close a file descriptor. There is no way to open a file descriptor;
4691 it must have been opened by yorick's parent process. These are
4692 intended for communicating binary data with the parent process,
4693 which must somehow arrange for yorick to know the values of FD.
4694 Yorick limits the number of open descriptors to 16 (although FD may
4695 have any value permitted by the system).
4696
4697 SEE ALSO: open, socket
4698 */
4699
4700 extern socket;
4701 extern socksend;
4702 extern sockrecv;
4703 /* DOCUMENT listener = socket(port) or socket(port, callback)
4704 * sock = socket(addr, port) or socket(addr, port, callback)
4705 * sock = listener() or listener(callback)
4706 * nbytes = socksend(sock, data)
4707 * nbytes = sockrecv(sock, data)
4708 * close, listener
4709 * close, sock
4710 * listener.port
4711 * sock.peer
4712 * callback, listener;
4713 * - callback must call listener()
4714 * callback, sock;
4715 * - callback must call sockrecv(sock, data)
4716 *
4717 * Create IP socket objects, which can be used to connect to other
4718 * processes. The final data transfer socket, sock, is a two-way pipe
4719 * for sending messages between the two processes. In order to make the
4720 * connection, one of the two processes must act as a server, which
4721 * listens for the second process to attempt to connect to it. The
4722 * listener itself is a special socket, which listens for connections
4723 * on a specific port, which can be any number less than 2^16 (65536).
4724 * Port numbers below 1024 are reserved for registered system services,
4725 * such as port 80, which is used for http connections, or port 22,
4726 * which is for ssh connections.
4727 *
4728 * While socket(port) creates a listener for a specific port, you are
4729 * only guaranteed not to collide with another program if you omit the
4730 * port, socket(), or pass port 0, socket(0), which means that you want
4731 * the operating system to choose an unused port number for you. After
4732 * socket(0) returns the listener, you can find the actual port number
4733 * which the system chose with listener.port.
4734 *
4735 * The second process must actively seek the connection, so it needs
4736 * to pass both the machine address addr (like "www.example.com") of
4737 * the listening process, as well as the port number on which it is
4738 * listening. Usually, the connecting process will be running on the
4739 * same machine as the listening process (your firewall should probably
4740 * block inter-machine traffic on a random port number). To connect on
4741 * to a listener on the same machine, pass the pseudo-index - as the addr,
4742 * socket(-, port).
4743 *
4744 * You call the listener object as a function listener() in order to
4745 * wait for a connection request. When the connection request arrives,
4746 * listener() returns a data transfer socket, sock, which will be
4747 * connected with the data transfer socket on the requestor's end.
4748 * The system puts this socket on a different port from the listener,
4749 * which can continue to listen for connections from other processes.
4750 * If you don't want to accept any more connections, you can close the
4751 * listener immediately after it returns sock. You can find out the
4752 * machine address where the accepted connection originated with
4753 * sock.peer.
4754 *
4755 * Once you have a data transfer socket, either from a listener accepting
4756 * a connection, or from having requested a conection yourself, the two
4757 * ends of the socket are completely symmetric. You send and receive
4758 * data with:
4759 * socksend, sock, data;
4760 * sockrecv, sock, data;
4761 * The data can be any numeric array -- but not strings (use strchar),
4762 * strct instances, pointers, or any other datatype. You must arrange
4763 * a protocol so that you know the exact type and number of items
4764 * being sent in each message. Currently, yorick makes no attempt to
4765 * switch byte order or make any other allowance for the possibility
4766 * that the binary formats might be different between the two ends of
4767 * the socket. Both send and recv block until the requested number
4768 * of bytes has been sent or received, raising an error if a
4769 * complete transfer does not occur. If you do not want an error,
4770 * you may invoke either socksend or sockrecv as a function, which will
4771 * return the number of bytes sent or received, normally sizeof(data),
4772 * or -1 on error. If the other side of the socket closes before
4773 * a sockrecv is complete, it may return 0<=nbytes<sizeof(data), but
4774 * socksend always returns either -1 or sizeof(nbytes).
4775 *
4776 * The listener() and sock.recv() calls block. If you want to use them
4777 * in an event-driven program which handles other events while waiting,
4778 * you can create the listener or sock with a callback, which can be either
4779 * a function or a closure, and will be called as noted when input is
4780 * ready (or a connection request has been received). If the callback
4781 * function fails to accept the connection or receive the data, it will
4782 * immediately be called again -- do not put more than the bare minimum
4783 * of code in such a callback; it can easily go into an infinite loop.
4784 * Closing the socket is the only way to break out of such a loop.
4785 *
4786 * Destroying the last reference to listener or sock frees it, but you
4787 * may explicitly a socket with the close function.
4788 *
4789 * SEE ALSO: open, fd_read
4790 */
4791 func _socket_caller {
4792 c = _socket_callback; s = _socket_socket;
4793 _socket_callback = _socket_socket = [];
4794 c, s;
4795 }
4796
4797 extern add_member;
4798 /* DOCUMENT add_member, file, struct_name, offset, name, type, dimlist
4799 adds a member to a data type in the file FILE. The data type name
4800 (struct name) is STRUCT_NAME, which will be created if it does
4801 not already exist. The new member will be at OFFSET (in bytes)
4802 from the beginning of an instance of this structure, and will
4803 have the specified NAME, TYPE, and DIMLIST. Use OFFSET -1 to
4804 have add_member compute the next available offset in the structure.
4805 The TYPE can be either a structure definition, or a string naming
4806 a previously defined data type in FILE. The optional DIMLIST is
4807 as for the "array" function.
4808 The STRUCT_NAME built from a series of add_member calls cannot be
4809 used until it is installed with install_struct.
4810 This function should be used very sparingly, mostly in code which
4811 is building the structure of a foreign-format binary file.
4812 SEE ALSO: add_variable, install_struct, struct_align
4813 */
4814
4815 extern install_struct;
4816 /* DOCUMENT install_struct, file, struct_name
4817 or install_struct, file, struct_name, size, align, order
4818 or install_struct, file, struct_name, size, align, order, layout
4819 installs the data type named STRUCT_NAME in the binary FILE. In
4820 the two argument form, STRUCT_NAME must have been built by one or
4821 more calls to the add_member function. In the 5 and 6 argument calls,
4822 STRUCT_NAME is a primitive data type -- an integer type for the 5
4823 argument call, and a floating point type for the 6 argument call.
4824 The 5 argument form may also be used to declare opaque data types.
4825 SIZE is the size of an instance in bytes, ALIGN is its alignment
4826 boundary (also in bytes), and ORDER is the byte order. ORDER is
4827 1 for most significant byte first, -1 for least significant byte
4828 first, and 0 for opaque (unconverted) data. Other ORDER values
4829 represent more complex byte permutations (2 is the byte order for
4830 VAX floating point numbers). If ORDER equals SIZE, then the data
4831 type is not only opaque, but also must be read sequentially.
4832 LAYOUT is an array of 7 long values parameterizing the floating
4833 point format, [sign_address, exponent_address, exponent_size,
4834 mantissa_address, mantissa_size, mantissa_normalized, exponent_bias]
4835 (the addresses and sizes are in bits, reduced to MSB first order).
4836 Use, e.g., nameof(float) for STRUCT_NAME to redefine the meaning
4837 of the float data type for FILE.
4838 SEE ALSO: add_variable, add_member
4839 */
4840
4841 extern data_align;
4842 /* DOCUMENT data_align, file, alignment
4843 in binary file FILE, align new variables to begin at a byte address
4844 which is a multiple of ALIGNMENT. (This affects placement of data
4845 declared using save and add_variable. For add_variable, data_align
4846 has an effect only if the address is not specified.) If ALIGNMENT
4847 is <=0, new variables will be aligned as they would be if they were
4848 data structure members. The default value is 0.
4849 SEE ALSO: save, add_variable
4850 */
4851
4852 extern struct_align;
4853 /* DOCUMENT struct_align, file, alignment
4854 in binary file FILE, align new struct members which are themselves
4855 struct instances to begin at a byte address which is a multiple of
4856 ALIGNMENT. (This affects members declared explicitly by add_member,
4857 as well as implicitly by save or add_variable.) If ALIGNMENT is <=0,
4858 returns to the default for this machine. The struct alignment is in
4859 addition to the alignment implied by the most restrictively aligned
4860 member of the struct. Most machines want ALIGNMENT of 1.
4861 SEE ALSO: add_member
4862 */
4863
4864 extern add_next_file;
4865 /* DOCUMENT failure= add_next_file(file, filename, create_flag)
4866 adds the next file to the FILE, which must contain history records.
4867 If FILENAME is non-nil, the new file will be called that, otherwise
4868 the next sequential filename is used. If CREATE_FLAG is present
4869 and non-zero, the new file will be created if it does not already
4870 exist. If omitted or nil, CREATE_FLAG defaults to 1 if the file has
4871 write permission and 0 if it does not.
4872 Returns 0 on success.
4873 SEE ALSO: openb, updateb, createb, add_record
4874 */
4875
4876 /*= SECTION(oxy) object oriented extensions to yorick ======================*/
4877
4878 local oxy;
4879 /* DOCUMENT oxy
4880 Object extension to yorick. Various yorick packages may create
4881 "objects", which are collections of data and methods (functions)
4882 for operating on that data. Yorick objects are much more free-form
4883 than other object-oriented languages, in keeping with the fact that
4884 yorick has no declarative statements.
4885
4886 Yorick objects have zero or more members; members may be anonymous
4887 or named. For objects supporting anonymous members (an optional
4888 feature), all members whether anonymous or named can be accessed
4889 by a 1-origin index, as if the members were a 1D array. Object
4890 indexing has unusual semantics, similar to the semantics of the
4891 arguments to the save and restore commands, in which it is the
4892 name of the variable passed as an argument to the object, rather
4893 than the value of the variable, which determines which member is
4894 to be extracted. For example,
4895 obj(i)
4896 refers to the member of obj named "i", whether the value of i is
4897 1 or 100 or "j" or sqrt(3)+2i or span(0,1,200). However, by passing
4898 an expression, rather than a simple variable reference, you can
4899 make the value of the argument (now that it has no name) be significant.
4900 Hence, obj("i") is also member "i", while obj(7) is the 7th member,
4901 obj(3*n+2) is the 3*n+2nd member, and so on. You can use the noop()
4902 function to make a variable into an expression, if the member specifier
4903 happens to be stored in a variable:
4904 obj(noop(membspec))
4905
4906 Objects also accept some special arguments:
4907 obj() returns the whole object (same as without the parens)
4908 obj(*) returns the number of members
4909 obj(*,) returns an array of member names (string(0) for anonymous)
4910 in the index order (if the object supports indexing)
4911 obj(*,m) returns an array of the specified member names, or the
4912 specified member indices if M is a string array
4913 (if the object supports indexing)
4914 obj(..) returns the attribute object associated with obj, which
4915 may be an empty object, or nil [] if obj does not support
4916 attributes
4917
4918 When called as a subroutine, objects accept keyword arguments as a
4919 shorthand for the save command:
4920 obj, m1=val1, m2=val2, ...;
4921 is the same as:
4922 save, obj, m1=val1, m2=val2, ...;
4923
4924 Yorick has a generic object, called a "group", which holds an arbitrary
4925 collection of yorick variables. You make group objects with the save
4926 function (see help,save), and you can also use save to add members to
4927 an existing group object. Another way to create a group object is by
4928 passing a membspec argument to any group which specifies multiple
4929 members -- the result will be a group containing all the specified
4930 members. Hence, membspec may be an array of strings, an array of
4931 indices, or an index range min:max:step, in order to produce a group
4932 object holding all the specified members. (Note that dimensionality
4933 of membspec arrays is lost, and potentially not even number is
4934 preserved if a single named member is specified multiple times.)
4935
4936 When you pass more than one argument to an object, the first one
4937 specifies a single member, and subsequent arguments apply to that
4938 member. Thus,
4939 obj(m, i, j, k) is similar to obj(m)(i, j, k)
4940 In fact, these are exactly the same as long as M does not specify
4941 a function. When M is a function, there is a slight difference,
4942 which is that the function (whether built-in or interpreted) is
4943 executed in the context of the object obj. Unlike classic object
4944 oriented languages, in yorick the use of the context object is not
4945 automatic -- the function M must specify which object members it
4946 wishes to access. You do that with the use function:
4947 func method(x, y, z) {
4948 extern var1, var2, var3;
4949 use, var1, var2, var3; // initializes vari from context object
4950 // compute using var1, var2, var3, possibly redefining them
4951 return result;
4952 // just before return, any
4953 // changes to var1, var2, var3 stored back to context object
4954 // if this function was called by another method by the
4955 // use_method function, the store back to the context object
4956 // is deferred until the outermost method returns
4957 }
4958 In this form, the arguments to the use call must be external variables
4959 to the function (method). If you put the use call(s) at the top of the
4960 function, you can dispense with the explicit extern statement, provided
4961 you are careful to check that none of the names matches any of the
4962 dummy parameter names (x, y, or z here). [Eventually, the yorick
4963 parser may treat use specially and enforce this restriction. For now,
4964 you need to be sure that any arguments are external to avoid incorrect
4965 behavior. Specifically, if any of the vari is local, the external
4966 variable of that name will be set to nil (or the actual argument value
4967 if vari is a dummy parameter) when the method returns. Ouch.]
4968 Although the vari look like they are extern to the method function,
4969 use saves their external values and arranges to replace them when the
4970 function returns, so they behave as if they were local to method.
4971
4972 Calling use() as a function, or using a special form of restore
4973 provides a means for direct read-only access to a member. For example,
4974 suppose you are going to modify var1 and var3, but merely read var2
4975 and var4 in the method context:
4976 func method(x, y, z) {
4977 use, var1, var3; // initializes vari from context object
4978 local var2, var4; // otherwise, restore arguments would be extern
4979 restore, use, var2, var4;
4980 // compute using vari
4981 var1 = something(var2); var3 = something(var4);
4982 return result;
4983 }
4984 Or equivalently,
4985 func method(x, y, z) {
4986 use, var1, var3; // initializes vari from context object
4987 // compute using vari
4988 var1 = something(use(var2)); var3 = something(use(var4));
4989 return result;
4990 }
4991 As a function, use(arg1, arg2, ...) is exactly the same as
4992 obj(arg1, arg2, ...), where obj is the context object for the function.
4993 You have to be careful not to mix this form of read-only access with
4994 the read-write access of use called as a subroutine: If you have changed
4995 the value of a variable, use(var) will pick up the unchanged value
4996 still stored in the context object.
4997
4998 You can a invoke method function M as a subroutine as well:
4999 obj, m, i, j, k;
5000 Inside a method function, you can invoke other methods with the
5001 use_method function:
5002 use_method, sibling_method, arg1, arg2;
5003 or
5004 x = use_method(sibling_method, arg1, arg2);
5005 where sibling_method is another method in the same context as the
5006 caller. Called as a function, use_method is very nearly the same
5007 as use; you could write the second line as:
5008 x = use(sibling_method, arg1, arg2);
5009 (See help,use for an explanation of the differences.)
5010
5011 The obj(method,arglist) syntax permits the method argument to be
5012 an expression whose value is a function. This allows you to
5013 invoke functions which are not members of obj in the context of
5014 obj. This is useful in two situations: First, you can define
5015 "friend" functions in C++ parlance, which are not a part of the
5016 object, but nevertheless understand some part of its structure.
5017 Second, this is the only way you can call a function in a base
5018 class which you have shadowed by a virtual function in one of
5019 its derived classes. For example, suppose the base_interface
5020 object contains the method functions f1, f2, f3, etc., and is
5021 used to derive an object with
5022 obj = save(,base_interface, data1, data2);
5023 save, obj, f2;
5024 where f2 is a different function than the one in base_interface.
5025 Inside the function f2, you can call the one in base_interface
5026 like this:
5027 func f2(a, b) {
5028 use, data1, data2;
5029 x = use_method(base_interface(f2), a, b);
5030 return x + data1 + data2; // or any other expression
5031 }
5032
5033 This stripped down facility lets you do most of the things (except
5034 arguably type checking) other object oriented languages feature,
5035 although it is a little difficult to see how to do this at first.
5036 For example, you can think of a "class" as the constructor function
5037 which makes instances:
5038 func myclass(data1, data2, ...) {
5039 // build and return the class, for example:
5040 return save(method1, method2, ..., data1, data2, ...);
5041 }
5042 func method1(x) { return something; }
5043 func method2(x,y) { return something; }
5044 You make an instance with:
5045 mything = myclass(d1, d2);
5046 Then you can use your object: mything(method2,x,y) and so on.
5047
5048 This is slightly untidy, because you have to worry about never
5049 colliding with the method names. So you could bundle it up neatly
5050 by making myclass itself an object containing all its methods and
5051 constructor(s):
5052 myclass = save(new, method1, method2, ...); // save old values
5053 func new(data1, data2, ...) {
5054 // build and return the class, for example:
5055 return save(method1, method2, ..., data1, data2, ...);
5056 }
5057 func method1(x) { return something; }
5058 func method2(x,y) { return something; }
5059 myclass = restore(myclass); // swap new values into myclass
5060 (See help,save for examples of this trick.) Now the only variable
5061 you have to worry about not clobbering is myclass, and you create
5062 your object with:
5063 mything = myclass(new, d1, d2);
5064 and use it as before.
5065
5066 There are many ways to handle inheritance (multiple inheritance
5067 is no harder); the simplest is just to use the save function to
5068 concatentate new members onto the base class. [Probably should
5069 illustrate a good style here...] The complete absence of type
5070 checking is actually an advantage here: If an object has a method
5071 with the required arguments and semantics, it will be usable no
5072 matter what other members it has.
5073
5074 You can also extract object members using the dot operator:
5075 obj.member is a synonym for obj("member")
5076 but note that obj.member(args) may be very different from
5077 obj(member,args); in general you are better off not using the
5078 dot operator with objects. In particular, note that
5079 obj.member = value; // ERROR!
5080 does NOT set the member to value. (Use obj,member=value;)
5081
5082 SEE ALSO: use, save, restore, is_obj, openb, createb, noop, closure,
5083 gaccess
5084 */
5085
5086 extern is_obj;
5087 /* DOCUMENT is_obj(x)
5088 * or is_obj(x,m)
5089 * or is_obj(x,m,errflag)
5090 * returns 1 if X is an object, else 0. If X is an object which permits
5091 * numerical indexing of its members, returns 3. With second parameter M,
5092 * query is for member M of object X. If M specifies multiple members
5093 * (an index range, index list, or list of member names), then returns
5094 * an array of results. Note that is_obj(x,) may return [] if the
5095 * object X is empty. With third parameter ERRFLAG non-nil and non-zero,
5096 * is_obj will return -2 if X is not an object, and -1 wherever M
5097 * specifies a non-member (either a name not present or an index out
5098 * of range). Without ERRFLAG, is_obj raises an error when M is not
5099 * a member.
5100 * SEE ALSO: oxy, save, restore
5101 */
5102
5103 extern use;
5104 extern use_method;
5105 /* DOCUMENT use, var1, var2, ...
5106 or use(membspec, arg1, arg2, ...)
5107 or use_method, memberspec, arg1, arg2, ...
5108 or use_method(memberspec, arg1, arg2, ...)
5109 Access the context object in an object method function (see help,oxy).
5110
5111 In the first form, the VARi must be extern to the calling function,
5112 and you get read-write access to the VARi. That is, if you redefine
5113 any of the VARi, your changes will be saved back to the context object
5114 when the calling function returns. Even though the VARi are external
5115 to the method function, use arranges for their external values to be
5116 replaced when the calling function returns, just as if they had been
5117 local variables.
5118
5119 The second form is equivalent to obj(membspec, arg1, arg2, ...),
5120 where obj is the context object. You can use this whenever you need
5121 only read access to membspec.
5122
5123 The third form permits you to call a method member of the context
5124 as a subroutine (like "noop,use(memberspec,arg1,arg2,...)").
5125 The fourth form is similar to the second -- use_method(...) is
5126 nearly a synonym for use(...), with two exceptions:
5127 1. use_method(memberspec) invokes the memberspec function with
5128 zero arguments, while use(memberspec) returns the function
5129 rather than invoking it.
5130 2. use_method raises an error if memberspec is not a function,
5131 while use does not (for example, memberspec could be an array).
5132
5133 When you invoke a method with use_method (or use as a function),
5134 any calls to the subroutine form of use (the first form) will
5135 be cumulative with calls made by the caller. When a method invoked
5136 by use_method (or use as a function) returns, the VARi from any
5137 use subroutine calls it has made are *not* restored when it returns.
5138 Instead, the restore and the update of the context object itself
5139 are deferred until the outermost method returns -- the one that
5140 was not invoked by use_method.
5141
5142 Therefore, you should generally use the first form for access to
5143 data members of an object, and the other forms for access to
5144 function (method) members of objects. If you violate this rule,
5145 your method code may have unexpected side effects, unless you can
5146 guarantee that it your method will never be invoked by another
5147 method by means of use_method (or use as a function).
5148
5149 Additionally, you can use the special forms of the save and
5150 restore function to explicitly save and restore variables from the
5151 context object:
5152 restore, use, var1, var2, ...;
5153 save, use, var1, var2, ...;
5154 The use function is normally the better choice; the special forms
5155 of save and restore are for slightly higher performance in unusual
5156 situations. If you mix save,use,var or restore,use,var with use,var,
5157 you will very likely have trouble with different versions of var
5158 overwriting each other unintentionally.
5159
5160 SEE ALSO: oxy, save, restore, openb, createb, noop, closure
5161 */
5162
5163 extern closure;
5164 /* DOCUMENT f = closure(function, data)
5165 or f = closure(object, member)
5166 creates a closure function from FUNCTION and DATA. Invoking the
5167 closure function invokes FUNCTION with argument DATA prepended
5168 to the argument list passed to the closure function. For example,
5169 f; is equivalent to FUNCTION, DATA;
5170 f(a1,a2) is equivalent to FUNCTION(DATA, a1, a2)
5171 and so on. When the first argument is an OBJECT, and the second
5172 argument a MEMBER, the object is invoked with the member as its
5173 first parameter. (Typically the member would be a function.)
5174 If the first argument is an object, then the second argument
5175 (MEMBER) has the same semantics as object(member, ...): namely,
5176 if MEMBER is a simple variable reference, its value is ignored,
5177 and only its name is used to specify which member of the object.
5178 Hence, if you want the value of MEMBER to be used, you need to
5179 be sure the second argument to closure is an expression, such
5180 as noop(member). If the first argument is a function, then
5181 the second argument is always a value.
5182
5183 Finally, the first argument can be a string in order to specify
5184 that the returned closure object use the value of the named
5185 variable at runtime for the function (or object). If you expect
5186 the value to be an object, prefix the variable name by "o:" in
5187 order to prevent the closure object from keeping a use of the
5188 value of the second argument, if MEMBER is a simple variable
5189 reference. For example,
5190 f = closure("myfunc", data); // keeps use of data value
5191 g = closure("o:myobj", member); // ignores value of member
5192 h = closure("myobj", noop(member)); // o: unnecessary
5193 This feature is primarily an aid during debugging; typically
5194 you would remove the quotes (and o:) once the code was working.
5195
5196 You can query a closure object using the member extraction
5197 operator:
5198 f.function returns function or object
5199 f.data returns data or member
5200 f.function_name returns name of function or object
5201 f.data_name returns name of data
5202 The names are string(0) if unknown; function_name is known
5203 if and only if the first argument to closure was a string;
5204 data_name is known only if the first argument was a string or
5205 an object and the second argument a simple variable reference.
5206
5207 SEE ALSO: oxy, is_func, use
5208 */
5209
5210 extern gaccess;
5211 /* DOCUMENT flags = gaccess(grp)
5212 * or grp = gaccess(grp, flags)
5213 * With single GRP argument, return current group object access flags.
5214 * With second FLAGS argument, set group object access flags, returning
5215 * the input GRP to allow constructs like g=gaccess(save(var1,var2), 3);
5216 * The access flags bits are:
5217 * 1 set if no new members may be created
5218 * 2 set if existing members cannot change data type or dimensions
5219 * (that is, they behave as x(..)=expr, rather than as x=expr)
5220 * SEE ALSO: oxy, save, restore
5221 */
5222
5223 /*= SECTION(system) interacting with system ================================*/
5224
5225 extern quit;
5226 /* DOCUMENT quit
5227 Exit YMainLoop when current task finishes.
5228 Normally this terminates the program.
5229 */
5230
5231 extern system;
5232 /* DOCUMENT system, "shell command line"
5233 Passes the command line string to a shell for execution.
5234 If the string is constant, you may use the special syntax:
5235 $shell command line
5236 (A long command line may be continued by ending the line with \
5237 as usual.) The system function syntax allows Yorick to compute
5238 parts of the command line string, while the simple $ escape
5239 syntax does not. In either case, the only way to get output
5240 back from such a command is to redirect it to a file, then
5241 read the file. Note that Yorick does not regain control
5242 until the subordinate shell finishes. (Yorick will get control
5243 back if the command line backgrounds the job.)
5244 WARNING: If Yorick has grown to a large size, this may crash
5245 your operating system, since the underlying POSIX fork function
5246 first copies all of the running Yorick process before the exec
5247 function can start the shell. See Y_SITE/sysafe.i for a fix.
5248 SEE ALSO: popen
5249 */
5250
5251 extern yorick_init;
5252 /* xxDOCUMENT yorick_init
5253 Re-initializes all of the built-in functions for this version
5254 of Yorick. To be used in desperation if you overwrite some
5255 critical built-in function by mistake. Of course, if you
5256 redefine yorick_init, you won't be able to recover anything.
5257 */
5258
5259 extern set_path;
5260 /* DOCUMENT set_path, "dir1:dir2:dir3:..."
5261 or set_path
5262 sets the include file search path to the specified list of
5263 directories. The specified directories are searched left to
5264 right for include files specified as relative file names in
5265 #include directives, or to the include or require functions.
5266 If the argument is omitted, restores the default search path,
5267 ".:~/yorick:~/Yorick:Y_SITE/i:Y_SITE/contrib:Y_SITE/i0:Y_HOME/lib",
5268 where y_site is the main Yorick directory for this site.
5269 The Y_LAUNCH directory is the directory which contains the
5270 executable; this directory is omitted if it is the same as
5271 Y_SITE.
5272
5273 Only the "end user" should ever call set_path, and then only in
5274 his or her custom.i file, for the purpose of placing a more
5275 elaborate set of personal directories containing Yorick procedures.
5276 For example, if someone else maintains Yorick code you use, you
5277 might put their ~/yorick on your include path.
5278
5279 SEE ALSO: Y_LAUNCH, Y_SITE, include, require, get_path
5280 */
5281
5282 extern get_path;
5283 /* DOCUMENT get_path()
5284 returns the current include file search path.
5285 SEE ALSO: set_path, get_pkgnames, split_path
5286 */
5287
5288 extern set_site;
5289 /* xxDOCUMENT set_site, site_directory
5290 sets Y_LAUNCH, Y_SITE as a side effect. Should only be called from
5291 paths.i. See paths.i. */
5292
5293 extern yorick_stats;
5294 /* DOCUMENT yorick_stats
5295 returns an array of longs describing Yorick memory usage.
5296 For debugging. See ydata.c source code.
5297 */
5298
5299 extern cd;
5300 /* DOCUMENT cd, directory_name
5301 or cd(directory_name)
5302 change current working directory to DIRECTORY_NAME, returning
5303 the expanded path name (i.e.- with leading environment variables,
5304 ., .., or ~ replaced by the actual pathname). If called as a
5305 function, returns nil to indicate failure, otherwise failure
5306 causes a Yorick error.
5307 SEE ALSO: lsdir, mkdir, rmdir, get_cwd, get_home, get_env, get_argv
5308 */
5309
5310 extern lsdir;
5311 /* DOCUMENT files = lsdir(directory_name)
5312 or files = lsdir(directory_name, subdirs)
5313 List DIRECTORY_NAME. The return value FILES is an array of
5314 strings or nil; the order of the filenames is unspecified;
5315 it does not contain "." or "..". If present, SUBDIRS must be
5316 a simple variable reference, and is set to a list of subdirectory
5317 names (or nil if none). If SUBDIRS is not present (first form),
5318 the return value of lsdir includes both files and subdirectories.
5319 If DIRECTORY_NAME does not exist or is not a directory, the return
5320 value is the integer 0 rather than nil. Hence:
5321 files = lsdir(dirname, subdirs);
5322 if (structof(files) == long) {
5323 directory does not exist
5324 } else {
5325 for (i=1 ; i<=numberof(files) ; ++i) {...use files(i)...}
5326 for (i=1 ; i<=numberof(subdirs) ; ++i) {...use subdirs(i)...}
5327 }
5328 SEE ALSO: cd, mkdir, rmdir, get_cwd, get_home, filepath
5329 */
5330
5331 extern mkdir;
5332 extern rmdir;
5333 /* DOCUMENT mkdir, directory_name
5334 or rmdir, directory_name
5335 Create DIRECTORY_NAME with mkdir, or remove it with rmdir. The rmdir
5336 function only works if the directory is empty. An error is raised if
5337 DIRECTORY_NAME is not a non-nil scalar string. If mkdir or rmdir are
5338 called as subroutines and the operation fails, no error is raised
5339 (so you can use this form even when the directory already exists for
5340 mkdir, or already is missing for rmdir). Otherwise, if
5341 DIRECTORY_NAME is a non-nil scalar string and if mkdir and rmdir are
5342 called as a function, they return an integer: 0 to indicate success and
5343 -1 to indicate failure.
5344
5345 SEE ALSO: mkdirp, cd, lsdir, get_cwd, get_home, filepath
5346 */
5347
mkdirp(dir)5348 func mkdirp(dir)
5349 /* DOCUMENT mkdirp, directory_name
5350 Create DIRECTORY_NAME, creating any missing parent directories
5351 (like UNIX utility mkdir -p). Unlike mkdir, signals error if
5352 the creation is unsuccessful. If DIRECTORY_NAME already exists
5353 and is a directory, mkdirp is a no-op.
5354 SEE ALSO: mkdir
5355 */
5356 {
5357 dir = strtrim(dir, 2, blank="/") + "/";
5358 list = strfind("/", dir, n=1024); /* assume <1024 components in dir */
5359 i = list(1:-1:2);
5360 list = i(where((i>0) & (list(2:0:2)>0)));
5361 for (i=numberof(list) ; i>=1 ; i--) {
5362 name = strpart(dir, [0,list(i)]);
5363 if (lsdir(name) != 0) break;
5364 }
5365 for (i++ ; i<=numberof(list) ; i++)
5366 mkdir, strpart(dir, [0,list(i)]);
5367 if (lsdir(dir) == 0) error, "mkdirp: failed to create "+dir;
5368 }
5369
5370 extern get_cwd;
5371 extern get_home;
5372 /* DOCUMENT get_cwd()
5373 or get_home()
5374 returns the pathname of the current working directory or of your
5375 home directory.
5376 SEE ALSO: cd, lsdir, get_env, get_argv
5377 */
5378
5379 extern get_env;
5380 /* DOCUMENT get_env(environment_variable_name)
5381 returns the environment variable (a string) associated with
5382 ENVIRONMENT_VARIABLE_NAME (calls ANSI getenv routine).
5383 SEE ALSO: cd, get_cwd, get_home, get_env, get_argv
5384 */
5385
5386 extern get_argv;
5387 /* DOCUMENT get_argv()
5388 returns string array containing the argv from the command line.
5389 The -batch and batch_include.i arguments are removed (not returned).
5390 SEE ALSO: process_argv, cd, get_cwd, get_home, get_env, batch
5391 */
5392
process_argv(msg)5393 func process_argv(msg)
5394 /* DOCUMENT remaining= process_argv()
5395 or remaining= process_argv("your startup message")
5396 Performs standard command line processing. This function is
5397 invoked by the default custom.i file (in $Y_SITE/i); you
5398 can also invoke it from your personal ~/yorick/custom.i file.
5399 The process_argv calls get_argv, removes any arguments of
5400 the form "-ifilename" or "-i filename" (the latter is a pair of
5401 arguments. It returns any arguments not of this form as its
5402 result, after including any filenames it found in the order
5403 they appeared on the command line.
5404 The optional string argument may be an array of strings to print
5405 a multi-line message.
5406
5407 A Yorick package may define the function get_command_line in
5408 order to feed process_argv something other than get_argv.
5409
5410 SEE ALSO: batch
5411 */
5412 {
5413 if (get_command_line == process_argv) return command_line;
5414 if (is_void(get_command_line)) command_line = get_argv();
5415 else command_line = get_command_line();
5416 get_command_line = process_argv; /* try to avoid infinite loops */
5417 if (numberof(command_line)>=2) {
5418 command_line = command_line(2:);
5419 mask = (strpart(command_line, 1:2) == "-i");
5420 j = (command_line(0) == "-i");
5421 if (j) mask(0) = 0;
5422 list = where(mask);
5423 n = numberof(list);
5424 if (n) {
5425 file = strpart(command_line(list), 3:);
5426 i = where(file == "");
5427 if (numberof(i)) {
5428 list = list(i) + 1;
5429 file(i) = command_line(list);
5430 mask(list) = 1;
5431 }
5432 /* push onto stack in reverse order, to include in given order */
5433 for (i=n ; i>=1 ; --i) include, file(i);
5434 }
5435 if (j) mask(0) = 1;
5436 command_line= command_line(where(!mask));
5437 } else {
5438 command_line= [];
5439 }
5440 mask = (command_line == "-q");
5441 if (noneof(mask)) {
5442 if (is_void(msg)) {
5443 v = Y_VERSION;
5444 msg = [
5445 " Copyright (c) 2005. The Regents of the University of California.",
5446 " All rights reserved. Yorick "+v+" ready. For help type 'help'"];
5447 }
5448 write, msg, format="%s\n";
5449 } else if (numberof(command_line)) {
5450 command_line = command_line(where(!mask));
5451 }
5452 return command_line;
5453 }
5454
5455 extern batch;
5456 /* DOCUMENT batch, 1
5457 batch, 0
5458 batch()
5459 turns on, turns off, or tests for batch mode, respectively.
5460 If yorick is started with the command line:
5461 yorick -batch batch_include.i ...
5462 then batch mode is turned on, the usual custom.i startup file is
5463 skipped, and the file batch_include.i is parsed and executed. The
5464 -batch and batch_include.i command line arguments are removed from
5465 the list returned by get_argv(). These must be the first two
5466 arguments on the command line.
5467
5468 In batch mode, any error will terminate Yorick (as by the quit
5469 function) rather than entering debug mode. Also, any attempt to
5470 read from the keyboard is an error.
5471
5472 SEE ALSO: process_argv, get_argv, set_idler, after_error
5473 */
5474
5475 extern set_idler;
5476 /* DOCUMENT set_idler, idler_function
5477 or set_idler, idler_function, errflags
5478 sets the idler function to IDLER_FUNCTION. Instead of waiting
5479 for keyboard input when all its tasks are finished, the interpreter
5480 will invoke IDLER_FUNCTION with no arguments. The idler function
5481 is normally invoked only once, so input from the keyboard resumes
5482 after one call to the idler. Of course, an idler is free to call
5483 set_idler again before it returns, which will have the effect of
5484 calling that function in a loop.
5485 If present, the ERRFLAGS argument changes the way errors are processed:
5486 0 - default processing, add any combination of:
5487 1 - suppress printing error messages
5488 2 - append [pc] relative program counter to function name in error
5489 message (use disassemble to find corresponding instruction)
5490 4 - call any after_error function in dbug mode (rather than clearing
5491 stack), so it is responsible for calling dbexit
5492 SEE ALSO: batch, maybe_prompt, after, after_error
5493 */
5494
5495 local after_error;
5496 /* DOCUMENT after_error = error_handler_func
5497 If the variable AFTER_ERROR is set to an interpreted function
5498 with no parameters, that function will be invoked after an error,
5499 before the next prompt, instead of entering or offering to enter
5500 debug mode. The error message will be printed, and also will be
5501 stored in the catch_message variable. A fault during the execution
5502 of the after_error function will not invoke after_error, but
5503 otherwise after_error is persistent (unlike set_idler). An error
5504 resets any functions scheduled using after or set_idler, so the
5505 after_error function must reschedule these if necessary.
5506 The catch function is a more appropriate way to recover from
5507 some errors.
5508 SEE ALSO: set_idler, catch, after
5509 */
5510
5511 extern maybe_prompt;
5512 /* DOCUMENT maybe_prompt
5513 Issue prompt for keyboard input if appropriate.
5514 This command only makes sense (I think) as the final statement
5515 of a function invoked as an idler (via set_idler), when yorick is
5516 in a loop with an idler function that continuously re-installs
5517 itself. Yorick ordinarily issues a prompt only just before it
5518 stops to wait for keyboard input, it will never prompt in this
5519 situation, even though it would accept keyboard input if it
5520 were typed.
5521 SEE ALSO: set_idler, prompt_marker
5522 */
5523
5524 extern prompt_marker;
5525 /* DOCUMENT prompt_marker, marker
5526 or prompt_marker
5527 set prompt marker string to MARKER. Omit MARKER or pass MARKER
5528 as string(0) or "" to remove any prompt marker.
5529 Yorick emits the prompt marker string immediately after any actual
5530 prompt and just before it blocks waiting for input. This is useful
5531 for writing programs in other languages designed to control yorick.
5532 For example,
5533 prompt_marker, "\5\5"
5534 will emit two ASCII ENQ characters. A controller can assume anything
5535 between the last newline and this marker is the true yorick prompt.
5536 More importantly, if it hasn't read the prompt marker, the controller
5537 knows yorick is still running, not waiting for input, so it is safe
5538 to block reading yorick's stdout, knowing that eventually the marker
5539 will arrive.
5540 SEE ALSO: maybe_prompt
5541 */
5542
5543 extern spawn;
5544 /* DOCUMENT process = spawn(argv, on_stdout)
5545 or process = spawn(argv, on_stdout, on_stderr)
5546 starts the process named in ARGV(1) with additional arguments
5547 in any subsequent elements of ARGV (which is a scalar or 1D
5548 array of strings). The ON_STDOUT and optional ON_STDERR
5549 are interpreted functions declared like this:
5550 func ON_STDOUT(msg)
5551 {
5552 commands to process msg on stdout from process
5553 }
5554
5555 Yorick will invoke ON_STDOUT asynchronously if process
5556 emits text to its stdout. Yorick includes the process in
5557 the list of event sources, which it polls whenever it waits
5558 for input. If the optional ON_STDERR is provided, it is
5559 called asynchronously whenever process emits a line to stderr;
5560 with no ON_STDERR, the process will share yorick's stderr,
5561 which generally means the process stderr prints at the terminal.
5562 (Note that you can make the third argument the same as the second
5563 if you want to use the same function to handle stdout and stderr.)
5564 When the process terminates, ON_STDOUT is invoked with
5565 string(0) and the process object becomes inactive. Note that
5566 ON_STDOUT and ON_STDERR are invoked via the name they were
5567 originally defined with (in the func or extern statement for
5568 interpreted and compiled functions, respectively).
5569
5570 The object returned by spawn, process, can be used to send input
5571 or signals to the process:
5572 process, msg;
5573 where msg is a string, sends msg to the process's stdin.
5574 process, signum;
5575 sends process the specified signal (e.g.- signum=2 sends SIGINT,
5576 like hitting control-C, while signum=9 kills the process), if
5577 signum is an integer (as opposed to a string). (Normally you
5578 should not send signals to a process.) If you redefine the
5579 final reference to process, for example by
5580 process = [];
5581 yorick will disconnect from the process, closing its end of
5582 the stdin, stdout, and, optionally, stderr pipes. For many
5583 programs, this will stop the program, but if the program can
5584 continue running without stdin and stdout, it will continue
5585 running. (If yorick were a shell, the process would be running
5586 in the background; if the process would live beyond the shell
5587 which created it, it will also survive its process variable
5588 being freed.)
5589
5590 Note: funcdef may be extremely useful for writing ON_STDOUT.
5591
5592 SEE ALSO: popen, system, suspend, funcdef, after, spawn_callback
5593 */
5594
5595 func spawn_callback(&prev, line)
5596 /* DOCUMENT spawn_callback -->
5597 func on_stdout(msg) {
5598 extern fragment; <or otherwise manage fragment>
5599 lines = spawn_callback(fragment, msg);
5600 for (i=1 ; i<=numberof(lines) ; i++) {
5601 line = lines(i);
5602 if (!line) {
5603 <handle process has died>
5604 } else {
5605 <handle complete line emitted by process>
5606 }
5607 }
5608 }
5609 Here is a template for a callback function to be passed to spawn.
5610 The spawn_callback function buffers any fragmentary lines,
5611 delivering only complete lines as output. Note that FRAGMENT
5612 must somehow be managed between calls to on_stdout; it should
5613 be intialized to [] before calling spawn.
5614
5615 SEE ALSO: spawn
5616 */
5617 {
5618 dead = !line; /* spawned process has died */
5619
5620 /* must be prepared for process output to dribble back a fraction of
5621 * a line at a time, or multiple lines at a time
5622 * prev holds the most recent incomplete line,
5623 * assuming the the remainder will arrive in future callbacks
5624 */
5625 if (is_void(prev)) prev = string(0);
5626 prev += line;
5627 selist = strword(prev, "\r\n", 256);
5628 line = strpart(prev, selist);
5629 line = line(where(line));
5630 n = numberof(line);
5631 if (n && selist(2*n)==strlen(prev)) {
5632 /* final character of input not \n, store fragment in prev */
5633 prev = line(0);
5634 line = (n==1)? [] : line(1:-1);
5635 } else {
5636 prev = string(0);
5637 }
5638
5639 if (dead) {
5640 if (is_void(line) || !line(0)) grow, line, [string(0)];
5641 }
5642 return line;
5643 }
5644
5645 extern suspend;
5646 extern resume;
5647 /* DOCUMENT suspend
5648 resume
5649 Stop execution of the current interpreted program with suspend.
5650 It resumes at the instruction following suspend when yorick
5651 becomes idle after another interpreted task has called resume.
5652 Note that the task which calls resume must be triggered by an
5653 input stream other than stdin, such as the on_stdout or on_stderr
5654 function of a spawned process or the on_elapse of an after.
5655 Use control-c to escape from a hung suspend state.
5656 SEE ALSO: spawn, funcdef, after
5657 */
5658
5659 extern _after_func; /* worker functions for after */
5660 func _after_work { _after_func; }
5661
5662 extern after;
5663 /* DOCUMENT after, secs, f
5664 or after, secs, f, arg
5665 of after, -, f, arg
5666 of after, -
5667 Execute yorick statement
5668 F;
5669 or
5670 F, ARG;
5671 when yorick becomes idle, but at least SECS seconds from now.
5672 SECS may be type double to specify fractions of a second.
5673 With SECS = 0.0, this is the same as set_idler, except that
5674 while you may have only a single idler function, you may have
5675 many after functions. F may be either a function (is_func(f)
5676 non-zero), or an oxy object (is_obj(f) non-zero). For example,
5677 after, 0.1, include, ["fma; plg, y, x;"];
5678 can obviously be modified to do anything you want, although you
5679 are probably better off writing a function containing the
5680 executable line, rather than putting it into a string.
5681 As another example,
5682 after, 0.1, object, method;
5683 invokes the object method after a delay of a tenth of a second.
5684 (See help,oxy for more on objects.) If F is an object, and method
5685 is a simple variable reference, the special semantics of object
5686 arguments apply; that is, only the name "method" is significant,
5687 not its value.
5688 In the third form, with the pseudo-index - as the first argument,
5689 cancels the specified after call(s). The ARG, if specified, must
5690 be the same variable, not just the same value. If no ARG is specified,
5691 all pending after callbacks with the given F are cancelled. If
5692 neither ARG nor F is specified, all after callbacks are cancelled.
5693 SEE ALSO: spawn, set_idler, after_error
5694 */
5695
5696 /*--------------------------------------------------------------------------*/
5697
5698 extern timestamp;
5699 /* DOCUMENT timestamp()
5700 or timestamp(utime)
5701 or timestamp, utime
5702 returns string of the form "Sun Jan 3 15:14:13 1988" -- always
5703 has 24 characters. If a simple variable reference UTIME is supplied,
5704 it will be set to the number of seconds since 1970 Jan 1 0000 UT.
5705 SEE ALSO: timer
5706 */
5707
5708 extern timer;
5709 /* DOCUMENT timer, elapsed
5710 or timer, elapsed, split
5711 updates the ELAPSED and optionally SPLIT timing arrays. These
5712 arrays must each be of type array(double,3); the layout is
5713 [cpu, system, wall], with all three times measured in seconds.
5714 ELAPSED is updated to the total times elapsed since this copy
5715 of Yorick started. SPLIT is incremented by the difference between
5716 the new values of ELAPSED and the values of ELAPSED on entry.
5717 This feature allows for primitive code profiling by keeping
5718 separate accounting of time usage in several categories, e.g.--
5719 elapsed= total= cat1= cat2= cat3= array(double, 3);
5720 timer, elapsed0;
5721 elasped= elapsed0;
5722 ... category 1 code ...
5723 timer, elapsed, cat1;
5724 ... category 2 code ...
5725 timer, elapsed, cat2;
5726 ... category 3 code ...
5727 timer, elapsed, cat3;
5728 ... more category 2 code ...
5729 timer, elapsed, cat2;
5730 timer, elapsed0, total;
5731 The wall time is not absolutely reliable, owning to possible
5732 rollover at midnight.
5733 SEE ALSO: timestamp, timer_print
5734 */
5735
timer_print(label,split,..)5736 func timer_print(label, split, ..)
5737 /* DOCUMENT timer_print, label1, split1, label2, split2, ...
5738 or timer_print
5739 or timer_print, label_total
5740 prints out a timing summary for splits accumulated by timer.
5741 timer_print, "category 1", cat1, "category 2", cat2,
5742 "category 3", cat3, "total", total;
5743 SEE ALSO: timer
5744 */
5745 {
5746 elapsed= s= array(double, 1:3);
5747 timer, elapsed;
5748 write,format="%30s CPU sec System sec Wall sec\n","Timing Category";
5749 if (!is_void(label) && !is_void(split)) {
5750 s(1:3)= split;
5751 write,format="%30s %11.3f %11.3f %11.3f\n", label, s(1), s(2), s(3);
5752 }
5753 while (more_args()>1) {
5754 labl= next_arg();
5755 s(1:3)= next_arg();
5756 write,format="%30s %11.3f %11.3f %11.3f\n", labl, s(1), s(2), s(3);
5757 }
5758 if (is_void(label) || is_void(split)) {
5759 if (is_void(label)) labl= "-----Total Elapsed Times-----";
5760 else labl= label;
5761 s(1:3)= elapsed;
5762 write,format="%30s %11.3f %11.3f %11.3f\n", labl, s(1), s(2), s(3);
5763 }
5764 }
5765
5766 _timer_elapsed= [0.,0.,0.];
5767 timer, _timer_elapsed;
5768
5769 /*= SECTION(mesh) functions on mesh arrays =================================*/
5770
area(y,x)5771 func area(y, x)
5772 /* DOCUMENT area(y, x)
5773 returns the zonal areas of the 2-D mesh (X, Y). If Y and X are
5774 imax-by-jmax, the result is (imax-1)-by-(jmax-1). The area is
5775 positive when, say, X increases with i and Y increases with j.
5776 For example, area([[0,0],[1,1]],[[0,1],[0,1]]) is +1.
5777 SEE ALSO: volume
5778 */
5779 { return x(dif,zcen)*y(zcen,dif) - x(zcen,dif)*y(dif,zcen); }
5780
volume(r,z)5781 func volume(r, z)
5782 /* DOCUMENT volume(r, z)
5783 returns the zonal volumes of the 2-D cylindrical mesh (R, Z).
5784 If R and Z are imax-by-jmax, the result is (imax-1)-by-(jmax-1).
5785 The volume is positive when, say, Z increases with i and R increases
5786 with j. For example, volume([[0,0],[1,1]],[[0,1],[0,1]]) is +pi.
5787 SEE ALSO: area
5788 */
5789 {
5790 s= r*r;
5791 v= z(dif,zcen)*s(zcen,dif) - z(zcen,dif)*s(dif,zcen);
5792 s= z*r;
5793 return (2.0*pi/3.0)*(v+s(dif,zcen)*r(zcen,dif)-s(zcen,dif)*r(dif,zcen));
5794 }
5795
ptcen(zncen,ireg)5796 func ptcen(zncen, ireg)
5797 /* DOCUMENT ptcen(zncen)
5798 or ptcen(zncen, ireg)
5799 returns point centered version of the 2-D zone centered array ZNCEN.
5800 The result is imax-by-jmax if ZNCEN is (imax-1)-by-(jmax-1).
5801 If the region number array IREG is specified, zones with region
5802 number 0 are not included in the point centering operation.
5803 Note that IREG should have dimensions imax-by-jmax; the first
5804 row and column of IREG are ignored.
5805 Without IREG, ptcen(zncen) is equivalent to zncen(pcen,pcen).
5806 SEE ALSO: zncen, uncen
5807 */
5808 {
5809 if (is_void(ireg)) return zncen(pcen, pcen, ..);
5810 void= use_origins(0);
5811 exist= (ireg(2:,2:)!=0);
5812 return (exist*zncen)(pcen,pcen,..)/(exist(pcen,pcen)+1.e-35);
5813 }
5814
zncen(ptcen,ireg)5815 func zncen(ptcen, ireg)
5816 /* DOCUMENT zncen(ptcen)
5817 or zncen(ptcen, ireg)
5818 returns zone centered version of the 2-D point centered array PTCEN.
5819 The result is (imax-1)-by-(jmax-1) if PTCEN is imax-by-jmax.
5820 If the region number array IREG is specified, zones with region
5821 number 0 are not included in the point centering operation.
5822 Note that IREG should have dimensions imax-by-jmax, like
5823 the input PTCEN array; the first row and column of IREG are ignored.
5824 Without IREG, zncen(ptcen) is equivalent to ptcen(zcen,zcen).
5825 SEE ALSO: ptcen, uncen
5826 */
5827 {
5828 if (is_void(ireg)) return ptcen(zcen, zcen, ..);
5829 void= use_origins(0);
5830 exist= (ireg(2:,2:)!=0);
5831 return exist*ptcen(zcen, zcen, ..);
5832 }
5833
uncen(ptcen,ireg)5834 func uncen(ptcen, ireg)
5835 /* DOCUMENT uncen(ptcen)
5836 or uncen(ptcen, ireg)
5837 returns zone centered version of the 2-D zone centered array PTCEN.
5838 The result is (imax-1)-by-(jmax-1) if PTCEN is imax-by-jmax.
5839 If the region number array IREG is specified, zones with region
5840 number 0 are not included in the point centering operation.
5841 Note that IREG should have dimensions imax-by-jmax, like
5842 the input PTCEN array; the first row and column of IREG are ignored.
5843 Without IREG, uncen(ptcen) is equivalent to ptcen(uncp,uncp).
5844
5845 Do not use uncen to zone center data which is naturally point
5846 centered -- use the zncen function for that purpose. The uncen
5847 function is the (nearly) exact inverse of the ptcen function,
5848 so that uncen(ptcen(zncen, ireg), ireg) will return the original
5849 zncen array. The uncen reconstruction is as exact as possible,
5850 given the finite precision of floating point operations.
5851 SEE ALSO: ptcen, zncen
5852 */
5853 {
5854 if (is_void(ireg)) return ptcen(uncp, uncp, ..);
5855 void= use_origins(0);
5856 exist= (ireg(2:,2:)!=0);
5857 return (exist(pcen,pcen)*ptcen)(uncp, uncp, ..);
5858 }
5859
5860 /*--------------------------------------------------------------------------*/
5861
5862 extern noop;
5863 /* DOCUMENT noop(x)
5864 returns X. Use to make simple variable references into expressions.
5865 The noop function is a builtin, which runs much faster than the
5866 interpreted "call" function. Also, if X is an array reference for
5867 a file handle, "call" performs the read, while "noop" does not.
5868 SEE ALSO: call
5869 */
5870
call(void)5871 func call(void)
5872 /* DOCUMENT call, subroutine(arg1, arg2, arg3, arg4, arg5
5873 arg6, arg7, arg8);
5874 allows a SUBROUTINE to be called with a very long argument list
5875 as an alternative to:
5876 subroutine, arg1, arg2, arg3, arg4, arg5,
5877 arg6, arg7, arg8;
5878 Note that the statement
5879 subroutine(arg1, arg2, arg3, arg4, arg5,
5880 arg6, arg7, arg8);
5881 will print the return value of subroutine, even if it is nil.
5882 If invoked as a function, call simply returns its argument.
5883 SEE ALSO: noop
5884 */
5885 { return void; }
5886
5887 /*= SECTION(checksum) crc, md5, sha1 checksums =============================*/
5888
5889 extern crc_on;
5890 /* DOCUMENT crc = crc_on(x)
5891 or crc = crc_on(x, crc0)
5892 or crc_table = crc_on(crc_def, -)
5893 or crc = crc_on(x, crc_table)
5894 or crc = crc_on(x, crc_table, crc0)
5895 or crc_def = crc_on(crc_table, -)
5896 return a cyclic redundancy check on X. The crc has type long which
5897 is very likely (1 chance in 4 billion) to remain unchanged if X is
5898 corrupted by random noise. With a non-nil crc0 argument previously
5899 returned by crc_on, begins with crc0 to yield (roughly speaking) the
5900 result you would have gotten on a single call if the two X arguments
5901 had been concatenated (note that the order matters).
5902
5903 If X is a string array, the strings themselves, not including trailing
5904 '\0', are concatenated; string(0) is indistinguishable from "".
5905 If X is a struct instance array or a pointer array, the checksum
5906 returns an error. X must be an array or nil [].
5907
5908 Note that the crc value for any data type other than char depends
5909 on the native binary format on the platform where crc_on runs; the
5910 value will be different on other formats, just as it will be different
5911 for an array cast to a different data type.
5912
5913 There are many different CRC algorithms, which can be parameterized
5914 by five integer values:
5915 CRC_DEF = [width, poly, init, reflect, xor]
5916 Here width is the width in bits, reflect is either 0 or 1 (false or
5917 true), and poly, init, and xor are zero except for at most their
5918 width least significant bits. The returned crc is also zero except
5919 for its width least significant bits. The parameterization is
5920 described in "A Painless Guide to CRC Error Detection Algorithms" at
5921 http://www.ross.net/crc/
5922 (The reflect parameter corresponds to refin and refot, which must
5923 be equal for crc_on to work, and the xor parameter corresponds to
5924 xorot.) You can find a list of popular parameter values at
5925 http://regregex.bbcmicro.net/crc-catalogue.htm
5926 Do not try to "roll your own" parameters; let the experts do it.
5927 Here are some popular choices (crc_on requires width>=8):
5928 crc_def = [32, 0x04C11DB7, 0xFFFFFFFF, 1, 0xFFFFFFFF] ("pkzip")
5929 crc_def = [32, 0x04C11DB7, 0, 0, 0xFFFFFFFF] ("cksum")
5930 crc_def = [24, 0x864CFB, 0xB704CE, 0, 0] ("crc24")
5931 crc_def = [16, 0x8005, 0, 1, 0] ("arc")
5932 crc_def = [16, 0x1021, 0, 1, 0] ("kermit")
5933 The default is "pkzip". You can pass any of these five strings
5934 instead of an array of five numbers as CRC_DEF.
5935
5936 To use a CRC algorithm other than "pkzip", you must first generate
5937 a CRC_TABLE by calling crc_on(crc_def,-), then pass the CRC_TABLE
5938 as the second argument with X as the first to compute the CRC.
5939 Finally, crc_on(crc_table,-) returns the corresponding CRC_DEF;
5940 crc_on(,-) returns the CRC_DEF for the default "pkzip" algorithm.
5941 SEE ALSO: md5, sha1
5942 */
5943
5944 extern md5;
5945 extern sha1;
5946 /* DOCUMENT digest = md5(data) compute digest of DATA array
5947 state = [] initialize STATE
5948 md5, state, data process DATA updating STATE
5949 digest = md5(state, data) return DIGEST from STATE
5950 sha1 function has same semantics as md5 function
5951 The md5 and sha1 functions compute message digests or hashes. The
5952 digest returned by md5 is an array of 16 char (128 bits); the digest
5953 returned by sha1 is an array of 20 char (160 bits). There is a
5954 single call form, in which the input DATA array comprises the entire
5955 "message" to be digested. There is also a multi-call sequence, in
5956 which you invoke md5 or sha1 with two arguments: The first argument
5957 is a STATE variable, while the second argument is the DATA to be
5958 appended to the "message" in that call. DATA may be nil [], which
5959 causes no change in the STATE. STATE must be a simple variable
5960 reference, which is updated and returned with each call. As long
5961 as you call md5 or sha1 as a subroutine, STATE continues to be updated;
5962 call md5 or sha1 as a function to return the final digest of the
5963 concatenated "message". Before the first call, you must initialize
5964 STATE to []. The final function call destroys STATE, returning it
5965 as []. (To generate the final digest, both the md5 and sha1 algorithms
5966 append some padding to the input message, which destroys STATE.)
5967
5968 If DATA is a string array, the strings themselves, not including trailing
5969 '\0', are concatenated; string(0) is indistinguishable from "".
5970 If DATA is a struct instance array or a pointer array, the digesting
5971 function returns an error. DATA must be an array or nil [].
5972
5973 Although STATE is an array of char, it is platform dependent even
5974 though the final digest is not. Do not attempt to save STATE or
5975 to use STATE itself as a digest.
5976
5977 The advantage of md5 or sha1 over the crc_on function is that
5978 the resulting digest will be unique; no two DATA streams will
5979 ever produce the same digest for nearly all practical purposes.
5980 For the 32-bit crc result, you will get different data streams
5981 that have identical crc values after you process a modest number
5982 of data streams (tens of thousands). Thus, md5 or sha1 can be used
5983 to "fingerprint" data streams; if the fingerprints of two streams
5984 agree, you can be practically sure the streams themselves agree.
5985
5986 Both md5 and sha1 have now been "broken" cryptographically, which
5987 means that it is possible by heroic effort to create two different
5988 streams with the same digest. (At this writing, many examples of
5989 streams with identical md5 digests exist. No such examples exist
5990 yet for sha1, but it is clear that a few will appear fairly soon.)
5991 However, absent malicious intent and huge levels of effort, both
5992 md5 and sha1 are perfectly useful for fingerprinting data. These
5993 algorithms give the same results as the md5sum and sha1sum
5994 utilities, widely used to fingerprint files on the Web.
5995
5996 SEE ALSO: crc_on
5997 */
5998
5999 /*= SECTION(debug) debug commands ==========================================*/
6000
6001 extern error;
6002 extern exit;
6003 /* DOCUMENT exit, msg
6004 error, msg
6005 Exits the current interpreted *main* program, printing the MSG.
6006 (MSG can be omitted to print a default.)
6007 In the case of exit, the result is equivalent to an immediate
6008 return from every function in the current calling chain.
6009 In the case of error, the result is the same as if an error had
6010 occurred in a compiled routine.
6011 SEE ALSO: print, write, batch, catch
6012 */
6013
6014 extern catch;
6015 /* DOCUMENT catch(category)
6016 Catch errors of the specified category. Category may be -1 to
6017 catch all errors, or a bitwise or of the following bits:
6018
6019 0x01 math errors (SIGFPE, math library)
6020 0x02 I/O errors
6021 0x04 keyboard interrupts (e.g.- control C interrupt)
6022 0x08 other compiled errors (YError)
6023 0x10 interpreted errors (error)
6024
6025 Use catch by placing it in a function before the section of code
6026 in which you are trying to catch errors. When catch is called,
6027 it always returns 0, but it records the virtual machine program
6028 counter where it was called, and longjumps there if an error is
6029 detected. The most recent matching call to catch will catch the
6030 error. Returning from the function in which catch was called
6031 pops that call off the list of catches the interpreter checks.
6032
6033 To use catch, place the call near the top of a function:
6034
6035 if (catch(category)) {
6036 ...<code to execute if error is caught>...
6037 }
6038 ...<code "protected" by the catch>...
6039
6040 If an error with the specified category occurs in the "protected"
6041 code, the program jumps back to the point of the catch and acts
6042 as if the catch function had returned 1 (remember that when catch
6043 is actually called it always returns 0).
6044
6045 In order to lessen the chances of infinite loops, the catch is
6046 popped off the active list if it is actually used, so that a
6047 second error will *not* be caught. Often, this is only desirable
6048 for the error handling code itself -- if you want to re-execute
6049 the "protected" code, do this, and take care of the possibility
6050 of infinite loops in your interpreted code:
6051
6052 while (catch(category)) {
6053 ...<code to execute if error is caught>...
6054 }
6055 ...<code "protected" by the catch>...
6056
6057 After an error has been caught, the associated error message
6058 (what would have been printed had it not been caught) is left
6059 in the variable catch_message.
6060
6061 ***WARNING***
6062 If the code protected by the catch contains include or require
6063 calls, or function references which force autoloads, and the
6064 fault occurs while yorick is interpreting an included file,
6065 catch will itself fault, and the error code will not execute.
6066 If a fault occurs after an include has pushed a file onto
6067 the include stack for delayed parsing and you catch that fault,
6068 the include stack will not unwind to its condition at the time
6069 catch was called. That is, catch is incapable of protecting
6070 you completely during operations involving nested levels of
6071 include files.
6072
6073 In some cases, after_error is a more appropriate way to recover
6074 from errors.
6075
6076 SEE ALSO: error, after_error
6077 */
6078
6079 extern dbexit;
6080 extern dbcont;
6081 extern dbret;
6082 extern dbskip;
6083 extern dbup;
6084 extern dbinfo;
6085 extern dbdis;
6086 extern dbauto;
6087 extern dbwhere;
6088 /* DOCUMENT Debug mode.
6089
6090 Yorick errors fall into two general categories: Syntax errors discovered
6091 during parsing, and runtime errors discovered when a Yorick program is
6092 actually running. When a runtime error occurs, Yorick offers the
6093 choice of entering "debug mode", which you can do by typing the <RETURN>
6094 key immediately after the error occurs. Typing a non-blank line exits
6095 debug mode automatically by default. In debug mode, the Yorick prompt
6096 becomes "dbug>" instead of the usual ">". When you see this prompt,
6097 Yorick has halted "in the middle of" the function in which the error
6098 occurred, and you can print, plot, modify, or save the local variables
6099 in that function by means of ordinary Yorick commands. Debug mode is
6100 recursive; that is, you can debug an error which occurred during
6101 debugging to any number of levels.
6102
6103 You can exit from debug mode in several ways:
6104
6105 dbexit -- exit current debug level, discarding all
6106 active functions and their local variables
6107 dbexit, 0 -- exit all debug levels
6108 dbexit, n -- exit (at most) N debug levels
6109
6110 dbcont -- continue execution of the current function
6111 Continuing is useful if you have managed to repair the
6112 problem which caused the error. The expression in which the
6113 error occurred will be evaluated a second time, so beware of
6114 side effects.
6115
6116 dbret, value -- continue execution by returning VALUE (which
6117 may be nil or omitted) to the caller of the
6118 function in which the error occurred.
6119 This is useful if the function in which the error occurred is
6120 hopelessly confounded, but you know the value it should return.
6121
6122 Yorick does not allow "single stepping" directly, although you can
6123 execute the statements in a function by copying them, then tell
6124 Yorick to skip those statements you have executed "by hand". There
6125 are two functions for skipping execution:
6126
6127 dbskip -- skip the next logical line (This will be only
6128 a portion of a source line if several statements
6129 are stacked on the source line.)
6130 dbskip, n -- skip next N (positive or negative) logical lines
6131
6132 dbup -- discard the current function, so that you are
6133 debugging its caller -- there is no way to go
6134 back "down", so be careful
6135
6136 There are two functions which print information (like other print
6137 functions, if called as functions instead of subroutines, their
6138 result is returned as a string array with one line per string):
6139
6140 dbinfo -- returns current function and source line
6141
6142 dbdis -- returns disassembled virtual machine code
6143 for the next line (use the disassemble function
6144 to get the entire function)
6145 This allows you to see exactly where in a line the error occurred.
6146 dbwhere -- returns entire calling stack as func[pc] strings
6147 The dbwhere function also works outside of dbug mode.
6148
6149 Finally,
6150
6151 dbauto -- toggles whether debug mode will be entered
6152 automatically when a runtime error occurs
6153 dbauto, 1 -- enter debug mode automatically after an error
6154 dbauto, 0 -- type <RETURN> after error to enter debug mode
6155 */
6156
6157 extern disassemble;
6158 /* DOCUMENT disassemble(function)
6159 or disassemble, function
6160 Disassembles the specified function. If called as a function, the
6161 result is returned as a vector of strings; if called as a subroutine,
6162 the disassembly is printed at the terminal. If the function is nil,
6163 the current *main* program is disassembled -- you must include the
6164 call to disassemble in the main program, of course, NOT on its own
6165 line as a separate main program.
6166 */
6167
6168 /*= SECTION(list) list objects (deprecated, use oxy) =======================*/
6169
6170 extern _lst;
6171 extern _cat;
6172 extern _car;
6173 extern _cdr;
6174 extern _cpy;
6175 extern _len;
6176 /* DOCUMENT list= _lst(item1, item2, item3, ...)
6177 list= _cat(item_or_list1, item_or_list2, item_or_list3, ...)
6178 list= _cpy(list)
6179 list= _cpy(list, i)
6180 length= _len(list)
6181 item= _car(list)
6182 item_i= _car(list, i)
6183 _car, list, i, new_item_i
6184 list= _cdr(list)
6185 list= _cdr(list, i)
6186 _cdr, list, i, new_list_i
6187
6188 **** DEPRECATED, object extensions in new code, see help,oxy
6189
6190 implement rudimentary Lisp-like list handling in Yorick.
6191 However, in Yorick, a list must have a simple tree structure
6192 - no loops or rings are allowed (loops break Yorick's memory
6193 manager - beware). You need to be careful not to do this as
6194 the error will not be detected.
6195
6196 Lists are required in Yorick whenever you need to hold an
6197 indeterminate amount of non-array data, such as file handles,
6198 bookmarks, functions, index ranges, etc. Note that Yorick
6199 pointers cannot point to these objects. For array data, you have
6200 a choice between a list and a struct or an array of pointers.
6201 Note that a list cannot be written into a file with the save
6202 function, since it may contain unsaveable items.
6203
6204 The _lst (list), _cat (catenate), and _cpy (copy) functions
6205 are the principal means for creating and maintaining lists.
6206 _lst makes a list out of its arguments, so that each argument
6207 becomes one item of the new list. Unlike Yorick array data
6208 types, a statement like x=list does not make a copy of the
6209 list, it merely makes an additional reference to the list.
6210 You must explicitly use the _cpy function to copy a list. Note
6211 that _cpy only copies the outermost list itself, not the items
6212 in the list (even if those items are lists). With the second
6213 argument i, _cpy copies only the first i items in the list.
6214 The _cat function concatentates several lists together,
6215 "promoting" any arguments which are not lists. This operation
6216 changes the values of list arguments to _cat, except for the
6217 final argument, since after _cat(list, item), the variable list
6218 will point to the new longer list returned by _cat.
6219
6220 Nil, or [], functions as an empty list. This leads to ambiguity
6221 in the argument list for _cat, since _cat "promotes" non-list
6222 arguments to lists; _cat treats [] as an empty list, not as a
6223 non-list item. Also, _lst() or _lst([]) returns a single item list,
6224 not [] itself.
6225
6226 The _len function returns the number of items in a list, or 0
6227 for [].
6228
6229 The _car and _cdr functions (the names are taken from Lisp,
6230 where they originally stood for something like "address register"
6231 and "data register" of some long forgotten machine) provide
6232 access to the items stored in a list. _car(list,i) returns the
6233 i-th item of the list, and i defaults to 1, so _car(list) is the
6234 first item. Also, _car,list,i,new_item_i sets the i-th item
6235 of the list. Finally, _cdr(list,i) returns a list of all the
6236 items beyond the i-th, where i again defaults to 1. The form
6237 _cdr,list,i,new_list_i can be used to reset all list items
6238 beyond the i-th to new values. In the _cdr function, i=0 is
6239 allowed. When used to set values, both _car and _cdr can also
6240 be called as functions, in which case they return the item or
6241 list which has been replaced. The _cdr(list) function returns
6242 nil if and only if LIST contains only a single item; this is
6243 the usual means of halting a loop over items in a list.
6244
6245 SEE ALSO: array, grow, _prt, _map, _rev, _nxt
6246 */
6247
_prt(x,indent)6248 func _prt(x, indent)
6249 /* DOCUMENT _prt, list
6250 print every item in a list, recursing if some item is itself a list.
6251 SEE ALSO: _lst
6252 */
6253 {
6254 if (is_void(indent)) indent= "";
6255 if (typeof(x)!="list") {
6256 write,format="%s\n",indent+print(x);
6257 return; /* exit recursion */
6258 }
6259 write,format="%s\n",indent+"list items:";
6260 do {
6261 _prt, _car(x), indent+" "; /* recurse */
6262 x= _cdr(x);
6263 } while (!is_void(x));
6264 }
6265
_map(f__map,list__map)6266 func _map(f__map, list__map)
6267 /* DOCUMENT _map(f, list)
6268 return a list of the results of applying function F to each
6269 element of the input LIST in turn, as if by
6270 _lst(f(_car(list,1)),f(_car(list,2)),...)
6271 SEE ALSO: _lst
6272 */
6273 {
6274 /* all locals here must have weird names, since the function f will
6275 * very often rely on external variables for arguments not varying
6276 * in the input list, or for accumulated outputs */
6277 if (is_void(list__map)) return [];
6278 result__map= tail__map= _lst(f__map(_car(list__map)));
6279 for (list__map=_cdr(list__map) ;
6280 !is_void(list__map) ; list__map=_cdr(list__map)) {
6281 _cat, tail__map, _lst(f__map(_car(list__map)));
6282 tail__map= _cdr(tail__map);
6283 }
6284 return result__map;
6285 }
6286
_rev(list)6287 func _rev(list)
6288 /* DOCUMENT _rev(list)
6289 returns the input list in reverse order
6290 SEE ALSO: _lst
6291 */
6292 {
6293 if (is_void(list)) return;
6294 prev= [];
6295 for (;;) {
6296 tail= _cdr(list, 1, prev);
6297 if (is_void(tail)) return list;
6298 prev= list;
6299 list= tail;
6300 }
6301 }
6302
6303 func _nxt(&list)
6304 /* DOCUMENT item= _nxt(list)
6305 return first item in LIST, and set LIST to list of remaining
6306 items. If you are iterating through a list, this is the way
6307 to do it, since a loop on _car(list,i) with i varying from 1
6308 to _len(list) scales quadratically with the length of the list,
6309 while a loop on _nxt(list) scales linearly.
6310 SEE ALSO: _car, _lst
6311 */
6312 {
6313 item= _car(list);
6314 list= _cdr(list);
6315 return item;
6316 }
6317
6318 /*--------------------------------------------------------------------------*/
6319