;=====
; In-class examples for Week 2 Lecture 1 - 2025-09-02
;     Cleaned up after class!
; last modified: 2025-09-02

;-----
; make available the functions and definitions in the module 2htdp/image

(require 2htdp/image)

;=====
; reminder: compound expression syntax:
;
; (operation arg-expr1 arg-expr2 ...)
;
; BUT: a compound expression's argument expressions
;     but be of the data type(s) expected, in the
;     order expected, for that operation

;-----
; more examples of compound expressions

(circle 23
        "solid"
        "darkgreen")

(regular-polygon 100 8 "outline" "gray")

;=====
; to describe functions, we will use the
;     following CLASS-style standard versions
;     of:
;     *   a function signature
;     *   a purpose statement
;    
; (NOTE: our CLASS STYLE for these is STRICTER than that in
; the course text...!
; *   BELOW is the style you are expected to use in CS 111
;     course assignments and exams.
;====
; a function signature is a comment that includes:
; *   the function's name
; *   the data type of each of its expected arguments
; *   the data type of the value it returns
; ...essentially, SYNTAX info for this function!
;
; CS 111 CLASS style for a function signature comment:
;
; ; signature: funct-name: desired-arg-type desired-arg-type
; ;                        desired-arg-type ... -> ret-type

;=====
; examples of function signature comments for several
;     Beginning Student Level (BSL) Racket built-in
;     functions:

; signature: string=?: string string -> boolean

; signature: regular-polygon: number number string string -> image

; NOTE: remember to use data types in function signatures

;----
; do you see that, especially for regular-polygon,
;     you NEED more information,
;     in addition to the function signature,
;     to be able to know how to reasonably use it?

;=====
; a purpose statement is a comment that basically
;     provides the SEMANTICS/meaning of this function --
;
; a purpose statement is a comment that DESCRIBES what
;   the function expects and DESCRIBES what it returns
;   (and also describes any side-effects it has),
;   formatted as follows:
;
; purpose: expects [describe what it expects] and returns
;   [describe what it returns]
;
; NOTE: class style is to explicitly SAY
;     expects ... and returns ...
; NOTE: these are expected to be DESCRIPTIVE -- don't just repeat
;     the signature!

;-----
; for example, let's add a purpose statement comment
;     along with the function signature given earlier for
;     BSL Racket's built-in function string=?
; (typically, we will write a function's signature and purpose statement
;     comments smushed together like this)

;-----
; signature: string=?: string string -> boolean
; purpose: expects two strings to be compared and returns
;     whether they are equivalent (whether
;    their values contain the same characters in the
;    same order)

(string=? "moo" "Moo")
(string=? "moo" "moo")

;-----
; and, let's add a purpose statement comment
;     along with the function signature given earlier for
;     BSL Racket's 2htdp/image module's function regular-polygon:

;-----
; signature: regular-polygon: number number string string -> image
; purpose: expects the length of side in pixels, the desired
;    number of sides, the desired style, and the desired color,
;    and returns a regular polygon with those features

(regular-polygon (* 25 2)
                 (string-length "abcdefgh")
                 "solid" "purple")

;-----
; note that string=? only works with arguments of type string,
;     and = only works with arguments of type number

;-----
; signature: = : number number ... number -> boolean
; purpose: expects two or more numbers, and returns whether
;    their values are equal

(= (string-length "moo")
   (string-length "Moo"))

;-----
; note that Racket provides two different functions
;     string=? and string? that do different things!
; (below, we are using Anything to mean an expression of
;     ANY data type...!)

;-----
; signature: string?: Anything -> boolean
; purpose: expects any expression with a value
;    and returns #true if it is of type string
;    and returns #false otherwise

(string? "moo")
(string? (string-length "moo"))

(string? (string-length "moo"))

;=====
; and, in the same vein: built-in functions boolean? and image?

;-----
; signature: boolean?: Anything -> boolean
; purpose: expects any expression with a value
;    and returns #true if it is of type boolean
;    and returns #false otherwise

(boolean? #true)
(boolean? 3)

;-----
; signature: image?: Anything -> boolean
; purpose: expects any expression with a value
;    and returns #true if it is of type image
;    and returns #false otherwise

(image? 3)
(image? (circle 20 "outline" "orange"))

;=====
; ASIDE -- Racket has relational operators like
;    > < >= <=
; and boolean operators like
;    and or not

;-----
; signature: <: number number ... number -> boolean
; purpose: expects 2 or more number arguments and returns whether
;     the 1st is less than the 2nd, which is less than the 3rd, etc.

(< 3 5)
(< 5 3)
(< 1 2 3 4 5 100)

;-----
; signature: >=: number number ... number -> boolean
; purpose: expects 2 or more number arguments and returns whether
;     the 1st is less-than-or-equal to the 2nd, which is less than
;     or equal to the 3rd, etc.

(>= 3 (+ 2 1))
(>= 15 (* 3 5) 14 13)

;-----
; signature: and: boolean boolean ... boolean -> boolean
; purpose: expects two or more boolean expressions,
;    and returns whether ALL of them have the value #true

(and (< 3 5) (>= 3 (+ 2 1)) (< 5 3) (= 2 2))

; (note: as soon as the and operation finds an argument whose value is
;     #false, it doesn't even bother doing anything with the
;     rest of the arguments -- DrRacket lets you know this
;     by highlighting those arguments when you click Run!

;-----
; signature: or: boolean boolean ... boolean -> boolean
; purpose: expects two or more boolean expressions,
;    and returns whether AT LEAST ONE of them has the value #true

(or (< 3 5) (>= 3 (+ 2 1)) (< 5 3) (= 2 2))

; (similarly, as soon as the or operation finds an argument whose value is
;     #true, it doesn't even bother doing anything with the
;     rest of the arguments -- again, DrRacket lets you know this
;     by highlighting those arguments when you click Run!

;-----
; signature: not: boolean -> boolean
; purpose: expects a boolean expression, and returns #false if
;    its value is #true, or returns #true if its value is #false

(not #true)
(not #false)

;=====
; some functions can can give a version of a value
;    in a different type

;-----
; signature: string->number: string -> number
; purpose: expects a string that can
;    be considered number-like, and returns
;    the corresponding number

(string->number "34")

;-----
; signature: number->string: number -> string
; purpose: expects a number, and returns
;    a version of that number in the form of a string 

(number->string 34)

; although sometimes the string it returns is, well,
;     surprising...!

(number->string 34.5)

;-----
; signature: text: string number string -> image
; purpose: expects a string, a desired font-size, and a color
;     expressed as a string, and returns an image of text in that
;     font-size and color

(text "moo" 30 "maroon")
(text "wine" 40 (color 128 0 32))

;-----
; signature: above: image image ... image -> image
; purpose: expects two or more images, and returns
;     a single image consisting of the first image
;     above the second image above ... above the last image

(above (text "moo" 30 "maroon")
       (text "wine" 40 (color 128 0 32))
       (text "moo" 30 "maroon")
       (text "wine" 40 (color 128 0 32))
       (text "moo" 30 "maroon")
       (text "wine" 40 (color 128 0 32))
       (text "moo" 30 "maroon")
       (text "wine" 40 (color 128 0 32)))

;-----
; Gee, wouldn't it be nice to be able to give a
;     name to a particular value, and use that
;     name instead of a possibly-cumbersone compound
;     expression, for example?
;
; Programming languages provide means for a programmer
;     to give names they choose to various things.
;
; An identifier is a name given by the programmer to
;     such a thing.
;
; Like what? Some of the common things are:
; *    the name of a new function
; *    a value you want to reuse (a named constant)
; *    a parameter that represents an argument to
;      be named later

;=====
; BSL Racket identifier syntax:
;    any consecutive collection of characters that
;    *   do not include:   ()[]{}",';#|\
;    *   do not include blank or newline
;    *   do not meet the syntax rules for any other type

;-----
; common STYLE (and class style)
;    make identifiers MEANINGFUL and NON-misleading
;
; and typically start with a letter...!

;-----
; There will be some other style requirements based on the
;     variety of identifier:
; *   For example, CS 111 class style is to write named constants
;     in all-uppercase
; *   And function names should be all-lowercase or camelCase starting with
;     lowercase letter
; *   And parameter names should also be all lowercase or camelCase
;     starting with a lowercase letter

;-----
; We'll first demo the syntax for a named constant,
;     a name a programmer chooses to give
;     a constant, unchanging value

;=====
; syntax for a named constant in BSL Racket:
;
; (define DESIRED-NEW-NAME expression)
;
; semantics: define does not return anything!
;     BUT when define is written using the above syntax,
;
;     it has the SIDE-EFFECT of making DESIRED-NEW-NAME
;     a simple expression whose value is the value of
;     the given argument expression,
;
;     and its type is the type of its given argument
;     expression

;=====
; class style: for a name representing a never-changing value,
;    write it in all-uppercase

(define RED-DOT (circle 10 "solid" "red"))

;-----
; now RED-DOT is a simple expression of type image:

RED-DOT

;-----
; ...and RED-DOT can be used anywhere an expression of
;     type image can be used:

(beside RED-DOT RED-DOT RED-DOT RED-DOT RED-DOT RED-DOT)