=encoding utf8 =head1 TITLE Synopsis 29: Builtin Functions =head1 AUTHORS Rod Adams Larry Wall Aaron Sherman Mark Stosberg Carl Mäsak Moritz Lenz Tim Nelson Carlin Bingham =head1 Version Created: 12 Mar 2005 Last Modified: 24 Feb 2010 Version: 46 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. =head1 Notes 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 C 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. =head2 Operators vs. Functions 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 C (see L) will be described as "functions", and everything else as "operators" which are outside of the scope of this document. (See S03 for operators.) =head2 Multis vs. Functions 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. =head1 Type Declarations The following type declarations are assumed: =over =item AnyChar The root class of all "character" types, regardless of level. This is a subtype of C, limited to a length of 1 at its highest supported Unicode level. The type name C 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 C when you don't care which level you're writing for. Subclasses (things that are C): =over =item CharLingua (language-defined characters) =item Grapheme (language-independent graphemes) =item Codepoint =item Byte Yes, Byte is both a string and a number. =back The short name for C is typically C 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 C because the type is meaningless outside the scope of a particular language declaration. In fact, C is itself an abstract type that cannot be instantiated. Instead you have names like C, C, C, etc. for instantiated C types. (Plus the corresponding C types, presumably.) =item Matcher subset Matcher of Mu where none(Bool) Used to supply a test to match against. Assume C<~~> will be used against it. Booleans are forbidden because they almost always indicate a programming error where the argument has been evaluated too soon against the wrong C<$_>. For instance: grep $_ == 1, 1,2,3; # evaluating wrong $_, so forbidden grep { $_ == 1 }, 1,2,3; # okay grep * == 1, 1,2,3; # okay =item Ordering 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 C, C, C, etc., as a $by parameter which provides the information on how two things compare relative to each other. =over =item Comparator 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. =item KeyExtractor A closure with arity of 1, which returns the "key" by which to compare. Values are compared using C for orderings and C for equivalences, which in Perl 6 do different comparisons depending on the types. (To get a Perl 5 string ordering you must compare with C instead.) Internally the result of the KeyExtractor on a value should be cached. Note that it is very easy to generate a simple C using C<~*> for strings and C<+*> for numbers, since with most simple operators C<*> returns a closure of one argument. @sorted = sort +*, @unsorted; #ascending numeric @sorted = sort -*, @unsorted; #descending numeric =item OrderingPair A combination of the two methods above, for when one wishes to take advantage of the internal caching of keys that is expected to happen, but wishes to compare them with something other than C or C, such as C=E> or C. =item Signature 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 [&&]. =item Whatever An ordering of C<*> does the default comparison for the operator: @sorted = sort *, @unsorted; =back =back =head1 Function Packages =head2 Context =over =item caller See L and C functions">. =item callframe See L and C functions">. =item eval multi eval ( Str|Buf $code, Grammar :$lang = CALLER::<$?PARSER>) Execute C<$code> as if it were code written in C<$lang>. If C<$code> is of type C, the same decoding techniques are applied as a compiler for C<$lang> would usually do to input files. The default for C<$lang> is the language in effect at the exact location of the eval call. Returns whatever C<$code> returns, or fails. =item evalfile multi evalfile (Str $filename ; Grammar :$lang = Perl6) Behaves like, and replaces Perl 5 C, with optional C<$lang> support. =item exit multi exit (Int $status = 0) Stops all program execution, and returns C<$status> to the calling environment. =item sleep our Num multi sleep ( Num $for = Inf ) Attempt to sleep for up to C<$for> seconds. Implementations are obligated to support sub-second resolutions if that is at all possible. See C for more details. =item die multi die (@LIST) Throws a fatal Exception. The default exception handler prints each element of the list to $*ERR (STDERR). =item fail multi fail (Str $message) Can only be called inside a routine and causes the routine to C an unthrown exception; a C object which stringifies to C<$message>. If C is in effect where the routine was called from, it throws the exception. =back =head2 Conversions =over =item bless our Object method bless(Object::RepCandidate $candidate, *@protos, *%init_args) Calling C on any invocant (but typically a type object) to create a new object with the same class as the invocant. C<$candidate> is used to provide the underlying representation of the object. The default is C, but various other representations might be desired, especially when interoperating with other languages. C<@protos> and C<%init_args> both provide ways for values to be provided to the new object, just like in the default C method. C automatically calls all appropriate C routines by calling the C routine for the current class, which initializes the object in least-derived to most-derived order. See L for more detailed information on object creation. =item chr =item ord multi method chr( Int $grid: --> Char ) is export multi sub chr( Int *@grid --> Char ) multi method ord( Str $string: --> Int ) is export C 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 pragmatic context, just as any other Str would be downgraded in context. C goes the other direction; it takes a string value and returns character values as integers. In item context, the return value is the just the integer value of the first character in the string. In list context, the return value is the list of integers representing the entire string. The definition of character is pragma 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 C function will know how to backtranslate such ids properly to codepoints or bytes in any context. Note that we are assuming that every codepoint's context knows its normalization preferences, and every byte's context also knows its encoding preferences. (These are knowable in the lexical scope via the $?NF and $?ENC compile-time constants).) =item item our Item multi item ( $item ) Forces generic Item context on its argument, and returns it. =item flat our List multi flat ( *@list ) Forces flat context on its arguments, and returns them. The heavy work is done by the C<*@> binding. =item list our List multi list ( Iterable $item ) { $item.iterator.list } our List multi list ( List \$iter ) { $iter } Almost a no-op; just makes sure that $item can be iterated. =item flat our List multi flat ( *@list ) Forces flat context on its arguments, and returns them. The heavy work is done by the C<*@> binding. =item slice 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.) Any C within the list will be transformed into a C. The work is actually done by the binding to the C<**@> parameter. =item hash The C 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 Cs), then a hash will be created from the list, taken as a list of Cs. (Any element in the list that is not a C will pretend to be a key and grab the next value in the list as its value.) Equivalent to C<%()> (except that empty C<%()> means C<%($/)>, while empty C means an empty hash). =item :16, :8, :2, :10 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 (C). Cs 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 and such. Replaces Perl 5 C and C. =back =head2 OS =over =item gethost 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 C function operates on host naming or address information and returns an C. An C 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 C yields its name. When stringified, an C yields its address in an appropriate text format (e.g. "10.1.2.3" for an IPV4 address). The optional C 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">); =item chroot our Bool multi chroot ( Str $path = CALLER::<$_> ) On POSIX systems, changes the process context of the current process such that the "root" directory becomes C<$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. =item getlogin our Str multi getlogin () Returns the username of the account running the program. This may not be as secure as using C on some platforms. =item kill 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 C<$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 C<$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 C<'TERM'>. If the C<:group> named parameter is passed, C will attempt to send the signal to a process I rather than a single process. This functionality is platform-specific. The special signal C<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); =item run 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 ) C 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 C<;> 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 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 C for more detail on how the C object is used. On failure to execute, an undefined value is returned. If the C<: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 C, 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 ] =item runinstead multi runinstead ( ; Str $path, *@args ) multi runinstead ( ; Str $command ) Identical to C except that it never returns. The executed program replaces the currently running program in memory. =item syscall =back =head2 Concurrency There are higher-level models of concurrency management in Perl (see L). These functions are simply the lowest level tools =over =item fork our Proc sub Processes::fork() Creates a copy of the current process. Both processes return from C. The original process returns the I process as a C object. The newly created process returns the I process as a C 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 C<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(); } =item 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 C<.status> method which is equal to: ($status.exit +< 8) +| $status.signal If C<$process> is supplied, then wait will only return when the given process has exited. Either a full C object can be passed, or just a numeric process ID. A C<-1> explicitly indicates that wait should return immediately if any child process exits. When called in this way, the returned C object will have a C<.pid> of C<-1> (which is also what it numifies to) if there was no such process to wait for. The named options include: =over =item blocking Defaults to true. If set to false, this forces wait to return immediately. =item WNOHANG Exists for historical compatibility. C 1> is identical to C False>. =back =back =head2 Pending Apocalypse The following functions are classified by Apocalypse/Synopsis numbers. =over 4 =item A/S??: OS Interaction chroot crypt getlogin /[get|set][pw|gr].*/ kill setpgrp setpriority times ... These are probably going to be part of POSIX, automatically imported to GLOBAL B the platform is the right one =back =head2 Default Functions These functions are exported into the default namespace =over =item all -- see S32-setting-library/Containers.pod =item any -- see S32-setting-library/Containers.pod =item cat -- see S32-setting-library/Containers.pod =item classify -- see S32-setting-library/Containers.pod =item defined -- see S32-setting-library/Scalars.pod =item grep -- see S32-setting-library/Containers.pod =item first -- see S32-setting-library/Containers.pod =item keys -- see S32-setting-library/Containers.pod =item kv -- see S32-setting-library/Containers.pod =item join -- see S32-setting-library/Containers.pod =item map -- see S32-setting-library/Containers.pod =item max -- see S32-setting-library/Containers.pod =item min -- see S32-setting-library/Containers.pod =item none -- see S32-setting-library/Containers.pod =item one -- see S32-setting-library/Containers.pod =item pairs -- see S32-setting-library/Containers.pod =item print -- see S32-setting-library/IO.pod =item printf -- see S32-setting-library/IO.pod =item roundrobin -- see S32-setting-library/Containers.pod =item pick -- see S32-setting-library/Containers.pod =item reduce -- see S32-setting-library/Containers.pod =item reverse -- see S32-setting-library/Containers.pod =item say -- see S32-setting-library/IO.pod =item shape -- see S32-setting-library/Containers.pod =item sort -- see S32-setting-library/Containers.pod =item srand -- see S32-setting-library/Numeric.pod =item undefine -- see S32-setting-library/Scalars.pod =item uri -- see S32-setting-library/IO.pod =item values -- see S32-setting-library/Containers.pod =item warn -- see S32-setting-library/Any.pod =item zip -- see S32-setting-library/Containers.pod =back =head2 Non-default Functions These functions which existed in perl5 still exist, but are not part of the default namespace any more. =head3 Container The following functions can now be found in or replaced by something in the Container modules. delete, exists, pop, push, shift, splice, unshift =head3 Numeric See L. =head3 IO 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 =head3 Temporal The following functions can now be found in or replaced by something in the Temporal modules. gmtime, localtime, time =head3 String 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 =head2 Obsolete Functions 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). =over 4 =item % $num1 % $num2 Does a floating point modulo operation, i.e. 5.5 % 1 == 0.5 and 5 % 2.5 == 0. =item dbmopen, dbmclose use DB_File; =item dump Dumped. Restoring from core dumps is in any event not very useful on modern virtual-memory operating systems. Startup acceleration should be accomplished using a precompiler of some kind (details will be very implementation specific), or a pre-forking daemon such as Perl 5's App::Persistant (which will be an external module when it is ported). =item each See .pairs() method, above. =item endpwent, endgrent, endservent, endprotoent, endnetent, endhostent The NameServices role in S16 covers most of these. =item format, formline See Exegesis 7. =item getgrgid, getgrnam, getpwnam, getpwuid The User and Group roles in S16 cover most of these. =item getpwent, getgrent, getservent, getnetent, gethostent The NameServices role in S16 covers most of these. =item length() This word is banned in Perl 6. You must specify units. In practise, this probably means you want Str.chars(), although it could be Str.bytes(), or even something else. See S32-setting-library/String for details. =item msgctl, msgget, msgrcv, msgsnd See IPC::SysV =item local Replaced by C which, unlike C, defaults to not changing the value. =item lock See L. C has been replaced by C. =item pos There is no C function in Perl 6 because that would not allow a string to be shared among threads. Generally you want to use C<$/.to> for that now, or keep your own position variable as a lexical. =item prototype &func.meta.signature; &func.^signature; =item ref 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 C<$var.WHAT.perl>. If you really want P5 ref semantics, use C. But if you're just wanting to test against a type, you're likely better off performing an C or C or C, or just C<$var ~~ TYPE>. =item reset Was there a I use for this? =item semctl, semget, semop See IPC::SysV; =item setpwent, setgrent, setservent, setprotoent, setnetent, sethostent The NameServices role in S16 covers most of these. =item shmctl, shmget, shmread, shmwrite See IPC::SysV; =item study Algorithm was too Anglo-centric. Could be brought back if generalized somehow. =item tie, tied 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 =item untie See notes on "tie", above, but basically these are replaced with container classes. =item vec Should replace C with declared buffer/array of C, C, C, etc. =item waitpid C can now be called with or without an optional process/pid. =item write See Exegesis 7. =back =head3 Keywords 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 =head1 Default Export Questions 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. =over =item Signal-related alarm kill =item OS or library related 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 =item Flow control succeed proceed redo =item Other bless caller chr die do eval exec exit fork goto hex import int oct ord require scalar sleep state syscall system times utime wait =back =head1 Additions Please post errors and feedback to perl6-language. If you are making a general laundry list, please separate messages by topic. =for vim:set expandtab sw=4: