Next

Prev

Prev-tail

Tail

Up

Chapter 23
urbiscript Standard Library

23.1 Barrier

Barrier is used to wait until another job raises a signal. This can be used to implement blocking calls waiting until a resource is available.

 23.1 Barrier
  23.1.1 Prototypes
  23.1.2 Construction
  23.1.3 Slots
 23.2 Binary
  23.2.1 Prototypes
  23.2.2 Construction
  23.2.3 Slots
 23.3 Boolean
  23.3.1 Prototypes
  23.3.2 Construction
  23.3.3 Truth Values
  23.3.4 Slots
 23.4 CallMessage
  23.4.1 Examples
  23.4.2 Slots
 23.5 Channel
  23.5.1 Prototypes
  23.5.2 Construction
  23.5.3 Slots
 23.6 Code
  23.6.1 Prototypes
  23.6.2 Construction
  23.6.3 Slots
 23.7 Comparable
  23.7.1 Slots
 23.8 Container
  23.8.1 Prototypes
  23.8.2 Slots
 23.9 Control
  23.9.1 Prototypes
  23.9.2 Slots
 23.10 Date
  23.10.1 Prototypes
  23.10.2 Construction
  23.10.3 Slots
 23.11 Dictionary
  23.11.1 Example
  23.11.2 Hash values
  23.11.3 Prototypes
  23.11.4 Construction
  23.11.5 Slots
 23.12 Directory
  23.12.1 Prototypes
  23.12.2 Construction
  23.12.3 Slots
 23.13 Duration
  23.13.1 Prototypes
  23.13.2 Construction
  23.13.3 Slots
 23.14 Enumeration
  23.14.1 Prototypes
  23.14.2 Examples
  23.14.3 Construction
  23.14.4 Slots
 23.15 Event
  23.15.1 Prototypes
  23.15.2 Examples
  23.15.3 Construction
  23.15.4 Slots
 23.16 Exception
  23.16.1 Prototypes
  23.16.2 Construction
  23.16.3 Slots
  23.16.4 Specific Exceptions
 23.17 Executable
  23.17.1 Prototypes
  23.17.2 Construction
  23.17.3 Slots
 23.18 File
  23.18.1 Prototypes
  23.18.2 Construction
  23.18.3 Slots
 23.19 Finalizable
  23.19.1 Example
  23.19.2 Prototypes
  23.19.3 Construction
  23.19.4 Slots
 23.20 Float
  23.20.1 Prototypes
  23.20.2 Construction
  23.20.3 Slots
 23.21 Float.limits
  23.21.1 Slots
 23.22 FormatInfo
  23.22.1 Prototypes
  23.22.2 Construction
  23.22.3 Slots
 23.23 Formatter
  23.23.1 Prototypes
  23.23.2 Construction
  23.23.3 Slots
 23.24 Global
  23.24.1 Prototypes
  23.24.2 Slots
 23.25 Group
  23.25.1 Example
  23.25.2 Prototypes
  23.25.3 Construction
  23.25.4 Slots
 23.26 Hash
  23.26.1 Prototypes
  23.26.2 Construction
  23.26.3 Slots
 23.27 InputStream
  23.27.1 Prototypes
  23.27.2 Construction
  23.27.3 Slots
 23.28 IoService
  23.28.1 Example
  23.28.2 Prototypes
  23.28.3 Construction
  23.28.4 Slots
 23.29 Job
  23.29.1 Prototypes
  23.29.2 Construction
  23.29.3 Slots
 23.30 Kernel1
  23.30.1 Prototypes
  23.30.2 Construction
  23.30.3 Slots
 23.31 Lazy
  23.31.1 Examples
  23.31.2 Caching
  23.31.3 Prototypes
  23.31.4 Construction
  23.31.5 Slots
 23.32 List
  23.32.1 Prototypes
  23.32.2 Examples
  23.32.3 Construction
  23.32.4 Slots
 23.33 Loadable
  23.33.1 Prototypes
  23.33.2 Example
  23.33.3 Construction
  23.33.4 Slots
 23.34 Lobby
  23.34.1 Prototypes
  23.34.2 Construction
  23.34.3 Examples
  23.34.4 Slots
 23.35 Location
  23.35.1 Prototypes
  23.35.2 Construction
  23.35.3 Slots
 23.36 Logger
  23.36.1 Examples
  23.36.2 Prototypes
  23.36.3 Construction
  23.36.4 Slots
 23.37 Math
  23.37.1 Prototypes
  23.37.2 Construction
  23.37.3 Slots
 23.38 Mutex
  23.38.1 Prototypes
  23.38.2 Construction
  23.38.3 Slots
 23.39 nil
  23.39.1 Prototypes
  23.39.2 Construction
  23.39.3 Slots
 23.40 Object
  23.40.1 Prototypes
  23.40.2 Construction
  23.40.3 Slots
 23.41 Orderable
 23.42 OutputStream
  23.42.1 Prototypes
  23.42.2 Construction
  23.42.3 Slots
 23.43 Pair
  23.43.1 Prototype
  23.43.2 Construction
  23.43.3 Slots
 23.44 Path
  23.44.1 Prototypes
  23.44.2 Construction
  23.44.3 Slots
 23.45 Pattern
  23.45.1 Prototypes
  23.45.2 Construction
  23.45.3 Slots
 23.46 Position
  23.46.1 Prototypes
  23.46.2 Construction
  23.46.3 Slots
 23.47 Primitive
  23.47.1 Prototypes
  23.47.2 Construction
  23.47.3 Slots
 23.48 Process
  23.48.1 Prototypes
  23.48.2 Example
  23.48.3 Construction
  23.48.4 Slots
 23.49 Profile
  23.49.1 Example
  23.49.2 Prototypes
  23.49.3 Construction
  23.49.4 Slots
 23.50 Profile.Function
  23.50.1 Prototypes
  23.50.2 Construction
  23.50.3 Slots
 23.51 PseudoLazy
 23.52 PubSub
  23.52.1 Prototypes
  23.52.2 Construction
  23.52.3 Slots
 23.53 PubSub.Subscriber
  23.53.1 Prototypes
  23.53.2 Construction
  23.53.3 Slots
 23.54 RangeIterable
  23.54.1 Prototypes
  23.54.2 Slots
 23.55 Regexp
  23.55.1 Prototypes
  23.55.2 Construction
  23.55.3 Slots
 23.56 Semaphore
  23.56.1 Prototypes
  23.56.2 Construction
  23.56.3 Slots
 23.57 Server
  23.57.1 Prototypes
  23.57.2 Construction
  23.57.3 Slots
 23.58 Singleton
  23.58.1 Prototypes
  23.58.2 Construction
  23.58.3 Slots
 23.59 Socket
  23.59.1 Example
  23.59.2 Prototypes
  23.59.3 Construction
  23.59.4 Slots
 23.60 StackFrame
  23.60.1 Construction
  23.60.2 Slots
 23.61 Stream
  23.61.1 Prototypes
  23.61.2 Construction
  23.61.3 Slots
 23.62 String
  23.62.1 Prototypes
  23.62.2 Construction
  23.62.3 Slots
 23.63 System
  23.63.1 Prototypes
  23.63.2 Slots
 23.64 System.PackageInfo
  23.64.1 Prototypes
  23.64.2 Slots
 23.65 System.Platform
  23.65.1 Prototypes
  23.65.2 Slots
 23.66 Tag
  23.66.1 Examples
  23.66.2 Construction
  23.66.3 Slots
  23.66.4 Hierarchical tags
 23.67 Timeout
  23.67.1 Prototypes
  23.67.2 Construction
  23.67.3 Examples
  23.67.4 Slots
 23.68 Traceable
  23.68.1 Slots
 23.69 TrajectoryGenerator
  23.69.1 Prototypes
  23.69.2 Examples
  23.69.3 Construction
  23.69.4 Slots
 23.70 Triplet
  23.70.1 Prototype
  23.70.2 Construction
  23.70.3 Slots
 23.71 Tuple
  23.71.1 Prototype
  23.71.2 Construction
  23.71.3 Slots
 23.72 UObject
  23.72.1 Prototypes
  23.72.2 Slots
 23.73 uobjects
  23.73.1 Prototypes
  23.73.2 Slots
 23.74 UValue
 23.75 UVar
  23.75.1 Construction
  23.75.2 Prototypes
  23.75.3 Slots
 23.76 void
  23.76.1 Prototypes
  23.76.2 Construction
  23.76.3 Slots

