Introduction

This page gives an overview of the lang package, which provides some basic language-related utilities.

Classes

The following are the notable classes in the lang package. Most just contain static methods.

lang.Class contains methods to look inside a class and get information about its members, superclasses, etc.

lang.Coexpression contains methods to manipulate co-expressions, including printing stack traces.

lang.Constructor is the equivalent of Class, but for record constructors.

lang.Proc contains methods to get information about a procedure, function or operator.

lang.Prog contains methods to manipulate and get information about loaded programs.

lang.Text contains methods for manipulating csets.

Outputting values

lang.to_stderr, lang.to_stdout, lang.to_string output arbitrary objects in a human-readable format. These actually use a special type of Stream, lang.ObjectOutputStream, which has several options for altering the output. ieval uses this class to output its results; for example :-

$ ieval -i lang
> l := [1,2,["cat"]]
list#2707[
   1,
   2,
   list#2706["cat"]
]
> put(l,l)
list#2707[
   1,
   2,
   list#2706["cat"],
   ref list#2707
]

If a class wishes to customise its output, then it can subclass the lang.ObjectOutput, and implement its only method, object_output. This takes a single parameter, namely the ObjectOutputStream to output to. ObjectOutputStream also contains some helpful methods which a class can use to produce output in a format consistent with other classes. For example, given :-

import lang

class Thing(ObjectOutput)
   protected override object_output(oo)
      oo.object_string(self, "Here is a thing")
   end
end

Then to_string(Thing()) will produce "object Thing#1(Here is a thing)".

Encoding and decoding values to strings

lang.encode and lang.decode transform arbitrary objects to and from concise strings. For example, given

l := [1,2,["cat"]]
put(l,l)
...
s := encode(l)

This would leave s as the string "L4I1I2L1Scat|X1".

Some things cannot be encoded (for example co-expressions, files, windows and so on). In this case, encode will fail, setting &why appropriately. decode may fail too, it the input string is invalid in some way.

A class may customise which fields are encoded by subclassing lang.ObjectCodec, and implementing its two methods. For example :-

import lang

class Thing(ObjectCodec)
   private x, y, junk

   protected override object_encode(c)
      every c.encode(x | y)
   end

   protected override object_decode(c)
      x := c.decode()
      y := c.decode()
      # Could assign some value to junk if desired...
   end

   public new()
      x := 1
      y := 2
      junk := 999
      return
   end
end

Here the x and y fields are saved in the string created by encode, but not junk. On restoration, it will be left as &null.

Another way of doing the same thing is to use the helpful class lang.SelectiveObjectCodec. This allows a class to specify in a single method which fields to encode :-

import lang

class Thing(SelectiveObjectCodec)
   private x, y, junk

   protected override get_template()
      suspend "x" | "y"
   end

   public new()
      x := 1
      y := 2
      junk := 999
      return
   end
end

A class which wishes to prevent encoding may subclass lang.Unencodable. Any attempt to use it with encode will cause that procedure to fail.

Cloning objects

lang.clone clones an arbitrary object, ie perform a deep copy.

A class which wishes to customise its cloning can subclass lang.ObjectClone and implement its single method. lang.SelfClone can be subclassed for an object which wishes to prevent cloning; in this case cloning an instance just results in the instance itself.

Comparing for equality

lang.equals compares arbitrary objects for equality. A related procedure, lang.hash, calculates a hash value for an arbitrary object. For any two objects for which equals indicates equality, the hash code should be the same.

A class may customise its equality comparison and/or hash calculation by subclassing lang.ObjectEquals and lang.ObjectHash. For example :-

import lang

class Thing(ObjectEquals, ObjectHash)
   private x, y

   protected override object_equals(d)
      return x = d.x
   end

   protected override object_hash()
      return x
   end

   public new(x, y)
      self.x := x
      self.y := y
      return
   end
end

Here, the value of the field y is regarded as irrelevant for equality and hash calculations.