Sand: Facilities

From AJS.COM

This document specifies the facilities of the Sand programming language. Sand is very similar to Perl, but this document will assume no knowledge of Perl. Specifically, this document seeks to outline the standard library that is associated with Sand. This standard library includes builtin functions and available library classes and modules.

Contents 1 Operators 1.1 Terms 1.2 Post-circumfix 1.3 Infix 1.4 Postfix 1.5 Prefix 1.6 Trinary 1.7 Not yet sorted into the above list 2 Builtins 2.1 does 2.2 exit 2.3 is 2.4 print 3 External libraries

Operators

Terms

...

Used as an expression, this operator yields a runtime exception. It is used to create stub routines and blocks for later development. It is also used to stub out methods in abstract classes and roles.

Post-circumfix

These operators have a left-hand-side (LHS) argument and an internal argument.

Example:

$x[7] # $x is the LHS, 7 is internal

()

Invokes the RHS as a subroutine or method, passing the internal argument as a parameter list.

[]

Indexes the LHS, using the internal argument. This can be a numeric or string-based lookup.

Infix

These operators have a left-hand-side (LHS) and right-hand-side (RHS) argument.

.

On the LHS object, invoke the RHS method or indirect reference (by name).

**

Raise the LHS to the RHS exponent. Implicitly calls the LHS's _exp method.

~~

Compare the LHS to the RHS using the LHS's _compare method.

!~

Identical to ~~, except that the result is negated, logically.

*

Numeric multiplication of the LHS times the RHS using the LHS's _multiply method.

/

Numeric division of the LHS by the RHS using the LHS's _divide method.

@

Repetition of the LHS by a count of the RHS. If the LHS is an array or other container type, then the return value is a list of the repeated values. Otherwise, the values are stringified, concatenated, and returned as a single string. Thus, a list of 20 number 1s could be generated like so:
$ones = [1] @ 20;
And a string of 20 number 1s could be generated like so:
$ones = 1 @ 20;

+

Numeric addition of the LHS by the RHS using the LHS's _add method.

-

Numeric subtraction of the LHS by the RHS using the LHS's _subtract method.

<<

The left bitshift operator which calls the LHS's _shift_left method with the RHS as a parameter. Nominally shifts the integer LHS left by RHS steps.

>>

The right bitshift operator which calls the LHS's _shift_right method with the RHS as a parameter. Nominally shifts the integer LHS right by RHS steps.

<

Returns true if LHS is numerically less than RHS.

>

Returns true if LHS is numerically greater than RHS.

<=

Returns true if LHS is numerically less than or equal to RHS.

>=

Returns true if LHS is numerically greater than or equal to RHS.

lt

Returns true if LHS is textually less than RHS.

gt

Returns true if LHS is textually greater than RHS.

le

Returns true if LHS is textually less than or equal to RHS.

ge

Returns true if LHS is textually greater than or equal to RHS.

==

Returns true if LHS is numerically equal to RHS.

!=

Returns true if LHS is numerically not equal to RHS.

<=>

Returns 1 if LHS is greater than RHS. Returns -1 if LHS is less than RHS. Returns 0 if they are equal. All comparisons are numeric.

eq

Returns true if LHS is textually equal to RHS.

ne

Returns true if LHS is textually not equal to RHS.

cmp

Returns 1 if LHS is greater than RHS. Returns -1 if LHS is less than RHS. Returns 0 if they are equal. All comparisons are textual.

&

Perform a bitwise and between the LHS and RHS using LHS's _bit_and method.

|

Perform a bitwise or between the LHS and RHS using LHS's _bit_or method.

^

Perform a bitwise xor between the LHS and RHS using LHS's _bit_xor method.

&&

Returns true if both LHS and RHS are true.

||

Returns true if either LHS or RHS are true.

.., ^.., ..^, ^..^

Returns the range from LHS to RHS, as defined by LHS's _range method. The caret on either side of the operator indicates a non-inclusive end-point, so 0 ^..^ 10 would be identical to 1 .. 9.

Postfix

These operators have only a left-hand-side (LHS) argument.

++

Increment the LHS, according to its _increment method.

--

Decrement the LHS, according to its _decrement method.

Prefix

These operators have only a right-hand-side (RHS) argument.

++

Increment the RHS, according to its _increment method.

--

Decrement the RHS, according to its _decrement method.

!

Negate the RHS, logically, returning true or false.

::

Return the type of the RHS. If RHS is an identifier, returns the named type.

&

Return a subroutine reference to the RHS. If RHS is an identifier, returns a reference to the named subroutine.

*

Turn RHS into an exploded list using its _explode method.

+

Convert the RHS into a numeric value.

-

Convert the RHS into a numeric value and invert its sign.

Trinary

Trinary operators have two parts and take three parameters: a left-hand-side (LHS), middle and a right-hand-side (RHS).

??!!

If LHS is logically true, then middle is returned, otherwise RHS is returned.

Not yet sorted into the above list

1. =, +=, -=, etc.
2. =>
3. ,
4. not prefix
5. and
6. or, xor

Builtins

does

sub does($object, type $role) -> bool { ... }

does takes an object and a role (type). It returns true if the object implements all of the properties specified by the role.

If does fails, it throws a soft exception with textual information about what properties were not provided.

exit

sub exit(int $status = 0) -> never { ... }

exit takes an optional status (typically zero indicates successful execution), and terminates the current process with that exit status.

is

sub is($object, type $class) -> bool { ... }

is takes an object and a class (type). It returns true if the object is either of the given type or inherits from it.

print

sub print(*@strings) -> int { ... }

print takes a list of arguments, and prints their string values, adding a trailing newline.

Print is also a method, specified by the IO role.

External libraries