IndexNextUpPreviousUrbi SDK 3.0.0

Chapter 21
urbiscript Standard Library

This chapter details the predefined objects.

 21.1 Barrier
  21.1.1 Prototypes
  21.1.2 Construction
  21.1.3 Slots
 21.2 Binary
  21.2.1 Prototypes
  21.2.2 Construction
  21.2.3 Slots
 21.3 Boolean
  21.3.1 Truth Values
  21.3.2 Prototypes
  21.3.3 Construction
  21.3.4 Slots
 21.4 CallMessage
  21.4.1 Examples
  21.4.2 Prototypes
  21.4.3 Slots
 21.5 Channel
  21.5.1 Prototypes
  21.5.2 Construction
  21.5.3 Slots
 21.6 Code
  21.6.1 Prototypes
  21.6.2 Construction
  21.6.3 Slots
 21.7 Comparable
  21.7.1 Example
  21.7.2 Prototypes
  21.7.3 Slots
 21.8 Container
  21.8.1 Prototypes
  21.8.2 Slots
 21.9 Control
  21.9.1 Prototypes
  21.9.2 Slots
 21.10 Date
  21.10.1 Prototypes
  21.10.2 Construction
  21.10.3 Slots
 21.11 Dictionary
  21.11.1 Example
  21.11.2 Hash values
  21.11.3 Prototypes
  21.11.4 Construction
  21.11.5 Slots
 21.12 Directory
  21.12.1 Prototypes
  21.12.2 Construction
  21.12.3 Slots
 21.13 Duration
  21.13.1 Prototypes
  21.13.2 Construction
  21.13.3 Slots
 21.14 Enumeration
  21.14.1 Examples
  21.14.2 Prototypes
  21.14.3 Construction
  21.14.4 Slots
 21.15 Event
  21.15.1 Examples
  21.15.2 Synchronicity of Event Handling
  21.15.3 Sustained Events
  21.15.4 Prototypes
  21.15.5 Construction
  21.15.6 Slots
 21.16 Exception
  21.16.1 Prototypes
  21.16.2 Construction
  21.16.3 Slots
 21.17 Executable
  21.17.1 Prototypes
  21.17.2 Construction
  21.17.3 Slots
 21.18 File
  21.18.1 Prototypes
  21.18.2 Construction
  21.18.3 Slots
 21.19 Finalizable
  21.19.1 Example
  21.19.2 Prototypes
  21.19.3 Construction
  21.19.4 Slots
 21.20 Float
  21.20.1 Prototypes
  21.20.2 Construction
  21.20.3 Slots
 21.21 Float.limits
  21.21.1 Prototypes
  21.21.2 Slots
 21.22 FormatInfo
  21.22.1 Prototypes
  21.22.2 Construction
  21.22.3 Slots
 21.23 Formatter
  21.23.1 Prototypes
  21.23.2 Construction
  21.23.3 Slots
 21.24 Global
  21.24.1 Prototypes
  21.24.2 Slots
 21.25 Group
  21.25.1 Example
  21.25.2 Prototypes
  21.25.3 Construction
  21.25.4 Slots
 21.26 Hash
  21.26.1 Prototypes
  21.26.2 Construction
  21.26.3 Slots
 21.27 InputStream
  21.27.1 Prototypes
  21.27.2 Construction
  21.27.3 Slots
 21.28 IoService
  21.28.1 Example
  21.28.2 Prototypes
  21.28.3 Construction
  21.28.4 Slots
 21.29 Job
  21.29.1 Prototypes
  21.29.2 Construction
  21.29.3 Slots
 21.30 Kernel1
  21.30.1 Prototypes
  21.30.2 Construction
  21.30.3 Slots
 21.31 Lazy
  21.31.1 Examples
  21.31.2 Caching
  21.31.3 Prototypes
  21.31.4 Construction
  21.31.5 Slots
 21.32 List
  21.32.1 Prototypes
  21.32.2 Construction
  21.32.3 Slots
 21.33 Loadable
  21.33.1 Example
  21.33.2 Prototypes
  21.33.3 Construction
  21.33.4 Slots
 21.34 Lobby
  21.34.1 Examples
  21.34.2 Prototypes
  21.34.3 Construction
  21.34.4 Slots
 21.35 Location
  21.35.1 Prototypes
  21.35.2 Construction
  21.35.3 Slots
 21.36 Logger
  21.36.1 Examples
  21.36.2 Existing Categories
  21.36.3 Prototypes
  21.36.4 Construction
  21.36.5 Slots
 21.37 Math
  21.37.1 Prototypes
  21.37.2 Construction
  21.37.3 Slots
 21.38 Matrix
  21.38.1 Prototypes
  21.38.2 Construction
  21.38.3 Slots
 21.39 Mutex
  21.39.1 Prototypes
  21.39.2 Construction
  21.39.3 Slots
 21.40 nil
  21.40.1 Prototypes
  21.40.2 Construction
  21.40.3 Slots
 21.41 Object
  21.41.1 Prototypes
  21.41.2 Construction
  21.41.3 Slots
 21.42 Orderable
  21.42.1 Example
  21.42.2 Prototypes
  21.42.3 Slots
 21.43 OutputStream
  21.43.1 Prototypes
  21.43.2 Construction
  21.43.3 Slots
 21.44 Pair
  21.44.1 Prototypes
  21.44.2 Construction
  21.44.3 Slots
 21.45 Path
  21.45.1 Prototypes
  21.45.2 Construction
  21.45.3 Slots
 21.46 Pattern
  21.46.1 Prototypes
  21.46.2 Construction
  21.46.3 Slots
 21.47 Position
  21.47.1 Prototypes
  21.47.2 Construction
  21.47.3 Slots
 21.48 Primitive
  21.48.1 Prototypes
  21.48.2 Construction
  21.48.3 Slots
 21.49 Process
  21.49.1 Example
  21.49.2 Prototypes
  21.49.3 Construction
  21.49.4 Slots
 21.50 Profile
  21.50.1 Example
  21.50.2 Prototypes
  21.50.3 Construction
  21.50.4 Slots
 21.51 Profile.Function
  21.51.1 Prototypes
  21.51.2 Construction
  21.51.3 Slots
 21.52 PseudoLazy
  21.52.1 Prototypes
  21.52.2 Slots
 21.53 PubSub
  21.53.1 Prototypes
  21.53.2 Construction
  21.53.3 Slots
 21.54 PubSub.Subscriber
  21.54.1 Prototypes
  21.54.2 Construction
  21.54.3 Slots
 21.55 RangeIterable
  21.55.1 Prototypes
  21.55.2 Slots
 21.56 Regexp
  21.56.1 Prototypes
  21.56.2 Construction
  21.56.3 Slots
 21.57 Semaphore
  21.57.1 Prototypes
  21.57.2 Construction
  21.57.3 Slots
 21.58 Serializables
  21.58.1 Prototypes
  21.58.2 Slots
 21.59 Server
  21.59.1 Prototypes
  21.59.2 Construction
  21.59.3 Slots
 21.60 Singleton
  21.60.1 Prototypes
  21.60.2 Construction
  21.60.3 Slots
 21.61 Slot
  21.61.1 Accessing the slot object
  21.61.2 Key features
  21.61.3 Split mode
  21.61.4 Construction
  21.61.5 Prototypes
  21.61.6 Slots
 21.62 Socket
  21.62.1 Example
  21.62.2 Prototypes
  21.62.3 Construction
  21.62.4 Slots
 21.63 StackFrame
  21.63.1 Prototypes
  21.63.2 Construction
  21.63.3 Slots
 21.64 Stream
  21.64.1 Prototypes
  21.64.2 Construction
  21.64.3 Slots
 21.65 String
  21.65.1 Prototypes
  21.65.2 Construction
  21.65.3 Slots
 21.66 Subscription
  21.66.1 Prototypes
  21.66.2 Construction
  21.66.3 Slots
 21.67 System
  21.67.1 Prototypes
  21.67.2 Slots
 21.68 System.PackageInfo
  21.68.1 Prototypes
  21.68.2 Slots
 21.69 System.Platform
  21.69.1 Prototypes
  21.69.2 Slots
 21.70 Tag
  21.70.1 Examples
  21.70.2 Hierarchical tags
  21.70.3 Prototypes
  21.70.4 Construction
  21.70.5 Slots
 21.71 Timeout
  21.71.1 Examples
  21.71.2 Prototypes
  21.71.3 Construction
  21.71.4 Slots
 21.72 Traceable
  21.72.1 Prototypes
  21.72.2 Slots
 21.73 TrajectoryGenerator
  21.73.1 Examples
  21.73.2 Prototypes
  21.73.3 Construction
  21.73.4 Slots
 21.74 Triplet
  21.74.1 Prototypes
  21.74.2 Construction
  21.74.3 Slots
 21.75 Tuple
  21.75.1 Prototypes
  21.75.2 Construction
  21.75.3 Slots
 21.76 UObject
  21.76.1 Prototypes
  21.76.2 Slots
 21.77 uobjects
  21.77.1 Prototypes
  21.77.2 Slots
 21.78 UValue
  21.78.1 Prototypes
  21.78.2 Slots
 21.79 UValueSerializable
  21.79.1 Example
  21.79.2 Prototypes
  21.79.3 Slots
 21.80 Vector
  21.80.1 Prototypes
  21.80.2 Construction
  21.80.3 Slots
 21.81 void
  21.81.1 Prototypes
  21.81.2 Construction
  21.81.3 Slots

