site Random() :: Integer

Return a random integer chosen from the range of all possible 32-bit integers.

site Random(Integer) :: Integer

Return a pseudorandom, uniformly distributed integer between 0 (inclusive) and the specified value (exclusive). If the argument is 0, halt silently.

site URandom() :: Number

Return a pseudorandom, uniformly distributed number between 0.0 (inclusive) and 1.0 (exclusive).

site UUID() :: String

Return a random (type 4) UUID represented as a string.

site Prompt(String) :: String

Prompt the user for some input. The user may cancel the prompt, in which case the site fails silently. Otherwise their response is returned as soon as it is received.

Example:

-- Publishes the user's name
Prompt("What is your name?")

The user response is always taken to be a string. Thus, integer 3 as a response will be treated as "3". To convert the response to its appropriate data type, use the library function Read:

-- Prompts the user to enter an integer, then parses the response.
Prompt("Enter an integer:") >r> Read(r)

def signals(Integer) :: Signal

Publish the given number of signals, simultaneously.

Example:

-- Publishes five signals
signals(5)

Implementation. 

              
def signals(Integer) :: Signal
def signals(n) = if n :> 0 then (signal | signals(n-1)) else stop


            

def for(Integer, Integer) :: Integer

Publish all values in the given half-open range, simultaneously.

Example:

-- Publishes: 1 2 3 4 5
for(1,6)

Implementation. 

              
def for(Integer, Integer) :: Integer
def for(low, high) =
  if low >= high then stop
  else ( low | for(low+1, high) )


            

def upto(Integer) :: Integer

upto(n) publishes all values in the range (0..n-1) simultaneously.

Example:

-- Publishes: 0 1 2 3 4
upto(5)

Implementation. 

              
def upto(Integer) :: Integer
def upto(high) = for(0, high)



import class Iterable = "java.lang.Iterable"


            

site IterableToStream[A](Iterable[A]) :: lambda () :: A

Converts a Java object implementing the Iterable interface into an Orc stream backed by the object's iterator. When the site is called, if the iterator has items remaining, the next item is returned. If the iterator has no items remaining, the call halts.

def iterableToList[A](Iterable[A]) :: List[A]

Given a Java object implementing the Iterable interface, create an Orc list whose elements are the values produced by the object's iterator, in the same order.

Implementation. 

              
def iterableToList[A](Iterable[A]) :: List[A]
def iterableToList(iterable) =
  val s = IterableToStream[A](iterable)
  def walk(List[A]) :: List[A]
  def walk(l) = s():l >m> walk(m) ; reverse(l)
  walk([])


            

def arrayToList[A](Array[A]) :: List[A]

Given an array, create an Orc list whose elements are exactly the contents of the array, in the same order.

Implementation. 

              
def arrayToList[A](Array[A]) :: List[A]
def arrayToList(a) =
  def walk(Integer, List[A]) :: List[A]
  def walk(0,acc) = acc
  def walk(i,acc) = walk(i-1, a(i-1)? : acc)
  walk(a.length?, [])


import class JavaList = "java.util.List"
import class JavaLinkedList = "java.util.LinkedList"

            

def listToJavaList[A](List[A]) :: JavaList[A]

Given an Orc list, create a java.util.List with the same elements.

Implementation. 

              
def listToJavaList[A](List[A]) :: JavaList[A]
def listToJavaList(list) =
  val javalist = JavaLinkedList[A]()
  def copy(List[A]) :: Bot
  def copy(x:xs) = javalist.add(x) >> copy(xs)
  copy(list) ; javalist


            

def listToArray[A](List[A]) :: Array[A]

Given an Orc list, create an array whose elements are exactly the contents of the list, in the same order. The size of the array is exactly the list length.

Implementation. 

              
def listToArray[A](List[A]) :: Array[A]
def listToArray(list) =
  val array = Array[A](length(list))
  def copy(List[A], Integer) :: Bot
  def copy(x:xs, i) = (array(i) := x) >> copy(xs, i+1)
  copy(list, 0) ; array


            

def fillArray[A](Array[A], lambda (Integer) :: A) :: Array[A]

Given an array and a function from indices to values, populate the array by calling the function for each index in the array. Publish the array once it has been populated.

For example, to set all elements of an array to zero:

-- Publishes: 0 0 0
val a = fillArray(Array(3), lambda (_) = 0)
a(0)? | a(1)? | a(2)?

Implementation. 

              
def fillArray[A](Array[A], lambda (Integer) :: A) :: Array[A]
def fillArray(a, f) =
  val n = a.length?
  def fill(Integer, lambda(Integer) :: A) :: Bot
  def fill(i, f) =
    if i = n then stop
    else ( a(i) := f(i) >> stop
         | fill(i+1, f) )
  fill(0, f) ; a


            

