docs: start writing README notes

1 files changed, 58 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..78659ab
--- /dev/null
+++ b/README.md
@@ -0,0 +1,58 @@
+* Introduction
+
+Hamlet, because "to zero, or not to zero - that is the question."
+
+Basically, I need a simple way to enforce constraints on command line
+flags without having to (yet) resort to third-party CLI libraries like
+Cobra, urfave, kong, etc.
+
+In Go, every datatype has a *zero value*. For example the zero value
+of the `string` type is "", that of the `int` type is 0, and so on. We
+can map this concept to propositional logic by defining a value to be
+*false* if it's the zero value, and *true* otherwise. In doing so, we
+impose a strictly higher-order concept on Go datatypes: this isn't to
+be confused with Go's own boolean `true` and `false` values. Loosely
+speaking, if a value is true, it's considered "present"; and if false,
+it's considered absent, missing, not provided, or what have you.
+
+* Command-Line Arguments
+
+I'm currently working on a web crawler. As of this writing, it gives
+users the option of launching the crawl either with a full URL using
+the `url` flag, or else with a shortcode read, using the `shortcode`
+flag, from a CSV file. Furthermore, if `shortcode` is provided, an
+additional `file` flag can specify the CSV file containing the
+shortcodes. Two things to note here:
+
+1. Exactly one of `url` or `shortcode` are required for launching the
+   web crawler.
+2. The `file` flag only applies whenever `shortcode` is given; using
+   it with `url` should be flagged as an error.
+ 
+I could attempt to enforce these constraints via one of the
+aforementioned third-party libraries by, for example, making `url` and
+`shortcodes` subcommands. However, I couldn't help but stumble on the
+realization explained in the Introduction, and became curious if it's
+viable enough for implementation in a real application.
+
+* Constraints
+
+And so, along these lines, we have the following constraints. Note
+that `⊻` is the XOR operator.
+
+```
+shortcode ⊻ url
+file → shortcode
+file → ~url
+```
+
+At first I was tempted to assert `file ↔ shortcode`, but I still
+wanted to keep the file argument optional, so that a default value
+could be used. Hence we can't assert `~file → ~shortcode`, which
+would've otherwise given us the double implication. In fact, it was
+this edge case that led me into the wider world of considering logical
+combinators in general, and not just whether two variables are either
+both zero or both non-zero.
+
+
+