21.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.

21.1.1 Prototypes

21.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  

21.1.3 Slots

21.2 Binary

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

21.2.1 Prototypes

21.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.

 
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.

21.2.3 Slots

21.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.

21.3.1 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  

21.3.2 Prototypes

The objects true and false have the following prototype.

21.3.3 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;  

21.3.4 Slots

21.4 CallMessage

Capturing a method invocation: its target and arguments.

21.4.1 Examples

21.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  

21.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  

21.4.2 Prototypes

21.4.3 Slots

21.5 Channel

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

21.5.1 Prototypes

21.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<my_label> 
 
ch1 << 1; 
[00000201:my_label] 1 
 
var ch2 = ch1; 
[00000201] Channel<my_label> 
 
ch2 << 1/2; 
[00000201:my_label] 0.5  

21.5.3 Slots

21.6 Code

Functions written in urbiscript.

21.6.1 Prototypes

21.6.2 Construction

The keywords function and closure build Code instances.

 
function(){}.protos[0] === ’package’.lang.getSlotValue("Code"); 
closure (){}.protos[0] === ’package’.lang.getSlotValue("Code");  

21.6.3 Slots

21.7 Comparable

Objects that can be compared for equality and inequality. See also Orderable.

21.7.1 Example

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); 
};  

21.7.2 Prototypes