def sliceArray[A](Array[A], Integer, Integer) :: Array[A]

Given an array and a half-open index range, create a new array which contains the elements of the original array in that index range.

Implementation. 

              
def sliceArray[A](Array[A], Integer, Integer) :: Array[A]
def sliceArray(orig, from, until) =
  val size = until - from
  val a = Array[A](size)
  def copy(i :: Integer) :: Bot =
    Ift(i <: size) >>
    a(i) := orig(from + i)? >>
    copy(i+1)
  copy(0) ; a


            

def takePubs[A](Integer, lambda () :: A) :: A

takePubs(n, f) calls f(), publishes the first n values published by f() (as they are published), and then halts.

Implementation. 

              

def takePubs[A](Integer, lambda () :: A) :: A
def takePubs(n, f) =
  val out = Channel[A]()
  val c = Counter(n)
  Let(
    f() >x>
    Ift(c.dec() >> out.put(x) >> false
       ; out.closeD() >> true)
  ) >> stop | repeat(out.get)


            

def withLock[A](Semaphore, lambda () :: A) :: A

Acquire the semaphore and run a thunk which is expected to publish no more than one value. Publishes the value published by the thunk and releases the semaphore.

Implementation. 

              

def withLock[A](Semaphore, lambda () :: A) :: A
def withLock(s, f) =
  s.acquire() >> (
    Let(f()) >x>
    s.release() >>
    x
    ; s.release() >> stop
  )



            

def synchronized[A](Semaphore, lambda () :: A)() :: A

Given a lock and thunk, return a new thunk which is serialized on the lock. Similar to Java's synchronized keyword.

Implementation. 

              

def synchronized[A](Semaphore, lambda () :: A) :: lambda() :: A
def synchronized(s,f) = lambda() = withLock(s, f)


            

site InvokeExecutable(command :: List[String])

Run an executable file in the host OS, with input/output addressable from Orc.

The executable file is invoked in a new OS process, and is passed the command arguments given to InvokeExecutable. The process is created with an input character stream, to which the Orc program can send strings. The process is also created with two output character strings, one for conventional output and one for error/diagnostic output, from which the Orc program can read. Upon process termination, the Orc program can read the exit status value.

Output streams from the process can be read while the process is running. The "chunk" of the stream that is returned from any one read operation is of an unspecified length, because of buffer sizes and operation granularity between the sender and receiver. Callers may need to reassemble output segments prior to further processing. If this is inconvenient, there are "read all" methods that wait for process termination, and then return the output as a single character string.

Assumptions: <ul> <li>The supplied "command" string refers to an executable file that is understandable by the OS hosting the Orc runtime engine.</li> <li>Input and output to the executable program are character strings encoded in the host OS's default character encoding.</li> </ul>

invokeexecutable.writeIn(String) :: Signal

Send the given string to the process's standard input stream. If the process has completed, halt silently.

invokeexecutable.closeIn(String) :: Signal

Close the process's standard input stream.

invokeexecutable.readOut() :: String

Receive a "chunk" of available characters from the process's standard output stream. The chunk size is not specified. If there is no output available from the process, wait for some. If there is no output available and the process has closed its output stream, halt silently.

invokeexecutable.readOutD() :: String

Receive a "chunk" of available characters from the process's standard output stream. The chunk size is not specified. If there is no output available from the process, halt silently.

invokeexecutable.readOutAll() :: String

If the process is running, wait for it to complete; then, receive all remaining standard output stream contents from the process as a single string. If there is no further output, halt silently.

invokeexecutable.readErr() :: String

Receive a "chunk" of available characters from the process's standard error (diagnostic) stream. The chunk size is not specified. If there is no output available from the process, wait for some. If there is no output available and the process has closed its output stream, halt silently.

invokeexecutable.readErrD() :: String

Receive a "chunk" of available characters from the process's standard error (diagnostic) stream. The chunk size is not specified. If there is no output available from the process, halt silently.

invokeexecutable.readErrAll() :: String

If the process is running, wait for it to complete; then, in any case, receive all remaining standard error (diagnostic) output from the process as a single string. If there is no further output, halt silently.

invokeexecutable.exitValue() :: Integer

Returns the exit status byte from the process running the executable. If the process has not completed, halt silently. Conventionally, a zero exit status value indicates a successful termination.

invokeexecutable.terminate() :: Signal

Send a termination signal (for example, SIGTERM) to the process running the executable. If the process has completed, then this method has no effect.

site OrcVersion() :: String

Return a name, version, URL, and copyright string for Orc.