;; This file is a tutorial to the basics of the Common Lisp programming language.
;; The file contains explainations as Lisp commments [a line starting with a semicolon]
;; and executable examples.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;
;;; Lisp as a pocket calculator for musical math: numbers and numerical functions
;; A number evaluates to itself:
;; Evaluate in Emacs by [i] placing cursor after number, [ii] pressing the key sequence
;; control-c control-e (C-c C-e)
;; Evaluate in MCL by [i] placing cursor after number, [ii] pressing return [key in number block]
;; Watch the listener...
7 ; -> 7 [means 'evaluates to 7']
3.14
;; A simple function call, an application of a function.
;; Syntax: [i] a list, ie. something in round paratheses, [ii] first list element is function,
;; [iii] all succeeding list elements are function arguments.
;; Semantic: first all function arguments are evaluated, then the function processes the
;; evaluated arguments according its definition.
;; Evaluate examples as described above.
(+ 7 5) ; -> 12 [means '7 + 5 = 12']
(* 7 5)
;; Nested function calls:
;; Note that first the inside addition is evaluated, then the outside multiplication.
(* (+ 3 4) 7) ; -> 49
;; Musical examples:
;; Transposing a MIDI pitch: middle c raised by a fifth [ie. 7 semitones].
(+ 60 7) ; -> 67
;; Transposing a frequency: concert pitch 'a' raised by a fifth
;; [Lisp supports numerical fractions].
(* 440 3/2) ; -> 660
;; Tempo: transform beats per minute value 120 into seconds per beat.
(/ 60.0 120) ; -> 0.5
;; Lisp supports very many numeric functions, to find out the function name for a particular
;; numeric function you may want to check the Lisp reference.
;; Abstract syntax of a function application / a function call: items in angle brackets <>
;; stand for programming constructs -- here, stands for an arbitrary function.
;; The star * means that its proceeding construct occurs either 0, 1 or more times.
; ( *)
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;
;;; Variable definitions give values names
;; Variables are unknowns, represented by a symbol and bound to some value.
;; pi is a predefined variable, bound to 3.141592653589793
pi ; -> 3.141592653589793
;; User variables can be defined by 'let'.
;; The syntax of let is a bit complex at first sight:
;; the following examples says 'let x have the value of 3, then multiply x with itself'.
;; Note the double parentheses around the variable definition.
(let ((x 3))
(* x x)) ; -> 9
;; A variable defined by let is only visible in the body of let,
;; ie. its surrounding parenthesis.
x ; error: is has no value outside let
;; let is a special Lisp construct: in all previous examples all arguments where
;; evaluated before usage. However, x is not evaluated in the variable definition
;; [the first occurence of x in let]. In the let body x evaluates to 3.
;; let can define multiple variables [hence the double parentheses].
;; Using variables with meaningful names makes code more easy to read.
;; Musical example: raise concert pitch by a fifth.
(let ((a4 440)
(fifth 3/2))
(* a4 fifth)) ; -> 660
;; Transforms beats per minute in seconds per beat.
(let ((bpm 120))
(/ 60.0 bpm)) ; -> 0.5
;; Abstract syntax for let:
; (let (*) )
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;
;;; Put functionality to reuse in a function
;; A function encapsulates some [arbitrary complex] computation into a single entity.
;; That way a function definition helps to structure a program.
;; After their definition, functions can be used [i.e. called] like buildin functions.
;; Functions may get arguments [some data, given only when the function is called].
;; All function arguments are evaluated before used in the function.
;; 'defun' [short for 'DEfine-FUNction'] defines a
;; function and gives the function a name.
;; The first argument of defun is the name for the function, the second argument is a list
;; of arguments [ie. the arguments are surrounded by parantheses]. The third argument defines the
;; function body.
(defun square (x)
(* x x))
; (square 3) -> 9
;; 'defun' is a special Lisp construct. Non of its arguments are evaluated directly.
;; When the define function is called, the variables in the function are bound by the
;; arguments
;; Musical examples:
(defun transpose-frequency (pitch interval)
(* pitch interval))
; (transpose-frequency 440 3/2) -> 660
(defun metronome->seconds (bpm)
"Transforms beats per minute in seconds per beat."
(/ 60.0 bpm))
;; (metronome->seconds 120) -> 0.5
;; abstract syntax for a function definition
(defun (*)
)