newLISP for mere mortals

Updated by Ivan on Fri Nov 14 13:14:50 CET 2025 This is work in progres …

Integer arithmetics

Performs calculations on integer numbers using functions like +, -, *, /, %, ++, and --. Results are truncated toward zero, wrap around on overflow, and preserve the sign of the operands.

• + - * / % ++ --
  • syntax: (func-op int-1 [int-2 …])
  • Notes:
  • [+] returns sum of all numbers
  • [-] subtracts int-2 from int-1, then the next int-i from the previous result. If only one argument is given, its sign is reversed.
  • [*] calculates the product for int-1 to int-i
  • [/] each result is divided successively until the end of the list is reached. Division by zero causes an error.
  • [%] each result is divided successively by the next int, then the rest (modulo operation) is returned. Division by zero causes an error.
• ++
  • syntax: (++ place [num … ])
  • Notes:
  • Without the optional argument in num, ++ increments the number in place by 1.
  • If floating point numbers are passed as arguments, their fractional part gets truncated first.
  • Calculations resulting in numbers greater than 9,223,372,036,854,775,807 wrap around to negative numbers.
  • Results smaller than -9,223,372,036,854,775,808 wrap around to positive numbers.
  • place is either a symbol or a place in a list structure holding a number, or a number returned by an expression.
  • If the symbol for place contains nil, it is treated as if containing 0.
• --
  • syntax: (-- place [num … ])
  • Notes:
  • Without the optional argument in num, -- decrements the number in place by 1.
  • If floating point numbers are passed as arguments, their fractional part gets truncated first.
  • Calculations resulting in numbers greater than 9,223,372,036,854,775,807 wrap around to negative numbers.
  • Results smaller than -9,223,372,036,854,775,808 wrap around to positive numbers.
  • place is either a symbol or a place in a list structure holding a number, or a number returned by an expression.
  • If the symbol for place contains nil, it is treated as if containing 0.
• Floating point values in arguments to +, -, *, /, %, ++ and – are truncated to the integer value closest to 0 (zero).

Examples:

; Basics
(+ 1 2 3 4 5)        ;-> 15
(+ 1 2 (- 5 2) 8)    ;-> 14
(+ 1.2 3.9)          ;-> 4
(- 10 3 2 1)         ;-> 4
(- (* 3 4) 6 1 2)    ;-> 3
(- 123)              ;-> -123
(* 1 2 3)            ;-> 6
(* 10 (- 8 2))       ;-> 60
(/ 12 3)             ;-> 4
(/ 120 3 20 2)       ;-> 1
(% 10 3)             ;-> 1
(% -10 3)            ;-> -1
(map - '(10 20 30))  ;-> (-10 -20 -30)

; Incrementing
(set 'x 1)    
(++ x)               ;-> 2

(set 'x 3.8)
(++ x)               ;-> 4
(++ x 1.3)           ;-> 5

(set 'lst '(1 2 3))
(++ (lst 1) 2))      ;-> 4
lst                  ;-> (1 4 3)

; Decrementing
(set 'x 1)    
(-- x)               ;-> 0

(set 'x 3.8)
(-- x)               ;-> 2
(-- x 1.3)           ;-> 1

(set 'lst '(1 2 3))
(-- (lst 1) 2))      ;-> 0
lst                  ;-> (1 0 3)

Floating point arithmetics

Handles calculations with floating point numbers using add, sub, mul, div, mod, inc, and dec. Operations always return floating point results; fractional parts and NaN values are preserved.

Built-in functions introduced:

• add
  • syntax: (add num-1 [num-2 … ])
  • Notes:
  • All of the numbers in num-1, num-2, and on are summed.
  • Accepts float or integer operands, but it always returns a floating point number.
  • Any floating point calculation with NaN also returns NaN.
• sub
  • syntax: (sub num-1 [num-2 … ])
  • Notes:
  • Successively subtracts the expressions in num-1, num-2 …
  • Accepts float or integer operands, but it always returns a floating point number.
  • If only one argument is supplied, its sign is reversed.
  • Any floating point calculation with NaN also returns NaN.
• mul
  • syntax: (mul num-1 num-2 [num-3 … ])
  • Notes:
  • Evaluates all expressions num-1 num-i calculating and returning the product.
  • Accepts float or integer operands, but it always returns a floating point number.
  • Any floating point calculation with NaN also returns NaN.
• div
  • syntax: (div num-1 num-2 [num-3 … ])
  • syntax: (div num-1)
  • Notes:
  • Successively divides num-1 by the number in num-2—
  • Accepts float or integer operands, but it always returns a floating point number.
  • Any floating point calculation with NaN also returns NaN.
• mod
  • syntax: (mod num-1 num-2 [num-3 … ])
  • syntax: (mod num-1)
  • Notes:
  • Calculates the modular value of the numbers in num-1 and num-2.
    • numerator - n * denominator where n is quotient rounded towards zero
  • Result has same sign as numerator.
  • Magnitude of result < magnitude of denominator.
  • With single argument, 1 is assumed for num-2 and the result is the fractional part of num-1.
  • Use the % (percent sign) function when working with integers only.
• inc !
  • syntax: (inc place [num])
  • Notes:
  • Increments the number in place by 1.0 or by the optional number num and returns the result.
  • Integer numbers are conveted into floating point type.
  • place is either a symbol or a place in a list structure holding a number, or a number returned by an expression.
  • If a symbol for place contains nil, it is treated as if containing 0.0
  • Places in a list structure or a number returned by another expression can be updated too
• dec !
  • syntax: (dec place [num])
  • Notes:
  • Decrements the number in place by 1.0 or by the optional number num and returns the result.
  • Integer numbers are conveted into floating point type.
  • place is either a symbol or a place in a list structure holding a number, or a number returned by an expression.
  • If a symbol for place contains nil, it is treated as if containing 0.0
  • Places in a list structure or a number returned by another expression can be updated too

Examples:

; Basics
(add 2 3.25 9)   ;-> 14.25
(add 1 2 3 4 5)  ;-> 15

(sub 10 8 0.25)  ;-> 1.75
(sub 123)        ;-> -123

(mul 1 2 3 4 5 1.1)  ;-> 132
(mul 0.5 0.5)        ;-> 0.25

(div 10 3)                 ;-> 3.333333333
(div 120 (sub 9.0 6) 100)  ;-> 0.4
(div 10)                   ;-> 0.1

(mod 10.5 3.3)   ;->  0.6
(mod -10.5 3.3)  ;-> -0.6
(mod -10.5)      ;-> -0.5

; Incrementing
(set 'x 0)    ;-> 0
(inc x)       ;-> 1
(inc x 0.25)  ;-> 1.25
(inc x)       ;-> 2.25

(set 'z nil)
(inc z) ;-> 1

(set 'lst '(1 2 3 4))
(inc (lst 3) 0.1) ;-> 4.1

; Decrementing
(set x 10)    ;-> 10
(dec x)       ;-> 9
(dec x 0.25)  ;-> 8.75

(set 'z nil)
(dec z) ;-> -1

(set 'lst '(1 2 3 4))
(dec (lst 3) 0.1) ;-> 3.9

Compare expressions

Compare two or more values using <, >, =, <=, >=, and !=. They return true or false and can be applied to integers, floats, strings, or symbols.

• < > = <= >= !=
  • syntax: (func-op exp-1 [exp-2 …])
  • Notes:
  • Expressions are evaluated and compared successively.
  • Returns true if all comparisons succeed; nil on first failure.
  • Single argument assumes 0 as second operand.
  • Can compare atoms, numbers, symbols, strings, and lists.
  • Lists are compared element-wise; longer lists are greater if elements match.
  • Mixed types are compared by type precedence; integers and floats are converted as needed.
  • Type precedence (low → high):
    • Atoms: nil, true, integer/float, string, symbol, primitive
    • Lists: quoted list/expression, list/expression, lambda, lambda-macro

Examples:

(< 3 5 8 9)                     ;-> true
(> 4 2 3 6)                     ;-> nil
(< "a" "c" "d")                 ;-> true
(>= duba aba)                   ;-> true
(< '(3 4) '(1 5))               ;-> nil
(> '(1 2 3) '(1 2))             ;-> true
(= '(5 7 8) '(5 7 8))           ;-> true
(!= 1 4 3 7 3)                  ;-> true

(< 1.2 6 "Hello" 'any '(1 2 3))           ;-> true
(< nil true)                              ;-> true
(< '(((a b))) '(((b c))))                 ;-> true
(< '((a (b c)) '(a (b d)) '(a (b (d)))))  ;-> true

; Single argument compares against 0
(> 1)    ;-> true ; checks for positive
(> -1)   ;-> nil  ; checks for negative
(= 123)  ;-> nil  ; checks for zero

; list is single argument, members are compared against 0
(map > '(1 3 -4 -3 1 2))   → (true true nil nil true true)

Moving bits with bit shift functions

• <<,>>
  • syntax: (<< int-1 int-2 [int-3 …])
  • syntax: (>> int-1 int-2 [int-3 …])
  • syntax: (<< int-1)
  • syntax: (>> int-1)
  • Notes:
  • int-1 is shifted left or right by int-2 bits, then by int-3, and so on.
  • Shifting right duplicates the most significant bit (arithmetic shift).
  • For 64-bit integers, shifting up to 63 bits is possible.
  • With a single argument, shifts by one bit.
  • &
  • syntax: (& int-1 int-2 [int-3 … ])
    • A bitwise and operation is performed on the number in int-1 with the number in int-2, then successively with int-3, etc.
  • |
  • syntax: (| int-1 int-2 [int-3 … ])
    • A bitwise or operation is performed on the number in int-1 with the number in int-2, then successively with int-3, etc.
  • ^
  • syntax: (^ int-1 int-2 [int-3 … ])
    • A bitwise xor operation is performed on the number in int-1 with the number in int-2, then successively with int-3, etc.
  • ~
  • syntax: (~ int)
    • A bitwise not operation is performed on the number in int, reversing all of the bits.

Examples:

(>> 0x8000000000000000 1) ;-> 0xC000000000000000 - not 0x0400000000000000!

(<< 1 3)      ;->  8
(<< 1 2 1)    ;->  8
(>> 1024 10)  ;->  1
(>> 160 2 2)  ;-> 10

(<< 3)        ;->  6
(>> 8)        ;->  4

(& 0xAABB 0x 000F) ;-> 11 which is 0xB
(| 0x10 0x80 2 1)  ;-> 147
(^ 0xAA 0x55)      ;-> 255
(format "%X" (~ 0xFFFFFFAA)) ;-> "55"
(~ 0xFFFFFFFF)               ;-> 0

Define user function or assign a value to a symbol

• define
  • syntax: (define (sym-name [sym-param-1 … ]) [body-1 … ])
  • syntax: (define (sym-name [(sym-param-1 exp-default) … ]) [body-1 … ])
  • syntax: (define sym-name exp)
  • Notes:
  • Define is equivalent to assigning a lambda expression to sym-name.
  • Function call:
    • All arguments are evaluated and assigned to parameters.
    • Body expressions are evaluated.
    • Returns the last expression evaluated in the body.
  • Parameters are optional:
    • Without argument, parameter defaults to nil.
    • If exp-default is provided, parameter takes that value.
  • define itself returns the assigned lambda expression.
  • See also: lambda, fn, set

Examples:

Define and call the function func1

(define (func1) 7) ;-> (lambda () 1)
;        ^name  ^value to return (the last expression)
(func1) ;-> 7
;  ^call function

Define function with parameter

;             parameter x
;             |
(define (area x) (* x x))
;        ^name      ^multiplication of x is returned
(area 5) ;-> 25
;     ^argument for parameter x

Define function with default parameter value

Parameters can have default values specified in the function definition

(define (area (x 5)) (* x x))
;                ^default value for x
(area) ;-> 25
(area 51) ;-> 2601

Default expressions are evaluated in the function’s current environment:

(define (area (x 5) (y (div x 2))) (list x y))
;                      ^ default value for y is computed calling (div x 2)
(area)     ;-> (5 2.5)
(area 30)  ;-> (30 15)
(area 3 4) ;-> (3 4) - value for y was provided so no computations is needed

Define function by assigning a lambda expression to sym-name

;     symbol name becomes function name
;     |
(set 'area (lambda ((x 5)) (* x x)))
;          ^--lambda expression---^
(area) ;-> 25
(area 8) ;-> 64

Define function assigning a fn expression to sym-name

Keyword fn is just a shorter form of writing lambda. fn is shorter and more typo prone :)

(set 'area (fn ((x 5)) (* x x)))

Anonymous function

lambda or fn expressions may be used by themselves as anonymous functions without being defined as a symbol:

((lambda (x y) (* x y)) 2 3) ;-> 6
((fn (x y) (* x y)) 2 3)     ;-> 6
;     ^-^parameters ^-^arguments

Define can assign a value to symbol like the set function

(define x 123) ;-> 123
(set 'x 123) ; equivalent

; the following are equivalent too
; all 3 expression will create the function area.
(define area (lambda ( x y) (* x y)))
(set 'area (lambda ( x y) (* x y)))
(define (area x y) (* x y))

Trying to redefine a protected symbol like built-in function will cause an error.

Sort elements

• sort !
  • syntax: (sort list [func-compare])
  • syntax: (sort array [func-compare])
  • Notes:
  • All elements in a list or array are sorted in ascending order.
  • Any type of element can be sorted.
  • Nested lists or arrays are compared recursively.
  • Different types are sorted by this precedence:
    • Atoms: nil, true, integer/float, string, symbol, primitive
    • Lists: quoted expression, list, lambda, lambda-macro
  • Sort is destructive: it modifies the original list/array and returns it.
  • Uses stable binary merge-sort (≈ O(n log₂ n)), preserving order of equal elements.
  • Optional comparison operator, user-defined function, or anonymous function can be supplied.
    • If used, it must support <= or >= to maintain stability.
  • The functor/operator can be given with or without a preceding quote.
  • See also:

The sort function can be used to sort lists and arrays. To sort a string, first convert it into a list of characters, then sort that list and join the characters back into a string.

Examples:

(join (sort (explode "note")))
(join (sort (explode "note") >))

Select elements from list and string

• select
  • syntax: (select list list-selection)
  • syntax: (select list [int-index_i … ])
  • syntax: (select string list-selection)
  • syntax: (select string [int-index_i … ])
  • Notes:
  • select picks elements from a list or characters from a string.
  • For lists:
    • One or more elements are chosen using specified indices.
    • Elements can be repeated and reordered freely.
  • For strings:
    • One or more characters are chosen using specified indices.
    • Characters can be repeated and reordered freely.
  • Negative indices count from the end.
  • The order of indices determines the output sequence.
  • See also:

Examples:

Select for lists

(setq lst '(1 2 3 4 5))
(select lst 0 3) ;-> (1 4)
; or
(select lst '(0 3)) ;-> (1 4)

Select for strings

(setq str "hello")
(select str (0 4)) ;-> "ho"
; or
(select str '(0 4)) ;-> "ho"

Special chapter: Sudden death :)

The following code or features can cause sudden death to your love or hate for newLISP

Crawler-Tractor concept

Contexts

Cameyo42 newLISP code examples

etc etc.