23.1.1 Prototypes

23.1.2 Construction

A Barrier can be created with no argument. Calls to signal and wait done on this instance are restricted to this instance.

 
Barrier.new; 
[00000000] Barrier_0x25d2280  

23.1.3 Slots

23.2 Binary

A Binary object, sometimes called a blob, is raw memory, decorated with a user defined header.

23.2.1 Prototypes

23.2.2 Construction

Binaries are usually not made by users, but they are heavily used by the internal machinery when exchanging Binary UValues. A binary features some content and some keywords, both simple Strings (Section 23.62).

 
Binary.new("my header", "my content"); 
[00000001] BIN 10 my header 
my content  

Beware that the third line above (‘my content’), was output by the system, although not preceded by a timestamp.

23.2.3 Slots

23.3 Boolean

There is no object Boolean in urbiscript, but two specific objects true and false. They are the result of all the comparison statements.

23.3.1 Prototypes

The objects true and false have the following prototype.

23.3.2 Construction

There are no constructors, use true and false. Since they are singletons, clone will return themselves, not new copies.

 
true; 
!false; 
2 < 6 === true; 
true.new === true; 
6 < 2 === false;  

23.3.3 Truth Values

As in many programming languages, conditions may be more than only true and false. Whether some value is considered as true depends on the type of this. Actually, by default objects as considered “true”, objects evaluating to “false” are the exception:

