Introduction.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Introduction"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "k is a family of concise, fast vector-oriented languages designed by [Arthur Whitney](https://aplwiki.com/wiki/Arthur_Whitney). Calling k a \"family\" is deliberate; there is no single definitive k, but instead a sequence of slightly incompatible versions. If you decide to stick with k, you'll see mentions of `k4`, `k5` etc. Exactly what those numbers mean aren't important–they're \"generations\", rather than versions, and not every generation was ever made available to the public, or even [completed](https://github.com/JohnEarnest/ok/blob/gh-pages/docs/Fromk5Tok6.md). A Python 2/3 split every time, if you like. \n",
    "\n",
    "Reputedly, Arthur always starts from scratch when making the next generation of k, happily and deliberately sacrificing backward compatibility in order to build something better and faster, cut fat or revert design decisions that didn't pan out. The bleeding edge k is being developed right now (at the time of writing) by Arthur's latest venture, [Shakti](https://shakti.com/). Shakti-k is dubbed by some as `k9`. If this all sounds a bit anarchic, that's because it is. There is no expectation that code written for one generation will always work unchanged in the next. Embrace it. Evolution is healthy.\n",
    "\n",
    "The main commercial version of k available today is [q/kdb+](https://code.kx.com/home/) from [kX systems](https://kx.com/), Arthur's previous venture. It's stable, fast, \"batteries included\" and really the benchmark k against which others are measured. kX's k version is usually thought of as `k4`. However, kX's main product is the language `q`–a k-derivative (implemented in k) that looks (a bit) more like a traditional programming language, and the [freakishly fast](https://tech.marksblogg.com/billion-nyc-taxi-kdb.html), distributed columnar store [kdb+](https://en.wikipedia.org/wiki/Kdb%2B). kX views k as \"exposed infrastructure\" and actively discourages its users from using it. kX provides exceptionally good [documentation](https://code.kx.com/q/) for q which is always worthwhile reading: even if q isn't k, it's close enough many times. `k9` currently has Arthur-style documentation only; the ref-card.\n",
    "\n",
    "A commercial license for `q/kdb+` is eye-wateringly expensive and likely out of reach for hobbyists. You can, however, [run it for free](https://code.kx.com/q/learn/install/) under a non-commercial evaluation license, but note that the product is \"tethered\", and so sends telemetry data back to base and cannot be used without an active internet connection. \n",
    "\n",
    "You can try `k9` under a free non-commercial evaluation [license](https://shakti.com/download/license), too, but `k9` is very much a moving, changing target at the time of writing."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Why k?\n",
    "\n",
    "I'd like to avoid the advocacy piece, as there seems to be little middle ground. As you've landed here, you've clearly somehow sought out k, and you likely have an idea what it's about. K, like its [Iversonian](https://aplwiki.com/wiki/Ken_Iverson) siblings [APL](https://en.wikipedia.org/wiki/APL_(programming_language)) and [J](https://www.jsoftware.com/#/README), values conciseness, or perhaps we should say terseness, of representation and speed of execution. \n",
    "\n",
    "The same baseless accusations of \"unreadable\", \"write-only\" and \"impossible to learn\" are leveled at all Iversonian languages, k included. I covered that a bit in the [introduction](https://xpqz.github.io/learnapl/intro.html#but-it-s-unreadable) to my book on APL, and so won't repeat that here. The k cognoscenti, when told the language is unreadable (again) will simply show you the whites of their eyes, mumble \"whatever\", and get on with their lives. Readability is a property of the reader, not the language.\n",
    "\n",
    "K is a general-purpose programming language that excels as a tool for data wrangling, analytics and transformation.  The analytics use case really drove both its inception and adoption in the financial industry. Compared with APL it's more consistent (partly a consequence of Arthur's propensity for always starting from scratch), perhaps a smidge less mathematically pure (instead choosing to optimise for speed and pragmatism), fewer \"batteries included\" and with a vector-, rather than array-oriented model. \n",
    "\n",
    "If you come to k knowing APL or J, the transition is pretty pain-free. If k is your first foray into vector and array languages, coming perhaps from Python or JavaScript, the learning ramp will feel steeper than you're used to, but at least the vector model will feel more familiar than APL's rank. In k, like in Python, depth and rank are the same thing.\n",
    "\n",
    "K is a teeny, tiny language. It has no libraries to speak of. You can pick up the basics in an afternoon. In terms of complexity, it's about as hard as learning regular expressions. However, like with most things, it takes tons of practice to become _good_ at it. In the hands of a master practitioner, it's truly a sight to behold.\n",
    "\n",
    "If you persist, you'll find you have a computational superpower at your fingertips. You'll learn new ways to think about data. Going back to a mainstream language will feel dull and boring.\n",
    "\n",
    "I think of k as APL's \"more punk rock little sister\". It's not for everyone. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Open source k\n",
    "\n",
    "There is a small, but thriving, open source k community, and there is probably half a dozen or more open source k implementations of k knocking around of varying degree of ambition. The k language deserves a future outside the commercial implementations marketed to the financial industry, and this book will deal solely with open source k. If you're a hedge fund jock who sees k as a way to get ahead, you're welcome here, too, but note that we'll not touch on either `q`, `kdb+` or the Shakti equivalents.\n",
    "\n",
    "This book is written as a [jupyter-book](https://jupyterbook.org/intro.html), using the [ngn/k](https://codeberg.org/ngn/k) [kernel](https://github.com/xpqz/ngnk_kernel) developed specifically for this book. All examples are thus run under `ngn/k`, which is a `k6`. You can run `ngn/k` directly in your [browser](https://ngn.bitbucket.io/k/#), too, and we'll link all examples to a live, web-based repl if you want to experiment.\n",
    "\n",
    "Installing `ngn/k` requires you to get your hands dirty and build from source. At the moment, it's buildable on Linux, FreeBSD, OpenBSD and MacOS. \n",
    "\n",
    "John Earnest's `oK` is another `k5/6`, available [on-line](http://johnearnest.github.io/ok/index.html). Most examples here should run unchanged under oK, and if that's not the case, we'll try to point that out. `oK` has a well-written [manual](https://github.com/JohnEarnest/ok/blob/gh-pages/docs/Manual.md) in addition to the traditional Arthur-style ref-card, and John's also written a more general intro to [programming in k](https://github.com/JohnEarnest/ok/blob/gh-pages/docs/Programming.md), too.\n",
    "\n",
    "There is also [kona](https://github.com/kevinlawler/kona), a `k3`, and [ktye/k](https://ktye.github.io/), which is the only open source k to support some of the ksql database extensions."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Nomenclature and style\n",
    "\n",
    "K uses nomenclature introduced in the J language (another APL derivative) with which Arthur was deeply involved. You may come across Arthur's sketched J interpreter fragment, known as the [J Incunabulum](https://code.jsoftware.com/wiki/Essays/Incunabulum), and been either awestruck or repelled that one can _do_ such unspeakable things in c. In J, and also in k, we borrow terms from linguistics, rather than from mathematics, to describe the building blocks of the language. J/k folk insist that this makes it easier to learn and understand, but if you're already versed in other programming languages, this is sure to grate a bit in the beginning. What the hell do you mean \"adverb\"?\n",
    "\n",
    "In k, we have nouns, verbs and adverbs, rather than data, functions and operators. We'll stick to these conventions. K, like APL and J, also uses the words \"monadic\" and \"dyadic\" to refer to verbs or adverbs taking one or two arguments respectively. \"Monadic\" has nothing to do with Haskell monads, you'll be pleased to hear.\n",
    "\n",
    "Traditions in k dictate that code should be as terse as possible. The use of unnecessary whitespace and non-single-letter names for things are seen as signs of inexperience. However, for the purposes of this book, we'll make no apologies for breaking such style guide lines where we think this aids clarity."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## About this book\n",
    "\n",
    "I can't claim to be an expert on k. Like with my [APL book](https://xpqz.github.io/learnapl), this is a jazzed-up version of the notes I took when learning. There is a lack of accessible introductory texts to k for experienced practitioners of other languages, and this is my contribution to help plug that gap. Moreover, k deserves to break free of its association with the financial industry, and perhaps this can help with that, too."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Ks have traditionally been 'documented' via a so-called [ref-card](https://kparc.com/k.txt). This is the briefest possible listing of built-ins, usually with zero context or explanation. This is part of the sometimes unhelpful mythology surrounding k, and -- some might argue -- a semi-deliberate barrier: you're expected to get yourself to a point where you also believe that the ref-card is sufficient documentation, and so complete the circle. `ngn/k`, the dialect we're chiefly concerned with here, carries on with the ref-card tradition, but its version is actually unusually comprehensive. You can view its ref card(s) with a few backslash commands in the repl, starting with a single `\\` for the index page:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\\   help               \\\\         exit\n",
      "\\a  license(AGPLv3)    \\l file.k  load\n",
      "\\0  types              \\t:n expr  time(elapsed milliseconds after n runs)\n",
      "\\+  verbs              \\v         variables\n",
      "\\:  I/O verbs          \\f         functions\n",
      "\\'  adverbs            \\cd path   change directory\n",
      "\\`  symbols            \\other     command(through /bin/sh)\n",
      "\\h  summary\n"
     ]
    }
   ],
   "source": [
    "\\"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By no means should you expect to be able to actually _learn_ k from the ref cards, but -- and I do feel slightly uncomfortable saying it -- you'll soon find them indispensable. For example, `\\+` lists the built-in <s>functions</s> verbs with both monadic and dyadic forms in one compact screen: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Verbs:    : + - * % ! & | < > = ~ , ^ # _ $ ? @ . 0: 1:\n",
      "notation: [c]har [i]nt [n]umber(int|float) [s]ymbol [a]tom [d]ict\n",
      "          [f]unc(monad) [F]unc(dyad) [xyz]any\n",
      "special:  var:y     set    a:1;a -> 1\n",
      "          (v;..):y  unpack (b;(c;d)):(2 3;4 5);c -> 4\n",
      "          :x        return {:x+1;2}[3] -> 4\n",
      "          $[x;y;..] cond   $[0;`a;\"\\0\";`b;`;`c;();`d;`e] -> `e\n",
      "          o[..]     recur  {$[x<2;x;+/o'x-1 2]}9 -> 34\n",
      "          [..]      progn  [0;1;2;3] -> 3\n",
      "\n",
      "::  self      ::12 -> 12\n",
      " :  right     1 :2 -> 2   \"abc\":'\"d\" -> \"ddd\"\n",
      " +x flip      +(\"ab\";\"cd\") -> (\"ac\";\"bd\")\n",
      "N+N add       1 2+3 -> 4 5\n",
      " -N negate    - 1 2 -> -1 -2\n",
      "N-N subtract  1-2 3 -> -1 -2\n",
      " *x first     *`a`b -> `a   *(0 1;\"cd\") -> 0 1\n",
      "N*N multiply  1 2*3 4 -> 3 8\n",
      " %N sqrt      %25 -> 5.0   %-1 -> 0n\n",
      "N%N divide    4 3%2 -> 2 1   4 3%2.0 -> 2.0 1.5\n",
      " !i enum      !3 -> 0 1 2   !-3 -> -3 -2 -1\n",
      " !I odometer  !2 3 -> (0 0 0 1 1 1;0 1 2 0 1 2)\n",
      " !d keys      !`a`b!0 1 -> `a`b\n",
      " !S ns keys   a.b.c:1;a.b.d:2;!`a`b -> ``c`d\n",
      "x!y dict      `a`b!1 2 -> `a`b!1 2\n",
      "i!I div       -10!1234 567 -> 123 56\n",
      "i!I mod       10!1234 567 -> 4 7\n",
      " &I where     &3 -> 0 0 0   &1 0 1 4 2 -> 0 2 3 3 3 3 4 4\n",
      " &x deepwhere &(0 1 0;1 0 0;1 1 1) -> (0 1 2 2 2;1 0 0 1 2)\n",
      "N&N min/and   2&-1 3 -> -1 2   0 0 1 1&0 1 0 1 -> 0 0 0 1\n",
      " |x reverse   |\"abc\" -> \"cba\"   |12 -> 12\n",
      "N|N max/or    2|-1 3 -> 2 3   0 0 1 1|0 1 0 1 -> 0 1 1 1\n",
      " <X ascend    <\"abacus\" -> 0 2 1 3 5 4\n",
      " >X descend   >\"abacus\" -> 4 5 3 1 0 2\n",
      " <s open      fd:<`\"/path/to/file.txt\"\n",
      " >i close     >fd\n",
      "N<N less      0 2<1 -> 1 0\n",
      "N>N more      0 1>0 2 -> 0 0\n",
      " =X group     =\"abracadabra\" -> \"abrcd\"!(0 3 5 7 10;1 8;2 9;,4;,6)\n",
      " =i unitmat   =3 -> (1 0 0;0 1 0;0 0 1)\n",
      "N=N equal     0 1 2=0 1 3 -> 1 1 0\n",
      " ~x not       ~(0 2;``a;\"a \\0\";::;{}) -> (1 0;1 0;0 0 1;1;0)\n",
      "x~y match     2 3~2 3 -> 1   \"4\"~4 -> 0   0~0.0 -> 0\n",
      " ,x enlist    ,0 -> ,0   ,0 1 -> ,0 1   ,`a!1 -> +(,`a)!,,1\n",
      "x,y concat    0,1 2 -> 0 1 2  \"a\",1 -> (\"a\";1)\n",
      " ^x null      ^(\" a\";0 1 0N;``a;0.0 0n) -> (1 0;0 0 1;1 0;0 1)\n",
      "a^y fill      1^0 0N 2 3 0N -> 0 1 2 3 1   \"b\"^\" \" -> \"b\"\n",
      "X^y without   \"abracadabra\"^\"bc\" -> \"araadara\"\n",
      " #x length    #\"abc\" -> 3   #4 -> 1   #`a`b`c!0 1 0 -> 3\n",
      "i#y reshape   3#2 -> 2 2 2\n",
      "I#y reshape   2 3#` -> (```;```)\n",
      "f#y replicate (3>#:')#(0;2 1 3;5 4) -> (0;5 4)   {2}#\"ab\" -> \"aabb\"\n",
      "x#d take      `c`d`f#`a`b`c`d!1 2 3 4 -> `c`d`f!3 4 0N\n",
      " _n floor     _12.34 -12.34 -> 12 -13\n",
      " _c lowercase _\"Ab\" -> \"ab\"\n",
      "i_Y drop      2_\"abcde\" -> \"cde\"   `b_`a`b`c!0 1 2 -> `a`c!0 2\n",
      "I_Y cut       2 4 4_\"abcde\" -> (\"cd\";\"\";,\"e\")\n",
      "f_Y weed out  (3>#:')_(0;2 1 3;5 4) -> ,2 1 3\n",
      "X_i delete    \"abcde\"_2 -> \"abde\"\n",
      " $x string    $(12;\"ab\";`cd;+) -> (\"12\";(,\"a\";,\"b\");\"cd\";,\"+\")\n",
      "i$C pad       5$\"abc\" -> \"abc  \"   -3$\"a\" -> \"  a\"\n",
      "s$y cast      `c$97 -> \"a\"   `i$-1.2 -> -1   `$\"a\" -> `a\n",
      "s$y int       `I$\"-12\" -> -12\n",
      " ?x uniq      ?\"abacus\" -> \"abcus\"\n",
      "X?y find      \"abcde\"?\"bfe\" -> 1 0N 4\n",
      "i?x roll      3?1000 -> 11 398 293   1?0 -> ,-8164324247243690787\n",
      "i?x deal      -3?1000 -> 11 398 293 /guaranteed distinct\n",
      " @x type      @1 -> `b   @\"ab\" -> `C   @() -> `A   @(@) -> `v\n",
      "x@y apply(1)  {x+1}@2 -> 3   \"abc\"@1 -> \"b\"   (`a`b!0 1)@`b -> 1\n",
      " .S get       a:1;.`a -> 1   b.c:2;.`b`c -> 2\n",
      " .C eval      .\"1+2\" -> 3\n",
      " .d values    .`a`b!0 1 -> 0 1\n",
      "x.y apply(n)  {x*y+1}. 2 3 -> 8   (`a`b`c;`d`e`f). 1 0 -> `d\n",
      "\n",
      "@[x;y;f]   amend  @[\"ABC\";1;_:] -> \"AbC\"   @[2 3;1;{-x}] -> 2 -3\n",
      "@[x;y;F;z] amend  @[\"abc\";1;:;\"x\"] -> \"axc\"   @[2 3;0;+;4] -> 6 3\n",
      ".[x;y;f]   drill  .[(\"AB\";\"CD\");1 0;_:] -> (\"AB\";\"cD\")\n",
      ".[x;y;F;z] drill  .[(\"ab\";\"cd\");1 0;:;\"x\"] -> (\"ab\";\"xd\")\n",
      ".[f;y;f]   try    .[+;1 2;\"E:\",] -> 3   .[+;1,`2;\"E:\",] -> \"E:typ\"\n",
      "?[x;y;z]   splice ?[\"abcd\";1 3;\"xyz\"] -> \"axyzd\"\n"
     ]
    }
   ],
   "source": [
    "\\+"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Are you ready? Let's crack open the kool-aid."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "ngn/k",
   "language": "ngnk",
   "name": "ngnk"
  },
  "language_info": {
   "file_extension": ".k",
   "mimetype": "text/ngnk",
   "name": "ngnk"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}