X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlsub.pod;h=b308298858a1e38ab065534962df7ff428711035;hb=a2eb900354d7492c5b0c2f521e88387de8974900;hp=1f5201a4c7b8df4449c4f4257d431a41d3268920;hpb=748a93069b3d16374a9859d1456065dd3ae11394;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlsub.pod b/pod/perlsub.pod index 1f5201a..b308298 100644 --- a/pod/perlsub.pod +++ b/pod/perlsub.pod @@ -6,8 +6,11 @@ perlsub - Perl subroutines To declare subroutines: - sub NAME; # A "forward" declaration. - sub NAME BLOCK # A declaration and a definition. + sub NAME; # A "forward" declaration. + sub NAME(PROTO); # ditto, but with prototypes + + sub NAME BLOCK # A declaration and a definition. + sub NAME(PROTO) BLOCK # ditto, but with prototypes To define an anonymous subroutine at runtime: @@ -19,42 +22,57 @@ To import subroutines: To call subroutines: - &NAME # Passes current @_ to subroutine. - &NAME(LIST); # Parens required with & form. NAME(LIST); # & is optional with parens. NAME LIST; # Parens optional if predeclared/imported. + &NAME; # Passes current @_ to subroutine. =head1 DESCRIPTION -Any arguments passed to the routine come in as array @_, that is -($_[0], $_[1], ...). The array @_ is a local array, but its values are -references to the actual scalar parameters. The return value of the -subroutine is the value of the last expression evaluated, and can be -either an array value or a scalar value. Alternatively, a return -statement may be used to specify the returned value and exit the -subroutine. To create local variables see the local() and my() -operators. - -A subroutine may be called using the "&" prefix. The "&" is optional in Perl -5, and so are the parens if the subroutine has been predeclared. -(Note, however, that the "&" is I optional when you're just naming the -subroutine, such as when it's used as an argument to defined() or -undef(). Nor is it optional when you want to do an indirect subroutine -call with a subroutine name or reference using the C<&$subref()> or -C<&{$subref}()> constructs. See L for more on that.) +Like many languages, Perl provides for user-defined subroutines. These +may be located anywhere in the main program, loaded in from other files +via the C, C, or C keywords, or even generated on the +fly using C or anonymous subroutines (closures). You can even call +a function indirectly using a variable containing its name or a CODE reference +to it, as in C<$var = \&function>. + +The Perl model for function call and return values is simple: all +functions are passed as parameters one single flat list of scalars, and +all functions likewise return to their caller one single flat list of +scalars. Any arrays or hashes in these call and return lists will +collapse, losing their identities--but you may always use +pass-by-reference instead to avoid this. Both call and return lists may +contain as many or as few scalar elements as you'd like. (Often a +function without an explicit return statement is called a subroutine, but +there's really no difference from the language's perspective.) + +Any arguments passed to the routine come in as the array @_. Thus if you +called a function with two arguments, those would be stored in C<$_[0]> +and C<$_[1]>. The array @_ is a local array, but its values are implicit +references (predating L) to the actual scalar parameters. The +return value of the subroutine is the value of the last expression +evaluated. Alternatively, a return statement may be used to specify the +returned value and exit the subroutine. If you return one or more arrays +and/or hashes, these will be flattened together into one large +indistinguishable list. + +Perl does not have named formal parameters, but in practice all you do is +assign to a my() list of these. Any variables you use in the function +that aren't declared private are global variables. For the gory details +on creating private variables, see the sections below on L<"Private +Variables via my()"> and L. To create +protected environments for a set of functions in a separate package (and +probably a separate file), see L. Example: - sub MAX { - my $max = pop(@_); + sub max { + my $max = shift(@_); foreach $foo (@_) { $max = $foo if $max < $foo; } - $max; + return $max; } - - ... - $bestday = &MAX($mon,$tue,$wed,$thu,$fri); + $bestday = max($mon,$tue,$wed,$thu,$fri); Example: @@ -62,7 +80,7 @@ Example: # that start with whitespace sub get_line { - $thisline = $lookahead; + $thisline = $lookahead; # GLOBAL VARIABLES!! LINE: while ($lookahead = ) { if ($lookahead =~ /^[ \t]/) { $thisline .= $lookahead; @@ -83,44 +101,327 @@ Use array assignment to a local list to name your formal arguments: sub maybeset { my($key, $value) = @_; - $foo{$key} = $value unless $foo{$key}; + $Foo{$key} = $value unless $Foo{$key}; } -This also has the effect of turning call-by-reference into -call-by-value, since the assignment copies the values. +This also has the effect of turning call-by-reference into call-by-value, +since the assignment copies the values. Otherwise a function is free to +do in-place modifications of @_ and change its callers values. + + upcase_in($v1, $v2); # this changes $v1 and $v2 + sub upcase_in { + for (@_) { tr/a-z/A-Z/ } + } + +You aren't allowed to modify constants in this way, of course. If an +argument were actually literal and you tried to change it, you'd take a +(presumably fatal) exception. For example, this won't work: + + upcase_in("frederick"); + +It would be much safer if the upcase_in() function +were written to return a copy of its parameters instead +of changing them in place: + + ($v3, $v4) = upcase($v1, $v2); # this doesn't + sub upcase { + my @parms = @_; + for (@parms) { tr/a-z/A-Z/ } + # wantarray checks if we were called in list context + return wantarray ? @parms : $parms[0]; + } + +Notice how this (unprototyped) function doesn't care whether it was passed +real scalars or arrays. Perl will see everything as one big long flat @_ +parameter list. This is one of the ways where Perl's simple +argument-passing style shines. The upcase() function would work perfectly +well without changing the upcase() definition even if we fed it things +like this: + + @newlist = upcase(@list1, @list2); + @newlist = upcase( split /:/, $var ); + +Do not, however, be tempted to do this: + + (@a, @b) = upcase(@list1, @list2); + +Because like its flat incoming parameter list, the return list is also +flat. So all you have managed to do here is stored everything in @a and +made @b an empty list. See L for alternatives. + +A subroutine may be called using the "&" prefix. The "&" is optional in +Perl 5, and so are the parens if the subroutine has been predeclared. +(Note, however, that the "&" is I optional when you're just naming +the subroutine, such as when it's used as an argument to defined() or +undef(). Nor is it optional when you want to do an indirect subroutine +call with a subroutine name or reference using the C<&$subref()> or +C<&{$subref}()> constructs. See L for more on that.) Subroutines may be called recursively. If a subroutine is called using -the "&" form, the argument list is optional. If omitted, no @_ array is -set up for the subroutine; the @_ array at the time of the call is -visible to subroutine instead. +the "&" form, the argument list is optional, and if omitted, no @_ array is +set up for the subroutine: the @_ array at the time of the call is +visible to subroutine instead. This is an efficiency mechanism that +new users may wish to avoid. &foo(1,2,3); # pass three arguments foo(1,2,3); # the same foo(); # pass a null list &foo(); # the same - &foo; # pass no arguments--more efficient -If a module wants to create a private subroutine that cannot be called -from outside the module, it can declare a lexical variable containing -an anonymous sub reference: + &foo; # foo() get current args, like foo(@_) !! + foo; # like foo() IFF sub foo pre-declared, else "foo" + +Not only does the "&" form make the argument list optional, but it also +disables any prototype checking on the arguments you do provide. This +is partly for historical reasons, and partly for having a convenient way +to cheat if you know what you're doing. See the section on Prototypes below. + +=head2 Private Variables via my() + +Synopsis: + + my $foo; # declare $foo lexically local + my (@wid, %get); # declare list of variables local + my $foo = "flurp"; # declare $foo lexical, and init it + my @oof = @bar; # declare @oof lexical, and init it + +A "my" declares the listed variables to be confined (lexically) to the +enclosing block, subroutine, C, or C'd file. If +more than one value is listed, the list must be placed in parens. All +listed elements must be legal lvalues. Only alphanumeric identifiers may +be lexically scoped--magical builtins like $/ must currently be localized with +"local" instead. + +Unlike dynamic variables created by the "local" statement, lexical +variables declared with "my" are totally hidden from the outside world, +including any called subroutines (even if it's the same subroutine called +from itself or elsewhere--every call gets its own copy). + +(An eval(), however, can see the lexical variables of the scope it is +being evaluated in so long as the names aren't hidden by declarations within +the eval() itself. See L.) + +The parameter list to my() may be assigned to if desired, which allows you +to initialize your variables. (If no initializer is given for a +particular variable, it is created with the undefined value.) Commonly +this is used to name the parameters to a subroutine. Examples: + + $arg = "fred"; # "global" variable + $n = cube_root(27); + print "$arg thinks the root is $n\n"; + fred thinks the root is 3 + + sub cube_root { + my $arg = shift; # name doesn't matter + $arg **= 1/3; + return $arg; + } + +The "my" is simply a modifier on something you might assign to. So when +you do assign to the variables in its argument list, the "my" doesn't +change whether those variables is viewed as a scalar or an array. So + + my ($foo) = ; + my @FOO = ; + +both supply a list context to the righthand side, while + + my $foo = ; + +supplies a scalar context. But the following only declares one variable: - my $subref = sub { ... } - &$subref(1,2,3); + my $foo, $bar = 1; -As long as the reference is never returned by any function within the module, -no outside module can see the subroutine, since its name is not in any -package's symbol table. +That has the same effect as -=head2 Passing Symbol Table Entries + my $foo; + $bar = 1; -[Note: The mechanism described in this section works fine in Perl 5, but -the new reference mechanism is generally easier to work with. See L.] +The declared variable is not introduced (is not visible) until after +the current statement. Thus, + + my $x = $x; + +can be used to initialize the new $x with the value of the old $x, and +the expression + + my $x = 123 and $x == 123 + +is false unless the old $x happened to have the value 123. + +Some users may wish to encourage the use of lexically scoped variables. +As an aid to catching implicit references to package variables, +if you say + + use strict 'vars'; + +then any variable reference from there to the end of the enclosing +block must either refer to a lexical variable, or must be fully +qualified with the package name. A compilation error results +otherwise. An inner block may countermand this with S<"no strict 'vars'">. + +A my() has both a compile-time and a run-time effect. At compile time, +the compiler takes notice of it; the principle usefulness of this is to +quiet C. The actual initialization doesn't happen +until run time, so gets executed every time through a loop. + +Variables declared with "my" are not part of any package and are therefore +never fully qualified with the package name. In particular, you're not +allowed to try to make a package variable (or other global) lexical: + + my $pack::var; # ERROR! Illegal syntax + my $_; # also illegal (currently) + +In fact, a dynamic variable (also known as package or global variables) +are still accessible using the fully qualified :: notation even while a +lexical of the same name is also visible: + + package main; + local $x = 10; + my $x = 20; + print "$x and $::x\n"; + +That will print out 20 and 10. + +You may declare "my" variables at the outer most scope of a file to +totally hide any such identifiers from the outside world. This is similar +to a C's static variables at the file level. To do this with a subroutine +requires the use of a closure (anonymous function). If a block (such as +an eval(), function, or C) wants to create a private subroutine +that cannot be called from outside that block, it can declare a lexical +variable containing an anonymous sub reference: + + my $secret_version = '1.001-beta'; + my $secret_sub = sub { print $secret_version }; + &$secret_sub(); + +As long as the reference is never returned by any function within the +module, no outside module can see the subroutine, since its name is not in +any package's symbol table. Remember that it's not I called +$some_pack::secret_version or anything; it's just $secret_version, +unqualified and unqualifiable. + +This does not work with object methods, however; all object methods have +to be in the symbol table of some package to be found. + +Just because the lexical variable is lexically (also called statically) +scoped doesn't mean that within a function it works like a C static. It +normally works more like a C auto. But here's a mechanism for giving a +function private variables with both lexical scoping and a static +lifetime. If you do want to create something like C's static variables, +just enclose the whole function in an extra block, and put the +static variable outside the function but in the block. + + { + my $secret_val = 0; + sub gimme_another { + return ++$secret_val; + } + } + # $secret_val now becomes unreachable by the outside + # world, but retains its value between calls to gimme_another + +If this function is being sourced in from a separate file +via C or C, then this is probably just fine. If it's +all in the main program, you'll need to arrange for the my() +to be executed early, either by putting the whole block above +your pain program, or more likely, merely placing a BEGIN +sub around it to make sure it gets executed before your program +starts to run: + + sub BEGIN { + my $secret_val = 0; + sub gimme_another { + return ++$secret_val; + } + } + +See L about the BEGIN function. + +=head2 Temporary Values via local() + +B: In general, you should be using "my" instead of "local", because +it's faster and safer. Execeptions to this include the global punctuation +variables, filehandles and formats, and direct manipulation of the Perl +symbol table itself. Format variables often use "local" though, as do +other variables whose current value must be visible to called +subroutines. + +Synopsis: + + local $foo; # declare $foo dynamically local + local (@wid, %get); # declare list of variables local + local $foo = "flurp"; # declare $foo dynamic, and init it + local @oof = @bar; # declare @oof dynamic, and init it + + local *FH; # localize $FH, @FH, %FH, &FH ... + local *merlyn = *randal; # now $merlyn is really $randal, plus + # @merlyn is really @randal, etc + local *merlyn = 'randal'; # SAME THING: promote 'randal' to *randal + local *merlyn = \$randal; # just alias $merlyn, not @merlyn etc + +A local() modifies its listed variables to be local to the enclosing +block, (or subroutine, C or C) and I. A local() just gives temporary values to global +(meaning package) variables. This is known as dynamic scoping. Lexical +scoping is done with "my", which works more like C's auto declarations. + +If more than one variable is given to local(), they must be placed in +parens. All listed elements must be legal lvalues. This operator works +by saving the current values of those variables in its argument list on a +hidden stack and restoring them upon exiting the block, subroutine or +eval. This means that called subroutines can also reference the local +variable, but not the global one. The argument list may be assigned to if +desired, which allows you to initialize your local variables. (If no +initializer is given for a particular variable, it is created with an +undefined value.) Commonly this is used to name the parameters to a +subroutine. Examples: + + for $i ( 0 .. 9 ) { + $digits{$i} = $i; + } + # assume this function uses global %digits hash + parse_num(); + + # now temporarily add to %digits hash + if ($base12) { + # (NOTE: not claiming this is efficient!) + local %digits = (%digits, 't' => 10, 'e' => 11); + parse_num(); # parse_num gets this new %digits! + } + # old %digits restored here + +Because local() is a run-time command, and so gets executed every time +through a loop. In releases of Perl previous to 5.0, this used more stack +storage each time until the loop was exited. Perl now reclaims the space +each time through, but it's still more efficient to declare your variables +outside the loop. + +A local is simply a modifier on an lvalue expression. When you assign to +a localized variable, the local doesn't change whether its list is viewed +as a scalar or an array. So + + local($foo) = ; + local @FOO = ; + +both supply a list context to the righthand side, while + + local $foo = ; + +supplies a scalar context. + +=head2 Passing Symbol Table Entries (typeglobs) + +[Note: The mechanism described in this section was originally the only +way to simulate pass-by-reference in older versions of Perl. While it +still works fine in modern versions, the new reference mechanism is +generally easier to work with. See below.] Sometimes you don't want to pass the value of an array to a subroutine but rather the name of it, so that the subroutine can modify the global copy of it rather than working with a local copy. In perl you can -refer to all the objects of a particular name by prefixing the name +refer to all objects of a particular name by prefixing the name with a star: C<*foo>. This is often known as a "type glob", since the star on the front can be thought of as a wildcard match for all the funny prefix characters on variables and subroutines and such. @@ -149,9 +450,262 @@ an array. It will certainly be faster to pass the typeglob (or reference). Even if you don't want to modify an array, this mechanism is useful for passing multiple arrays in a single LIST, since normally the LIST mechanism will merge all the array values so that you can't extract out -the individual arrays. +the individual arrays. For more on typeglobs, see L. + +=head2 Pass by Reference + +If you want to pass more than one array or hash into a function--or +return them from it--and have them maintain their integrity, +then you're going to have to use an explicit pass-by-reference. +Before you do that, you need to understand references as detailed in L. +This section may not make much sense to you otherwise. + +Here are a few simple examples. First, let's pass in several +arrays to a function and have it pop all of then, return a new +list of all their former last elements: + + @tailings = popmany ( \@a, \@b, \@c, \@d ); + + sub popmany { + my $aref; + my @retlist = (); + foreach $aref ( @_ ) { + push @retlist, pop @$aref; + } + return @retlist; + } + +Here's how you might write a function that returns a +list of keys occurring in all the hashes passed to it: + + @common = inter( \%foo, \%bar, \%joe ); + sub inter { + my ($k, $href, %seen); # locals + foreach $href (@_) { + while ( $k = each %$href ) { + $seen{$k}++; + } + } + return grep { $seen{$_} == @_ } keys %seen; + } + +So far, we're just using the normal list return mechanism. +What happens if you want to pass or return a hash? Well, +if you're only using one of them, or you don't mind them +concatenating, then the normal calling convention is ok, although +a little expensive. + +Where people get into trouble is here: + + (@a, @b) = func(@c, @d); +or + (%a, %b) = func(%c, %d); + +That syntax simply won't work. It just sets @a or %a and clears the @b or +%b. Plus the function didn't get passed into two separate arrays or +hashes: it got one long list in @_, as always. + +If you can arrange for everyone to deal with this through references, it's +cleaner code, although not so nice to look at. Here's a function that +takes two array references as arguments, returning the two array elements +in order of how many elements they have in them: + + ($aref, $bref) = func(\@c, \@d); + print "@$aref has more than @$bref\n"; + sub func { + my ($cref, $dref) = @_; + if (@$cref > @$dref) { + return ($cref, $dref); + } else { + return ($dref, $cref); + } + } + +It turns out that you can actually do this also: + + (*a, *b) = func(\@c, \@d); + print "@a has more than @b\n"; + sub func { + local (*c, *d) = @_; + if (@c > @d) { + return (\@c, \@d); + } else { + return (\@d, \@c); + } + } + +Here we're using the typeglobs to do symbol table aliasing. It's +a tad subtle, though, and also won't work if you're using my() +variables, since only globals (well, and local()s) are in the symbol table. + +If you're passing around filehandles, you could usually just use the bare +typeglob, like *STDOUT, but typeglobs references would be better because +they'll still work properly under C. For example: + + splutter(\*STDOUT); + sub splutter { + my $fh = shift; + print $fh "her um well a hmmm\n"; + } + + $rec = get_rec(\*STDIN); + sub get_rec { + my $fh = shift; + return scalar <$fh>; + } + +If you're planning on generating new filehandles, you could do this: + + sub openit { + my $name = shift; + local *FH; + return open (FH, $path) ? \*FH : undef; + } + +Although that will actually produce a small memory leak. See the bottom +of L for a somewhat cleaner way using the FileHandle +functions supplied with the POSIX package. + +=head2 Prototypes + +As of the 5.002 release of perl, if you declare + + sub mypush (\@@) + +then mypush() takes arguments exactly like push() does. The declaration +of the function to be called must be visible at compile time. The prototype +only affects the interpretation of new-style calls to the function, where +new-style is defined as not using the C<&> character. In other words, +if you call it like a builtin function, then it behaves like a builtin +function. If you call it like an old-fashioned subroutine, then it +behaves like an old-fashioned subroutine. It naturally falls out from +this rule that prototypes have no influence on subroutine references +like C<\&foo> or on indirect subroutine calls like C<&{$subref}>. + +Method calls are not influenced by prototypes either, because the +function to be called is indeterminate at compile time, since it depends +on inheritance. + +Since the intent is primarily to let you define subroutines that work +like builtin commands, here are the prototypes for some other functions +that parse almost exactly like the corresponding builtins. + + Declared as Called as + + sub mylink ($$) mylink $old, $new + sub myvec ($$$) myvec $var, $offset, 1 + sub myindex ($$;$) myindex &getstring, "substr" + sub mysyswrite ($$$;$) mysyswrite $buf, 0, length($buf) - $off, $off + sub myreverse (@) myreverse $a,$b,$c + sub myjoin ($@) myjoin ":",$a,$b,$c + sub mypop (\@) mypop @array + sub mysplice (\@$$@) mysplice @array,@array,0,@pushme + sub mykeys (\%) mykeys %{$hashref} + sub myopen (*;$) myopen HANDLE, $name + sub mypipe (**) mypipe READHANDLE, WRITEHANDLE + sub mygrep (&@) mygrep { /foo/ } $a,$b,$c + sub myrand ($) myrand 42 + sub mytime () mytime + +Any backslashed prototype character represents an actual argument +that absolutely must start with that character. The value passed +to the subroutine (as part of C<@_>) will be a reference to the +actual argument given in the subroutine call, obtained by applying +C<\> to that argument. + +Unbackslashed prototype characters have special meanings. Any +unbackslashed @ or % eats all the rest of the arguments, and forces +list context. An argument represented by $ forces scalar context. An +& requires an anonymous subroutine, which, if passed as the first +argument, does not require the "sub" keyword or a subsequent comma. A +* does whatever it has to do to turn the argument into a reference to a +symbol table entry. + +A semicolon separates mandatory arguments from optional arguments. +(It is redundant before @ or %.) + +Note how the last three examples above are treated specially by the parser. +mygrep() is parsed as a true list operator, myrand() is parsed as a +true unary operator with unary precedence the same as rand(), and +mytime() is truly argumentless, just like time(). That is, if you +say + + mytime +2; + +you'll get mytime() + 2, not mytime(2), which is how it would be parsed +without the prototype. + +The interesting thing about & is that you can generate new syntax with it: + + sub try (&$) { + my($try,$catch) = @_; + eval { &$try }; + if ($@) { + local $_ = $@; + &$catch; + } + } + sub catch (&) { @_ } + + try { + die "phooey"; + } catch { + /phooey/ and print "unphooey\n"; + }; + +That prints "unphooey". (Yes, there are still unresolved +issues having to do with the visibility of @_. I'm ignoring that +question for the moment. (But note that if we make @_ lexically +scoped, those anonymous subroutines can act like closures... (Gee, +is this sounding a little Lispish? (Nevermind.)))) + +And here's a reimplementation of grep: + + sub mygrep (&@) { + my $code = shift; + my @result; + foreach $_ (@_) { + push(@result, $_) if &$code; + } + @result; + } -=head2 Overriding builtin functions +Some folks would prefer full alphanumeric prototypes. Alphanumerics have +been intentionally left out of prototypes for the express purpose of +someday in the future adding named, formal parameters. The current +mechanism's main goal is to let module writers provide better diagnostics +for module users. Larry feels the notation quite understandable to Perl +programmers, and that it will not intrude greatly upon the meat of the +module, nor make it harder to read. The line noise is visually +encapsulated into a small pill that's easy to swallow. + +It's probably best to prototype new functions, not retrofit prototyping +into older ones. That's because you must be especially careful about +silent impositions of differing list versus scalar contexts. For example, +if you decide that a function should take just one parameter, like this: + + sub func ($) { + my $n = shift; + print "you gave me $n\n"; + } + +and someone has been calling it with an array or expression +returning a list: + + func(@foo); + func( split /:/ ); + +Then you've just supplied an automatic scalar() in front of their +argument, which can be more than a bit surprising. The old @foo +which used to hold one thing doesn't get passed in. Instead, +the func() now gets passed in 1, that is, the number of elments +in @foo. And the split() gets called in a scalar context and +starts scribbling on your @_ parameter list. + +This is all very powerful, of course, and should only be used in moderation +to make the world a better place. + +=head2 Overriding Builtin Functions Many builtin functions may be overridden, though this should only be tried occasionally and for good reason. Typically this might be @@ -201,10 +755,37 @@ question using eval, and then execute that subroutine using a special form of "goto" that erases the stack frame of the C routine without a trace. (See the standard C module, for example.) But an C routine can also just emulate the routine and never -define it. A good example of this is the standard Shell module, which +define it. For example, let's pretend that a function that wasn't defined +should just call system() with those arguments. All you'd do is this: + + sub AUTOLOAD { + my $program = $AUTOLOAD; + $program =~ s/.*:://; + system($program, @_); + } + date(); + who('am', i'); + ls('-l'); + +In fact, if you preclare the functions you want to call that way, you don't +even need the parentheses: + + use subs qw(date who ls); + date; + who "am", "i"; + ls -l; + +A more complete example of this is the standard Shell module, which can treat undefined subroutine calls as calls to Unix programs. -There are mechanisms available for modules to help them split themselves -up into autoloadable files to be used with the standard AutoLoader module. -See the document on extensions. +Mechanisms are available for modules writers to help split the modules +up into autoloadable files. See the standard AutoLoader module described +in L, the standard SelfLoader modules in L, and +the document on adding C functions to perl code in L. + +=head1 SEE ALSO +See L for more on references. See L if you'd +like to learn about calling C subroutines from perl. See +L to learn about bundling up your functions in +separate files.