21.7.3 Slots

21.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.

21.8.1 Prototypes

21.8.2 Slots

21.9 Control

Control is a namespace for control sequences used by the Urbi engine to execute some urbiscript features. It is internal; in other words, users are not expected to use it, much less change it.

21.9.1 Prototypes

21.9.2 Slots

21.10 Date

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

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

21.10.1 Prototypes

21.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:637"); 
[00000001] 2003-10-10 20:10:50.637000 
 
Date.new("2003-10-10 20:10:50"); 
[00000001] 2003-10-10 20:10:50.000000 
 
Date.new("2003-Oct-10 20:10"); 
[00000002] 2003-10-10 20:10:00.000000 
 
Date.new("2003-10-10 20"); 
[00000003] 2003-10-10 20:00:00.000000  

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  

Pay attention that the format is not strict enough either; for instance, below, the ‘.’ separator seem to prefix microseconds, but actually merely denotes the minutes. Seconds must be spelled out in order to introduce microseconds.

 
Date.new("2003-10-10 00.12"); 
[00000003] 2003-10-10 00:12:00.000000 
 
Date.new("2003-10-10 00:00.12"); 
[00000003] 2003-10-10 00:00:12.000000  

21.10.3 Slots

21.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.

21.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  

21.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, …

21.11.3 Prototypes