The method Object.asBool is in charge of converting some arbitrary value into a Boolean.

 
assert(Global.asBool == true); 
assert(nil.asBool ==    false); 
void.asBool; 
[00000421:error] !!! unexpected void  

23.3.4 Slots

23.4 CallMessage

Capturing a method invocation: its target and arguments.

23.4.1 Examples

23.4.1.1 Evaluating an argument several times

The following example implements a lazy function which takes an integer n, then arguments. The n-th argument is evaluated twice using evalArgAt.

 
function callTwice 
{ 
  var n = call.evalArgAt(0); 
  call.evalArgAt(n); 
  call.evalArgAt(n) 
} |; 
 
// Call twice echo("foo"). 
callTwice(1, echo("foo"), echo("bar")); 
[00000001] *** foo 
[00000002] *** foo 
 
// Call twice echo("bar"). 
callTwice(2, echo("foo"), echo("bar")); 
[00000003] *** bar 
[00000004] *** bar  

23.4.1.2 Strict Functions

Strict functions do support call.

 
function strict(x) 
{ 
  echo("Entering"); 
  echo("Strict: " + x); 
  echo("Lazy:   " + call.evalArgAt(0)); 
} |; 
 
strict({echo("1"); 1}); 
[00000011] *** 1 
[00000013] *** Entering 
[00000012] *** Strict: 1 
[00000013] *** 1 
[00000014] *** Lazy:   1  

23.4.2 Slots

23.5 Channel

Returning data, typically asynchronous, with a label so that the “caller” can find it in the flow.

23.5.1 Prototypes

23.5.2 Construction

Channels are created like any other object. The constructor must be called with a string which will be the label.

 
var ch1 = Channel.new("my_label"); 
[00000201] Channel_0x7985810 
 
ch1 << 1; 
[00000201:my_label] 1 
 
var ch2 = ch1; 
[00000201] Channel_0x7985810 
 
ch2 << 1/2; 
[00000201:my_label] 0.5  

23.5.3 Slots

23.6 Code

Functions written in urbiscript.

23.6.1 Prototypes

