This file was automatically generated from http://svn.pugscode.org/pugs/docs/Perl6/Spec/S29-functions.pod on Sat Aug 1 14:01:18 2009 GMT, revision 27701.
Synopsis 29: Builtin Functions
Rod Adams <rod@rodadams.net>
Larry Wall <larry@wall.org>
Aaron Sherman <ajs@ajs.com>
Mark Stosberg <mark@summersault.com>
Carl Mäsak <cmasak@gmail.com>
Moritz Lenz <moritz@faui2k3.org>
Tim Nelson <wayland@wayland.id.au>
Created: 12 Mar 2005
Last Modified: 30 May 2009
Version: 43
The document is a draft.
If you read the HTML version, it is generated from the pod in the pugs repository under /docs/Perl6/Spec/S29-functions.pod so edit it there in the SVN repository if you would like to make changes.
In Perl 6, all builtin functions belong to a named package (generally a
class or role). Not all
functions are guaranteed to be imported into the CORE scope.
In addition, the list of functions imported into CORE will be
subject to change with each release of Perl. Authors wishing to
"Future Proof" their code should either specifically import the
functions they will be using, or always refer to the functions by their
full name.
After 6.0.0 comes out, global aliases will not be removed lightly, and will never be removed at all without having gone through a deprecation cycle of at least a year. In any event, you can specify that you want the interface for a particular version of Perl, and that can be emulated by later versions of Perl to the extent that security updates allow.
Where code is given here, it is intended to define semantics, not to dictate implementation.
There is no particular difference between an operator and a function,
but for the sake of documentation, only functions declared without
specifying a grammatical category or with a category of term:
(see S02/"Bits and Pieces") will be described as "functions",
and everything else as "operators" which are outside of the scope
of this document. (See S03 for operators.)
In actual fact, most of the "functions" defined here are multi subs, or are multi methods that are also exported as multi subs. The Setting is responsible for importing all the standard multi subs from their various packages into the CORE lexical scope. See S02.
The following type declarations are assumed:
The root class of all "character" types, regardless of level.
This is a subtype of Str, limited to a length of 1 at it's highest
supported Unicode level.
The type name Char is aliased to the maximum supported Unicode level
in the current lexical scope (where "current" is taken to mean the
eventual lexical scope for generic code (roles and macros), not the
scope in which the generic code is defined). In other words, use Char
when you don't care which level you're writing for.
Subclasses (things that are isa AnyChar):
The short name for Grapheme is typically Char since that's the
default Unicode level. A grapheme is defined as a base codepoint plus
any subsequent "combining" codepoints that apply to that base codepoint.
Graphemes are always assigned a unique integer id which, in the case of
a grapheme that has a precomposed codepoint, happens to be the same as
that codepoint.
There is no short name for CharLingua because the type is meaningless
outside the scope of a particular language declaration. In fact,
CharLingua is itself an abstract type that cannot be instantiated.
Instead you have names like CharFrench, CharJapanese,
CharTurkish, etc. for instantiated CharLingua types.
(Plus the corresponding StrLingua types, presumably.)
subset Matcher of Object where { $_.can('ACCEPTS') };
Used to supply a test to match against. Assume ~~ will be used against it.
subset KeyExtractor of Code where { .signature === :(Any --> Any) };
subset Comparator of Code where { .signature === :(Any, Any --> Int ) };
subset OrderingPair of Pair where { .left ~~ KeyExtractor && .right ~~ Comparator };
subset Ordering where Signature | KeyExtractor | Comparator | OrderingPair | Whatever;
Used to handle comparisons between things. Generally this
ends up in functions like cmp(), eqv(), sort(),
min(), max(), etc., as a $by parameter which provides
the information on how two things compare relative to each other.
Note that eqv() and cmp() do almost but not the same thing
since with eqv() you don't care if two things are ordered
increasing or decreasing but only if they are the same or not.
Rather than declare an Equiving type declaration Ordering will
just do double duty.
A closure with arity of 2, which for ordering returns negative/zero/positive, signaling the first argument should be before/tied with/after the second. aka "The Perl 5 way".
For equivalence the closure returns either not 0 or 0 indicating if the first argument is equivalent or not to the second.
A closure with arity of 1, which returns the "key" by which
to compare. Values are compared using cmp for orderings
and eqv for equivalences, which in Perl 6 do different
comparisons depending on the types. (To get a Perl 5 string
ordering you must compare with leg instead.)
Internally the result of the KeyExtractor on a value should be cached.
Note that it is very easy to generate a simple KeyExtractor
using ~* for strings and +* for numbers, since with most
simple operators * returns a closure of one argument.
@sorted = sort +*, @unsorted; #ascending numeric
@sorted = sort -*, @unsorted; #descending numeric
eqv or cmp, such as <=> or leg.
If a signature is specified as a criterion, the signature is bound to each value and then each parameter does comparisons in positional order according to its type, as modified by its traits. Basically, the system will write the body of the key extraction and comparison subroutine for you based on the signature.
For ordering the list of positional parameter comparisons is reduced as if using [||] but all comparisons do not need to be performed if an early one determines an increasing or decreasing order. For equivalence the list is reduced as if using [&&].
An ordering of * does the default comparison for the operator:
@sorted = sort *, @unsorted;
context and caller functions".
context and caller functions".
multi eval ( Str|Buf $code, Grammar :$lang = CALLER::<$?PARSER>)
Execute $code as if it were code written in $lang. If $code
is of type Buf, the same decoding techniques are applied as a compiler
for $lang would usually do to input files.
The default for $lang is the language in effect at the exact
location of the eval call.
Returns whatever $code returns, or fails.
multi evalfile (Str $filename ; Grammar :$lang = Perl6)
Behaves like, and replaces Perl 5 do EXPR, with optional $lang
support.
multi exit (Int $status = 0)
Stops all program execution, and returns $status to the calling environment.
our Num multi sleep ( Num $for = Inf )
Attempt to sleep for up to $for seconds. Implementations are obligated
to support sub-second resolutions if that is at all possible.
See Synopsis 17: Concurrency for more details.
want function.
our Object method bless(Object::RepCandidate $candidate, *@protos, *%init_args)
Calling bless on any invocant (but typically a type object) to create a new
object with the same class as the invocant.
$candidate is used to provide the underlying representation of the object.
The default is P6opaque, but various other representations might be
desired, especially when interoperating with other languages. @protos and
%init_args both provide ways for values to be provided to the new
object, just like in the default new method.
bless automatically calls all appropriate BUILD routines by calling the
BUILDALL routine for the current class, which initializes the object in
least-derived to most-derived order. See S12/Objects
for more detailed information on object creation.
multi method chr( Int $grid: --> Char ) is export multi sub chr( Int *@grid --> Char ) multi method ord( Str $string: --> Int ) is export
chr takes zero or more integer grapheme ids and returns the
corresponding characters as a string. If any grapheme id is used
that represents a higher abstraction level than the current
lexical scope supports, that grapheme is converted to the
corresponding lower-level string of codepoints/bytes that would
be appropriate to the current context, just as any other Str
would be downgraded in context.
ord goes the other direction; it takes a string value and returns
character values as integers. In a scalar context, the return value
is the just the integer value of the first character in the string. In
a list context, the return value is the list of integers representing
the entire string. The definition of character is context dependent.
Normally it's a grapheme id, but under codepoints or bytes scopes,
the string is coerced to the appropriate low-level view and interpreted
as codepoints or bytes. Hence, under "use bytes" you will never see a
value larger than 256, and under "use codepoints" you will never see a
value larger than 0x10ffff. The only guarantee under "use graphemes"
(the default) is that the number returned will correspond to the
codepoint of the precomposed codepoint representing the grapheme, if
there is such a codepoint. Otherwise, the implementation is free to
return any unique id that larger than 0x10ffff. (The chr function
will know how to backtranslate such ids properly to codepoints or
bytes in any context. Note that we are assuming that every codepoints
context knows its normalization preferences, and every bytes context
also knows its encoding preferences. (These are knowable in the
lexical scope via the $?NF and $?ENC compile-time constants).)
our Item multi item ( $item )
Forces generic Item context on its argument, and returns it.
our List multi list ( *@list )
Forces List Context on it's arguments, and returns them.
our List multi slice ( *@list )
Forces the argument list to be evaluated in slice context.
(Slices are considered to be potentially multidimensional in Perl 6.)
A list of Captures will be transformed into a list of lists.
Equivalent to @@() (except that empty @@() means @@($/), while
empty slice() means a null slice).
The hash contextualizer
our Hash multi hash ( *@list )
Forces the argument list to be evaluated in hash context.
The expression is evaluated in list context (flattening any Captures),
then a hash will be created from the list, taken as a list of Pairs.
(Any element in the list that is not a Pair will pretend to be a key
and grab the next value in the list as its value.) Equivalent to
%() (except that empty %() means %($/), while
empty hash() means an empty hash).
our Num multi prefix:<:16> ( Str $hexstr ) our Num multi prefix:<:8> ( Str $octstr ) our Num multi prefix:<:2> ( Str $binstr ) our Num multi prefix:<:10> ( Str $decstr ) etc.
Interprets string as a number, with a default
hexadecimal/octal/binary/decimal radix. Any radix prefix (0b, 0d, 0x, 0o)
mentioned inside the string will override this operator (this statement is true: 10 == :8("0d10")), except 0b and 0d will be interpreted
as hex digits by :16 (hex("0d10") == :16 "0d10"). fails on failure.
These aren't really functions, syntactically, but adverbial forms that just happen to allow a parenthesize argument. But more typically you'll see
:4<222>
:16<deadbeef>
and such.
Replaces Perl 5 hex and oct.
our OS::Name multi gethost() our OS::Name multi gethost( Str $name, OS::Addfamily :$type ) our OS::Name multi method gethost( OS::Addr $addr: ) is export our OS::Name multi method gethost( URI $uri: ) is export
The gethost function operates on host naming or address information
and returns an OS::Name. An OS::Name is, minimally:
class OS::Name {
has Str $.name;
has OS::Addr $.addr;
has Array of Str @.aliases;
has Array of OS::Addr @.addrs;
}
Such names can apply to anything which has a name that maps to an address, however, in this case the name is a hostname and the address is some sort of network identifier (e.g. an IPV4 address when resolving hosts that have IPV4 addresses).
When stringified, an OS::Name yields its name. When
stringified, an OS::Addr yields its address in an
appropriate text format (e.g. "10.1.2.3" for an IPV4 address).
The optional type adverb can be passed when resolving a hostname,
and will filter the result to only those addresses that are of
the appropriate address family. This feature may be supported by
the underlying operating system, or Perl may emulate it.
Examples:
say "Connection from {$socket.peer.gethost}";
my $address = gethost("foo.example.com").addr;
my $hostname = gethost(:addr<"10.1.2.3">);
our Bool multi chroot ( Str $path = CALLER::<$_> )
On POSIX systems, changes the context of the current process such
that the "root" directory becomes $path and all rooted paths
(those that begin with a leading path separator) are relative to
that path. For security reasons, many operating systems limit
this functionality to the superuser. The return value will be
true on success.
our Str multi getlogin ()
Returns the username of the account running the program. This may
not be as secure as using getpwuid on some platforms.
our Bool multi kill ( OS::Signal $signal, Bool :$group, *@pids ) our Bool multi method kill ( Proc::PID $pid: OS::Signal $signal?, Bool :$group )
Sends the given $signal to the process(es) given and returns a boolean
value indicating success (true) if all of the processes existed and were
sent the signal and failure (false) if any of the processes did not exist
or the signal could not be delivered to them.
The $signal can be initialized from an integer signal number or a
string. Common signals are:
KILL - stop the process, do not allow it to exit gracefully TERM - stop the process, allow it to exit gracefully HUP - Hangup, often used as a request to re-run from scratch STOP - Pause execution CONT - Continue after a STOP
Consult your operating system documentation for the full list of signal names and numbers. For compatibility, a signal name may be prefixed with "SIG".
The method form may omit the signal. In this case, the default signal is
'TERM'.
If the :group named parameter is passed, kill will attempt to
send the signal to a process group rather than a single process.
This functionality is platform-specific.
The special signal 0 can be sent which does not actually deliver a
signal at all, and is used to determine if processes are still running:
say "Still running" if $proc.kill(0);
our Proc::Status multi run ( ; Str $command, :%env = %*ENV ) our Proc::Status multi run ( ; Str $path, *@args, :%env = %*ENV ) our Proc::Status multi run ( Str @path_and_args, :%env = %*ENV ) our Proc multi run ( ; Str $command, Bool :$bg!, :%env = %*ENV ) our Proc multi run ( ; Str $path, Bool :$bg!, *@args, :%env = %*ENV ) our Proc multi run ( Str @path_and_args, Bool :$bg!, :%env = %*ENV )
run executes an external program, and returns control to the caller
once the program has exited.
The default form expects a single string argument which contains the
full command-line. This command-line will be scanned for special
characters that the operating system's shell might interpret such as
; or embedded quotes. If any are found, the command will be run
through a sub-shell in an operating system specific fashion (on
POSIX systems, this means sh -c).
If called like this:
run( :path<'/some/path'>, 'arg1', 'arg2', ... )
or with a single array (containing both the path and arguments), then the path given is executed directly with no shell interpretation.
The return value is the exit status of the program, and can be evaluated in the following contexts:
Bool - True = success; False = failure Int - Exit status (per the .exit method)
See wait for more detail on how the Proc::Status object
is used.
On failure to execute, an undefined value is returned.
If the :bg named parameter is passed, the program will be executed
in the background, and the run command will return as soon as the
child process is created. This means that the object returned is
actually a Proc, which represents the created process.
[ Note: should the :bg form take rw filehandles or is that over-overloading the functionality of run? Should run be the new open with respect to executing external code? -ajs ]
[ Note: system() should be renamed to sys() or sh() or run() or some such to avoid P5-induced boolean inversion confusion, plus Huffmanize it a little better. I'm thinking run() might be best for MMD reasons. --law
Note: exec should also be renamed to something clearer and "final" and huffmanly longer. I'm thinking runinstead(). And maybe the function behind qq:x should be rungather() rather than readpipe(). -law ]
multi runinstead ( ; Str $path, *@args ) multi runinstead ( ; Str $command )
Identical to run except that it never returns. The executed program
replaces the currently running program in memory.
There are higher-level models of concurrency management in Perl (see S17/Concurrency). These functions are simply the lowest level tools
our Proc sub Processes::fork()
Creates a copy of the current process. Both processes return from
fork. The original process returns
the child process as a Proc object. The newly created process
returns the parent process as a Proc object. As with
any Proc object, the child process object numifies to the
process ID (OS dependent integer). However, the parent process object
numifies to 0 so that the child and parent can distinguish each other.
Typical usage would be:
if !defined(my $pid = fork) {
die "Error calling fork: $!";
} elsif $pid == 0 {
say "I am the new child!";
exit 0;
} else {
say "I am the parent of {+$pid}";
wait();
}
our Proc::Status multi method wait( Proc $process: *%options ) our Proc::Status multi wait ( Proc $process = -1, *%options )
Waits for a child process to terminate and returns the status object for the child. This status object will numify to the process ID of the child that exited.
Important Proc::Status methods:
.exit - Numeric exit value .pid - Process ID .signal - Signal number if any, otherwise 0
For historical reasons there is a .status method which is equal to:
($status.exit +< 8) +| $status.signal
If $process is supplied, then wait will only return when the given process
has exited. Either a full Proc object can be passed, or just a
numeric process ID. A -1 explicitly indicates that wait should return
immediately if any child process exits.
When called in this way, the returned Proc::Status object
will have a .pid of -1 (which is also what it numifies to) if
there was no such process to wait for.
The named options include:
WNOHANG = 1> is identical to
blocking = False>.
The following functions are classified by Apocalypse/Synopsis numbers.
chroot crypt getlogin /[get|set][pw|gr].*/ kill setpgrp setpriority times
... These are probably going to be part of POSIX, automatically imported to GLOBAL if the platform is the right one
These functions are exported into the default namespace
These functions which existed in perl5 still exist, but are not part of the default namespace any more.
The following functions can now be found in or replaced by something in the Container modules.
delete, exists, pop, push, shift, splice, unshift
The following functions can now be found in or replaced by something in the Numeric modules.
abs, atan2, cos, exp, log, rand, sqrt, sin
The following functions can now be found in or replaced by something in the IO modules.
accept, bind, binmode, chdir, chmod, chown, close, closedir, connect eof, fcntl, fileno, flock, getc, getsockname, getsockopt, glob, ioctl, link, listen lstat, mkdir, open, opendir, pipe, print, printf, read, readdir, readline, readlink readpipe, recv, rename, rewinddir, rmdir, say, seek, seekdir, select, send, setsockopt shutdown, socket, socketpair, stat, symlink, sysopen, sysread, sysseek syswrite, tell, telldir, truncate, umask, unlink
The following functions can now be found in or replaced by something in the Temporal modules.
gmtime, localtime, time
The following functions can now be found in or replaced by something in the String module.
chop, chomp, index, lc, lcfirst, pack, quotemeta, rindex, split, sprintf, substr, uc, ucfirst, unpack
Some of these are obsoleted only as general functions, and are still available by using the right packages. Others are obsoleted in that they're keywords, rather than functions (these are in their own section, below).
$num1 % $num2
Does a floating point modulus operation, i.e. 5.5 % 1 == 0.5 and 5 % 2.5 == 0.
use DB_File;
.perl method fills this role in Perl 6.
temp which, unlike local, defaults to not changing the value.
lock has been replaced by
is atomic.
pos function in Perl 6 because that would not allow a string
to be shared among threads. Generally you want to use $/.to for that now,
or keep your own position variable as a lexical.
&func.meta.signature; &func.^signature;
There is no ref() any more, since it was almost always used to get
the type name in Perl 5. If you really want the type name, you can
use $var.WHAT.perl. If you really want P5 ref
semantics, use Perl5::p5ref.
But if you're just wanting to test against a type, you're likely better off
performing an isa or does or can, or just $var ~~ TYPE.
These are replaced by container types. The compiler is free to assume that any lexical variable is never going to change its container type unless some representation is made to that effect in the declaration. Note: P5's tied() is roughly replaced by P6's variable().
XXX Examples?
my $foo is ....? is tie the meta operation on the container type for 'rebless' - macro tie ( $var, $class, *@args ) { CODE { variable($var).meta.rebless( $class, *@args ) } } )
endXXX
vec with declared buffer/array of bit, uint2,
uint4, etc.
wait can now be called with or without an optional process/pid.
The following were listed in Perl 5's perlfunc, but should now be considered keywords rather than functions.
last, my, next, no, our, package, return, sub, use
Not sure whether these are exported by default or not. Also, many may no longer exist; if so, they should be entered in the "Obsolete" section.
chroot crypt getlogin getpeername -- should this go on Pipe?
OS objects:
--Process getpgrp getppid getpriority setpgrp setpriority --Service getservbyname getservbyport --Protocol getprotobyname getprotobynumber --Network getnetbyaddr getnetbyname --Host gethostbyaddr gethostbyname
Please post errors and feedback to perl6-language. If you are making a general laundry list, please separate messages by topic.