§

GIVEN

Introduces function parameters with their types. Used to declare what inputs a function accepts.

Syntax

GIVEN name IS A Type

GIVEN name IS A Type, name2 IS A Type2

GIVEN name1 IS A Type1
      name2 IS A Type2

Purpose

GIVEN declares the parameters of a function before the function definition. Each parameter has a name and a type.

Examples

Example file:

-- GIVEN keyword examples

-- Single Parameter Functions

GIVEN x IS A NUMBER
`double the value` x MEANS x TIMES 2

GIVEN `person name` IS A STRING
`greet the person` `person name` MEANS CONCAT "Hello, ", `person name`

#EVAL `double the value` 21
#EVAL `greet the person` "World"

-- Multiple Parameters (Same Line)

GIVEN a IS A NUMBER, b IS A NUMBER
`add two numbers` a b MEANS a PLUS b

GIVEN x IS A NUMBER, y IS A NUMBER
`multiply two numbers` x y MEANS x TIMES y

#EVAL `add two numbers` 10 32
#EVAL `multiply two numbers` 6 7

-- Multiple Parameters (Continuation with Indentation)

GIVEN x1 IS A NUMBER
      y1 IS A NUMBER
      z1 IS A NUMBER
`sum of three numbers` x1 y1 z1 MEANS x1 PLUS y1 PLUS z1

#EVAL `sum of three numbers` 1 2 3

-- Parameters with Complex Types

DECLARE Point HAS x IS A NUMBER, y IS A NUMBER

GIVEN p IS A Point
`get x coordinate` p MEANS p's x

GIVEN p1 IS A Point
      p2 IS A Point
`distance squared between points` p1 p2 MEANS
  LET `delta x` IS p2's x MINUS p1's x
      `delta y` IS p2's y MINUS p1's y
  IN (`delta x` TIMES `delta x`) PLUS (`delta y` TIMES `delta y`)

DECIDE `the origin` IS Point WITH x IS 0, y IS 0
DECIDE `point one` IS Point WITH x IS 3, y IS 4

#EVAL `get x coordinate` `point one`
#EVAL `distance squared between points` `the origin` `point one`

-- Type Parameters

GIVEN a IS A TYPE, xs IS A LIST OF a
GIVETH A NUMBER
`length of list` xs MEANS
  CONSIDER xs
  WHEN EMPTY THEN 0
  WHEN hd FOLLOWED BY tail THEN 1 PLUS `length of list` tail

#EVAL `length of list` (LIST 1, 2, 3, 4, 5)
#EVAL `length of list` (LIST "a", "b", "c")

-- Combined with GIVETH

GIVEN n IS A NUMBER
GIVETH A BOOLEAN
`is positive number` n MEANS n > 0

GIVEN num IS A NUMBER
GIVETH A STRING
`sign of number` num MEANS
  IF num > 0 THEN "positive"
  ELSE IF num < 0 THEN "negative"
       ELSE "zero"

#EVAL `is positive number` 5
#EVAL `sign of number` (-3)

Single Parameter

GIVEN x IS A NUMBER
double x MEANS x TIMES 2

Multiple Parameters (Same Line)

GIVEN a IS A NUMBER, b IS A NUMBER
add a b MEANS a PLUS b

Multiple Parameters (Continuation)

Use indentation to continue the parameter list:

GIVEN x IS A NUMBER
      y IS A NUMBER
      z IS A NUMBER
sum3 x y z MEANS x PLUS y PLUS z

With Type Parameters

GIVEN a IS A TYPE
GIVEN xs IS A LIST OF a
length xs MEANS
  CONSIDER xs
  WHEN EMPTY THEN 0
  WHEN _ FOLLOWED BY tail THEN 1 PLUS length tail

With Complex Types

DECLARE Person HAS name IS A STRING, age IS A NUMBER

GIVEN p IS A Person
getName p MEANS p's name

Annotations

Parameters can have NLG annotations:

GIVEN customer IS A Person @nlg
GIVEN amount IS A NUMBER @nlg
processPayment customer amount MEANS ...

See Also