23.6.2 Construction

The keywords function and closure build Code instances.

 
function(){}.protos[0] === &Code; 
closure (){}.protos[0] === &Code;  

23.6.3 Slots

23.7 Comparable

Objects that can be compared for equality and inequality. See also Orderable (Section 23.41).

This object, made to serve as prototype, provides a definition of != based on ==. Object provides a default implementation of == that bounces on the physical equality ===.

 
class Foo : Comparable 
{ 
  var value = 0; 
  function init (v)    { value = v; }; 
  function ’==’ (that) { value == that.value; }; 
}|; 
assert 
{ 
  Foo.new(1) == Foo.new(1); 
  Foo.new(1) != Foo.new(2); 
};  

23.7.1 Slots

23.8 Container

This object is meant to be used as a prototype for objects that support has and hasNot methods. Any class using this prototype must redefine either has, hasNot or both.

23.8.1 Prototypes

23.8.2 Slots

23.9 Control

Control is designed as a namespace for control sequences. Some of these entities are used by the Urbi engine to execute some urbiscript features; in other words, users are not expected to you use it, much less change it.

23.9.1 Prototypes

23.9.2 Slots

23.10 Date

This class is meant to record dates in time, with microsecond resolution.

This feature is experimental. It might be changed in the future. Feedback on its use would be appreciated.

23.10.1 Prototypes

23.10.2 Construction

Without argument, newly constructed Dates refer to the current date.

 
Date.new; 
[00000001] 2010-08-17 14:40:52.549726  

With a string argument d, refers to the date contained in d. The string should be formatted as ‘yyyy-mm-dd hh:mn:ss ’ (see asString). mn and ss are optional. If the block ‘hh:mn:ss ’ is absent, the behavior is undefined.

 
Date.new("2003-10-10 20:10:50"); 
[00000001] 2003-10-10 20:10:50 
 
Date.new("2003-Oct-10 20:10"); 
[00000002] 2003-10-10 20:10:00 
 
Date.new("2003-10-10 20"); 
[00000003] 2003-10-10 20:00:00  

Pay attention that the format is rather strict; for instance too many spaces between day and time result in an error.

 
Date.new("2003-10-10  20:10:50"); 
[00001968:error] !!! new: cannot convert to date: 2003-10-10  20:10:50  

23.10.3 Slots

23.11 Dictionary

A dictionary is an associative array, also known as a hash in some programming languages. They are arrays whose indexes are arbitrary objects.

23.11.1 Example

The following session demonstrates the features of the Dictionary objects.

 
var d = ["one" => 1, "two" => 2]; 
[00000001] ["one" => 1, "two" => 2] 
 
for (var p : d) 
  echo (p.first + " => " + p.second); 
[00000003] *** one => 1 
[00000002] *** two => 2 
 
"three" in d; 
[00000004] false 
d["three"]; 
[00000005:error] !!! missing key: three 
d["three"] = d["one"] + d["two"] | {}; 
"three" in d; 
[00000006] true 
d.getWithDefault("four", 4); 
[00000007] 4  

23.11.2 Hash values

Arbitrary objects can be used as dictionary keys. To map to the same cell, two objects used as keys must have equal hashes (retrieved with the Object.hash method) and be equal to each other (in the Object.’==’ sense).

This means that two different objects may have the same hash: the equality operator (Object.’==’) is checked in addition to the hash, to handle such collision. However a good hash algorithm should avoid this case, since it hinders performances.

See Object.hash for more detail on how to override hash values. Most standard value-based classes implement a reasonable hash function: see Float.hash, String.hash, List.hash, …

23.11.3 Prototypes

23.11.4 Construction

The Dictionary constructor takes arguments by pair (key, value).

 
Dictionary.new("one", 1, "two", 2); 
[00000000] ["one" => 1, "two" => 2] 
Dictionary.new; 
[00000000] [ => ]  

There must be an even number of arguments.

 
Dictionary.new("1", 2, "3"); 
[00000001:error] !!! new: odd number of arguments  

You are encouraged to use the specific syntax for Dictionary literals:

 
["one" => 1, "two" => 2]; 
[00000000] ["one" => 1, "two" => 2] 
[=>]; 
[00000000] [ => ]  

An extra comma can be added at the end of the list.

 
[ 
  "one" => 1, 
  "two" => 2, 
]; 
[00000000] ["one" => 1, "two" => 2]  

It is guaranteed that the pairs to insert are evaluated left-to-write, key first, the value.

 
   ["a".fresh => "b".fresh, "c".fresh => "d".fresh] 
== ["a_5"     => "b_6",     "c_7"     => "d_8"];  

23.11.5 Slots

23.12 Directory

A Directory represents a directory of the file system.

23.12.1 Prototypes

23.12.2 Construction

A Directory can be constructed with one argument: the path of the directory using a String (Section 23.62) or a Path (Section 23.44). It can also be constructed by the method open of Path (Section 23.44).

 
Directory.new("."); 
[00000001] Directory(".") 
Directory.new(Path.new(".")); 
[00000002] Directory(".")  

23.12.3 Slots

23.13 Duration

This class records differences between Dates (Section 23.10).

This feature is experimental. It might be changed in the future. Feedback on its use would be appreciated.

23.13.1 Prototypes

23.13.2 Construction

Without argument, a null duration.

 
Duration.new; 
[00000001] Duration(0s) 
Duration.new(1h); 
[00023593] Duration(3600s)  

Durations can be negative.

 
Duration.new(-1); 
[00000001] Duration(-1s)  

23.13.3 Slots

23.14 Enumeration

Prototype of enumeration types.

23.14.1 Prototypes

23.14.2 Examples

See Section 22.5.

23.14.3 Construction

An Enumeration is created with two arguments: the name of the enumeration type, and the list of possible values. Most of the time, it is a good idea to store it in a variable with the same name.

 
var Direction = Enumeration.new("Direction", ["up", "down", "left", "right"]); 
[00000001] Direction 
Direction.up; 
[00000002] up  

The following syntax is equivalent.

 
enum Direction 
{ 
  up, 
  down, 
  left, 
  right 
}; 
[00000001] Direction  

The created values are derive from the created enumeration type.

 
Direction.isA(Enumeration); 
Direction.up.isA(Direction);  

23.14.4 Slots

23.15 Event

An event can be “emitted” and “caught”, or “sent” and “received”. See also Section 14.2.

23.15.1 Prototypes

23.15.2 Examples

There are several examples of uses of events in the documentation of event-based constructs. See at (Listing 22.10.1), waituntil (Listing 22.10.6), whenever (Listing 22.10.7), and so forth. The tutorial chapter about event-based programming contains other examples, see Listing 14.

23.15.3 Construction

An Event is created like any other object, without arguments.

 
var e = Event.new; 
[00000001] Event_0x9ad8118  

23.15.4 Slots

23.16 Exception

Exceptions are used to handle errors. More generally, they are a means to escape from the normal control-flow to handle exceptional situations.

The language support for throwing and catching exceptions (using try/catch and throw, see Section 22.8) work perfectly well with any kind of object, yet it is a good idea to throw only objects that derive from Exception.

23.16.1 Prototypes

23.16.2 Construction

There are several types of exceptions, each of which corresponding to a particular kind of error. The top-level object, Exception, takes a single argument: an error message.

 
Exception.new("something bad has happened!"); 
[00000001] Exception something bad has happened!’ 
Exception.Arity.new("myRoutine", 1, 10, 23); 
[00000002] Exception.Arity myRoutine: expected between 10 and 23 arguments, given 1’  

23.16.3 Slots

Exception has many slots which are specific exceptions. See Section 23.16.4 for their documentation.

23.16.4 Specific Exceptions

In the following, since these slots are actually Objects, what is presented as arguments to the slots are actually arguments to pass to the constructor of the corresponding exception type.

23.17 Executable

This class is used only as a common ancestor to Primitive (Section 23.47) and Code (Section 23.6).

23.17.1 Prototypes

