## Prelude Libarary

The prelude can be imported into every L4 program with `IMPORT prelude` and provides foundational functions for working with lists, Maybe types, Booleans, and more.

### Location

[jl4-core/libraries/prelude.l4](https://github.com/smucclaw/l4-ide/blob/main/jl4-core/libraries/prelude.l4)

### Key Functions

#### List Functions

**Construction and Deconstruction:**

- `null` - Check if list is empty
- `reverse` - Reverse a list
- `replicate` - Create list of n copies
- `range` - Generate numeric range

**Transformation:**

- `map` - Apply function to each element
- `filter` - Keep elements matching predicate
- `count` - Count number of elements in a list
- `take` - First n elements
- `drop` - All but first n elements
- `takeWhile` / `dropWhile` - Conditional take/drop

**Combination:**

- `append` - Concatenate two lists
- `concat` - Flatten list of lists
- `zip` / `zipWith` - Combine two lists
- `partition` - Split by predicate

**Aggregation:**

- `foldr` / `foldl` - Fold (reduce) a list
- `sum` - Sum of numbers
- `product` - Product of numbers
- `maximum` / `minimum` - Largest/smallest element
- `and` / `or` - Logical aggregation
- `all` / `any` - Check if all/any satisfy predicate

**Searching:**

- `elem` - Check if element is in list
- `at` - Get element at index
- `lookup` - Find value by key in association list

**Sorting:**

- `sort` - Sort numbers
- `sortBy` - Sort with custom comparator
- `insertBy` - Insert maintaining order

**Uniqueness:**

- `nub` / `nubBy` - Remove duplicates
- `delete` / `deleteBy` - Remove element

#### Maybe Functions

- `isJust` / `isNothing` - Check Maybe status
- `fromMaybe` - Extract with default
- `maybe` - Fold over Maybe
- `orElse` - Alternative Maybe
- `mapMaybe` - Filter map
- `catMaybes` - Extract all JUST values
- `asum` / `firstJust` - First successful Maybe
- `maybeToList` / `listToMaybe` - Convert between Maybe and List

#### Either Functions

- `either` - Fold over Either

#### Pair Functions

- `pmap` / `mapSnd` - Map over second element
- `fmap` / `mapPairs` - Map over list of pairs

#### Dictionary Functions

**Construction:**

- `emptyDict` - Create empty dictionary
- `singleton` / `singleToDict` - Single key-value entry
- `pairToDict` - From pair
- `listToDict` / `fromList` - From association list
- `fromListGrouped` - Group values by key

**Query:**

- `dictLookup` - Find value by key
- `dictMember` / `dictNotMember` - Check key existence
- `dictFindWithDefault` - Lookup with default
- `dictKeys` - All keys
- `dictElems` - All values
- `dictToList` - Convert to association list
- `dictSize` - Number of entries
- `dictIsEmpty` - Check if empty

**Modification:**

- `dictInsert` - Add or update entry
- `dictInsertWith` - Insert with combining function
- `dictDelete` - Remove entry
- `dictAdjust` - Modify value at key
- `dictUpdate` - Modify or delete

**Combination:**

- `dictUnion` - Merge dictionaries
- `dictUnionWith` - Merge with combining function

**Higher-Order:**

- `mapDict` - Map over values
- `dictMapWithKey` - Map with key access
- `filterDict` - Filter by value predicate
- `dictFilterWithKey` - Filter by key-value predicate
- `foldrDict` / `foldlDict` - Fold over values
- `dictFoldrWithKey` / `dictFoldlWithKey` - Fold with keys

**Grouping:**

- `insertValue` - Insert into grouped pairs
- `groupPairs` - Group flat pairs by key

#### Utility Functions

- `id` - Identity function
- `const` - Constant function
- `even` / `odd` - Number parity
- `max` / `min` - Maximum/minimum of two values
- `TBD` - Polymorphic placeholder

### Example: Using Prelude Functions



```l4-file
-- Prelude Example: Demonstrating core list and Maybe patterns
-- The prelude is automatically imported and provides foundational types

-- List construction using FOLLOWED BY (cons) and EMPTY
DECIDE `first few numbers` IS 1 FOLLOWED BY 2 FOLLOWED BY 3 FOLLOWED BY EMPTY
#EVAL `first few numbers`  -- LIST 1, 2, 3

-- Alternative: LIST syntax
DECIDE `more numbers` IS LIST 4, 5, 6
#EVAL `more numbers`  -- LIST 4, 5, 6

-- Pattern matching on lists with CONSIDER
GIVEN list IS A LIST OF NUMBER
GIVETH A NUMBER
`length of list` list MEANS
  CONSIDER list
  WHEN EMPTY THEN 0
  WHEN x FOLLOWED BY xs THEN 1 PLUS `length of list` xs

#EVAL `length of list` `first few numbers`  -- 3

-- Map: Apply function to each element
GIVEN list IS A LIST OF NUMBER
GIVETH A LIST OF NUMBER
`double all values` list MEANS
  CONSIDER list
  WHEN EMPTY THEN EMPTY
  WHEN x FOLLOWED BY xs THEN (x TIMES 2) FOLLOWED BY `double all values` xs

#EVAL `double all values` `first few numbers`  -- LIST 2, 4, 6

-- Filter: Keep elements matching predicate
GIVEN list IS A LIST OF NUMBER
GIVETH A LIST OF NUMBER
`keep only even numbers` list MEANS
  CONSIDER list
  WHEN EMPTY THEN EMPTY
  WHEN x FOLLOWED BY xs THEN
    IF x MODULO 2 EQUALS 0
    THEN x FOLLOWED BY `keep only even numbers` xs
    ELSE `keep only even numbers` xs

#EVAL `keep only even numbers` (LIST 1, 2, 3, 4, 5, 6)  -- LIST 2, 4, 6

-- Fold: Reduce list to single value (sum)
GIVEN list IS A LIST OF NUMBER
GIVETH A NUMBER
`sum of all values` list MEANS
  CONSIDER list
  WHEN EMPTY THEN 0
  WHEN x FOLLOWED BY xs THEN x PLUS `sum of all values` xs

#EVAL `sum of all values` `first few numbers`  -- 6

-- Maybe type: JUST for present values, NOTHING for absent
DECIDE `maybe has value` IS JUST 42
DECIDE `no value present` IS NOTHING

#EVAL `maybe has value`  -- JUST 42
#EVAL `no value present`     -- NOTHING

-- Pattern matching on Maybe
GIVEN maybe IS A MAYBE NUMBER
GIVETH A NUMBER
`get value or default to zero` maybe MEANS
  CONSIDER maybe
  WHEN NOTHING THEN 0
  WHEN JUST x THEN x

#EVAL `get value or default to zero` `maybe has value`  -- 42
#EVAL `get value or default to zero` `no value present`     -- 0

-- Either type: LEFT or RIGHT
DECIDE `successful result` IS RIGHT 100
DECIDE `error result` IS LEFT "error"

#EVAL `successful result`  -- RIGHT 100
#EVAL `error result`  -- LEFT "error"

-- Element membership check
GIVEN x IS A NUMBER
      list IS A LIST OF NUMBER
GIVETH A BOOLEAN
`is element in list` x list MEANS
  CONSIDER list
  WHEN EMPTY THEN FALSE
  WHEN y FOLLOWED BY ys THEN
    IF x EQUALS y THEN TRUE ELSE `is element in list` x ys

#EVAL `is element in list` 2 `first few numbers`  -- TRUE
#EVAL `is element in list` 9 `first few numbers`  -- FALSE
```



**See [prelude.l4](https://github.com/smucclaw/l4-ide/blob/main/jl4-core/libraries/prelude.l4) source for all functions.**