21.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"];  

Duplicate keys in Dictionary literal are an error. On this regards, urbiscript departs from choices made in JavaScript, Perl, Python, Ruby, and probably many other languages.

 
["one" => 1, "one" => 2]; 
[00000001:error] !!! duplicate dictionary key: "one"  

21.11.5 Slots

21.12 Directory

A Directory represents a directory of the file system.

21.12.1 Prototypes

21.12.2 Construction

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

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

21.12.3 Slots

21.13 Duration

This class records differences between Dates.

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

21.13.1 Prototypes

21.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)  

21.13.3 Slots

21.14 Enumeration

Prototype of enumeration types.

21.14.1 Examples

See Section 20.5.

21.14.2 Prototypes

21.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);  

21.14.4 Slots

21.15 Event

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

21.15.1 Examples

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

21.15.2 Synchronicity of Event Handling

A particular emphasis should be put on the synchronicity of the event handling, i.e., whether the bodies of the event handlers are run before the control flow returns from the event emission. By default, (i.e., at (e?...) and e!(...)/e.emit(...))) the execution is asynchronous, but if either the emitted or the handler is marked asynchronous (i.e., at sync (e?...) or e.syncEmit(...)), then the execution is synchronous.

Contrast the following examples:

Asynchronous handlers  

 
var e = Event.new() |; 
 
at (e?) 
  { echo("a"); sleep(20ms); echo("b") } 
onleave 
  { echo("c"); sleep(20ms); echo("d") }; 
 
e! | echo("done"); 
[00000001] *** done 
sleep(25ms); 
[00000002] *** a 
[00000003] *** c 
[00000101] *** b 
[00000102] *** d 
 
e.syncEmit() | echo("done"); 
[00000001] *** a 
[00000101] *** b 
[00000102] *** c 
[00000202] *** d 
[00000203] *** done  

Synchronous handlers  

 
var e = Event.new() |; 
 
at sync (e?) 
  { echo("a"); sleep(20ms); echo("b") } 
onleave 
  { echo("c"); sleep(20ms); echo("d") }; 
 
e! | echo("done"); 
// No need to sleep. 
[00000011] *** a 
[00000031] *** b 
[00000031] *** c 
[00000052] *** d 
[00000052] *** done 
 
e.syncEmit() | echo("done"); 
[00000052] *** a 
[00000073] *** b 
[00000073] *** c 
[00000094] *** d 
[00000094] *** done  

For more information about the synchronicity of event handlers, see Listing 20.11.1.3.

21.15.3 Sustained Events

Events can also be sustained during a time span starting at trigger and ending at handler.stop. Note that the onleave-clauses of the event handlers is not executed right after the event was first triggered, but rather when it is stopped.

Synchronicity for sustained events is more complex: the at-clause is handled asynchronously iff both the emission and the handler are asynchronous, whereas the onleave-clause is handled asynchronously iff the emission was synchronous. Be warned, but do not depend on this, as in the future we might change this.

Asynchronous Trigger  

 
var e = Event.new()|; 
at (e?(var v)) 
  { echo("a"+v); sleep(20ms); echo("b"+v) } 
onleave 
  { echo("c"+v); sleep(20ms); echo("d"+v) }; 
 
var handler = e.trigger(1) | echo("triggered"); 
[00000001] *** triggered 
[00000002] *** a1 
[00000102] *** b1 
sleep(200ms); 
handler.stop() | echo("stopped"); 
[00000301] *** stopped 
sleep(25ms); 
[00000302] *** c1 
[00000402] *** d1 
 
// at and onleave clauses may overlap. 
handler = e.trigger(2) | handler.stop(); 
sleep(25ms); 
[00000001] *** a2 
[00000002] *** c2 
sleep(25ms); 
[00000201] *** b2 
[00000202] *** d2 
 
handler = e.syncTrigger(3) | echo("triggered"); 
[00000002] *** a3 
[00000102] *** b3 
[00000001] *** triggered 
handler.stop() | echo("stopped"); 
[00000302] *** c3 
[00000402] *** d3 
[00000301] *** stopped  

Synchronous Trigger  

 
var e = Event.new()|; 
at sync (e?(var v)) 
  { echo("a"+v); sleep(20ms); echo("b"+v) } 
onleave 
  { echo("c"+v); sleep(20ms); echo("d"+v) }; 
 
var handler = e.trigger(1) | echo("triggered"); 
// No need to sleep. 
[00000002] *** a1 
[00000102] *** b1 
[00000001] *** triggered 
handler.stop() | echo("stopped"); 
[00000301] *** stopped 
sleep(25ms); 
[00000302] *** c1 
[00000402] *** d1 
 
// at and onleave clauses don’t overlap. 
handler = e.trigger(2) | handler.stop(); 
sleep(25ms); 
[00000001] *** a2 
[00000201] *** b2 
[00000002] *** c2 
[00000202] *** d2 
 
 
handler = e.syncTrigger(3) | echo("triggered"); 
[00000002] *** a3 
[00000102] *** b3 
[00000001] *** triggered 
handler.stop() | echo("stopped"); 
[00000302] *** c3 
[00000402] *** d3 
[00000301] *** stopped  

21.15.4 Prototypes

21.15.5 Construction

An Event is created like any other object. The constructor takes no argument.

 
var e = Event.new(); 
[00000001] Event_0x9ad8118  

21.15.6 Slots

21.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 20.8) work perfectly well with any kind of object, yet it is a good idea to throw only objects that derive from Exception.

21.16.1 Prototypes

21.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’  

21.16.3 Slots

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

21.16.3.1 General Features

21.16.3.2 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.

21.17 Executable

This class is used only as a common ancestor to Primitive and Code.

21.17.1 Prototypes

21.17.2 Construction

There is no point in constructing an Executable.

21.17.3 Slots

21.18 File

21.18.1 Prototypes

21.18.2 Construction

Files may be created from a String, or from a Path. 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.new("file.txt"); 
[00000001:error] !!! new: no such file or directory: file.txt 
 
File.create("file.txt"); 
[00000002] File("file.txt") 
 
File.new(Path.new("file.txt")); 
[00000003] File("file.txt")  

You may use InputStream and OutputStream to read or write to Files.

21.18.3 Slots

21.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.

21.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  

21.19.2 Prototypes

21.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 this invalid constructs,

 
class o2 

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

write:

 
class o1 : Finalizable 

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

If you need multiple prototypes, do as follows.

 
import Global.*; 
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  

21.19.4 Slots

21.20 Float

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

21.20.1 Prototypes

21.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;  

Actually, underscores can be inserted between digits to improve legibility.

 
123_456.78_90 == 1234567890 / 10_000;  

There are also some special numbers, nan, inf.

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

A null float can also be obtained with new.

 
Float.new() == 0;  

21.20.3 Slots

21.21 Float.limits

This singleton handles various limits related to the Float objects.

21.21.1 Prototypes

21.21.2 Slots

21.22 FormatInfo

A format info is used when formatting a la printf. It store the formatting pattern itself and all the format information it can extract from the pattern.

21.22.1 Prototypes

21.22.2 Construction

The constructor expects a string as argument, whose syntax is similar to printf’s. It is detailed below.

 
FormatInfo.new("%+2.3d"); 
[00000001] %+2.3d  

A formatting pattern must one of the following (brackets denote optional arguments):

where:

When accepted, the format string is decoded, and its features are made available as separate slots of the FormatInfo object.

 
do (FormatInfo.new("%5$+’=#06.12X")) 

  assert 
  { 
    rank      == 5;    // 5$ 
    prefix    == "+";  // + 
    group     == " ";  // ’ 
    alignment == 0;    // = 
    alt       == true; // # 
    pad       == "0";  // 0 
    width     == 6;    // 6 
    precision == 12;   // .12 
    uppercase == 1;    // X 
    spec      == "x";  // X 
  }; 
}|;  

Formats that do not conform raise errors.

 
FormatInfo.new("foo"); 
[00000001:error] !!! new: format: pattern does not begin with %: foo 
 
FormatInfo.new("%20m"); 
[00000002:error] !!! new: format: invalid conversion type character: m 
 
FormatInfo.new("%"); 
[00000003:error] !!! new: format: trailing ‘%’ 
 
FormatInfo.new("%ss"); 
[00062475:error] !!! new: format: spurious characters after format: s 
 
FormatInfo.new("%.ss"); 
[00071153:error] !!! new: format: invalid width after ‘.’: s 
 
FormatInfo.new("%|-8.2f|%%"); 
[00034983:error] !!! new: format: spurious characters after format: %%  

21.22.3 Slots

21.23 Formatter

A formatter stores format information of a format string like used in printf in the C library or in boost::format.

21.23.1 Prototypes

21.23.2 Construction

Formatters are created from format strings: they are split into regular strings and formatting patterns (FormatInfo), and stores them.

 
Formatter.new("Name:%s, Surname:%s;"); 
[00000001] Formatter ["Name:", %s, ", Surname:", %s, ";"]  

All the patterns are introduced with the percent character (%), and they must conform to a specific syntax, detailed in the section on the construction of the FormatInfo. To denote the percent character instead of introducing a formatting-specification, use two percent characters.

 
var f = Formatter.new("%10s level: %-4.1f%%"); 
[00039525] Formatter [%10s, " level: ", %-4.1f, "%"] 
 
for (var d: ["Battery" => 83.3, "Sound" => 60]) 
  echo (f % d.asList()); 
[00041133] ***    Battery level: 83.3% 
[00041138] ***      Sound level: 60  %  

Patterns can either all be non-positional (e.g., %s%s), or all positional (e.g., %1$s%2$s).

 
Formatter.new("%s%s"); 
[00371506] Formatter [%s, %s] 
Formatter.new("%1$s%2$s"); 
[00385602] Formatter [%1$s, %2$s] 
 
Formatter.new("%1$s%s"); 
[00409657:error] !!! new: format: cannot mix positional and non-positional\ 
 arguments: %1$s vs. %s  

21.23.3 Slots

21.24 Global

Global is designed for the purpose of being global namespace. Since Global is a prototype of Object and all objects are an Object, all slots of Global are accessible from anywhere.

21.24.1 Prototypes

21.24.2 Slots

21.25 Group

A transparent means to send messages to several objects as if they were one.

21.25.1 Example

The following session demonstrates the features of the Group objects. It first creates the Sample family of object, makes a group of such object, and uses that group.

 
class Sample 

  var value = 0; 
  function init(v)    { value = v; }; 
  function asString() { "<" + value.asString() + ">"; }; 
  function timesTen() { new(value * 10); }; 
  function plusTwo()  { new(value + 2); }; 
}; 
[00000000] <0> 
 
var group = Group.new(Sample.new(1), Sample.new(2)); 
[00000000] Group [<1>, <2>] 
group << Sample.new(3); 
[00000000] Group [<1>, <2>, <3>] 
group.timesTen.plusTwo; 
[00000000] Group [<12>, <22>, <32>] 
 
// Bouncing getSlot and updateSlot. 
group.value; 
[00000000] Group [1, 2, 3] 
group.value = 10; 
[00000000] Group [10, 10, 10] 
 
// Bouncing to each&. 
var sum = 0| 
for& (var v : group) 
  sum += v.value; 
sum; 
[00000000] 30  

21.25.2 Prototypes

21.25.3 Construction

Groups are created like any other object. The constructor can take members to add to the group.

 
Group.new(); 
[00000000] Group [] 
Group.new(1, "two"); 
[00000000] Group [1, "two"]  

21.25.4 Slots

21.26 Hash

A hash is a condensed, easily comparable representation of another value. They are mainly used to map Dictionary keys to values.

Equal objects must always have the same hash. Different objects should, as much as possible, have different hashes.

21.26.1 Prototypes

21.26.2 Construction

Objects can be hashed with Object.hash.

 
Object.new().hash().isA(Hash);  

21.26.3 Slots

21.27 InputStream

InputStreams are used to read (possibly binary) files by hand. File provides means to swallow a whole file either as a single large string, or a list of lines. InputStream provides a more fine-grained interface to read files.

21.27.1 Prototypes

Windows Issues

Beware that because of limitations in the current implementation, one cannot safely read from two different files at the same time under Windows.

21.27.2 Construction

An InputStream is a reading-interface to a file, so its constructor requires a File.

 
InputStream.new(0); 
[00000919:error] !!! new: argument 1: unexpected 0, expected a File 
 
File.save("file.txt""1\n2\n"); 
var i1 = InputStream.new(File.new("file.txt")); 
[00001208] InputStream_0x1046d16e0  

Cloning a closed Stream is valid, but it is forbidden to clone an opened one.

 
var i2 = InputStream.clone().new(File.new("file.txt")); 
[00001211] InputStream_0x1045f6760 
 
i1.clone(); 
[00001288:error] !!! clone: cannot clone opened Streams  

Do not forget to close the streams you opened (Section 21.64.2).

 
i1.close(); 
i2.close();  

21.27.3 Slots

21.28 IoService

An IoService is used to manage the various operations of a set of Socket.

All Socket and Server are by default using the default IoService which is polled regularly by the system.

21.28.1 Example

Using a different IoService is required if you need to perform synchronous read operations.

The Socket must be created by the IoService that will handle it using its makeSocket function.

 
var io = IoService.new()|; 
var s = io.makeSocket()|;  

You can then use this socket like any other.

 
// Make a simple hello server. 
var serverPort = 0| 
do (Server.new()) 

  listen("127.0.0.1""0"); 
  lobby.serverPort = port; 
  at (connection?(var s)) 
  { 
    s.write("hello"); 
  } 
}|; 
// Connect to it using our socket. 
s.connect("0.0.0.0", serverPort); 
at (s.received?(var data)) 
  echo("received something"); 
s.write("1;");  

…except that nothing will be read from the socket unless you call one of the poll/pollFor/pollOneFor functions of io.

 
sleep(200ms); 
s.isConnected(); // Nothing was received yet 
[00000001] true 
io.poll(); 
[00000002] *** received something 
sleep(200ms);  

21.28.2 Prototypes

21.28.3 Construction

A IoService is constructed with no argument.

21.28.4 Slots

21.29 Job

Jobs are independent threads of executions. Jobs can run concurrently. They can also be managed using Tags.

21.29.1 Prototypes

21.29.2 Construction

A Job is typically constructed via Control.detach, Control.disown, or Code.spawn.

 
detach(sleep(10)); 
[00202654] Job<shell_7> 
 
disown(sleep(10)); 
[00204195] Job<shell_8> 
 
function () { sleep(10) }.spawn(false); 
[00274160] Job<shell_9>  

21.29.3 Slots

21.30 Kernel1

This object plays the role of a name-space in which obsolete functions from urbiscript 1.0 are provided for backward compatibility. Do not use these functions, scheduled for removal.

21.30.1 Prototypes

21.30.2 Construction

Since it is a Singleton, you are not expected to build other instances.

21.30.3 Slots

21.31 Lazy

Lazies are objects that hold a lazy value, that is, a not yet evaluated value. They provide facilities to evaluate their content only once (memoization) or several times. Lazy are essentially used in call messages, to represent lazy arguments, as described in Section 21.4.

21.31.1 Examples

21.31.1.1 Evaluating once

One usage of lazy values is to avoid evaluating an expression unless it’s actually needed, because it’s expensive or has undesired side effects. The listing below presents a situation where an expensive-to-compute value (heavy_computation) might be needed zero, one or two times. The objective is to save time by:

