document stuff better

README.md

@@ -1,17 +1,23 @@
-# A minimalist calculator for f estimation
+# A minimalist calculator for fermi estimation
 
-This project is a minimalist, stack-based DSL for f estimation. It can multiply and divide scalars, lognormals and beta distributions.
+This project is a minimalist, stack-based DSL for fermi estimation. It can multiply, divide, add and substract scalars, lognormals and beta distributions.
 
 ## Motivation
 
 Sometimes, [Squiggle](https://github.com/quantified-uncertainty/squiggle), [simple squiggle](https://git.nunosempere.com/quantified.uncertainty/simple-squiggle) or [squiggle.c](https://git.nunosempere.com/personal/squiggle.c) are still too complicated and un-unix-like.
 
-## Usage
+## Installation
-
-Here is an example
 
 ```
-$ go run f.go
+make build
+sudo make install
+fermi 
+```
+
+## Usage
+
+```
+$ fermi
 5000000 12000000
 => 5.0M 12.0M
 * beta 1 200
@@ -31,7 +37,7 @@ $ go run f.go
 Perhaps this example is more understandable with comments and better units:
 
 ```
-$ sed -u "s|#.*||" | sed -u 's|M|000000|g' | go run f.go
+$ fermi
 5M 12M        # number of people living in Chicago
 => 5.0M 12.0M
 * beta 1 200  # fraction of people that have a piano
@@ -51,6 +57,7 @@ piano_tuners_in_Chicago => 5.9 568.3
 Here is instead an example using beta distributions and variables:
 
 ```
+$ fermi
 1 2
 => 1.0 2.0
 * 1_000_000_000
@@ -77,6 +84,7 @@ The difference between `=: x` and `=. y` is that `=.` clears the stack after the
 If you type "help", you can see a small grammar:
 
 ```
+$ fermi
 help
   Operation | Variable assignment | Special
     Operation:                             operator operand
@@ -85,9 +93,13 @@ help
             lognormal:                     low high
             beta:                          beta alpha beta
     Variable assignment:                   =: variable_name
-      Clear stack:                           . | c | clear
     Variable assignment and clear stack:   =. variable_name
-      Other special operations:              help | debug | exit
+    Special:
+         Clear stack:                      clear | c | .
+         Print this help message:          help  | h
+         Print debug info:                 debug | d
+         Exit:                             exit  | e
+         Comment:                          # this is a comment
   Examples:
     + 2
     / 2.5
@@ -99,47 +111,14 @@ help
     .
     1 100
     + x
+    # this is a comment
+    * 1 12 # this is an operation followed by a comment
     exit
 ```
 
-## Installation
-
-```
-make build
-sudo make install
-f # rather than the previous go run f.go
-```
-
-Why use make instead of the built-in go commands? Because the point of make is to be able to share command-line recipes. 
-
-## Usage together with standard Linux utilities
-
-```bash
-f
-sed -u "s|#.*||" | sed -u 's|M|000000|g' | f
-
-cat more/piano-tuners.f | f
-cat more/piano-tuners-commented.f | sed -u "s|#.*||" | sed -u 's|M|000000|g' | f
-
-tee -a input.log | go run f.go | tee -a output.log
-tee -a io.log | go run f.go | tee -a io.log
-
-function f(){
-  sed -u "s|#.*||" | 
-  sed -u "s|//.*||" | 
-  sed -u 's|K|000|g' | 
-  sed -u 's|M|000000|g' | 
-  sed -u 's|B|000000000|g' | 
-  /usr/bin/f
-}
-```
-
-Note that these sed commands are just hacks, and won't parse e.g., `3.5K` correctly—it will just substitute for 3.5000
-
 ## Tips & tricks
 
 - It's conceptually clearer to have all the multiplications first and then all the divisions
-- Sums and divisions now also supported
 - For things between 0 and 1, consider using a beta distribution
 
 ## Different levels of complexity
@@ -159,6 +138,7 @@ Done:
 - [x] Save to file?
 - [x] Allow comments?
   - [x] Use a sed filter? 
+  - [x] Add proper comment processing
 - [x] Add show more info version
 - [x] Scalar multiplication and division
 - [x] Think how to integrate with squiggle.c to draw samples
@@ -169,6 +149,7 @@ Done:
 - [x] Consider the following: make this into a stack-based DSL, with:
   - [x] Variables that can be saved to and then displayed
   - [x] Other types of distributions, particularly beta distributions? => But then this requires moving to bags of samples. It could still be ~instantaneous though.
+  - [x] Added bags of samples to support addition and multiplication of betas and lognormals
 - [x] Figure out go syntax for
   - Maps
   - Joint types
@@ -176,11 +157,11 @@ Done:
 - [x] Fix correlation problem, by spinning up a new randomness thing every time some serial computation is done.
 - [x] Clean up error code. Right now only needed for division
 - [x] Maintain *both* a more complex thing that's more featureful *and* the more simple multiplication of lognormals thing.
+- [x] Allow input with K/M/T
 
 To (possibly) do:
 
 - [ ] Document parenthesis syntax
-- [ ] Allow input with K/M/T
 - [ ] Add functions. Now easier to do with an explicit representation of the stakc
 - [ ] Think about how to draw a histogram from samples
 - [ ] Dump samples to file

f.go

@@ -71,9 +71,15 @@ const HELP_MSG = "  Operation | Variable assignment | Special\n" +
 	"            lognormal:                     low high\n" +
 	"            beta:                          beta alpha beta\n" +
 	"    Variable assignment:                   =: variable_name\n" +
-	"    Clear stack:                           . | c | clear\n" +
 	"    Variable assignment and clear stack:   =. variable_name\n" +
-	"    Other special operations:              help | debug | exit\n" +
+	"    Special: \n" +
+	"         Comment:                          # this is a comment\n" +
+	"         Clear stack:                      clear | c | .\n" +
+	"         Print debug info:                 debug | d\n" +
+	"         Print help message:               help  | h\n" +
+	"         Start additional stack:           operator (\n" +
+	"         Return from additional stack      )\n" +
+	"         Exit:                             exit  | e\n" +
 	"  Examples: \n" +
 	"    + 2\n" +
 	"    / 2.5\n" +
@@ -85,7 +91,14 @@ const HELP_MSG = "  Operation | Variable assignment | Special\n" +
 	"    .\n" +
 	"    1 100\n" +
 	"    + x\n" +
+	"    # this is a comment\n" +
+	"    * 1 12 # this is an operation followed by a comment\n" +
+	"    * (\n" +
+	"    1 10\n" +
+	"    + beta 1 100\n" +
+	"    )\n" +
 	"    exit\n"
+
 const NORMAL90CONFIDENCE = 1.6448536269514727
 const INIT_DIST Scalar = Scalar(1)
 const N_SAMPLES = 1_000_000

makefile

@@ -5,6 +5,7 @@ build:
 	go build f.go
 
 install: f 
-	sudo mv f /usr/bin/f
 	rm /usr/bin/fermi
+	rm /usr/bin/f
+	sudo mv f /usr/bin/f
 	sudo ln -s /usr/bin/f /usr/bin/fermi