IndexNextUpPreviousUrbi SDK 2.7.5

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.

 
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.

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: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  

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 or a Path. It can also be constructed by the method open of Path.

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

23.12.3 Slots

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

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 and Code.

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, 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.create("file.txt"); 
[00000001] File("file.txt") 
 
File.new(Path.new("file.txt")); 
[00000001] File("file.txt")  

You may use InputStream and OutputStream 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

23.21 Float.limits

This singleton handles various limits related to the Float objects.

23.21.1 Slots

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

23.22.1 Prototypes

23.22.2 Construction

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

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

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

options is a sequence of 0 or several of the following characters:



- Left alignment.
= Centered alignment.
+ Show sign even for positive number.
‘ ’ If the string does not begin with ‘+’ or ‘-’, insert a space before the converted string.
0 Pad with 0’s (inserted after sign or base indicator).
# Show numerical base, and decimal point.


spec is the conversion character and must be one of the following:



s Default character, prints normally
d Case modifier: lowercase
D Case modifier: uppercase
x Prints in hexadecimal lowercase
X Prints in hexadecimal uppercase
o Prints in octal
e Prints floats in scientific format
E Prints floats in scientific format uppercase
f Prints floats in fixed format


23.22.3 Slots

23.23 Formatter

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

23.23.1 Prototypes

23.23.2 Construction

Formatters are created with the format string. It cuts the string to separate regular parts of string and formatting patterns, and stores them.

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

Actually, formatting patterns are translated into FormatInfo.

23.23.3 Slots

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

23.24.1 Prototypes

23.24.2 Slots

23.25 Group

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

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

23.25.2 Prototypes

23.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"]  

23.25.4 Slots

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

23.26.1 Prototypes

23.26.2 Construction

Objects can be hashed with Object.hash.

 
Object.new.hash.isA(Hash);  

23.26.3 Slots

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

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

23.27.2 Construction

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

 
File.save("file.txt""1\n2\n"); 
var is = InputStream.new(File.new("file.txt")); 
[00000001] InputStream_0x827000  

Bear in mind that open streams should be closed (Section 23.61.2).

 
is.close;  

23.27.3 Slots

23.28 IoService

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

23.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 functions of io.

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

23.28.2 Prototypes

23.28.3 Construction

A IoService is constructed with no argument.

23.28.4 Slots

23.29 Job

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

23.29.1 Prototypes

23.29.2 Construction

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

 
detach(sleep(10)); 
[00202654] Job<shell_4> 
 
disown(sleep(10)); 
[00204195] Job<shell_5> 
 
spawn (function () { sleep(10) }, false); 
[00274160] Job<shell_6>  

23.29.3 Slots

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

23.30.1 Prototypes

23.30.2 Construction

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

23.30.3 Slots

23.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 23.4.

23.31.1 Examples

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

23.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 23.4.1.1.