We thus make the wanted expression lazy, and use the value method to fetch its value when needed.

 
// This function supposedly performs expensive computations. 
function heavy_computation() 

  echo("Heavy computation"); 
  return 1 + 1; 
}|; 
 
// We want to do the heavy computations only if needed, 
// and make it a lazy value to be able to evaluate it "on demand". 
var v = Lazy.new(closure () { heavy_computation() }); 
[00000000] heavy_computation() 
/* some code */
// So far, the value was not needed, and heavy_computation 
// was not evaluated. 
/* some code */
// If the value is needed, heavy_computation is evaluated. 
v.value(); 
[00000000] *** Heavy computation 
[00000000] 2 
// If the value is needed a second time, heavy_computation 
// is not reevaluated. 
v.value(); 
[00000000] 2  

21.31.1.2 Evaluating several times

Evaluating a lazy several times only makes sense with lazy arguments and call messages. See example with call messages in Section 21.4.1.1.

21.31.2 Caching

Lazy is meant for functions without argument. If you need caching for functions that depend on arguments, it is straightforward to implement using a Dictionary. In the future urbiscript might support dictionaries whose indices are not only strings, but in the meanwhile, convert the arguments into strings, as the following sample object demonstrates.

 
class UnaryLazy 

  function init(f) 
  { 
    results = [ => ]; 
    func = f; 
  }; 
  function value(p) 
  { 
    var sp = p.asString(); 
    if (results.has(sp)) 
      return results[sp]; 
    var res = func(p); 
    results[sp] = res | 
    res 
  }; 
  var results; 
  var func; 
} | 
// The function to cache. 
var inc = function(x) { echo("incing " + x) | x+1 } | 
// The function with cache. UnaryLazy simply takes the function as argument. 
var p = UnaryLazy.new(inc); 
[00062847] UnaryLazy_0x78b750 
p.value(1); 
[00066758] *** incing 1 
[00066759] 2 
p.value(1); 
[00069058] 2 
p.value(2); 
[00071558] *** incing 2 
[00071559] 3 
p.value(2); 
[00072762] 3 
p.value(1); 
[00074562] 2  

21.31.3 Prototypes

21.31.4 Construction

Lazies are seldom instantiated manually. They are mainly created automatically when a lazy function call is made (see Section 20.3.4). One can however create a lazy value with the standard new method of Lazy, giving it an argument-less function which evaluates to the value made lazy.

 
Lazy.new(closure () { /* Value to make lazy */ 0 }); 
[00000000] 0  

21.31.5 Slots

21.32 List

Lists implement possibly-empty ordered (heterogeneous) collections of objects.

21.32.1 Prototypes

21.32.2 Construction

Lists can be created with their literal syntax: a possibly empty sequence of expressions in square brackets, separated by commas. Non-empty lists may end with a comma (Section 20.1.6.5).

 
[]; // The empty list 
[00000000] [] 
[1, "2", [3,],]; 
[00000000] [1, "2", [3]]  

However, new can be used as expected.

 
List.new(); 
[00000001] [] 
[1, 2, 3].new(); 
[00000002] [1, 2, 3]  

21.32.3 Slots

21.33 Loadable

Loadable objects can be switched on and off — typically physical devices.

21.33.1 Example

The intended use is rather as follows:

 
import gsrapi.*; 
class Motor: Loadable 

  var val = 0; 
  function go(var d) 
  { 
    if (load) 
      val += d 
    else 
      echo("cannot advance, the motor is off")|; 
  }; 
}; 
[00000002] Motor 
 
var m = Motor.new(); 
[00000003] Motor_0x42364388 
 
m.load; 
[00000004] false 
 
m.go(1); 
[00000006] *** cannot advance, the motor is off 
 
m.on(); 
[00000007] Motor_0x42364388 
 
m.go(123); 
m.val; 
[00000009] 123  

21.33.2 Prototypes

21.33.3 Construction

Loadable can be constructed, but it hardly makes sense. This object should serve as a prototype.

21.33.4 Slots