CheatSheet.org

#+TITLE: JavaScript CheatSheet
# +SUBTITLE: ---Reference Sheet for “What I'm Currently Learning”---
#+MACRO: blurb Quick reference to the tremendously accessible high-level language of the web ^_^
#+AUTHOR: [[http://www.cas.mcmaster.ca/~alhassm/][Musa Al-hassy]]
#+EMAIL: alhassy@gmail.com
#+OPTIONS: toc:nil
#+INCLUDE: CheatSheet/CheatSheetSetup.org
#+PROPERTY: header-args:js  :results output :prologue const assert = require('assert');
#+TODO: Todo | spacing LaTeX

:Setup:

#+begin_src emacs-lisp
(use-package ob-js
  :ensure t
  :config
  (add-to-list 'org-babel-load-languages '(js . t))
  (org-babel-do-load-languages 'org-babel-load-languages org-babel-load-languages)
  (add-to-list 'org-babel-tangle-lang-exts '("js" . "js"))
  (system-packages-ensure "node"))
  ;; use “:results output” for js blocks!

;; Seamless use of babel: No confirmation upon execution.
;; Downside: Could accidentally evaluate harmful code.
(setq org-confirm-babel-evaluate nil)

(load-file (let ((coding-system-for-read 'utf-8))
                (shell-command-to-string "/usr/local/bin/agda-mode locate")))
;; Unicode Input via Agda Input:2 ends here

;; [[file:~/.emacs.d/init.org::*Unicode Input via Agda Input][Unicode Input via Agda Input:3]]
(use-package agda-input
  :ensure nil ;; I have it locally.
  :demand t
  :hook ((text-mode prog-mode) . (lambda () (set-input-method "Agda")))
  :custom (default-input-method "Agda"))
  ;; Now C-\ or M-x toggle-input-method turn it on and offers
;; Unicode Input via Agda Input:3 ends here

#+end_src

Test:
#+BEGIN_SRC js
console.log('ola');
#+END_SRC

#+RESULTS:
: ola

:End:

* LaTeX Extra, Local, Setup  :ignore:

# Empty by default.
#+LATEX_HEADER: \def\cheatsheeturl{https://github.com/alhassy/JavaScriptCheatSheet}

# The following are the defaults & may be omitted.
#+LATEX_HEADER: \def\cheatsheetcols{2}
#+LATEX_HEADER: \landscapetrue
#+LATEX_HEADER: \def\cheatsheetitemsep{-0.5em}

# Example unicode declarations; see section “unicode” below.
#+LATEX_HEADER: \newunicodechar{𝑻}{\ensuremath{T}}
#+LATEX_HEADER: \newunicodechar{⊕}{\ensuremath{\oplus}}
#+LATEX_HEADER: \newunicodechar{≈}{\ensuremath{\approx}}

#+LATEX_HEADER: \newunicodechar{𝓍}{\ensuremath{x}}
#+LATEX_HEADER: \newunicodechar{𝓎}{\ensuremath{y}}
#+LATEX_HEADER: \newunicodechar{𝓈}{\ensuremath{s}}
#+LATEX_HEADER: \newunicodechar{𝓌}{\ensuremath{w}}
#+LATEX_HEADER: \newunicodechar{𝓋}{\ensuremath{v}}

#+LATEX_HEADER: \newunicodechar{ʸ}{\ensuremath{^y}}
#+LATEX_HEADER: \newunicodechar{₋}{\ensuremath{_{-}}}
#+LATEX_HEADER: \newunicodechar{₁}{\ensuremath{_1}}

* Contents                                         :TOC_2:QUOTE:ignore:
#+BEGIN_QUOTE
- [[#extra-local-setup][Extra, Local, Setup]]
- [[#intro][Intro]]
- [[#negative-space][Negative space]]
- [[#types][Types]]
- [[#negative-space-1][Negative space]]
- [[#variable-bindings][Variable Bindings]]
- [[#scope-and-statements][Scope and Statements]]
- [[#negative-space-2][Negative space]]
- [[#arithmetic][Arithmetic]]
- [[#booleans][Booleans]]
  - [[#empty-values][Empty Values]]
- [[#strings][Strings]]
  - [[#string-methods][String Methods]]
  - [[#method-names-shared-with-arrays][Method Names Shared with Arrays]]
  - [[#treating-strings-as-arrays][Treating Strings as Arrays]]
- [[#arrays][Arrays]]
  - [[#array-methods][Array methods]]
- [[#functions][Functions]]
  - [[#intro-1][Intro]]
  - [[#default-values][Default Values]]
  - [[#rest-parameters][Rest Parameters]]
  - [[#higher-order-functions][Higher-order Functions]]
- [[#negative-space-3][Negative space]]
- [[#destructuring-and-the-spread-operator][Destructuring and the “spread” Operator]]
- [[#objects][Objects]]
  - [[#object-creation][Object Creation]]
  - [[#getters-and-setters----get-set][Getters and Setters -- ~get, set~]]
  - [[#dictionries-or-maps][Dictionries or maps]]
- [[#negative-space-4][Negative space]]
- [[#the-this-keyword][The ~this~ Keyword]]
  - [[#call][~Call~]]
  - [[#the-this-of-parent-scopes][The ~this~ of Parent Scopes]]
- [[#object-oriented-programming][Object-Oriented Programming]]
  - [[#intro-2][Intro]]
  - [[#adding-new-methods-or-overriding-methods][Adding New Methods or Overriding Methods]]
  - [[#inheritance-and-null-parents][Inheritance and Null Parents]]
  - [[#1-prototype-example][⟨1⟩ Prototype Example]]
  - [[#2-manual-constructor-functions][⟨2⟩ Manual Constructor Functions]]
  - [[#3-constructor-functions-with-new][⟨3⟩ Constructor Functions with ~new~]]
  - [[#4-class-notation][⟨4⟩ ~class~ Notation]]
- [[#the-iterator-interface][The Iterator Interface]]
- [[#negative-space-5][Negative space]]
- [[#javascript-and-the-browser][JavaScript and the Browser]]
  - [[#large-scripts][Large Scripts]]
- [[#break][Break]]
- [[#reads][Reads]]
- [[#some-fun-stuff-_][Some Fun Stuff ^_^]]
#+END_QUOTE

* Intro                                                              :ignore:

#+latex: \vspace{1em}
  
JavaScript is what everyone calls the language, but that name is [[https://softwareengineering.stackexchange.com/questions/135905/legal-ramifications-of-use-of-the-javascript-trademark][trademarked]] (by
Oracle, which inherited the trademark from Sun). Therefore, the official name of
JavaScript is ECMAScript. The “ECMA” in “ECMAScript” comes from the organisation
that hosts the primary standard, the European Computer Manufacturers
Association.

# JavaScript initially did not have exceptions, and so it simply “fails silently”
# by giving error values, ~0 / 0 ≈ NaN~, rather than raising exceptions.

As the programming language of browsers, it is remarkably error-tolerant. It
simply “fails silently” by giving error values such as ~undefined~ when things
are not there or ~0 / 0 ≈ NaN~ for nonsensical numeric expressions.

By accident, there are two (mostly) /interchangeable/ values ~null~ and
~undefined~ that denote the absence of a meaningful value. Many operations that
don't produce meaningful values yield ~undefined~ simply because they have to
yield /some/ value. [[https://funcall.blogspot.com/2007/11/in-kingdom-of-nouns.html?m=1][Here]] is a neat story about null.

* COMMENT This is how we do it ---Assertions


An [[https://nodejs.org/api/assert.html#assert_strict_mode][assertion]] describes what the result of a computation is expected to look like
and throws an exception if those expectations are not met.
#+BEGIN_SRC js
const assert = require('assert');
assert.ok(!null)

// Printing a value to standard out (another method call)
console.log('Hello!');
#+END_SRC

#+RESULTS:
: Hello!
* Negative space :ignore:
#+latex: \vspace{-1em}
* Types

JavaScript considers types only when actually running the program, and even
there often tries to implicitly convert values to the type it expects.

+ ~typeof~ gives a string value naming the type of its argument.
+ The functions ~Number, String, Boolean~ try to convert values into those
  types.
#+BEGIN_SRC js
  console.log(typeof 4.5, typeof '4.5', typeof true)
  // ⇒ number string boolean

  console.log(8 * null // Multiplication needs numbers so null ↦ 0
               , 'five' * 2 // 'five' is not a number, so 'five' ↦ NaN
               , '5' - 1    // Subtraction needs numbers so '5' ↦ 5
               , '5' + 1)   // The first is a string, 
                            // so “+” denotes catenation, so 1 ↦ '1'

  console.log(Number('2.3')   // ⇒ 2.3
             ,Number('five')  // ⇒ NaN
             ,Boolean('five') // ⇒ true
             ,Boolean('')     // ⇒ false
             ,String(NaN)     // ⇒ 'NaN'
             ,String(null))  // ⇒ 'null'
#+end_src

#+RESULTS:
: 2.3 NaN true false NaN null
* Negative space :ignore:
#+latex: \vspace{-1em}
* Variable Bindings

~let x₀ = v₀, …, xₙ = vₙ;~ introduces 𝓃-new names ~xᵢ~ each having value ~vᵢ~.
    - The ~vᵢ~ are optional, defaulting to ~undefined~.
    - The program crashes if any ~xᵢ~ is already declared.
    - Later we use ~xᵢ = wᵢ;~ to update the name ~xᵢ~ to refer to a new value
      ~wᵢ~.
        * Augmented updates: ~x ⊕= y ≡ x = x ⊕ y~
        * Increment: ~x-- ≡ x += 1~
        * Decrement: ~y-- ≡ x -= 1~
        
#+BEGIN_SRC js
let x, y = 1, z;
console.log(x, y, z); // ⇒ undefined 1 undefined
#+END_SRC
    
- In the same way, for the same purpose, we may use ~var~ but it has undesirable
  properties; e.g., its declarations are in the global scope and no error is
  raised using ~var x = ⋯~ if ~x~ is already declared.

- In the same way, we may use ~const~ to introduce names that are constant: Any
  attempt to change their values crashes the program.
  
- A binding name may include dollar signs ($) or underscores (_) but no other
  punctuation or special characters.

* COMMENT Negative space                                             :ignore:
#+latex: \vspace{-1em}
* Scope and Statements

Each binding has a scope, which is the part of the program in which
the binding is visible. For bindings defined outside of any function
or block, the scope is the whole program—you can refer to such
bindings wherever you want. These are called global.

# #
#+begin_parallel org
#+BEGIN_SRC js
let x = 10;

{ // new local scope
  let y = 20;
  var z = 30;
  console.log(x + y + z); // ⇒ 60
}

// y is not visible here
// console.log(y)

// But z is!
console.log(x + z); // ⇒ 40
#+END_SRC

#+latex: \columnbreak

#+latex: \vspace{2em}
⊙ /global bindings/ are defined outside of any block and can be referenced anywhere.

#+latex: \vspace{1em}
⊙ /local bindings/ are defined within a block and can only be referenced in it.

#+latex: \vspace{1em}
⊙ =let, const= declare local bindings;  =var= always makes global ones!

#+end_parallel


Besides the assignment statement, we also have the following statements:
+ Conditionals:
  ~if (condition) A else B~
+ Blocks:
  If ~Sᵢ~ are statements, then ~{S₀; …; Sₙ;}~ is a statement.
+ The ~for/of~ syntax applies to arrays, strings, and other iterable structures
  ---we will define our own later.  
  #+BEGIN_SRC js
// Print all the elements in the given list.
for (let x of ['a', 1, 2.3]) {
  console.log(`x ≈ ${x}`);
  }
#+END_SRC

JavaScript is whitespace insensitive.

* Negative space :ignore:
  #+latex: \vspace{-1em}
* [[https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number][Arithmetic]]

In addition to the standard arithmetic operations, we have ~Math.max(x₀, …, xₙ)~
that takes any number of numbers and gives the largest; likewise ~Math.min(⋯)~.
Other common functions include ~Math.sqrt, Math.ceil, Math.round, Math.abs,~ and
~Math.random()~ which returns a random number between 0 and 1.
Also, use ~%~ for remainder after division.

#+BEGIN_SRC js
  // Scientific notation: 𝓍e𝓎 ≈ 𝓍 × 10ʸ
  console.log(1, 2.998e8, 100 + 4 * 11)

  // Special numbers so that division “never crashes”.
  console.log(1/0, -1/0, Infinity - 10) // ⇒ Infinity -Infinity Infinity
  console.log(Infinity - Infinity, 0/0) // ⇒ NaN NaN

  // Random number in range min...Max
  Math.floor(Math.random() * (max - min) + min)
#+END_SRC

:Hide:
#+BEGIN_SRC js
// Random number in 0..9
console.log(Math.floor(Math.random() * 10));

let max = 100, min = 30
let x =  Math.floor(Math.random() * (max - min) + min);
console.log(x)
#+END_SRC
:End:

~NaN~ stands for “not a number”, it is what you get when a numeric expression
    has no meaningful value.
    # It is what we get when “things go wrong”, like ~1 / 0~.

+ Any ~NaN~ in an arithmetic expressions swallows the whole expression into a ~NaN~.

+ ~Number.isNaN(x)~ is true iff ~x~ is ~NaN~.

Everything is equal to itself, except ~NaN~. Why? ~NaN~ denotes the result of
nonsensical computations, and so is not equal to the result of any other
nonsensical computation.
#+BEGIN_SRC js
console.log(NaN == NaN) // ⇒ false
#+END_SRC

#+RESULTS:
: false

* [[https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean][Booleans]]

The empty string =''=, list =[]=, and ~0, NaN~ are falsey ---all else is truthy.
+ Note: ~(p < q < r) ≈ (p < q) < r~, it is not conjunctive!

#+BEGIN_SRC js
console.log(true, false, 3 > 2, 1 < 2, 1 != 2, 4 <= 2 < 3)

// Upper case letters come first, then lower case ones.
console.log('abc' < 'def', 'Z' < 'a')

// Equality with coercions, and without.
console.log(1.23 == '1.23', 1.23 === '1.23')
#+END_SRC

#+RESULTS:
: true false true true true true false
: true true
: true false

+ /Precise Equality/ ~===~ is equality with no type coercions.
  # - ~x == y~ ≡  ~coe x === coe y~

+ Applying the “not” =!= operator will convert a value to Boolean type before negating
  it.

+ Precedence: Relationals like ~==~ and ~>~ are first, then “and” ~&&~, then “or” ~||~.

+ The ternary operator: =condition ? if_true : if_false=

# && and || are lazy.

** Empty Values

 #+BEGIN_SRC js
 console.log(null == undefined) // ⇒ true
 #+END_SRC

 #+RESULTS:
 : true

 Only the empty values are coerced into being equal, no other value
 is equal to an empty value. As such, ~x != null~ means that ~x~ is not an
 empty value, and is in fact a real meaningful value.

 Since ~&&~ and ~||~ are lazy, ~x || y~ means return ~x~ if ~x != false~
 and otherwise return ~y~; i.e., /give me x if it's non-empty, else y/.

 Likewise, ~x && y~ means /give me y, if x is nonempty, else give me the particular
 empty value x/.

 #+begin_src js
 console.log( 4  == 3   && 4   // 3 is truthy 
            ,''  == ''  && 4   // '' is falsey
            ,'H' == 'H' && 4   // 'H' is truthy
            , 0  == 0   && 4   // 0 is falsey
            , 4  == 0   || 4   // 0 is falsey
            )
 #+end_src

 #+RESULTS:
* [[https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String][Strings]]

  Any pair of matching single-quotes, backticks, or double-quotes will produce a
  string literal. However, backticks come with extra support: They can span
  multiple lines and produce /formatted strings/, where an expression can be
  evaluated if it is enclosed in ~${⋯}~.

:Hide:
#+BEGIN_SRC js
console.log('this', `and`, "this")
console.log('single: \', backtick: `, and double: "')
// ⇒ single: ', backtick: `, and double: "
#+END_SRC
:End:

#+BEGIN_SRC js
console.log(`half of 100 is ${100 / 2}`) // ⇒ half of 100 is 50
#+END_SRC

** String Methods

+ ~s.repeat(𝓃)~ ≈ Get a new string by gluing 𝓃-copies of the string 𝓈.
+ Trim removes spaces, newlines, tabs, and other whitespace from the start and end of a string.
  #+BEGIN_SRC js
  console.log("  okay \n ".trim()); // ⇒ okay
#+END_SRC
+ ~s.toUpperCase()~ and ~s.toLowerCase()~ to change case.
+ ~𝓈.padStart(𝓁, 𝓅)~ ≈ Ensure 𝓈 is of length ≥ 𝓁 by padding it with 𝓅 at the start.
  #+BEGIN_SRC js
  console.log(String(6).padStart(3, "0")); // ⇒ 006
#+END_SRC
+ ~𝓈.replace(/./g, c => p(c) ? f(c) : '')~ ≈ Keep only the characters that
  satisfy predicate ~p~, then transform them via ~f~.
  #+BEGIN_SRC js
let s = 'abcde'.replace(/./g, c => 'ace'.includes(c) ? c.toUpperCase() : '')
console.log(s); // ⇒ ACE
#+END_SRC

** Method Names Shared with Arrays

The following methods also apply to arrays.
:Justification:
#+BEGIN_SRC js
console.log(Object.getOwnPropertyNames(String.prototype)
           .filter(x => Object.getOwnPropertyNames(Array.prototype).includes(x)))
#+END_SRC
:End:
+ ~s.length~ ⇒ Length of string
+ ~s[𝒾]~ ⇒ Get the 𝒾-th character from the start
  - Unless ~0 ≤ 𝒾 < s.length~, we have ~s[𝒾] = undefined~.
+ ~s.concat(t)~ ⇒ Glue together two strings into one longer string; i.e., ~s + t~.
  #+BEGIN_SRC js
console.log(('cat' + 'enation').toUpperCase()) // ⇒ CATENATION
#+END_SRC
+ ~s.includes(t)~ ⇒ Does ~s~ contain ~t~ as a substring?
+ ~s.indexOf(t)~ ⇒ Where does substring ~t~ start in ~s~, or -1 if it's not in ~s~.
  - To search from the end instead of the start, use ~lastIndexOf~.
  # Both indexOf and lastIndexOf take an optional second argument that indicates where to start searching.
+ ~s.slice(𝓂,𝓃)~ ⇒ Get the substring between indices 𝓂 (inclusive) and 𝓃 (exclusive).
  - 𝓃 is optional, defaulting to ~s.length~.
  - If 𝓃 is negative, it means start from the end: ~s.slice(-𝓃) ≈ s.slice(s.length - 𝓃)~.    
  - ~s.slice()~ ⇒ Gives a copy of ~s~.

** Treating Strings as Arrays

- There is no character type, instead characters are just strings of length 1.
- You can “split” a string on every occurrence of another string to get a list
  of words, and which you can “join” to get a new sentence. ~𝓈.split(𝒹).join(𝒹) ≈ 𝓈~.
- To treat a string as an array of characters, so we can apply array only methods such
  as ~f = reverse~, we can use split and join:
  | ~𝓈.split('').f().join('')~ |
- Keeping certain characters is best done with regular expressions.

** COMMENT Warning: Care needs to be taken when working with strings of Unicode symbols.

#+BEGIN_SRC js
console.log("🐴👟".length); // ⇒ 4!
console.log("🐴👟"[1]); // Invalid half-characters!
for (let it of "🐴👟") console.log(it); // Better!
#+END_SRC

UTF-16, the format used by JavaScript strings, describes most common characters
using a single 16-bit code unit but uses a pair of two such units for others.
UTF-16 is generally considered a bad idea today.

* [[https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array][Arrays]]
# arrays are objects!

Array indexing, ~arr[𝒾]~, yields the 𝒾-th element from the start; i.e., the
number of items to skip; whence ~arr[0]~ is the first element.

# #
#+begin_parallel org
#+BEGIN_SRC js
  let numbers = [];

  numbers.push(2);
  numbers.push(5);
  numbers.push(7);

  // or 
  numbers = [2, 5, 7]

  console.log(numbers[2]); // ⇒ 7
  let last = numbers.pop() // ⇒ 7
  console.log(numbers) // ⇒ [ 2, 5 ]

  // ⇒ undefined
  console.log(numbers[2]);

  // Is an element in the array? No.
  console.log(numbers.includes(7)) 

  numbers  = numbers.concat('ola')
  console.log(numbers)
  // ⇒ [ 2, 5, 'ola' ]

  console.log(numbers.reverse()) 
  // ⇒ [ 'ola', 5, 2 ]
#+END_SRC

#+RESULTS:
: 7
: [ 2, 5 ]
: undefined
: false
: [ 2, 5, 'ola' ]
: [ 'ola', 5, 2 ]

#+end_parallel
#   // Arrays can invert the order of their elements

#+latex: \vspace{-1em}
(*Stack*) The push method adds values to the end of an array, and the pop method
does the opposite, removing the last value in the array and returning it.
(*Queue*) The corresponding methods for adding and removing things at the start
of an array are called ~unshift~ and ~shift~, respectively.

Arrays have the following methods, which behave similar to the string ones from earlier.
| ~length~ | ~concat~ | ~includes~ | ~indexOf~ | ~lastIndexOf~ | ~slice~ |

One difference is that unlike string's ~indexOf~, which searches for substrings, array's
~indexOf~ searches for a specific value, a single element.

#+BEGIN_SRC js
console.log([1, 2, 3, 2, 1].indexOf(2));     // ⇒ 1
console.log([1, 2, 3, 2, 1].lastIndexOf(2)); // ⇒ 3
#+END_SRC

The ~concat~ method can be used to glue arrays together to create a new array,
similar to what the ~+~ operator does for strings.
- If you pass ~concat~ an argument that is not an array, that value will be added
  to the new array as if it were a one-element array. This is a ~push~.

~Array(𝓃).fill(𝓍)~ ≈ Get a new array of 𝓃-copies of element 𝓍.
:Hide:
   #+BEGIN_SRC js
console.log(Array(10).fill(3));
#+END_SRC
:End:
** Array methods

#+latex: \vspace{1em}
#  Arrays provide a number of useful higher-order methods. 
 + ~xs.forEach(a)~ to loop over the elements in an array and perform action ~a~.
   # - It provides something like a ~for-of~ loop as a higher-order function.
 + ~xs.filter(p)~ returns a new array containing only the elements that pass the predicate ~p~.
 + ~xs.map(f)~  transforms an array by putting each element through the function ~f~.
 + ~xs.reduce(f, e)~ combines all the elements in an array into a single value. 
   - We can omit the starting value ~e~ if the array ~xs~ is non-empty,
     in which case ~e~ is taken to be the first element ~xs[0]~.
 + ~xs.some(p)~ tests whether any element matches a given predicate function ~p~.
   - ~xs.every(p)~ tests if every element of ~xs~ satisfies ~p~.
   # - xs.includes(x) ≡ xs.some(e => e == x)
 + ~xs.findIndex(p)~ finds the position of the first element that matches the predicate ~p~.

 With the exception of ~forEach~, the above functions do not modify the array
 they are given.

 #+BEGIN_SRC js
 // Print the elements of the given array
 [`a`, `b`, `c`].forEach(l => console.log(l));

 // ∃/∀
 console.log([1, 2, 3].some(e => e == 2))  // true
 console.log([1, 2, 3].every(e => e == 2)) // false

 // Sum the elements of an array
 console.log([1, 2, 3, 4].reduce((soFar, current) => soFar + current)); // ⇒ 10

 // flatten an array of arrays
 let flatten = (xss) => xss.reduce((sofar, xs) => sofar.concat(xs), [])

 let arrays = [[1, 2, 3], [4, 5], [6]]; 
 console.log(flatten(arrays)) // ⇒ [ 1, 2, 3, 4, 5, 6 ]
 #+End_src

 Higher-order functions start to shine when you need to compose operations.

* COMMENT Control Flow

+ Braces form blocks:
  If ~Sᵢ~ are statements, then ~{S₀; …; Sₙ;}~ is a statement.

+ Conditional statement:
  ~if (condition) S else S′~

+ Loop: ~while (condition) S~.

+
#+begin_src js
let i = 0;
while (i < 10) console.log(Math.pow(2, i++))
console.log('-------')
for(let i = 0; i < 10; i++) console.log(Math.pow(2, i))
#+end_src

+ ~break;~ ⇒ Exit the current loop.
+ ~continue;~ ⇒ Jump out of the body and contiue with the next iteration of the loop.
+ ~for~ rewrites to a ~while~ loop: ~for(init; cond; change) body ≈ init;
  while(cond){body; change;}~. As such, all three pieces of ~for~ are optional.

+ Dispatching on a value with switch

#+begin_src js
switch (x){
  case v₀: S₀
  ⋮
  case vₙ₋₁: Sₙ₋₁
  default: Sₙ
}
#+end_src
Find the /first/ 𝒾 with ~x == vᵢ~, then execute
~{Sᵢ; ⋯; Sₘ;}~, if there is no such 𝒾, execute the
default statement ~Sₙ~. Where ~Sₘ~ is the first
statement after ~Sᵢ~ that ends with ~break;~.

E.g., ~case v: S; case w: S′; break~
means do ~S;S′~ if we see ~v~
but we do ~S′~
when seeing both ~v~ and ~w~.

#+begin_src js
switch (2){
  case 0: console.log(0)
  case 1: console.log(1)
  case 2: console.log(2)
  default: console.log(-1)
}
#+end_src

#+RESULTS:
: 2
: -1
* [[https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function][Functions]]

** Intro                                                             :ignore:

Function values can do all the things that other values can do; i.e., they can
be used in arbitrary expressions; e.g., a binding that holds a function is still
just a regular binding and can, if not constant, be assigned a new value.

+ A ~function~ definition is a regular binding where the value of the binding is a
  function.

  Functions declared using the top-level ~function~ keyword may be used before
  their declarations.
  # Conceptually, they are moved to the top of their scope.  
# #
#+begin_parallel org

  #+BEGIN_SRC js
const square = function(x) {
  return x * x;
};

console.log(square(12)); // ⇒ 144
#+END_SRC

  #+BEGIN_SRC js
// Shorter way to define functions
console.log(square2(12));
function square2(x) {
  return x * x;
}
#+END_SRC
#+end_parallel

#+latex: \vspace{-0.5em}
+ A ~return~ keyword without an expression after it will cause the
  function to return ~undefined~.
  
+ Functions that don’t have a ~return~ statement at all, similarly return
  ~undefined~.

+ Declaring ~function f (⋯) {⋯}~ will not raise a warning if the name ~f~
  is already in use ---similar to ~var~.

+ One may also define functions using “arrow” notation: ~(x₀, …, xₙ) => ⋯~.
  - When there is only one parameter name, you can omit the parentheses around
    the parameter list.
  - If the body is a single expression, rather than a (multi-line) block in
    braces, that expression will be returned from the function.

  So, these two definitions of square do the same thing:  
  #+BEGIN_SRC js
  const square1 = (x) => { return x * x; };
  const square2 =  x  => x * x;
  #+END_SRC  

#+latex: \vspace{-0.5em}
As will be seen, arrow functions are [[https://stackoverflow.com/a/34361380/3550444][not exactly]] the same as declared functions.

*JavaScript is extremely fault-tolerant:* If we give a function more arguments
than it needs, the extra arguments are just ignored.
If we give it too few arguments, the missing arguments are assigned ~undefined~.

#+BEGIN_SRC js
// Extra arguments are ignored
console.log(square(4, true, "hedgehog")); // ⇒ 16

// No longer a function!
square = 'g'
#+END_SRC

** Default Values

(*Default Values*)
If you write an = operator after a parameter, followed by an expression, the
value of that expression will replace the argument when it is not given.

#+BEGIN_SRC js
let square = (x = 1) => x * x;
console.log(square(3)); // ⇒ 9
console.log(square());  // ⇒ 1
#+END_SRC

# “let clauses”!

** Rest Parameters

(*Rest Parameters*)
It can be useful for a function to accept any number of arguments. For example,
~Math.max~ computes the maximum of all the arguments it is given. To write such
a function, you put three dots before the function’s last parameter, which is called
“the rest parameter” and it is treated as an array containing all further arguments.

# #
#+begin_parallel org
#+BEGIN_SRC js
function max(...numbers) {
  let result = -Infinity;
  for (let number of numbers) {
    if (number > result)
      result = number;
  }
  return result;
}

console.log(max(4, 1, 9, -2));  // ⇒ 9
#+END_SRC
#+latex: \columnbreak
You can use a similar three-dot notation to call a function with an array of arguments.
#+latex: \vspace{1em}
#+BEGIN_SRC js
let numbers = [5, 1, 7];
console.log(max(...numbers));
// ⇒ 7
#+END_SRC
# #
# Lisp's “apply” and Python's “unpacking *” operation! 
#+end_parallel

This “spreads” out the array into the function call, passing its elements as
separate arguments. It is possible to include an array like that along with
other arguments, as in ~max(9, ...numbers, 2)~.
:Hide:
Square bracket array notation similarly allows the triple-dot operator to spread
another array into the new array.
#+BEGIN_SRC js
let words = ["never", "fully"];
console.log(["will", ...words, "understand"]);
// ⇒ ["will", "never", "fully", "understand"]
#+END_SRC
:End:

** Higher-order Functions

 # + Functions are first-class citizens! They can be passed around like other values.
 # + Multiline arrows need to be enclosed in {/}.

 *Higher-order functions* allow us to abstract over actions, not just values.
 They come in several forms. 

 For example, we can have functions that create new functions.
 #+BEGIN_SRC js
 let greaterThan   = n => (m => m > n);
 let greaterThan10 = greaterThan(10);
 console.log(greaterThan10(11)); // ⇒ true
 #+END_SRC

 And we can have functions that change other functions. (*Decorators*)

 #+BEGIN_SRC js
 function noisy(f) {
   return (...args) => {
     let result = f(...args);
     console.log(`Called: ${f.name}(${args}) ≈ ${result}`);
     return result;
   };
 }
 noisy(Math.min)(3, 2, 1); // Called: min(3,2,1) ≈ 1
 #+END_SRC

 :FunctionProperties:
 #+BEGIN_SRC js
 console.log(Object.getOwnPropertyNames(Function.prototype))
 #+END_SRC
 :End:

 We can even write functions that provide new types of control flow.
# #
#+begin_parallel org
 #+BEGIN_SRC js
 function unless(test, then) {
   if (!test) then();
 }
#+END_SRC
#+latex: \columnbreak
#+BEGIN_SRC js
 let n = 8;
 unless(n % 2 == 1, () => {
     console.log(n, "is even");
   });
 // ⇒ 8 is even
 #+END_SRC
#+end_parallel

* Negative space :ignore:
#+latex: \vspace{-2em}
* Destructuring and the “spread” Operator

If you know the value you are binding is an array/object, you can use []/{} brackets
to “look inside” of the value, binding its contents.

# - A similar trick works for objects, using braces instead of square brackets.

#+latex: \vspace{-0.3em}
One of the reasons the ~doit~ function below is awkward to read is that we have
a binding pointing at our array, but we’d much prefer to have bindings for the
elements of the array, whence the second definition of ~doit~.

#+latex: \vspace{-0.3em}
#+BEGIN_SRC js 
let xs = [9, 11, 22, 666, 999];

// The following are the same.
function doit(xs){ return xs[0] + xs[1] + xs[2]; }
function doit([x, y, z]) {return x + y + z; }
//
// Only first three items accessed in “doit”; extra args are ignored as usual.
console.log(doit(xs)) 

// Destructuring to get first three elements and remaining
let x = xs[0], y = xs[1], z = xs[2], ws = xs.slice(3);
console.log(x, y, z, ws) // ⇒ 9 11 22 [ 666, 999 ]
// Nice! Same thing.
let [a, b, c, ...ds] = xs 
console.log(a, b, c, ds) // ⇒ 9 11 22 [ 666, 999 ]

// Destructuring to get first and remaining elements
let [head, ...tail] = xs
console.log(head, tail) // ⇒ 9 [ 11, 22, 666, 999 ]

// Destructuring on an object to get two properties and the remaining subobject 
let {name, age, ...more} = {name: "Musa", age: 72, x: 1, y: 2}
console.log(name, age, more) // ⇒ Musa 72 { x: 1, y: 2 }

// Destructuring: Simultaneous assignment!
var p = 1, q = 2    // ⇒ 1, 2
var [p, q] = [q, p] // swap them
console.log(p, q)   // ⇒ 2, 1

// Unpacking: f(...[x₀, …, xₙ]) ≈ f(x₀, …, xₙ)
console.log(Math.min(...xs)) // ⇒ 9

// Unpacking: Merging arrays/objects
let ys = [1, ...xs, 2, 3] // ⇒ 1, 9, 11, 22, 666, 999, 2, 3
let zs = {w: 0, ...more, z: 3} // ⇒ { w: 0, x: 1, y: 2, z: 3 }

// Updating a property, a key-value pair
zs = {...zs, w: -1} // ⇒ { w: -1, x: 1, y: 2, z: 3 }
#+END_SRC

# objArray.map(obj => ({ ...obj, keyToChange: 667, key: 42 }))

Note that if you try to destructure ~null~ or ~undefined~, you get an error,
much as you would if you directly try to access a property of those values.

:Hide:
|   | ~let {x₀, …, xₙ, ...𝓌} = 𝓋~                                       |
| ≡ | ~let x₀ = 𝓋.x₀, …, xₙ = 𝓋.xₙ; 𝓌 = 𝓋; delete 𝓌.x₀, …, delete 𝓌.xₙ~ |
:End:

#+BEGIN_SRC js
   let {x₀, …, xₙ, ...𝓌} = 𝓋                                       
≡ let x₀ = 𝓋.x₀, …, xₙ = 𝓋.xₙ; 𝓌 = 𝓋; delete 𝓌.x₀, …, delete 𝓌.xₙ
#+END_SRC
 
As usual, in arrow functions, we may destructure according to the shape
of the elements of the array; e.g., if they are lists of at least length 2
we use ~(soFar, [x, y]) => ⋯~. This may be useful in higher order functions
such as ~map, filter, reduce~.

* [[https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object][Objects]]

# Numbers, Booleans, and strings are the atoms that data structures are built
# from. Many types of information require more than one atom, though. Objects
# allow us to group values—including other objects—to build more complex
# structures.

Objects and arrays (which are a specific kind of object) provide ways to group
several values into a single value. Conceptually, this allows us to put a bunch
of related things in a bag and run around with the bag, instead of wrapping our
arms around all of the individual things and trying to hold on to them
separately. These “things” are called /properties/.

Arrays are just a kind of object specialised for storing sequences of things.

** Object Creation

Values of the type /object/ are arbitrary collections of properties. One way to
create an object is by using braces as an expression that lists properties as /“name:value”/
pairs.

:MergingObjects:
#+BEGIN_SRC js
  // JavaScript does pushouts-ish: There’s an Object.assign function that copies
  // all properties from one object into another:
  // Object.assign(x, y)  ≡  x = x ∪ y
  let objectA = {a: 1, b: 2};
  Object.assign(objectA, {b: 3, c: 4});
  console.log(objectA);
  // ⇒ {a: 1, b: 3, c: 4}
#+END_SRC
:End:
:the_delete_keyword:
The difference between setting a property to undefined and actually deleting it
is that, in the first case, the object still has the property (it just doesn’t
have a very interesting value), whereas in the second case the property is no
longer present and in will return false.
:End:

1. Almost all JavaScript /values/ have properties. The exceptions are ~null~ and
 ~undefined~. If you try to access a property on one of these nonvalues, you get
 an error. Properties are accessed using ~value.prop~ or ~value["prop"]~.
  
2. Whereas ~value.x~ fetches the property of value named /x/, ~value[e]~ tries to
 evaluate the expression ~e~ and uses the result, converted to a string, as the
 property name.
  
3. The dot notation only works with properties whose names look like valid
   (variable) binding names. So if you want to access a property named ~2~ or ~John
   Doe~, you must use square brackets: ~value[2]~ or ~value["John Doe"]~.
   
   # E.g., rather than ~array["length"]~ we typically write ~array.length~ since it's
   # shorter.
   
   # Properties that contain functions are generally called methods of the value they
   # belong to, as in “toUpperCase is a method of a string”.   

4. Unless ~value~ contains a property ~x~, we have ~value.x ≈ undefined~.
   - Hence, out of bounds indexing results in ~undefined~. 
   # E.g., if ~xs ≈ [1, 2]~ then ~xs[66]~ is undefined.

   # !('x' in o) ⇒ o.x ≈ undefined; the converse is not true.

5. Notice that the ~this~ keyword allows us to refer to other parts of /this/
   object literal. Above, ~info~ used the ~person~ object's information, whereas
   ~speak~ did not. The ~“this”~ keyword is covered in more detail below.

6. Variables names in an object literal, like ~languages~, denote a shorthand
   for a property with the same and value, but otherwise is no longer related to
   that binding.

   This is useful if we want multiple objects to have the same binding; e.g.,
   with ~let x = ⋯, a = {name: 'a', x}, b = {name: 'b', x}~, both objects have
   a ~x~ property: ~a.x~ and ~b.x~.

   :Example:
#+BEGIN_SRC js
let x = 3, a = {name: 'a', x}, b = {name: 'b', x};
console.log(a.x)
#+END_SRC
:End:

7. We cannot dynamically attach new properties to the atomic types String, Number, Boolean;   
   e.g., ~let x = 2; x.vest = 'purple'; console.log(x.vest);~ prints ~undefined~.
   We can write it, but they “don't stick”.

8. Below, we could have begun with the empty object then added properties dynamically:
   ~let person = {}; person.name = `musa`; person.age = 29; …~.

#+latex: \columnbreak
#+BEGIN_SRC js
let languages = ['js', 'python', 'lisp']
let person = { name: 'musa'
             , age: 27
             , 'favourite number': 1
             , languages // Shorthand for “languages: ['js', 'python', 'lisp']”
             , age: 29  // Later bindings override earlier ones.
             // Two ways to attach methods; the second is a shorthand.
             , speak: () => `Salamun Alaykum! Hello!`
             , info () { return `${this.name} is ${this.age} years old!`; }
             };

console.log(person.age) // ⇒ 29

// Trying to access non-existent properties
// Reading a property that doesn’t exist will give you the value undefined.
console.log(person.height) // ⇒ undefined
              
// Is the property “name” in object “person”?
console.log('name' in person); // ⇒ true

// Updating a (computed) property
let prop = 'favourite' + ' ' + 'number'
person['favourite number'] = 1792       
console.log(person[prop]) // ⇒ 1792

// Dynamically adding a new property
person.vest = 'purple'
console.log(person.vest) // ⇒ purple

// Discard a property
delete person['favourite number']

// Get the list of property names that an object *currently* has.
console.log(Object.keys(person)) // ⇒ [ 'name', 'age', 'languages', 'vest' ]

// Variables can contribute to object definitions, but are otherwise unrelated.
languages = ['C#', 'Ruby', 'Prolog']
console.log(person.languages) // ⇒ [ 'js', 'python', 'lisp' ]

// Calling an object's methods
console.log(person.speak()) // ⇒ Salamun Alaykum! Hello!
console.log(person.info())  // ⇒ musa is 29 years old!
#+END_SRC

** COMMENT Equality 

References to the same object are equal, whereas different object literals
with the same properties are considered different.
#+BEGIN_SRC js
let a = {value: 10};
let b = a;
let c = {value: 10};

console.log(a == b); // ⇒ true
console.log(a == c); // ⇒ false

a.value = 15;
console.log(b.value); // ⇒ 15
console.log(c.value); // ⇒ 10
#+END_SRC

Since ~a~ and ~b~ refer to the same object, changing one also changes the value of
the other. However, ~c~ only superficially looks the same.

We say different objects with the same properties are “deeply equal”.
#+BEGIN_SRC js
  // If non-objects, perform strict equality. Else, recursively check they have
  // the (deeply) same values and properties.
  function deepEqual(x, y){
    if (typeof x != typeof y) return false;
    if (x && y && typeof x != 'object') return x === y; // Values
    let props = Object.keys(x).concat(Object.keys(y));
    for (let p of props) if (! deepEqual(x[p], y[p])) return false;
    return true;
  }

  let obj = {here: {is: "an"}, object: 2};
  console.log(deepEqual(obj, {here: 1, object: 2})); // ⇒ false
  console.log(deepEqual(obj, {here: {is: "an"}, object: 2})); // ⇒ true
  console.log(deepEqual(1, 0 + 1)); // ⇒ true
#+END_SRC

Because of a historical accident, ~typeof null~ produces ~"object"~.

** COMMENT TODO Mutability

   Bindings can also be changeable or constant, but this is separate from the
   way their values behave. Even though number values don’t change, you can use
   a let binding to keep track of “a changing number” by changing the value the
   binding points at. Similarly, though a const binding to an object can itself
   not be changed and will continue to point at the same object, the contents of
   that object might change.

#+BEGIN_SRC js
const score = {visitors: 0, home: 0};
// This is okay
score.visitors = 1;
// This isn't allowed
score = {visitors: 1, home: 1};
#+END_SRC


When you compare objects with JavaScript’s == operator, it compares by identity:
it will produce true only if both objects are precisely the same value.
Comparing different objects will return false, even if they have identical
properties. There is no “deep” comparison operation built into JavaScript, which
compares objects by contents, but it is possible to write it yourself (which is
one of the exercises at the end of this chapter).

** Getters and Setters -- ~get, set~

 # Even properties that are accessed directly may hide a
 # method call. Such methods are called getters, and they are defined by writing
 # get in front of the method name in an object expression or class declaration.

  You can define getters and setters to secretly call methods every time an
  object’s property is accessed. E.g., below ~num~ lets you read and write
  ~value~ as any number, but internally the getter method is called which only
  shows you the value's remainder after division by the modulus property.

 :Hide:
 #+BEGIN_SRC js
 let varyingSize = {
   get size() {
     return Math.floor(Math.random() * 100);
   }
 };

 console.log(varyingSize.size); // ⇒ 73
 console.log(varyingSize.size); // ⇒ 49
 #+END_SRC

 Whenever someone reads from this object’s size property, the associated method
 is called. You can do a similar thing when a property is written to, using a
 setter.
 :End:

#+latex: \vspace{-1em}
 #+BEGIN_SRC js 
 let num = { modulus: 10
           , get value() { return this._secret % this.modulus; }
           , set value(val) { this._secret = val; } }
#+END_SRC
# #
#+begin_parallel org
#+BEGIN_SRC js
 num.value = 99
 console.log(num._secret) // ⇒ 99
#+END_SRC
#+latex: \columnbreak
#+BEGIN_SRC js
 console.log(num.value) // ⇒ 9
 num.modulus = 12;
 console.log(num.value) // ⇒ 3
 #+END_SRC
#+end_parallel

 # Here's how we could consider numbers that are always less than 10, by
 # considering their remainder after division by ~modulus~, which is 10 by default.

#+latex: \vspace{-1.5em}
 - Exercise: Make an object ~num~ such that ~num.value~ varies, returning
   a random number less than 100, each time it's accessed.  

 Using ~get, set~ is a way to furnish prototypes with well-behaved properties
 that are readable or writable, or both.

** Dictionries or maps

   An object can also be used as a /“key:value”/ dictionary: When we ‘look-up’ a key,
   we find a particular value. E.g., with ~ages = {mark: 12, james: 23, larry: 42}~
   we use ~ages.mark~ to find Mark's age.

   Similarly, objects can be used to simulate /keyword arguments/ in function calls.

** COMMENT TODO getters                                            :privates:
 It is also common to put an underscore (_) character at the start of property
 names to indicate that those properties are private.
* Negative space :ignore:
#+latex: \vspace{-1em}
* The ~this~ Keyword

:Hide:
Methods are nothing more than properties that hold function values. This is a
simple method:

#+BEGIN_SRC js
let rabbit = {};
rabbit.speak = function(line) {
  console.log(`The rabbit says '${line}'`);
};

rabbit.speak("I'm alive."); // ⇒ The rabbit says 'I'm alive.'
#+END_SRC
:End:

Usually a method needs to do something with the object it was called on. When a
function is called as a method --- looked up as a property and immediately
called, as in ~object.method()~ —-- the binding called ~this~ in its body
automatically points at the object that it was called on.

#+BEGIN_SRC js
function speak(line) {
  console.log(`The ${this.type} rabbit says '${line}'`);
}
let whiteRabbit  = {type: "white", speak};
let hungryRabbit = {type: "hungry", speak};

whiteRabbit.speak("Hola!"); // ⇒ The white rabbit says 'Hola!'
hungryRabbit.speak("Hey!")  // ⇒ The hungry rabbit says 'Hey!'
#+END_SRC

** ~Call~
You can think of ~this~ as an extra parameter that is passed in a different way.
If you want to pass it explicitly, you can use a function’s ~call~ method, which
takes the ~this~ value as its first argument and treats further arguments as
normal parameters.

#+BEGIN_SRC js
speak.call(hungryRabbit, "Burp!");
// ⇒ The hungry rabbit says 'Burp!'
#+END_SRC

# It can be used to invoke (call) a method with an owner object as an argument (parameter).

With ~call~, an object can use a method belonging to another object. E.g., below
we use ~whiteRabbit~'s speaking method with its ~this~ keywords referring to
~exoticRabbit~.
# ⇒ e.g, a.f.call(b)  ≈  let this = b; a.f() ;; more or less.
# #
# a.f(args) ≈ a.f.call(a, args)
#+BEGIN_SRC js
let exoticRabbit = {type: 'exotic'}

whiteRabbit.speak.call(exoticRabbit, `Jambo!`) 
// ⇒ The exotic rabbit says 'Jambo!'
#+END_SRC

#+RESULTS:
: 

# .bind() sets the value of this and changes the function to a new function, but
# it doesn’t invoke the function.
# #
# f.bind(b) ≈ (...args) => f.call(b, ...args)

** The ~this~ of Parent Scopes
Since each function has its own ~this~ binding, whose value depends on the way it
is called, you cannot refer to the ~this~ of the wrapping scope in a regular
function defined with the function keyword.

Arrow functions are different ---they do not bind their own ~this~ but can see the
~this~ binding of the scope around them. Thus, you can do something like the
following code, which references ~this~ from inside a local function:
#+BEGIN_SRC js
function normalise() {
  console.log(this.coords.map(n => n / this.length));
}
normalise.call({coords: [0, 2, 3], length: 5}); // ⇒ [0, 0.4, 0.6]
#+END_SRC

If we had written the argument to ~map~ using the ~function~ keyword, the code wouldn’t work.

* Object-Oriented Programming

** COMMENT Four ways to classes

#+BEGIN_SRC js
// [0] Declare a prototypical rabbit
let protoRabbit = {
    speak(line) {
      console.log(`The ${this.age} year-old ${this.type} rabbit says “${line}”`);
    }
  }

// [1] Declare an instance of protoRabbit
// let killerRabbit = Object.create(protoRabbit)
// I.e., we copy-paste the contents of “protoRabbit” into a new empty object.
let killerRabbit = { ...protoRabbit }

// [2] Initialise its attributes
killerRabbit.type = 'killer';
killerRabbit.age  = 37;

// [3] Use its methods
killerRabbit.speak('SKREEE!'); // ⇒ The 37 year-old killer rabbit says “SKREEE!”

////////////////////////////////////////////////////////////////////////////////
// In [2], we manually need to ensure the “this.𝓅” properties of [0] are setup.
// This, along with [1], is the purpose of a “constructor” function.
function makeRabbit(type, age) {
  let rabbit  = Object.create(protoRabbit);
  rabbit.type = type;
  rabbit.age  = age;
  return rabbit;
}

let kiraRabbit = makeRabbit('Kira', 21) // Steps [1] and [2] above are now conflated.
kiraRabbit.speak('JUSTICE!') // ⇒ The 21 year-old Kira rabbit says “JUSTICE!”

//////////////////////////////////////////////////////////////////////////////// 
// Constructors can be made shorter via the “new” syntactic sugar:
// “new f(args)”  ≈  “f.call(Object.create(f.prototype), args);”

function Rabbit(type, age) {  // c.f., [2]
  this.type = type;
  this.age  = age;
}

// c.f., [0]
Rabbit.prototype.speak = function (line) {
      console.log(`The ${this.age} year-old ${this.type} rabbit says “${line}”`);
    };

let woahRabbit = new Rabbit('Toon', 12); // c.f., [1] and [2]
woahRabbit.speak("What's up doc?") // ⇒ The 12 year-old Toon rabbit says “What's up doc?”

////////////////////////////////////////////////////////////////////////////////
// An easier way to do [0, 1, 2] ^_^
class Wabbit {
  // Step 1: Set up all non-functional properties
  constructor(type, age) { 
    this.type = type;
    this.age  = age;
  }
  // Step 2: Set up all method-properties
    speak(line) {
      console.log(`The ${this.age} year-old ${this.type} rabbit says “${line}”`);
    }
}

let elle = new Wabbit('ℒ', 18)
elle.speak('𝒴') // ⇒ The 18 year-old ℒ rabbit says “𝒴”
#+END_SRC

#+RESULTS:
: The 37 year-old killer rabbit says “SKREEE!”
: The 21 year-old Kira rabbit says “JUSTICE!”
: The 12 year-old Toon rabbit says “What's up doc?”
: The 18 year-old ℒ rabbit says “𝒴”

** Intro :ignore:

In English, /prototype/ means a preliminary model of something from which
other forms are developed or /copied/. As such, a /prototypical/ object
is an object denoting the original or typical form of something.

In addition to their properties, JavaScript objects also have prototype ---i.e.,
another object that is used as a source of additional properties. When an object
gets a request for a property that it does not have, its prototype will be
searched for the property, then the prototype’s prototype, and so on.
# the way JavaScript objects work. In addition to their set of properties, most
# objects also have a prototype. A prototype is another object that is used as a
# fallback source of properties. When an object gets a request for a property that
# it does not have, its prototype will be searched for the property, then the
# prototype’s prototype, and so on.

+ ~Object.getPrototypeOf(x)~ returns the prototype of an object ~x~.

For example, arrays are derived from ~Array.prototype~ which is derived from
~Object.prototype~ ---which is the great ancestral prototype, the entity behind
almost all object. ~Object.prototype~ provides a few methods that show up in all
objects, such as ~toString~, which converts an object to a string representation.

# What Properties Does a (prototype) Object have?
+ We can use the ~Object.getOwnPropertyNames(x)~ to get all the property names
  linked to object ~x~.

It is occasionally useful to know whether an object was derived from a specific
class. For this, JavaScript provides a binary operator called ~instanceof~.
Almost every object is an instance of Object.

+ ~𝓍 instanceof 𝓎  ≈  Object.getPrototypeOf(𝓍) == 𝓎.prototype~

#+BEGIN_SRC js
 // “Object” includes “toString”, and some other technical utilities.
 console.log(Object.getOwnPropertyNames(Object.prototype))

// Some true facts
console.log( {}       instanceof Object
           , []       instanceof Array
           , Math.max instanceof Function
           , Math.max instanceof Object) // Since Function derives from Object

// “Object” has no parent prototype.
console.log(Object.getPrototypeOf(Object.prototype)); // ⇒ null
#+END_SRC

** Adding New Methods or Overriding Methods

 (*Extension Methods / Open Classes*) To attach a new property to a ‘kind’ of
 object, we simply need to attach it to the prototype ---since all those ‘kinds’
 of objects use the prototype's properties.
 Let's attach a new method that can be used with /any/ array.   
 # One says JS Classes/Prototypes are “open”, we can extend them on the fly, as needed
 
#+latex: \vspace{-0.5em}
 #+BEGIN_SRC js
 Array.prototype.max = function () { 
    console.log('ola'); return Math.max(...this)
    }

 console.log([3,1,5].max()); // ⇒ Prints “ola”, returns 5

 console.log(Object.getOwnPropertyNames(Array.prototype))
 // ⇒ Includes length, slice, …, and our new “max” from above
 #+END_SRC

 :More:
 For any obj, including our own.
 #+BEGIN_SRC js
 let xs = [1, 2, 3]
 xs.neato = _ => console.log('ola')

 console.log(Object.getOwnPropertyNames(xs))
 console.log(Object.keys(xs))
 #+END_SRC
 :End:

 # If you open Chrome Developer tools and go to the console and type ~console.log(Array.prototype)~ and hit enter you will see 
 # a list of all utilities with additional information.
 # 
 # 
 # Likewise for Object.prototype and String.prototype

 When you call the ~String~ function (which converts a value to a string) on an
 object, it will call the ~toString~ method on that object to try to create a
 meaningful string from it.

 # Calling toString on an array gives a result similar to calling .join(",") on
 # it —it puts commas between the values in the array.
#+latex: \vspace{-0.5em}
 #+BEGIN_SRC js
 Array.prototype.toString = function() { return this.join(' and '); };
 console.log(String([1, 2, 3])) // ⇒ 1 and 2 and 3
 #+END_SRC

# +latex: \newpage
 (*Overriding*)
 When you add a property to an object, whether it is present in the prototype or
 not, the property is added to the object itself. If there was already a property
 with the same name in the prototype, this property will no longer affect the
 object, as it is now hidden behind the object’s own property.
#+latex: \vspace{-0.5em}
# #
#+begin_parallel org 
 #+BEGIN_SRC js
Array.prototype.colour = 'purple'

let xs = [1, 2, 3]
console.log(xs.colour) // ⇒ purple
#+END_SRC
#+latex: \columnbreak
#+BEGIN_SRC js
xs.colour = 'green'
console.log(xs.colour) // ⇒ green

console.log(Array.prototype.colour)
// ⇒ purple 
#+END_SRC
#+end_parallel

#+latex: \vspace{-1em}

** Inheritance and Null Parents

You can use ~Object.create~ to create an object with a specific prototype.
The default prototype is ~Object.prototype~. For the most part,
~Object.create(someObject) ≈ { ...someObject }~; i.e., we /copy/ the properties
of ~someObject~ into an empty object, thereby treating ~someObject~ as a prototype
from which we will build more sophisticated objects.
# Not generally true since not all objects inherit from “Object”.

Unlike other object-oriented languages where ~Object~ sits as the ancestor of /all/
objects, in JavaScript it is possible to create objects with no prototype parent!

# If you pass null to Object.create, the resulting object will not derive from
# Object.prototype and can safely be used as a map.

#+BEGIN_SRC js
// Empty object that *does* derive from “Object”
let basic = {}
console.log( basic instanceof Object // ⇒ true
           , "toString" in basic)    // ⇒ true

// Empty object that does not derive from “Object”
let maximal = Object.create(null);
console.log( maximal instanceof Object // ⇒ false
           , "toString" in maximal)    // ⇒ false
#+END_SRC

** ⟨1⟩ Prototype Example                                            :classes:

Prototypes let us define properties that are the same for all instances,
but properties that differ per instance are stored directly in the objects themselves.
E.g., the prototypical person acts as a container for the properties that are shared
by all people. An individual person object, like ~kathy~ below, contains properties
that apply only to itself, such as its name, and derives shared properties from
its prototype.

#+latex: \vspace{-0.5em}
#+BEGIN_SRC js
// An example object prototype
let prototypicalPerson    = {};
prototypicalPerson._world = 0;
prototypicalPerson.speak  = function () {
  console.log(`I am ${this.name}, a ${this.job}, in a world of `
               + `${prototypicalPerson._world} people.`) }
prototypicalPerson.job = `farmer`;
  
// Example use: Manually ensure the necessary properties are setup
// and then manually increment the number of people in the world.
let person = Object.create(prototypicalPerson);
person.name = `jasim`;
prototypicalPerson._world++;
person.speak() // ⇒ I am jasim, a farmer, in a world of 1 people.

// Another person requires just as much setup
let kathy = { ...prototypicalPerson }; // Same as “Object.create(⋯)”
kathy.name = `kathy`;
prototypicalPerson._world++;
kathy.speak() // ⇒ I am kathy, a farmer, in a world of 2 people.
#+END_SRC
** ⟨2⟩ Manual Constructor Functions                                 :classes:

# | Class ≈ Prototype + Constructor |
#+latex: \vspace{0.5em}
| /Classes are prototypes along with constructor functions!/ |

A /class/ defines the shape of a kind of object; i.e., what properties it has;
e.g., a Person can ~speak~, as all people can, but should have its own ~name~
property to speak of. This idea is realised as a prototype along with a
/constructor/ function that ensures an instance object not only derives from the
proper prototype but also ensures it, itself, has the properties that instances
of the class are supposed to have.

#+BEGIN_SRC js
let prototypicalPerson    = {};
prototypicalPerson._world = 0;
prototypicalPerson.speak  = function () {
  console.log(`I am ${this.name}, a ${this.job}, in a world of `
               + `${prototypicalPerson._world} people.`) }

function makePerson(name, job = `farmer`) {
  let person  = Object.create(prototypicalPerson);
  person.name = name;
  person.job  = job;
  prototypicalPerson._world++;
  return person;
}

// Example use
let jasim = makePerson(`jasim`);
jasim.speak() // I am jasim, a farmer, in a world of 1 people.
makePerson(`kathy`).speak() // I am kathy, a farmer, in a world of 2 people.
#+END_SRC

#+RESULTS:
: I am jasim, a farmer, in a world of 1 people.
: I am kathy, a farmer, in a world of 2 people.

** ⟨3⟩ Constructor Functions with ~new~                             :classes:
We can fuse these under one name by making the prototype a part of the constructor.
- By convention, the names of constructors are capitalised so that they can
  easily be distinguished from other functions.
#+BEGIN_SRC js
function Person(name, job = `farmer`) {
 this.name = name;
 this.job  = job;
 Person.prototype._world++;
}

Person.prototype._world = 0;
Person.prototype.speak = function () {
  console.log(`I am ${this.name}, a ${this.job}, in a world of `
               + `${Person.prototype._world} people.`) }

// Example use
let jasim = Object.create(Person.prototype)
Person.call(jasim, `jasim`)
jasim.speak() // ⇒ I am jasim, a farmer, in a world of 1 people.

// Example using shorthand
let kasim = new Person (`kathy`)
kasim.speak()  // ⇒ I am kathy, a farmer, in a world of 2 people.
#+END_SRC

#+RESULTS:
: I am jasim, a farmer, in a world of 1 people.
: I am kathy, a farmer, in a world of 2 people.

If you put the keyword ~new~ in front of a function call, the function is
treated as a constructor. This means that an object with the right prototype is
automatically created, bound to ~this~ in the function, and returned at the end
of the function.


#+BEGIN_SRC js
  new f(args)                                                                   
≈ (_ => let THIS = Object.create(f.prototype);
        f.call(THIS, args); return THIS;) ()
#+END_SRC

All functions automatically get a property named ~prototype~, which by default
holds a plain, empty object that derives from ~Object.prototype~. You can
overwrite it with a new object if you want. Or you can add properties to the
existing object, as the example does.

Notice that the ~Person~ object /derives/ from ~Function.prototype~,
but also has a /property/ named ~prototype~ which is used for instances
created through it.
#+BEGIN_SRC js
console.log( Object.getPrototypeOf(Person) == Function.prototype
           , Person instanceof Function
           , jasim  instanceof Person
           , Object.getPrototypeOf(jasim) == Person.prototype)
#+END_SRC

Hence, we can update our motto:
| /Classes are constructor functions with a prototype property!/ |

** ⟨4⟩ ~class~ Notation                                             :classes:
Rather than declaring a constructor, /then/ attaching properties to its prototype,
we may perform both steps together using ~class~ notation shorthand.
#+BEGIN_SRC js
class Person {
  static #world = 0
  constructor(name, job = `farmer`) { 
    this.name = name;
    this.job  = job;
    Person.#world++;
  }
  speak() {
    console.log(`I am ${this.name}, a ${this.job}, in a world of `
               + `${Person.#world} people.`) 
  }               
}

// Example use

let jasim = new Person(`jasim`)
jasim.speak()               
// ⇒ I am jasim, a farmer, in a world of 1 people.

new Person(`kathy`).speak()
// ⇒ I am kathy, a farmer, in a world of 2 people.
#+END_SRC

#+RESULTS:
: I am jasim, a farmer, in a world of 1 people.
: I am kathy, a farmer, in a world of 2 people.

:Hide:
#+BEGIN_SRC js
// “class” is just a shorthand
console.log( Object.getPrototypeOf(Person) == Function.prototype
           , Person instanceof Function
           , jasim  instanceof Person
           , Object.getPrototypeOf(jasim) == Person.prototype)
#+END_SRC
:End:

Notice that there is a special function named ~constructor~ which is 
bound to the class name, ~Person~, outside the class. The remainder of the
class declarations are bound to the constructor's prototype.
Thus, the earlier class declaration is equivalent to the constructor
definition from the previous section. It just looks nicer.
- Actually, this is even better: The ~static #world = 0~ declaration makes the
  property ~world~ /private/, completely inaccessible from the outside the
  class. The ~static~ keyword attaches the name not to particular instances
  (~this~) but rather to the constructor/class name (~Person~).
- Indeed, in the previous examples we could have accidentally messed-up our world count.
  Now, we get an error if we write ~Person.#world~ outside of the class.

** COMMENT ~class~ expression

Like function, class can be used both in statements and in expressions. When
used as an expression, it doesn’t define a binding but just produces the
constructor as a value. You are allowed to omit the class name in a class
expression.
#+BEGIN_SRC js
let object = new class { getWord() { return "hello"; } };
console.log(object.getWord());
// ⇒ hello
#+END_SRC

** COMMENT Inheritance

 With ~extends~, the new class inherits properties and behavior from the old
 class ---it is like ~Object.create(parentPrototype)~. The old, parent, class is
 called the “super-class” and we refer to it using the ~super~ binding.

 #+BEGIN_SRC js
   class Person {
     constructor(name) { this.name = name; }
     speak() { console.log(`I am ${this.name}`); }
   }

   // Use “super” to invoke properties of the parent, such as the parent's
   // constructor.
   class Teacher extends Person {
    constructor(name, topic) { super(name); this.topic = topic; }
    speak() { super.speak(); console.log(`I teach ${this.topic}`); }
   }

   let bobby = new Person('Bob');
   bobby.speak(); // ⇒ I am Bob

   let bobert = new Teacher('Bob', 'Maths');
   bobert.speak(); // ⇒ I am Bob \n I teach Maths
 #+END_SRC
 :Hide:
 #+BEGIN_SRC js
   // It is occasionally useful to know whether an object was derived from a
   // specific class. For this, JavaScript provides a binary operator called
   // instanceof. Almost every object is an instance of Object.
   console.log( bobert instanceof Person  
              , bobert instanceof Teacher
              , bobby  instanceof Teacher
              , [1, 2] instanceof Array
              )
 #+END_SRC
 :End:

** COMMENT OOP Summary
 So objects do more than just hold their own properties. They have prototypes,
 which are other objects. They’ll act as if they have properties they don’t have
 as long as their prototype has that property. Simple objects have
 Object.prototype as their prototype.

 Constructors, which are functions whose names usually start with a capital
 letter, can be used with the new operator to create new objects. The new
 object’s prototype will be the object found in the prototype property of the
 constructor. You can make good use of this by putting the properties that all
 values of a given type share into their prototype. There’s a class notation that
 provides a clear way to define a constructor and its prototype.

 You can define getters and setters to secretly call methods every time an
 object’s property is accessed. Static methods are methods stored in a class’s
 constructor, rather than its prototype.

 The instanceof operator can, given an object and a constructor, tell you whether
 that object is an instance of that constructor.

 When implementing multiple classes that differ in only some details, it can be
 helpful to write the new classes as subclasses of an existing class, inheriting
 part of its behavior.

* The Iterator Interface

The object given to a ~for/of~ loop is expected to be iterable. This means it
has a method named ~Symbol.iterator~. When called, that method should return an
object that provides a second interface, the iterator. This is the actual thing
that iterates. It has a ~next~ method that returns the next result. That result
should be an object with a ~value~ property that provides the next value, if
there is one, and a ~done~ property, which should be true when there are no more
results and false otherwise.

Let's make an iterable to traverse expression trees.
#+BEGIN_SRC js
class Expr { // [0] Our type of expression trees
  static Constant(x) { 
     let e = new Expr();
     e.tag = 'constant', e.constant = x; 
     return e; 
     }

  static Plus(l, r) { 
     let e = new Expr();
     e.tag = 'plus', e.left = l, e.right = r;
     return e; 
     }
}

// [1] The class tracks the progress of iterating over an expression tree
class ExprIterator {
  constructor(expr) { this.expr = expr; this.unvisited = [{expr, depth: 0}]; }
  next () {
   if(this.unvisited.length == 0) return {done: true};
   let {expr , depth} = this.unvisited.pop();
   if (expr.tag == 'constant') return {value: {num: expr.constant, depth}}
   if (expr.tag == 'plus') {
     // pre-order traversal
     this.unvisited.push({expr: expr.right, depth: depth + 1})
     this.unvisited.push({expr: expr.left, depth: depth + 1})
     }
   return this.next()
  }
}

// [2] We can add the iterator after-the-fact rather than within the Expr class.
Expr.prototype[Symbol.iterator] = function () { return new ExprIterator(this) }

// [3] Here's some helpers and an example.
let num = (i) => Expr.Constant(i)
let sum = (l, r) => Expr.Plus(l, r)
// test ≈ 1 +  (2 + (3 + 4))
let test = sum( num(1), sum( num(2), sum(num(3), num(4))))
// console.log(test) // ⇒ Nice looking tree ^_^

// [4] We now loop over an expression with for/of
for (let {num, depth} of test)
  console.log(`${num} is ${depth} deep in the expression`)
#+END_SRC

Recall that inside a class declaration, methods that have ~static~ written
before their name are *stored on* the constructor. It appears that static
properties are shared by all instances, because the constructor /object/ has
these as properties rather than particular instance objects.

:Hide:
We can directly use this iterable interface ourselves.

#+BEGIN_SRC js
let okIterator = "OK"[Symbol.iterator]();
console.log(okIterator.next()); // ⇒ {value: "O", done: false}
console.log(okIterator.next()); // ⇒ {value: "K", done: false}
console.log(okIterator.next()); // ⇒ {value: undefined, done: true}
#+END_SRC
:End:

:Hide:
*wrt* to factory methods, “static” is syntactic sugar:
  ~class C { ⋯ static M (){⋯} }; let c = C.M()~
≈ ~class C {⋯}; function M() {⋯}; let c = new M()~.
:End:
* Negative space :ignore:
#+latex: \vspace{-1em}
* JavaScript and the Browser

:Ignore:
Running programs downloaded from the Internet is potentially dangerous. You do
not know much about the people behind most sites you visit, and they do not
necessarily mean well. Running programs by people who do not mean well is how
you get your computer infected by viruses, your data stolen, and your accounts
hacked.

Yet the attraction of the Web is that you can browse it without necessarily
trusting all the pages you visit. This is why browsers severely limit the things
a JavaScript program may do: it can’t look at the files on your computer or
modify anything not related to the web page it was embedded in.
:End:

Browsers run JavaScript programs, which may be dangerous and so browsers limit
what a program may do ---e.g., it cannot look at your files.

:Ignore:
HTML is parsed in a remarkably error-tolerant way. When tags that should be
there are missing, the browser reconstructs them. The way in which this is done
has been standardized, and you can rely on all modern browsers to do it in the
same way.

The <html>, <head>, and <body> tags are gone completely. The browser knows that
<meta> and <title> belong in the head and that <h1> means the body has started.
Furthermore, I am no longer explicitly closing the paragraphs since opening a
new paragraph or ending the document will close them implicitly. The quotes
around the attribute values are also gone.

This book will usually omit the <html>, <head>, and <body> tags from examples to
keep them short and free of clutter.
:End:

An HTML document is a nested sequence of tagged items, which may be interpreted
as a living data-structure ---with the screen reflecting any modifications.
- The most important HTML tag is ~<script>~. This tag allows us to include a
  piece of JavaScript in a document.

The data-structure is called the *Document Object Model*, or /DOM/, and it is
accessed with the variable ~document~.
- The DOM interface wasn't designed for just JavaScript; e.g., it can be used with XML.
:Hide:
parts of the DOM interface also feel cumbersome and alien. The reason for this
is that the DOM wasn’t designed for just JavaScript. Rather, it tries to be a
language-neutral interface that can be used in other systems as well—not just
for HTML but also for XML, which is a generic data format with an HTML-like
syntax.
:End:

Call the following snippet ~test.html~, then open it in your favourite browser.
#+BEGIN_SRC html :tangle ~/Downloads/testing2.html
<title> Ola! </title>

<h3 id="myHeader"></h3>

<script>
alert(`Welcome to my webapge!`);

let count = 0;
function modifyThePage(){
  document.title = `New zany title ~ ${Math.random()}`;
  myHeader.innerText = `New zany heading ~ ${count}`;
  count += Math.floor(Math.random() * 10);
}
</script>

<button onclick="modifyThePage();">Change the title and header </button>
#+END_SRC
# ⇒ file:///Users/musa/Downloads/testing2.html

:Hide:
#+BEGIN_SRC html :tangle ~/Downloads/testing.html
<h1>Testing alert</h1>
<script>alert("hello!");</script>

<button onclick="alert('Boom!');">DO NOT PRESS</button>
#+END_SRC
# See it by clicking here: file:///Users/musa/Downloads/testing.html
:End:

Such a script will run as soon as its ~<script>~ tag is encountered while the
browser reads the HTML. This page will pop up a dialog when opened to show a
message.

Some attributes can also contain a JavaScript program. The ~<button>~ tag shows
up as a button and has an ~onclick~ attribute whose value (function) will be run
whenever the button is clicked.

Notice that by providing ID's to tags, we may refer to them in our JavaScript code.

** Large Scripts

Including large programs directly in HTML documents is often impractical. The
~<script>~ tag can be given a ~src~ attribute to fetch a script file (a text file
containing a JavaScript program) from a URL.

#+BEGIN_SRC html
<h1>Testing alert</h1>
<script src="code/hello.js"></script>
#+END_SRC

The ~code/hello.js~ file included here contains the simple program ~alert("hello!")~.
# When an HTML page references other URLs as part of itself—for example, an image
# file or a script—web browsers will retrieve them immediately and include them in
# the page.

* Break :ignore:
#+latex: \columnbreak
* Reads

# Mention that JS, like Python, has decoraters with @-syntax and generators with yield-syntax.
# The book Eloquent Javascript has useful stuff to revisit.
# 
# http://es6-features.org/

+ https://eloquentjavascript.net/

  /This is a book about JavaScript, programming, and the wonders of the digital./

  Many of the examples in this cheatsheet were taken from this excellent read!

+ https://exploringjs.com/index.html

  /Exploring JS: Free JavaScript books for programmers/
  ---E.g., “JavaScript for impatient programmers”

+ https://www.w3schools.com/js/

  /This tutorial will teach you JavaScript from basic to advanced./
 
  Other bite-sized lessions can be found at: https://masteringjs.io/fundamentals

+ https://learnxinyminutes.com/docs/javascript/

  /Take a whirlwind tour of your next favorite language. Community-driven!/

+ https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference

  /The JavaScript reference serves as a repository of facts about the JavaScript
  language. The entire language is described here in detail./

+ https://github.com/you-dont-need/You-Dont-Need-Loops
  
  /Avoid The One-off Problem, Infinite Loops, Statefulness and Hidden intent./

* Some Fun Stuff ^_^
#+BEGIN_SRC js
// A “quine” is a program that prints itself, such as this one:
f = _ => console.log(`f = ${f};f()`); f()
// Prints:
// f = _ => console.log(`f = ${f};f()`);f()

// Range of numbers. Including start, excluding end.
let range = (start, end) => [...Array(end - start).keys()].map(x => x + start)
console.log(range(3, 8)) // ⇒ [ 3, 4, 5, 6, 7 ]

// Flatten an array
let xss     = [[1, 2, 3], [4, 5, 6]]
let flatten = xss => [].concat(...xss)
console.log(flatten(xss)) // ⇒ [ 1, 2, 3, 4, 5, 6 ]

// Randomise the elements of an array
let shuffle = (arr) => arr.slice().sort(() => Math.random() - 0.5)
let xs = [1, 2, 3, 4, 5, 6] 
console.log(shuffle(xs)) // ⇒ [ 5, 1, 4, 6, 2, 3 ]
#+END_SRC

** COMMENT Keywords can be used as property names, but not as identifiers.

 #+BEGIN_SRC js
 // const if = 123; // SyntaxError: Unexpected token if
 // But they are allowed as names of properties:
 const obj = { if: 123 };
 obj.if
 #+END_SRC

 In this way we can simulate control flow at the object level:
 Rather than forcing objects into situations, we kindly request them into
 certain situations.

** COMMENT A working clock!
 #+BEGIN_SRC js :tangle ~/Downloads/clock.html
 <body onload="setInterval(()=>document.body.innerHTML=new Date().toGMTString().slice(17,25))"></body>
 #+END_SRC
 file:~/Downloads/clock.html

** COMMENT Remove duplicates from the iterable `arr`
 [...new Set(arr)]
 + https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set

** COMMENT Forward function application.
 #+BEGIN_SRC js
 let pipe = (arg, ...fns) => fns.reduce((v, f) => f(v), arg)

 let x  = pipe([...Array(10).keys()]
              ,xs => xs.filter(x => x % 3 == 0)
              ,xs => xs.map(x => 2 * x)
              ,xs => xs.reduce(((sum, x) => sum + x), 0)
              )
 // console.log([].filter.call([1, 2], x => x))
 // console.log(Array.prototype.filter.call([1, 2], x => x))


 // neato!
 x = [...Array(10).keys()]
     .filter(x => x % 3 == 0)
     .map(x => 2 * x)
     .reduce(((sum, x) => sum + x), 0)

 console.log(x)
 #+END_SRC

 The only to get rid of the “xs =>” porition is to have
 pipe “introduce” such a local name. For that, we would need macros.

* COMMENT What if I want ~N~ columns? Or non-landscape? Or multiple formats?

Press ~C-c C-c~ on the following incantation to produce a single column portrait of the cheat sheet.
#+name: make-portrait
#+BEGIN_SRC emacs-lisp :results none
(with-temp-buffer
    (insert
    "#+EXPORT_FILE_NAME: CheatSheet_Portrait.pdf
     ,#+LATEX_HEADER_EXTRA: \\landscapefalse \\def\\cheatsheetcols{1}
     ,#+INCLUDE: CheatSheet.org
    ")

    (let ((org-export-use-babel nil))
      (org-mode)
      (org-latex-export-to-pdf)
      )
)
#+END_SRC

* COMMENT Making ~README.org~

  Evaluate the following source block with ~C-c C-c~
  to produce a ~README~ file.

  # :'( For some reason using {{{title}}} below would not work.

#+NAME: make-readme
#+BEGIN_SRC emacs-lisp
(with-temp-buffer
    (insert
    "#+EXPORT_FILE_NAME: README.org
     # HTML: <h1> JavaScriptCheatSheet </h1>
     ,#+OPTIONS: toc:nil d:nil
     # Toc is displayed below at a strategic position.

     {{{blurb}}}

     :Hide:
     This project is to contain a listing of common results in X Theory.

     ,*The repo contains other articles I've written on X Theory;*
     ,*which may be read in a blog-format at:*
     https://alhassy.github.io/blog/categories/#Xtheory
     :End:

     #+begin_quote
    ,*The listing sheet, as PDF, can be found
     [[https://alhassy.github.io/JavaScriptCheatSheet/CheatSheet.pdf][here]]*,
     or as a [[https://alhassy.github.io/JavaScriptCheatSheet/CheatSheet_Portrait.pdf][single column portrait]],
     while below is an unruly html rendition.
     #+end_quote

     # Markdown links: [title](target)

     This reference sheet is built from a
     [[https://github.com/alhassy/CheatSheet][CheatSheets with Org-mode]]
     system.

     # html: <p align=\"center\"><a href=\"https://www.python.org/\"><img src=\"https://img.shields.io/badge/Python-3.8.1-b48ead.svg?style=plastic\"/></a></p><p align=\"center\"><img src=\"emacs-birthday-present.png\" width=200 height=250/></p>

     ,#+TOC: headlines 2
     ,#+INCLUDE: CheatSheet.org
    ")

    ;; No code execution on export
    ;; ⟪ For a particular block, we use “:eval never-export” ⟫
    ;;
    (let ((org-export-use-babel nil))
      (org-mode)
      ; (org-md-export-to-markdown)
      ; (package-install 'toc-org)
      (toc-org-mode)
      (toc-org-insert-toc)
      (org-org-export-to-org)
      )
)
#+END_SRC

#+RESULTS: make-readme
: README.org

Note that the ~blurb~ macro is defined by the user, to provide a terse description of the project.
   - Think the one-line statement at the top of a github repo page.

#    The ~d:nil~ ensures the ‘drawer’ ~:Hide: ⋯ :End:~ is not exported; it's there for me
#    as a reminder.
* COMMENT footer

0. The first “eval” below is convenience matter
   that should be loaded whenever CheatSheet.org is opened.

1. The second “eval” makes a README for the repo, whenever the file is opened,
   and is then bound to ~f11~ for convenience.

2. Likewise, the third eval is for making a portrait form of the cheatsheet ---~f12~.

3. :TOC: should not be exported in this file.

   See https://github.com/snosov1/toc-org for more on toc-org.

   (add-to-list 'org-export-exclude-tags "TOC")
   (delete "TOC" org-export-exclude-tags)

    And every time you'll be saving an org file, the first headline with a :TOC:
    tag will be updated with the current table of contents.
    (toc-org-enable)

# Local Variables:
# eval: (progn (visual-line-mode t) (require 'ox-extra) (ox-extras-activate '(ignore-headlines)))
# eval: (local-set-key (kbd "<f11>") '(lambda () (interactive) (org-babel-goto-named-src-block "make-readme") (org-babel-execute-src-block) (outline-hide-sublevels 1)))
# eval: (local-set-key (kbd "<f12>") '(lambda () (interactive) (org-babel-goto-named-src-block "make-portrait") (org-babel-execute-src-block) (outline-hide-sublevels 1)))
# eval:    (add-to-list 'org-export-exclude-tags "TOC")
# eval: (progn (visual-line-mode t) (require 'ox-extra) (ox-extras-activate '(ignore-headlines)))
# compile-command: (org-latex-export-to-pdf)
# End: