• Table of Contents
• Cheat Sheet
• Architecture
• Hand Book

Supers; A Whole Level Beyond Types

# Path\To\Super\SuperName
 
# Description of this Super, probably in markdown formatting
 
Super [extends Path\To\Another\Super\SuperName] {
  [arguments {
    [const] argName0 : Type0 [= DEFAULT_0]; # Description of argName0
    ...                                   ; # ...
    [const] argNameN : TypeN [= DEFAULT_N]; # Description of argNameN      
  }]
  [ validation { VALIDATION_BODY } ]
  predicate { PREDICATE_BODY }
  [ type<TARGET_0> { TYPE_0_BODY } ]
  [ marshal<TARGET_0> { MARSHAL_0_BODY } ]
  [ unmarshal<TARGET_0> { UNMARSHAL_0_BODY } ]
  ...
  [ type<TARGET_N> { TYPE_N_BODY } ]
  [ marshal<TARGET_N> { MARSHAL_N_BODY } ]
  [ unmarshal<TARGET_N> { UNMARSHAL_N_BODY } ]
}

# \Xua\Supers\Universal
Super {
    Predicate {
        return true;
    }
}

# PHP Blocks
Validation            => protected _validation(SuperValidationException $exception)
Predicate             => protected _predicate($input, string &$message)
Marshal<database>     => protected _marshalDatabase($input)
Unmarshal<database>   => protected _unmarshalDatabase($input)
Marshal<php>          => protected _marshal($input)
Unmarshal<php>        => protected _unmarshal($input)
Type<database>          => protected _databaseType()
Type<php>          => protected _phpType()
# non-PHP Blocks
Marshal<FRONT_LANG>   => protected _marshal($input)
Unmarshal<FRONT_LANG> => protected _unmarshal($input)
Type<FRONT_LANG>          => protected _type()

$type = new Path\To\Super\SuperName([
    'argName0' => $value0,
    ...,
    'argNameN' => $valueN,
]);

var_dump(get_class($type));
var_dump($type->parameters());
var_dump($type->toString());

string "Path\To\Super\SuperName"
[
    argName0 => value0,
    ...,
    argNameN => valueN
]
string "Path\To\Super\SuperName(argName0 = value0, ..., argNameN = valueN)"

if ($type->explicitlyAccepts($value, $reason)) {
    var_dump($value);
    echo 'is of type ' . $type->toString();
} else {
    echo 'Rejected, because:' . $reason;
}

if ($type->implicitlyAccepts($value, $reasons, [self::METHOD_IDENTITY, self::METHOD_UNMARSHAL
])) {
    var_dump($value);
    echo 'kinda fits in the type ' . $type->toString();
} else {
    echo 'fully rejected because of the following reasons';
    var_dump($reasons);
}

$originalValue = $value;
if ($type->accepts($value, $reasons, [self::METHOD_IDENTITY, self::METHOD_UNMARSHAL
])) {
    var_dump($originalValue);
    echo 'was changed to';
    var_dump($value);
    echo 'to fit in type ' . $type->toString();
} else {
    echo 'fully rejected because of the following reasons';
    var_dump($reasons);
}

$marshaledValue = $type->marshal($value);
$originalValue = $type->unmarshal($marshaledValue);
if ($value !== $originalValue) {
    var_dump('something is wrong with marshal/unmarshal functions of ' . $type->toString());
}

$marshaledValue = $type->marshalDatabase($value);
$originalValue = $type->unmarshalDatabase($marshaledValue);
if ($value !== $originalValue) {
    var_dump('something is wrong with marshalDatabase/unmarshalDatabase functions of ' . $type->toString());
}

Path\To\Super\SuperName(
    argName0 = constant0,
    ...,
    argNameN = constantN,
)

Super extends Integer

# Supers\Integers\Range
Super extends Integer {
    arguments {
        start : Integer();
        end   : Integer();
    }
    validation {
        # TODO implement
    }
    predicate {
        # TODO implement
    }
}

validation {
    if ($this->end < $this->start) {
        $exception->setError('end', 'The argument `end` cannot be less than the argument `start`.');
    }
}

Predicate {
    return parent::_predicate($input) and $this->start <= $input and $input < $this->end;
}

Predicate {
    if (!parent::_validation($input, $message)) {
        // The message is already filled here by the parent _validation
        return false;
    }
    if ($input < $this->start) {
        $message = $input . ' is less than ' . $this->start;
        return false;
    }
    if ($input >= $this->end) {
        $message = $input . ' is not less than ' . $this->end;
        return false;
    }
    return true;
}

Marshal<php> {
    return $input - $this->start;
}
Unmarshal<php> {
    return $input + $this->start;
}
Marshal<javascript> {
    return input - this.args.start;
}
Unmarshal<javascript> {
    return input + this.args.start;
}

$min = $this->start;
$max = $this->end - 1;
$absMax = max(abs($min), abs($max));

$n = ceil(log($absMax, 2)) + 1;

type<database> {
    $min = $this->start;
    $max = $this->end - 1;
    $absMax = max(abs($min), abs($max));
    $n = ceil(log($absMax, 2)) + 1;
    return "INT($n)";
}

# Supers\Integers\PositiveRange
Super extends Range () {
    validation {
        parent::validation();
        if ($this->start<= 0) {
            $exception->setError('start', 'The range must be positive.');
        }
    }
}

# Supers\Integers\NaturalUpperLimit
Super extends Range {
    arguments {
        const start : Integer() = 0;
    }
}

$type = new NaturalUpperLimit(['start' => 1, 'end' => 2]);

# Supers\Integers\EfficientRange
Super extends Range () {
    Marshal<php> {
        return $input;
    }
    Unmarshal<php> {
        return $input;
    }
    Marshal<javascript> {
        return $input;
    }
    Unmarshal<javascript> {
        return $input;
    }
    Marshal<database> {
        return $input - $this->start;
    }
    Unmarshal<database> {
        return $input + $this->start;
    }
    DatabaseType {
        $max = $this->end - $this->start - 1;
        $n = ceil(log($max, 2)) + 1;
        return "INT($n)";
    }
}

# Supers\Integers\StepRange
Super extends Range {
    arguments {
        step : Integer() = 1;
    }
    validation {
        parent::validation();
        if (step < 1) {
            $exception->setError('step', 'The step must be at least 1.');
        }
    }
    predicate {
        if (!parent::predicate($input, $message)) {
            return false;
        }
        if ($input - $this->argument['start'] % $this->argument['step'] != 0) {
            $message = "value {$input} minus starting point {$this->argument['start']} is not devisable by step value {$this->argument['step']}.";
            return false;
        }
        return true;
    }
}

$type = new EfficientRange(['start' => 10, 'end' => 30]);

var_dump($type->toString());

$value = 25;
var_dump($type->explicitlyAccepts($value)); # dumps true
$value = 5;
var_dump($type->implicitlyAccepts($value)); # dumps true

$value = 25;
var_dump($type->implicitlyAccepts($value)); # dumps true

$value = 15;
var_dump($type->accepts($value)); # dumps true
var_dump($value); # dumps 15

$value = 5;
var_dump($type->accepts($value)); # dumps true
var_dump($value); # dumps 15

$value = 5;
var_dump($type->explicitlyAccepts($value, $reason)); # dumps false
var_dump($reason); # dumps '5 is less than 10'

$value = 30;
var_dump($type->explicitlyAccepts($value, $reason)); # dumps false
var_dump($reason); # dumps '30 is not less than 30'

$value = 30;
var_dump($type->accepts($value, $reasons)); # dumps false
var_dump($reasons);

[
    'identity' => '30 is not less than 30',
    'unmarshal' => '30 is not less than 30',
    'unmarshalDatabase' => '40 is not less than 30',
]

[
    'identity' => '5 is less than 10',
    'unmarshal' => '5 is less than 10',
    'unmarshalDatabase' => null,
]

var_dump($type->DatabaseType()); # Dumps 'INT(6)'

# Supers\Gender
Super {
    arguments {
        possibilities : Range(start = 2, end = 4) = 2;
    }
    predicate {
        $choices = ['male', 'female'];
        if ($this->possibilities == 3) {
            $choices = ['male', 'female', 'non-binary'];
        }
        $message = '$input is not in ' . implode(", ", $choices);
        return in_array($input, $choices);
    }
}