23.17.2 Construction

There is no point in constructing an Executable.

23.17.3 Slots

23.18 File

23.18.1 Prototypes

23.18.2 Construction

Files may be created from a String (Section 23.62), or from a Path (Section 23.44). Using new, the file must exist on the file system, and must be a file. You may use create to create a file that does not exist (or to override an existing one).

 
File.create("file.txt"); 
[00000001] File("file.txt") 
 
File.new(Path.new("file.txt")); 
[00000001] File("file.txt")  

You may use InputStream (Section 23.27) and OutputStream (Section 23.42) to read or write to Files.

23.18.3 Slots

23.19 Finalizable

Objects that derive from this object will execute their finalize routine right before being destroyed (reclaimed) by the system. It is comparable to a destructor.

23.19.1 Example

The following object is set up to die verbosely.

 
var obj = 
  do (Finalizable.new) 
  { 
    function finalize () 
    { 
      echo ("Ouch"); 
    } 
  }|;  

It is reclaimed by the system when it is no longer referenced by any other object.

 
var alias = obj|; 
obj = nil|;  

Here, the object is still alive, since alias references it. Once it no longer does, the object dies.

 
alias = nil|; 
[00000004] *** Ouch  

23.19.2 Prototypes

23.19.3 Construction

The constructor takes no argument.

 
Finalizable.new; 
[00000527] Finalizable_0x135360  

Because of specific constraints of Finalizable, you cannot change the prototype of an object to make it “finalizable”: it must be an instance of Finalizable from its inception.

There, instead of these two invalid constructs,

 
class o1 : Finalizable.new 
{ 
  function finalize() 
  { 
    echo("Ouch"); 
  } 
}|; 
[00000008:error] !!! apply: cannot inherit from a Finalizable without being one 
 
class o2 
{ 
  protos = [Finalizable]; 
  function finalize() 
  { 
    echo("Ouch"); 
  } 
}|; 
[00000010:error] !!! updateSlot: cannot inherit from a Finalizable without being one  

write:

 
var o3 = 
  do (Finalizable.new) 
  { 
    function finalize() 
    { 
      echo("Ouch"); 
    } 
  }|;  

If you need multiple prototypes, do as follows.

 
class Global.Foo 
{ 
  function init() 
  { 
    echo("1"); 
  }; 
}|; 
 
class Global.FinalizableFoo 
{ 
  addProto(Foo.new); 
 
  function new’() 
  { 
    var r = clone | 
    r.init | 
    Finalizable.new.addProto(r); 
  }; 
 
  function init() 
  { 
    echo("2"); 
  }; 
 
  function finalize() 
  { 
    echo("3"); 
  }; 
 
}|; 
 
var i = FinalizableFoo.new|; 
[00000117] *** 1 
[00000117] *** 2 
 
i = nil; 
[00000117] *** 3  

23.19.4 Slots

23.20 Float

A Float is a floating point number. It is also used, in the current version of urbiscript, to represent integers.

23.20.1 Prototypes

23.20.2 Construction

The most common way to create fresh floats is using the literal syntax. Numbers are composed of three parts:

integral
(mandatory) a non empty sequence of (decimal) digits;
fractional
(optional) a period, and a non empty sequence of (decimal) digits;
exponent
(optional) either ‘e’ or ‘E’, an optional sign (‘+’ or ‘-’), then a non-empty sequence of digits.

In other words, float literals match the [0-9]+(\.[0-9]+)?([eE][-+]?[0-9]+)? regular expression. For instance:

 
0 == 0000.0000; 
// This is actually a call to the unary ’+’. 
+1 == 1; 
0.123456 == 123456 / 1000000; 
1e3 == 1000; 
1e-3 == 0.001; 
1.234e3 == 1234;  

There are also some special numbers, nan, inf (see below).

 
Math.log(0) == -inf; 
Math.exp(-inf) == 0; 
(inf/inf).isNan;  

A null float can also be obtained with Float’s new method.

 
Float.new == 0;  

23.20.3 Slots