This file has been translated from LaTeX by HeVeA.

File: omake-doc, Node: Subsection 10-5-8,	Next: Subsection 10-5-9,	Prev: Subsection 10-5-7,	Up: Section 10-5


10.5.8  readlink, readlink-raw
==============================
\@n
ame{function:readlink-raw}
<<   $(readlink node...) : Node
        node : Node
     $(readlink-raw node...) : String
        node : Node
>>

  The readlink function reads the value of a symbolic link. 

File: omake-doc, Node: Subsection 10-5-9,	Next: Subsection 10-5-10,	Prev: Subsection 10-5-8,	Up: Section 10-5


10.5.9  chmod
=============

<<   chmod(mode, dst...)
        mode : Int
        dst : Node or Channel
     chmod(mode dst...)
        mode : String
        dst : Node Sequence
     raises RuntimeException
>>

  The chmod function changes the permissions of the targets.
  Options: 

 -v  Explain what is happening. 
 -r  Change files and directories recursively. 
 -f  Continue on errors. 
 --  Interpret the remaining argument literally. 


File: omake-doc, Node: Subsection 10-5-10,	Next: Subsection 10-5-11,	Prev: Subsection 10-5-9,	Up: Section 10-5


10.5.10  chown
==============

<<   chown(uid, gid, node...)
        uid : Int
        gid : Int
        node : Node or Channel
     chown(uid, node...)
        uid : Int
        node : Node or Channel
     raises RuntimeException
>>

  The chown function changes the user and group id of the file. If the
gid is not specified, it is not changed. If either id is -1, that id is
not changed. 

File: omake-doc, Node: Subsection 10-5-11,	Next: Subsection 10-5-12,	Prev: Subsection 10-5-10,	Up: Section 10-5


10.5.11  utimes
===============

<<   utimes(atime, mtime, node...)
        atime : Float
        mtime : Float
        node : Node
     raises RuntimeException
>>

  The utimes function changes the access and modification times of the
files. 

File: omake-doc, Node: Subsection 10-5-12,	Next: Subsection 10-5-13,	Prev: Subsection 10-5-11,	Up: Section 10-5


10.5.12  truncate
=================

<<   truncate(length, node...)
         length : Int
         node : Node or Channel
     raises RuntimeException
>>

  The truncate function truncates a file to the given length. 

File: omake-doc, Node: Subsection 10-5-13,	Prev: Subsection 10-5-12,	Up: Section 10-5


10.5.13  umask
==============

<<    $(umask mode) : Int
         mode : Int
      raises RuntimeException
>>

  Sets the file mode creation mask. The previous mask is returned. This
value is not scoped, changes have global effect. 

File: omake-doc, Node: Section 10-6,	Next: Section 10-7,	Prev: Section 10-5,	Up: Chapter 10


10.6  vmount
************


* Menu:

* Subsection 10-6-1::	vmount
* Subsection 10-6-2::	vmount-map
* Subsection 10-6-3::	add-project-directories
* Subsection 10-6-4::	remove-project-directories


File: omake-doc, Node: Subsection 10-6-1,	Next: Subsection 10-6-2,	Up: Section 10-6


10.6.1  vmount
==============

<<    vmount(src, dst)
         src, dst : Dir
      vmount(flags, src, dst)
         flags : String
         src, dst : Dir
>>

  "Mount" the src directory on the dst directory. This is a virtual
mount, changing the behavior of the $(file ...) function. When the
$(file str) function is used, the resulting file is taken relative to
the src directory if the file exists. Otherwise, the file is relative to
the current directory.
  The main purpose of the vmount function is to support multiple builds
with separate configurations or architectures.
  The options are as follows. 

 l  Create symbolic links to files in the src directory. 
 c  Copy files from the src directory. 

  Mount operations are scoped. 

File: omake-doc, Node: Subsection 10-6-2,	Next: Subsection 10-6-3,	Prev: Subsection 10-6-1,	Up: Section 10-6


10.6.2  vmount-map
==================

<<    vmount-map() : Map
>>

  Answer a Map object with the currently active virtual mounts. 

File: omake-doc, Node: Subsection 10-6-3,	Next: Subsection 10-6-4,	Prev: Subsection 10-6-2,	Up: Section 10-6


10.6.3  add-project-directories
===============================

<<    add-project-directories(dirs)
         dirs : Dir Array
>>

  Add the directories to the set of directories that omake considers to
be part of the project. This is mainly used to avoid omake complaining
that the current directory is not part of the project. 

File: omake-doc, Node: Subsection 10-6-4,	Prev: Subsection 10-6-3,	Up: Section 10-6


10.6.4  remove-project-directories
==================================
\@nam
e{hevea_fun172}
<<    remove-project-directories(dirs)
         dirs : Dir Array
>>

  Removed the directories from the set of directories that omake
considers to be part of the project. This is mainly used to cancel a
.SUBDIRS from including a directory if it is determined that the
directory does not need to be compiled. 

File: omake-doc, Node: Section 10-7,	Next: Section 10-8,	Prev: Section 10-6,	Up: Chapter 10


10.7  File predicates
*********************


* Menu:

* Subsection 10-7-1::	test
* Subsection 10-7-2::	find


File: omake-doc, Node: Subsection 10-7-1,	Next: Subsection 10-7-2,	Up: Section 10-7


10.7.1  test
============

<<   test(exp) : Bool
        exp : String Sequence
>>

  The expression grammar is as follows:


   - ! expression : expression is not true 
   - expression1 -a expression2 : both expressions are true 
   - expression1 -o expression2 : at least one expression is true 
   - ( expression ) : expression is true 

  The base expressions are:


   - -n string : The string has nonzero length 
   - -z string : The string has zero length 
   - string = string : The strings are equal 
   - string != string : The strings are not equal

   - int1 -eq int2 : The integers are equal 
   - int1 -ne int2 : The integers are not equal 
   - int1 -gt int2 : int1 is larger than int2 
   - int1 -ge int2 : int2 is not larger than int1 
   - int1 -lt int2 : int1 is smaller than int2 
   - int1 -le int2 : int1 is not larger than int2

   - file1 -ef file2 : On Unix, file1 and file2 have the same device and
   inode number. On Win32, file1 and file2 have the same name. 
   - file1 -nt file2 : file1 is newer than file2 
   - file1 -ot file2 : file1 is older than file2

   - -b file : The file is a block special file 
   - -c file : The file is a character special file 
   - -d file : The file is a directory 
   - -e file : The file exists 
   - -f file : The file is a normal file 
   - -g file : The set-group-id bit is set on the file 
   - -G file : The file's group is the current effective group 
   - -h file : The file is a symbolic link (also -L) 
   - -k file : The file's sticky bit is set 
   - -L file : The file is a symbolic link (also -h) 
   - -O file : The file's owner is the current effective user 
   - -p file : The file is a named pipe 
   - -r file : The file is readable 
   - -s file : The file has a non-zero size 
   - -S file : The file is a socket 
   - -u file : The set-user-id bit is set on the file 
   - -w file : The file is writable 
   - -x file : The file is executable 

  A string is any sequence of characters; leading - characters are
allowed.
  An int is a string that can be interpreted as an integer. Unlike
traditional versions of the test program, the leading characters may
specify an arity. The prefix 0b means the numbers is in binary; the
prefix 0o means the number is in octal; the prefix 0x means the number
is in hexadecimal. An int can also be specified as -l string, which
evaluates to the length of the string.
  A file is a string that represents the name of a file.
  The syntax mirrors that of the test(1) program. If you are on a Unix
system, the man page explains more. Here are some examples.
<<    # Create an empty file
      osh> touch foo
      # Is the file empty?
      osh> test(-e foo)
      - : true
      osh> test(! -e foo)
      - : false
      # Create another file
      osh> touch boo
      # Is the newer file newer?
      osh> test(boo -nt foo)
      - : true
      # A more complex query
      # boo is newer than foo, and foo is empty
      osh> test(\( boo -nt foo \) -a -e foo)
      - : true
>>


File: omake-doc, Node: Subsection 10-7-2,	Prev: Subsection 10-7-1,	Up: Section 10-7


10.7.2  find
============

<<   find(exp) : Node Array
        exp : String Sequence
>>

  The find function searches a directory recursively, returning the
files for which the expression evaluates to true.
  The expression argument uses the same syntax as the test function,
with the following exceptions.


   1. The expression may begin with a directory. If not specified, the
   current directory is searched. 
   2. The {} string expands to the current file being examined. 

  The syntax of the expression is the same as test, with the following
additions.


   - -name string : The current file matches the glob expression (see
   Section 10.4*Note Section 10-4::). 
   - -regex string : The current file matches the regular expression 

  The find function performs a recursive scan of all subdirectories. The
following call is being run from the root of the omake source directory.
<<    osh> find(. -name fo* )
      - : <array
              /home/jyh/.../omake/mk/.svn/format
              /home/jyh/.../omake/RPM/.svn/format
              ...

/home/jyh/.../omake/osx_resources/installer_files/.svn/format>
>>

  Another example, listing only those files that are normal files or
symbolic links.
<<    osh> find(. -name fo* -a \( -f {} -o -L {} \))
      - : <array
              /home/jyh/.../omake/mk/.svn/format
              /home/jyh/.../omake/RPM/.svn/format
              ...

/home/jyh/.../omake/osx_resources/installer_files/.svn/format>
>>


File: omake-doc, Node: Section 10-8,	Next: Section 10-9,	Prev: Section 10-7,	Up: Chapter 10


10.8  IO functions
******************


* Menu:

* Subsection 10-8-1::	Standard channels
* Subsection 10-8-2::	open-in-string
* Subsection 10-8-3::	open-out-string, out-contents
* Subsection 10-8-4::	fopen
* Subsection 10-8-5::	close
* Subsection 10-8-6::	read, input-line
* Subsection 10-8-7::	write
* Subsection 10-8-8::	lseek
* Subsection 10-8-9::	rewind
* Subsection 10-8-10::	tell
* Subsection 10-8-11::	flush
* Subsection 10-8-12::	channel-name
* Subsection 10-8-13::	dup
* Subsection 10-8-14::	dup2
* Subsection 10-8-15::	set-nonblock
* Subsection 10-8-16::	set-close-on-exec-mode
* Subsection 10-8-17::	pipe
* Subsection 10-8-18::	mkfifo
* Subsection 10-8-19::	select
* Subsection 10-8-20::	lockf
* Subsection 10-8-21::	InetAddr
* Subsection 10-8-22::	Host
* Subsection 10-8-23::	gethostbyname
* Subsection 10-8-24::	Protocol
* Subsection 10-8-25::	getprotobyname
* Subsection 10-8-26::	Service
* Subsection 10-8-27::	getservbyname
* Subsection 10-8-28::	socket
* Subsection 10-8-29::	bind
* Subsection 10-8-30::	listen
* Subsection 10-8-31::	accept
* Subsection 10-8-32::	connect
* Subsection 10-8-33::	getchar
* Subsection 10-8-34::	gets
* Subsection 10-8-35::	fgets


File: omake-doc, Node: Subsection 10-8-1,	Next: Subsection 10-8-2,	Up: Section 10-8


10.8.1  Standard channels
=========================

  The following variables define the standard channels.
 stdin

<<stdin : InChannel
>>

  The standard input channel, open for reading.
 stdout
 
<<stdout : OutChannel
>>

  The standard output channel, open for writing.
 stderr
 
<<stderr : OutChannel
>>

  The standard error channel, open for writing. 

File: omake-doc, Node: Subsection 10-8-2,	Next: Subsection 10-8-3,	Prev: Subsection 10-8-1,	Up: Section 10-8


10.8.2  open-in-string
======================
 The open-in-string treats a string as if it were a file and returns
a channel for reading.
<<   $(open-in-string s) : Channel
         s : String
>>


File: omake-doc, Node: Subsection 10-8-3,	Next: Subsection 10-8-4,	Prev: Subsection 10-8-2,	Up: Section 10-8


10.8.3  open-out-string, out-contents
=====================================
 The open-out-string creates a channel that writes to a string
instead of a file. The string may be retrieved with the out-contents
function.
<<   $(open-out-string) : Channel
     $(out-contents chan) : String
         chan : OutChannel
>>


File: omake-doc, Node: Subsection 10-8-4,	Next: Subsection 10-8-5,	Prev: Subsection 10-8-3,	Up: Section 10-8


10.8.4  fopen
=============

  The fopen function opens a file for reading or writing.
<<   $(fopen file, mode) : Channel
        file : File
        mode : String
>>

  The file is the name of the file to be opened. The mode is a
combination of the following characters. 

 r  Open the file for reading; it is an error if the file does not
   exist. 
 w  Open the file for writing; the file is created if it does not exist.

 a  Open the file in append mode; the file is created if it does not
   exist. 
 +  Open the file for both reading and writing. 
 t  Open the file in text mode (default). 
 b  Open the file in binary mode. 
 n  Open the file in nonblocking mode. 
 x  Fail if the file already exists. 

  Binary mode is not significant on Unix systems, where text and binary
modes are equivalent. 

File: omake-doc, Node: Subsection 10-8-5,	Next: Subsection 10-8-6,	Prev: Subsection 10-8-4,	Up: Section 10-8


10.8.5  close
=============

<<    $(close channel...)
         channel : Channel
>>

  The close function closes a file that was previously opened with
fopen. 

File: omake-doc, Node: Subsection 10-8-6,	Next: Subsection 10-8-7,	Prev: Subsection 10-8-5,	Up: Section 10-8


10.8.6  read, input-line
========================

<<   $(read channel, amount) : String
     $(input-line channel) : String
        channel : InChannel
        amount  : Int
     raises RuntimeException
>>

  The read function reads up to amount bytes from an input channel, and
returns the data that was read. The input-line function reads a line
from the file and returns the line read, without the line terminator. If
an end-of-file condition is reached, both functions raise a
RuntimeException exception. 

File: omake-doc, Node: Subsection 10-8-7,	Next: Subsection 10-8-8,	Prev: Subsection 10-8-6,	Up: Section 10-8


10.8.7  write
=============

<<   $(write channel, buffer, offset, amount) : String
        channel : OutChannel
        buffer  : String
        offset  : Int
        amount  : Int
     $(write channel, buffer) : String
        channel : OutChannel
        buffer  : String
     raises RuntimeException
>>

  In the 4-argument form, the write function writes bytes to the output
channel channel from the buffer, starting at position offset. Up to
amount bytes are written. The function returns the number of bytes that
were written.
  The 3-argument form is similar, but the offset is 0.
  In the 2-argument form, the offset is 0, and the amount if the length
of the buffer.
  If an end-of-file condition is reached, the function raises a
RuntimeException exception. 

File: omake-doc, Node: Subsection 10-8-8,	Next: Subsection 10-8-9,	Prev: Subsection 10-8-7,	Up: Section 10-8


10.8.8  lseek
=============

<<    $(lseek channel, offset, whence) : Int
         channel : Channel
         offset  : Int
         whence  : String
      raises RuntimeException
>>

  The lseek function repositions the offset of the channel channel
according to the whence directive, as follows:


 SEEK_SET  The offset is set to offset. 
 SEEK_CUR  The offset is set to its current position plus offset bytes. 
 SEEK_END  The offset is set to the size of the file plus offset bytes. 

  The lseek function returns the new position in the file. 

File: omake-doc, Node: Subsection 10-8-9,	Next: Subsection 10-8-10,	Prev: Subsection 10-8-8,	Up: Section 10-8


10.8.9  rewind
==============

<<   rewind(channel...)
        channel : Channel
>>

  The rewind function set the current file position to the beginning of
the file. 

File: omake-doc, Node: Subsection 10-8-10,	Next: Subsection 10-8-11,	Prev: Subsection 10-8-9,	Up: Section 10-8


10.8.10  tell
=============

<<    $(tell channel...) : Int...
         channel : Channel
      raises RuntimeException
>>

  The tell function returns the current position of the channel. 

File: omake-doc, Node: Subsection 10-8-11,	Next: Subsection 10-8-12,	Prev: Subsection 10-8-10,	Up: Section 10-8


10.8.11  flush
==============

<<   $(flush channel...)
        channel : OutChannel
>>

  The flush function can be used only on files that are open for
writing. It flushes all pending data to the file. 

File: omake-doc, Node: Subsection 10-8-12,	Next: Subsection 10-8-13,	Prev: Subsection 10-8-11,	Up: Section 10-8


10.8.12  channel-name
=====================

<<   $(channel-name channel...) : String
        channel : Channel
>>

  The channel-name function returns the name that is associated with the
channel. 

File: omake-doc, Node: Subsection 10-8-13,	Next: Subsection 10-8-14,	Prev: Subsection 10-8-12,	Up: Section 10-8


10.8.13  dup
============

<<    $(dup channel) : Channel
         channel : Channel
      raises RuntimeException
>>

  The dup function returns a new channel referencing the same file as
the argument. 

File: omake-doc, Node: Subsection 10-8-14,	Next: Subsection 10-8-15,	Prev: Subsection 10-8-13,	Up: Section 10-8


10.8.14  dup2
=============

<<   dup2(channel1, channel2)
        channel1 : Channel
        channel2 : Channel
     raises RuntimeException
>>

  The dup2 function causes channel2 to refer to the same file as
channel1. 

File: omake-doc, Node: Subsection 10-8-15,	Next: Subsection 10-8-16,	Prev: Subsection 10-8-14,	Up: Section 10-8


10.8.15  set-nonblock
=====================

<<   set-nonblock-mode(mode, channel...)
        channel : Channel
        mode : String
>>

  The set-nonblock-mode function sets the nonblocking flag on the given
channel. When IO is performed on the channel, and the operation cannot
be completed immediately, the operations raises a RuntimeException. 

File: omake-doc, Node: Subsection 10-8-16,	Next: Subsection 10-8-17,	Prev: Subsection 10-8-15,	Up: Section 10-8


10.8.16  set-close-on-exec-mode
===============================

<<   set-close-on-exec-mode(mode, channel...)
        channel : Channel
        mode : String
     raises RuntimeException
>>

  The set-close-on-exec-mode function sets the close-on-exec flags for
the given channels. If the close-on-exec flag is set, the channel is not
inherited by child processes. Otherwise it is. 

File: omake-doc, Node: Subsection 10-8-17,	Next: Subsection 10-8-18,	Prev: Subsection 10-8-16,	Up: Section 10-8


10.8.17  pipe
=============

<<   $(pipe) : Pipe
     raises RuntimeException
>>

  The pipe function creates a Pipe object, which has two fields. The
read field is a channel that is opened for reading, and the write field
is a channel that is opened for writing. 

File: omake-doc, Node: Subsection 10-8-18,	Next: Subsection 10-8-19,	Prev: Subsection 10-8-17,	Up: Section 10-8


10.8.18  mkfifo
===============

<<   mkfifo(mode, node...)
        mode : Int
        node : Node
>>

  The mkfifo function creates a named pipe. 

File: omake-doc, Node: Subsection 10-8-19,	Next: Subsection 10-8-20,	Prev: Subsection 10-8-18,	Up: Section 10-8


10.8.19  select
===============

<<   $(select rfd..., wfd..., wfd..., timeout) : Select
        rfd : InChannel
        wfd : OutChannel
        efd : Channel
        timeout : float
     raises RuntimeException
>>

  The select function polls for possible IO on a set of channels. The
rfd are a sequence of channels for reading, wfd are a sequence of
channels for writing, and efd are a sequence of channels to poll for
error conditions. The timeout specifies the maximum amount of time to
wait for events.
  On successful return, select returns a Select object, which has the
following fields: 

 read  An array of channels available for reading. 
 write  An array of channels available for writing. 
 error  An array of channels on which an error has occurred. 


File: omake-doc, Node: Subsection 10-8-20,	Next: Subsection 10-8-21,	Prev: Subsection 10-8-19,	Up: Section 10-8


10.8.20  lockf
==============

<<    lockf(channel, command, len)
         channel : Channel
         command : String
         len : Int
      raises RuntimeException
>>

  The lockf function places a lock on a region of the channel. The
region starts at the current position and extends for len bytes.
  The possible values for command are the following. 

 F_ULOCK  Unlock a region. 
 F_LOCK  Lock a region for writing; block if already locked. 
 F_TLOCK  Lock a region for writing; fail if already locked. 
 F_TEST  Test a region for other locks. 
 F_RLOCK  Lock a region for reading; block if already locked. 
 F_TRLOCK  Lock a region for reading; fail is already locked. 


File: omake-doc, Node: Subsection 10-8-21,	Next: Subsection 10-8-22,	Prev: Subsection 10-8-20,	Up: Section 10-8


10.8.21  InetAddr
=================

  The InetAddr object describes an Internet address. It contains the
following fields.


 addr  String: the Internet address. 
 port  Int: the port number. 


File: omake-doc, Node: Subsection 10-8-22,	Next: Subsection 10-8-23,	Prev: Subsection 10-8-21,	Up: Section 10-8


10.8.22  Host
=============

  A Host object contains the following fields.


 name  String: the name of the host. 
 aliases  String Array: other names by which the host is known. 
 addrtype  String: the preferred socket domain. 
 addrs  InetAddr Array: an array of Internet addresses belonging to the
   host. 


File: omake-doc, Node: Subsection 10-8-23,	Next: Subsection 10-8-24,	Prev: Subsection 10-8-22,	Up: Section 10-8


10.8.23  gethostbyname
======================

<<   $(gethostbyname host...) : Host...
        host : String
     raises RuntimeException
>>

  The gethostbyname function returns a Host object for the specified
host. The host may specify a domain name or an Internet address.

File: omake-doc, Node: Subsection 10-8-24,	Next: Subsection 10-8-25,	Prev: Subsection 10-8-23,	Up: Section 10-8


10.8.24  Protocol
=================

  The Protocol object represents a protocol entry. It has the following
fields.


 name  String: the canonical name of the protocol. 
 aliases  String Array: aliases for the protocol. 
 proto  Int: the protocol number. 


File: omake-doc, Node: Subsection 10-8-25,	Next: Subsection 10-8-26,	Prev: Subsection 10-8-24,	Up: Section 10-8


10.8.25  getprotobyname
=======================

<<   $(getprotobyname name...) : Protocol...
        name : Int or String
     raises RuntimeException
>>

  The getprotobyname function returns a Protocol object for the
specified protocol. The name may be a protocol name, or a protocol
number. 

File: omake-doc, Node: Subsection 10-8-26,	Next: Subsection 10-8-27,	Prev: Subsection 10-8-25,	Up: Section 10-8


10.8.26  Service
================

  The Service object represents a network service. It has the following
fields.


 name  String: the name of the service. 
 aliases  String Array: aliases for the service. 
 port  Int: the port number of the service. 
 proto  Protocol: the protocol for the service. 


File: omake-doc, Node: Subsection 10-8-27,	Next: Subsection 10-8-28,	Prev: Subsection 10-8-26,	Up: Section 10-8


10.8.27  getservbyname
======================

<<   $(getservbyname service...) : Service...
        service : String or Int
     raises RuntimeException
>>

  The getservbyname function gets the information for a network service.
The service may be specified as a service name or number. 

File: omake-doc, Node: Subsection 10-8-28,	Next: Subsection 10-8-29,	Prev: Subsection 10-8-27,	Up: Section 10-8


10.8.28  socket
===============

<<   $(socket domain, type, protocol) : Channel
        domain : String
        type : String
        protocol : String
     raises RuntimeException
>>

  The socket function creates an unbound socket.
  The possible values for the arguments are as follows.
  The domain may have the following values. 

 PF_UNIX or unix  Unix domain, available only on Unix systems. 
 PF_INET or inet  Internet domain, IPv4. 
 PF_INET6 or inet6  Internet domain, IPv6. 

  The type may have the following values. 

 SOCK_STREAM or stream  Stream socket. 
 SOCK_DGRAM or dgram  Datagram socket. 
 SOCK_RAW or raw  Raw socket. 
 SOCK_SEQPACKET or seqpacket  Sequenced packets socket 

  The protocol is an Int or String that specifies a protocol in the
protocols database. 

File: omake-doc, Node: Subsection 10-8-29,	Next: Subsection 10-8-30,	Prev: Subsection 10-8-28,	Up: Section 10-8


10.8.29  bind
=============

<<   bind(socket, host, port)
        socket : InOutChannel
        host : String
        port : Int
     bind(socket, file)
        socket : InOutChannel
        file : File
     raise RuntimeException
>>

  The bind function binds a socket to an address.
  The 3-argument form specifies an Internet connection, the host
specifies a host name or IP address, and the port is a port number.
  The 2-argument form is for Unix sockets. The file specifies the
filename for the address. 

File: omake-doc, Node: Subsection 10-8-30,	Next: Subsection 10-8-31,	Prev: Subsection 10-8-29,	Up: Section 10-8


10.8.30  listen
===============

<<   listen(socket, requests)
        socket : InOutChannel
        requests : Int
     raises RuntimeException
>>

  The listen function sets up the socket for receiving up to requests
number of pending connection requests. 

File: omake-doc, Node: Subsection 10-8-31,	Next: Subsection 10-8-32,	Prev: Subsection 10-8-30,	Up: Section 10-8


10.8.31  accept
===============

<<   $(accept socket) : InOutChannel
        socket : InOutChannel
     raises RuntimeException
>>

  The accept function accepts a connection on a socket. 

File: omake-doc, Node: Subsection 10-8-32,	Next: Subsection 10-8-33,	Prev: Subsection 10-8-31,	Up: Section 10-8


10.8.32  connect
================

<<    connect(socket, addr, port)
         socket : InOutChannel
         addr : String
         port : int
      connect(socket, name)
         socket : InOutChannel
         name : File
      raise RuntimeException
>>

  The connect function connects a socket to a remote address.
  The 3-argument form specifies an Internet connection. The addr
argument is the Internet address of the remote host, specified as a
domain name or IP address. The port argument is the port number.
  The 2-argument form is for Unix sockets. The name argument is the
filename of the socket. 

File: omake-doc, Node: Subsection 10-8-33,	Next: Subsection 10-8-34,	Prev: Subsection 10-8-32,	Up: Section 10-8


10.8.33  getchar
================

<<    $(getc) : String
      $(getc file) : String
         file : InChannel or File
      raises RuntimeException
>>

  The getc function returns the next character of a file. If the
argument is not specified, stdin is used as input. If the end of file
has been reached, the function returns false. 

File: omake-doc, Node: Subsection 10-8-34,	Next: Subsection 10-8-35,	Prev: Subsection 10-8-33,	Up: Section 10-8


10.8.34  gets
=============

<<   $(gets) : String
     $(gets channel) : String
        channel : InChannel or File
     raises RuntimeException
>>

  The gets function returns the next line from a file. The function
returns the empty string if the end of file has been reached. The line
terminator is removed. 

File: omake-doc, Node: Subsection 10-8-35,	Prev: Subsection 10-8-34,	Up: Section 10-8


10.8.35  fgets
==============

<<   $(fgets) : String
     $(fgets channel) : String
        channel : InChannel or File
     raises RuntimeException
>>

  The fgets function returns the next line from a file that has been
opened for reading with fopen. The function returns the empty string if
the end of file has been reached. The returned string is returned as
literal data. The line terminator is not removed. 

File: omake-doc, Node: Section 10-9,	Next: Section 10-10,	Prev: Section 10-8,	Up: Chapter 10


10.9  Printing functions
************************

   





  Output is printed with the print and println functions. The println
function adds a terminating newline to the value being printed, the
print function does not.
<<    fprint(<file>, <string>)
      print(<string>)
      eprint(<string>)
      fprintln(<file>, <string>)
      println(<string>)
      eprintln(<string>)
>>

  The fprint functions print to a file that has been previously opened
with fopen. The print functions print to the standard output channel,
and the eprint functions print to the standard error channel. 

File: omake-doc, Node: Section 10-10,	Next: Section 10-11,	Prev: Section 10-9,	Up: Chapter 10


10.10  Value printing functions
*******************************

   





  Values can be printed with the printv and printvln functions. The
printvln function adds a terminating newline to the value being printed,
the printv function does not.
<<    fprintv(<file>, <string>)
      printv(<string>)
      eprintv(<string>)
      fprintvln(<file>, <string>)
      printvln(<string>)
      eprintvln(<string>)
>>

  The fprintv functions print to a file that has been previously opened
with fopen. The printv functions print to the standard output channel,
and the eprintv functions print to the standard error channel. 
* Menu:

* Subsection 10-10-1::	Miscellaneous functions


File: omake-doc, Node: Subsection 10-10-1,	Up: Section 10-10


10.10.1  Miscellaneous functions
================================


10.10.1.1  set-channel-line
---------------------------

<<    set-channel-line(channel, filename, line)
          channel : Channel
          filename : File
          line : int
>>

  Set the line number information for the channel. 

File: omake-doc, Node: Section 10-11,	Prev: Section 10-10,	Up: Chapter 10


10.11  Higher-level IO functions
********************************


* Menu:

* Subsection 10-11-1::	Regular expressions
* Subsection 10-11-2::	cat
* Subsection 10-11-3::	grep
* Subsection 10-11-4::	scan
* Subsection 10-11-5::	awk
* Subsection 10-11-6::	fsubst
* Subsection 10-11-7::	lex
* Subsection 10-11-8::	lex-search
* Subsection 10-11-9::	Lexer
* Subsection 10-11-10::	Omake_lexer.Lexer matching
* Subsection 10-11-11::	Extending lexer definitions
* Subsection 10-11-12::	Threading the lexer object
* Subsection 10-11-13::	Parser
* Subsection 10-11-14::	Calling the parser
* Subsection 10-11-15::	Parsing control
* Subsection 10-11-16::	Extending parsers
* Subsection 10-11-17::	Passwd
* Subsection 10-11-18::	getpwnam, getpwuid
* Subsection 10-11-19::	getpwents
* Subsection 10-11-20::	Group
* Subsection 10-11-21::	getgrnam, getgrgid
* Subsection 10-11-22::	tgetstr
* Subsection 10-11-23::	xterm-escape-begin, xterm-escape-end
* Subsection 10-11-24::	xterm-escape
* Subsection 10-11-25::	prompt-invisible-begin, prompt-invisible-end
* Subsection 10-11-26::	prompt-invisible
* Subsection 10-11-27::	gettimeofday
* Subsection 10-11-28::	Tm
* Subsection 10-11-29::	gmtime, localtime
* Subsection 10-11-30::	mktime, normalize-time


File: omake-doc, Node: Subsection 10-11-1,	Next: Subsection 10-11-2,	Up: Section 10-11


10.11.1  Regular expressions
============================
   
  Many of the higher-level functions use regular expressions. Regular
expressions are defined by strings with syntax nearly identical to
awk(1).
  Strings may contain the following character constants.


   - \\ : a literal backslash. 
   - \a : the alert character ^G. 
   - \b : the backspace character ^H. 
   - \f : the formfeed character ^L. 
   - \n : the newline character ^J. 
   - \r : the carriage return character ^M. 
   - \t : the tab character ^I. 
   - \v : the vertical tab character. 
   - \xhh... : the character represented by the string of hexadecimal
   digits h. All valid hexadecimal digits following the sequence are
   considered to be part of the sequence. 
   - \ddd : the character represented by 1, 2, or 3 octal digits. 

  Regular expressions are defined using the special characters
.\^$[(){}*?+.


   - c : matches the literal character c if c is not a special
   character. 
   - \c : matches the literal character c, even if c is a special
   character. 
   - . : matches any character, including newline. 
   - ^ : matches the beginning of a line. 
   - $ : matches the end of line. 
   - [abc...] : matches any of the characters abc... 
   - [^abc...] : matches any character except abc... 
   - r1|r2 : matches either r1 or r2. 
   - r1r2 : matches r1 and then r2. 
   - r+ : matches one or more occurrences of r. 
   - r* : matches zero or more occurrences of r. 
   - r? : matches zero or one occurrence of r. 
   - (r) : parentheses are used for grouping; matches r. 
   - \(r\) : also defines grouping, but the expression matched within
   the parentheses is available to the output processor through one of
   the variables $1, $2, ... 
   - r{n} : matches exactly n occurrences of r. 
   - r{n,} : matches n or more occurrences of r. 
   - r{n,m} : matches at least n occurrences of r, and no more than m
   occurrences. 
   - \y: matches the empty string at either the beginning or end of a
   word. 
   - \B: matches the empty string within a word. 
   - \<: matches the empty string at the beginning of a word. 
   - \>: matches the empty string at the end of a word. 
   - \w: matches any character in a word. 
   - \W: matches any character that does not occur within a word. 
   - \`: matches the empty string at the beginning of a file. 
   - \': matches the empty string at the end of a file. 

  Character classes can be used to specify character sequences
abstractly. Some of these sequences can change depending on your LOCALE.


   - [[:alnum:]] Alphanumeric characters. 
   - [[:alpha:]] Alphabetic characters. 
   - [[:lower:]] Lowercase alphabetic characters. 
   - [[:upper:]] Uppercase alphabetic characters. 
   - [[:cntrl:]] Control characters. 
   - [[:digit:]] Numeric characters. 
   - [[:xdigit:]] Numeric and hexadecimal characters. 
   - [[:graph:]] Characters that are printable and visible. 
   - [[:print:]] Characters that are printable, whether they are visible
   or not. 
   - [[:punct:]] Punctuation characters. 
   - [[:blank:]] Space or tab characters. 
   - [[:space:]] Whitespace characters. 


File: omake-doc, Node: Subsection 10-11-2,	Next: Subsection 10-11-3,	Prev: Subsection 10-11-1,	Up: Section 10-11


10.11.2  cat
============

<<    cat(files) : Sequence
         files : File or InChannel Sequence
>>

  The cat function concatenates the output from multiple files and
returns it as a string. 

File: omake-doc, Node: Subsection 10-11-3,	Next: Subsection 10-11-4,	Prev: Subsection 10-11-2,	Up: Section 10-11


10.11.3  grep
=============

<<   grep(pattern) : String  # input from stdin, default options
        pattern : String
     grep(pattern, files) : String  # default options
        pattern : String
        files   : File Sequence
     grep(options, pattern, files) : String
       options : String
       pattern : String
       files   : File Sequence
>>

  The grep function searches for occurrences of a regular expression
pattern in a set of files, and prints lines that match. This is like a
highly-simplified version of grep(1).
  The options are: 

 q  If specified, the output from grep is not displayed. 
 h  If specified, output lines will not include the filename (default,
   when only one input file is given). 
 n  If specified, output lines include the filename (default, when more
   than one input file is given). 
 v  If specified, search for lines without a match instead of lines with
   a match, 

  The pattern is a regular expression.
  If successful (grep found a match), the function returns true.
Otherwise, it returns false. 

File: omake-doc, Node: Subsection 10-11-4,	Next: Subsection 10-11-5,	Prev: Subsection 10-11-3,	Up: Section 10-11


10.11.4  scan
=============

<<   scan(input-files)
     case string1
        body1
     case string2
        body2
     ...
     default
        bodyd
>>

  The scan function provides input processing in command-line form. The
function takes file/filename arguments. If called with no arguments, the
input is taken from stdin. If arguments are provided, each specifies an
InChannel, or the name of a file for input. Output is always to stdout.
  The scan function operates by reading the input one line at a time,
and processing it according to the following algorithm.
  For each line, the record is first split into fields, and the fields
are bound to the variables $1, $2, .... The variable $0 is defined to be
the entire line, and $* is an array of all the field values. The $(NF)
variable is defined to be the number of fields.
  Next, a case expression is selected. If string_i matches the token $1,
then body_i is evaluated. If the body ends in an export, the state is
passed to the next clause. Otherwise the value is discarded.
  For example, here is an scan function that acts as a simple command
processor.
<<    calc() =
         i = 0
         scan(script.in)
         case print
            println($i)
         case inc
            i = $(add $i, 1)
            export
         case dec
            i = $(sub $i, 1)
            export
         case addconst
            i = $(add $i, $2)
            export
         default
            eprintln($"Unknown command: $1")
>>

  The scan function also supports several options.
<<    scan(options, files)
      ...
>>



 A  Parse each line as an argument list, where arguments may be quoted.
   For example, the following line has three words, "ls", "-l", "Program
   Files".
   <<       ls -l "Program Files"
        >>

 O  Parse each line using white space as the separator, using the usual
   OMake algorithm for string parsing. This is the default. 
 x  Once each line is split, reduce each word using the hex
   representation. This is the usual hex representation used in URL
   specifiers, so the string "Program Files" may be alternately
   represented in the form ProgramProgram+Files. 

  Note, if you want to redirect the output to a file, the easiest way is
to redefine the stdout variable. The stdout variable is scoped the same
way as other variables, so this definition does not affect the meaning
of stdout outside the calc function.
<<    calc() =
          stdout = $(fopen script.out, w)
          scan(script.in)
             ...
          close($(stdout))
>>


File: omake-doc, Node: Subsection 10-11-5,	Next: Subsection 10-11-6,	Prev: Subsection 10-11-4,	Up: Section 10-11


10.11.5  awk
============

<<   awk(input-files)
     case pattern1:
        body1
     case pattern2:
        body2
     ...
     default:
        bodyd
>>

  or
<<   awk(options, input-files)
     case pattern1:
        body1
     case pattern2:
        body2
     ...
     default:
        bodyd
>>

  The awk function provides input processing similar to awk(1), but more
limited. The input-files argument is a sequence of values, each
specifies an InChannel, or the name of a file for input. If called with
no options and no file arguments, the input is taken from stdin. Output
is always to stdout.
  The variables RS and FS define record and field separators as regular
expressions. The default value of RS is the regular expression
\r|\n|\r\n. The default value of FS is the regular expression [ \t]+.
  The awk function operates by reading the input one record at a time,
and processing it according to the following algorithm.
  For each line, the record is first split into fields using the field
separator FS, and the fields are bound to the variables $1, $2, .... The
variable $0 is defined to be the entire line, and $* is an array of all
the field values. The $(NF) variable is defined to be the number of
fields.
  Next, the cases are evaluated in order. For each case, if the regular
expression pattern_i matches the record $0, then body_i is evaluated. If
the body ends in an export, the state is passed to the next clause.
Otherwise the value is discarded. If the regular expression contains
\(r\) expression, those expression override the fields $1, $2, ....
  For example, here is an awk function to print the text between two
delimiters \begin{<name>} and \end{<name>}, where the <name> must belong
to a set passed as an argument to the filter function.
<<    filter(names) =
         print = false

         awk(Awk.in)
         case $"^\\end\{\([[:alpha:]]+\)\}"
            if $(mem $1, $(names))
               print = false
               export
            export
         default
            if $(print)
               println($0)
         case $"^\\begin\{\([[:alpha:]]+\)\}"
            print = $(mem $1, $(names))
            export
>>

  Note, if you want to redirect the output to a file, the easiest way is
to redefine the stdout variable. The stdout variable is scoped the same
way as other variables, so this definition does not affect the meaning
of stdout outside the filter function.
<<    filter(names) =
          stdout = $(fopen file.out, w)
          awk(Awk.in)
             ...
          close($(stdout))
>>

  Options. 

 b  "Break" when evaluating cases. Only the first case that matches will
   be selected. 

  The 'break' function can be used to abort the loop, exiting the awk
function immediately. 

File: omake-doc, Node: Subsection 10-11-6,	Next: Subsection 10-11-7,	Prev: Subsection 10-11-5,	Up: Section 10-11


10.11.6  fsubst
===============

<<   fsubst(files)
     case pattern1 [options]
        body1
     case pattern2 [options]
        body2
     ...
     default
        bodyd
>>

  The fsubst function provides a sed(1)-like substitution function.
Similar to awk, if fsubst is called with no arguments, the input is
taken from stdin. If arguments are provided, each specifies an
InChannel, or the name of a file for input.
  The RS variable defines a regular expression that determines a record
separator, The default value of RS is the regular expression \r|\n|\r\n.
  The fsubst function reads the file one record at a time.
  For each record, the cases are evaluated in order. Each case defines a
substitution from a substring matching the pattern to replacement text
defined by the body.
  Currently, there is only one option: g. If specified, each clause
specifies a global replacement, and all instances of the pattern define
a substitution. Otherwise, the substitution is applied only once.
  Output can be redirected by redefining the stdout variable.
  For example, the following program replaces all occurrences of an
expression word. with its capitalized form.
<<    section
         stdout = $(fopen Subst.out, w)
         fsubst(Subst.in)
         case $"\<\([[:alnum:]]+\)\." g
            value $(capitalize $1).
         close($(stdout))
>>


File: omake-doc, Node: Subsection 10-11-7,	Next: Subsection 10-11-8,	Prev: Subsection 10-11-6,	Up: Section 10-11


10.11.7  lex
============

<<   lex(files)
     case pattern1
        body1
     case pattern2
        body2
     ...
     default
        bodyd
>>

  The lex function provides a simple lexical-style scanner function. The
input is a sequence of files or channels. The cases specify regular
expressions. Each time the input is read, the regular expression that
matches the longest prefix of the input is selected, and the body is
evaluated.
  If two clauses both match the same input, the last one is selected for
execution. The default case matches the regular expression .; you
probably want to place it first in the pattern list.
  If the body end with an export directive, the state is passed to the
next clause.
  For example, the following program collects all occurrences of
alphanumeric words in an input file.
<<    collect-words(files) =
         words[] =
         lex($(files))
         default
            # empty
         case $"[[:alnum:]]+" g
            words[] += $0
            export
         value $(words)
>>

  The default case, if one exists, matches single characters. Since
  It is an error if the input does not match any of the regular
expressions.
  The 'break' function can be used to abort the loop. 

File: omake-doc, Node: Subsection 10-11-8,	Next: Subsection 10-11-9,	Prev: Subsection 10-11-7,	Up: Section 10-11


10.11.8  lex-search
===================

<<   lex-search(files)
     case pattern1
        body1
     case pattern2
        body2
     ...
     default
        bodyd
>>

  The lex-search function is like the lex function, but input that does
not match any of the regular expressions is skipped. If the clauses
include a default case, then the default matches any skipped text.
  For example, the following program collects all occurrences of
alphanumeric words in an input file, skipping any other text.
<<    collect-words($(files)) =
         words[] =
         lex-search($(files))
         default
            eprintln(Skipped $0)
         case $"[[:alnum:]]+" g
            words[] += $0
            export
>>

  The default case, if one exists, matches single characters. Since
  It is an error if the input does not match any of the regular
expressions.
  The 'break' function can be used to abort the loop. 

File: omake-doc, Node: Subsection 10-11-9,	Next: Subsection 10-11-10,	Prev: Subsection 10-11-8,	Up: Section 10-11


10.11.9  Lexer
==============

  The Omake_lexer.Lexer object defines a facility for lexical analysis,
similar to the lex(1) and flex(1) programs.
  In omake, lexical analyzers can be constructed dynamically by
extending the Omake_lexer.Lexer class. A lexer definition consists of a
set of directives specified with method calls, and set of clauses
specified as rules.
  For example, consider the following lexer definition, which is
intended for lexical analysis of simple arithmetic expressions for a
desktop calculator.
<<   lexer1. =
        extends $(Omake_lexer.Lexer)

        other: .
           eprintln(Illegal character: $* )
           lex()

        white: $"[[:space:]]+"
           lex()

        op: $"[-+*/()]"
           switch $*
           case +
              Token.unit($(loc), plus)
           case -
              Token.unit($(loc), minus)
           case *
              Token.unit($(loc), mul)
           case /
              Token.unit($(loc), div)
           case $"("
              Token.unit($(loc), lparen)
           case $")"
              Token.unit($(loc), rparen)

        number: $"[[:digit:]]+"
           Token.pair($(loc), exp, $(int $* ))

        eof: $"\'"
           Token.unit($(loc), eof)
>>

  This program defines an object lexer1 the extends the
Omake_lexer.Lexer object, which defines lexing environment.
  The remainder of the definition consists of a set of clauses, each
with a method name before the colon; a regular expression after the
colon; and in this case, a body. The body is optional, if it is not
specified, the method with the given name should already exist in the
lexer definition.
  NB The clause that matches the longest prefix of the input is
selected. If two clauses match the same input prefix, then the last one
is selected. This is unlike most standard lexers, but makes more sense
for extensible grammars.
  The first clause matches any input that is not matched by the other
clauses. In this case, an error message is printed for any unknown
character, and the input is skipped. Note that this clause is selected
only if no other clause matches.
  The second clause is responsible for ignoring white space. If
whitespace is found, it is ignored, and the lexer is called recursively.
  The third clause is responsible for the arithmetic operators. It makes
use of the Token object, which defines three fields: a loc field that
represents the source location; a name; and a value.
  The lexer defines the loc variable to be the location of the current
lexeme in each of the method bodies, so we can use that value to create
the tokens.
  The Token.unit($(loc), name) method constructs a new Token object with
the given name, and a default value.
  The number clause matches nonnegative integer constants. The
Token.pair($(loc), name, value) constructs a token with the given name
and value.
  Omake_lexer.Lexer object operate on InChannel objects. The method
lexer1.lex-channel(channel) reads the next token from the channel
argument.

File: omake-doc, Node: Subsection 10-11-10,	Next: Subsection 10-11-11,	Prev: Subsection 10-11-9,	Up: Section 10-11


10.11.10  Omake_lexer.Lexer matching
====================================

  During lexical analysis, clauses are selected by longest match. That
is, the clause that matches the longest sequence of input characters is
chosen for evaluation. If no clause matches, the lexer raises a
RuntimeException. If more than one clause matches the same amount of
input, the first one is chosen for evaluation.

File: omake-doc, Node: Subsection 10-11-11,	Next: Subsection 10-11-12,	Prev: Subsection 10-11-10,	Up: Section 10-11


10.11.11  Extending lexer definitions
=====================================

  Suppose we wish to augment the lexer example so that it ignores
comments. We will define comments as any text that begins with the
string (*, ends with *), and comments may be nested.
  One convenient way to do this is to define a separate lexer just to
skip comments.
<<   lex-comment. =
        extends $(Omake_lexer.Lexer)

        level = 0

        other: .
           lex()

        term: $"[*][)]"
           if $(not $(eq $(level), 0))
              level = $(sub $(level), 1)
              lex()

        next: $"[(][*]"
           level = $(add $(level), 1)
           lex()

        eof: $"\'"
           eprintln(Unterminated comment)
>>

  This lexer contains a field level that keeps track of the nesting
level. On encountering a (* string, it increments the level, and for *),
it decrements the level if nonzero, and continues.
  Next, we need to modify our previous lexer to skip comments. We can do
this by extending the lexer object lexer1 that we just created.
<<   lexer1. +=
        comment: $"[(][*]"
           lex-comment.lex-channel($(channel))
           lex()
>>

  The body for the comment clause calls the lex-comment lexer when a
comment is encountered, and continues lexing when that lexer returns.

File: omake-doc, Node: Subsection 10-11-12,	Next: Subsection 10-11-13,	Prev: Subsection 10-11-11,	Up: Section 10-11


10.11.12  Threading the lexer object
====================================

  Clause bodies may also end with an export directive. In this case the
lexer object itself is used as the returned token. If used with the
Parser object below, the lexer should define the loc, name and value
fields in each export clause. Each time the Parser calls the lexer, it
calls it with the lexer returned from the previous lex invocation. 