23.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. 
// Use "getSlot" to get the function, not its evaluation. 
var p = UnaryLazy.new(getSlot("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  

23.31.3 Prototypes

23.31.4 Construction

Lazies are seldom instantiated manually. They are mainly created automatically when a lazy function call is made (see Section 22.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  

23.31.5 Slots

23.32 List

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

23.32.1 Prototypes

23.32.2 Examples

Since lists are RangeIterable, they also support RangeIterable.all and RangeIterable.any.

 
// Are all elements positive? 
! [-2, 0, 2, 4].all(function (e) { 0 < e }); 
// Are all elements even? 
  [-2, 0, 2, 4].all(function (e) { e % 2 == 0 }); 
 
// Is there any even element? 
! [-3, 1, -1].any(function (e) { e % 2 == 0 }); 
// Is there any positive element? 
  [-3, 1, -1].any(function (e) { 0 < e });  

23.32.3 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 actually end with a comma.

 
[]; // 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]  

23.32.4 Slots

23.33 Loadable

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

23.33.1 Prototypes

23.33.2 Example

The intended use is rather as follows:

 
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_0xADDR 
 
m.load; 
[00000004] false 
 
m.go(1); 
[00000006] *** cannot advance, the motor is off 
 
m.on; 
[00000007] Motor_0xADDR 
 
m.go(123); 
m.val; 
[00000009] 123  

23.33.3 Construction

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

23.33.4 Slots

23.34 Lobby

A lobby is the local environment for each (remote or local) connection to an Urbi server.

23.34.1 Prototypes

23.34.2 Construction

A lobby is implicitly created at each connection. At the top level, this is a Lobby.

 
this.protos; 
[00000001] [Lobby] 
this.protos[0].protos; 
[00000003] [Channel_0xADDR]  

Lobbies cannot be cloned, they must be created using create.

 
Lobby.new; 
[00000177:error] !!! new: ‘Lobby’ objects cannot be cloned 
Lobby.create; 
[00000174] Lobby_0x126450  

23.34.3 Examples

Since every lobby is-a Channel, one can use the methods of Channel.

 
lobby << 123; 
[00478679] 123 
lobby << "foo"
[00478679] "foo"  

23.34.4 Slots

23.35 Location

This class aggregates two Positions and provides a way to print them as done in error messages.

23.35.1 Prototypes

23.35.2 Construction

Without argument, a newly constructed Location has its Positions initialized to the first line and the first column.

 
Location.new; 
[00000001] 1.1  

With a Position argument p, the Location will clone the Position into the begin and end Positions.

 
Location.new(Position.new("file.u",14,25)); 
[00000001] file.u:14.25  

With two Positions arguments begin and end, the Location will clone both Positions into its own fields.

 
Location.new(Position.new("file.u",14,25), Position.new("file.u",14,35)); 
[00000001] file.u:14.25-34  

23.35.3 Slots

23.36 Logger

Logger is used to report information to the final user or to the developer. It allows to pretty print warnings, errors, debug messages or simple logs. Logger can also be used as Tag objects for it to handle nested calls indentation. A log message is assigned a category which is shown between brackets at beginning of lines, and a level which defines the context in which it has to be shown (see Section 21.1.2). Log level definition and categories filtering can be changed using environment variables defined in Section 21.1.2.

23.36.1 Examples

The proper use of Loggers is to instantiate your own category, and then to use the operator << for log messages, possibly qualified by the proper level (in increase order of importance: dump, debug, trace, log, warn, err):

 
var logger = Logger.new("Category")|; 
 
logger.dump << "Low level debug message"|; 
// Nothing displayed, unless the debug level is set to DUMP. 
 
logger.warn << "something wrong happened, proceeding"|; 
[       Category        ] something wrong happened, proceeding 
 
logger.err << "something really bad happened!"|; 
[       Category        ] something really bad happened!  

You may also directly use the logger and passing arguments to these slots.

 
Logger.log("message""Category") |; 
[       Category        ] message 
 
Logger.log("message""Category") : 

  Logger.log("indented message""SubCategory"
}|; 
[       Category        ] message 
[      SubCategory      ]   indented message  

23.36.2 Prototypes

23.36.3 Construction

Logger can be used as is, without being cloned. It is possible to clone Logger defining a category and/or a level of debug.

 
Logger.log("foo"); 
[        Logger         ] foo 
[00004702] Logger<Logger> 
 
Logger.log("foo""Category") |; 
[       Category        ] foo 
 
var l = Logger.new("Category2"); 
[00004703] Logger<Category2> 
 
l.log("foo")|; 
[       Category2       ] foo 
 
l.log("foo""ForcedCategory") |; 
[    ForcedCategory     ] foo  

23.36.4 Slots

23.37 Math

This object is actually meant to play the role of a name-space in which the mathematical functions are defined with a more conventional notation. Indeed, in an object-oriented language, writing pi.cos makes perfect sense, yet cos(pi) is more usual.

23.37.1 Prototypes

23.37.2 Construction

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

23.37.3 Slots

23.38 Mutex

Mutex allow to define critical sections.

23.38.1 Prototypes

23.38.2 Construction

A Mutex can be constructed like any other Tag but without name.

 
var m = Mutex.new; 
[00000000] Mutex_0x964ed40  

You can define critical sections by tagging your code using the Mutex.

 
var m = Mutex.new|; 
m: echo("this is critical section"); 
[00000001] *** this is critical section  

As a critical section, two pieces of code tagged by the same “Mutex” will never be executed at the same time.

23.38.3 Slots

23.39 nil

The special entity nil is an object used to denote an empty value. Contrary to void, it is a regular value which can be read.

23.39.1 Prototypes

23.39.2 Construction

Being a singleton, nil is not to be constructed, just used.

 
nil == nil;  

23.39.3 Slots

23.40 Object

Object includes the mandatory primitives for all objects in urbiscript. All objects in urbiscript must inherit (directly or indirectly) from it.

23.40.1 Prototypes

23.40.2 Construction

A fresh object can be instantiated by cloning Object itself.

 
Object.new; 
[00000421] Object_0x00000000  

The keyword class also allows to define objects intended to serve as prototype of a family of objects, similarly to classes in traditional object-oriented programming languages (see Section 11.4).

 

  class Foo 
  { 
    var attr = 23; 
  }; 
  assert 
  { 
    Foo.localSlotNames == ["asFoo""attr""type"]; 
    Foo.asFoo === Foo; 
    Foo.attr == 23; 
    Foo.type == "Foo"
  }; 
};  

23.40.3 Slots