From afd2fd5058d14c99ca60e9be28ee778f5df1958d Mon Sep 17 00:00:00 2001
From: Vincent Ambo <tazjin@google.com>
Date: Sat, 14 Sep 2019 13:07:21 +0100
Subject: docs(README): Add usage information to README

This fixes #2.
---
 README.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 46 insertions(+), 2 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 383ae1788b..54e3e4a6a4 100644
--- a/README.md
+++ b/README.md
@@ -5,7 +5,7 @@ yants
 
 This is a tiny type-checker for data in Nix, written in Nix.
 
-Features:
+# Features
 
 * Checking of primitive types (`int`, `string` etc.)
 * Checking polymorphic types (`option`, `list`, `either`)
@@ -16,7 +16,7 @@ Features:
 * Types are composable! `option string`! `list (either int (option float))`!
 * Type errors also compose!
 
-Lacking:
+Currently lacking:
 
 * Any kind of inference
 * Convenient syntax for attribute-set function signatures
@@ -40,3 +40,47 @@ Lacking:
 ## Functions!
 
 ![functions](screenshots/functions.png)
+
+# Usage
+
+Yants can be imported from its `default.nix`. A single attribute (`lib`) can be
+passed, which will otherwise be imported from `<nixpkgs>`.
+
+Examples for the most common import methods would be:
+
+1. Import into scope with `with`:
+    ```nix
+    with (import ./default.nix {});
+    # ... Nix code that uses yants ...
+    ```
+
+2. Import as a named variable:
+    ```nix
+    let yants = import ./default.nix {};
+    in yants.string "foo" # or other uses ...
+    ````
+
+3. Overlay into `pkgs.lib`:
+    ```nix
+    # wherever you import your package set (e.g. from <nixpkgs>):
+    import <nixpkgs> {
+      overlays = [
+        (self: super: {
+          lib = super.lib // { yants = import ./default.nix { inherit (super) lib; }; };
+        })
+      ];
+    }
+
+    # yants now lives at lib.yants, besides the other library functions!
+    ```
+
+Please see my [Nix one-pager](https://github.com/tazjin/nix-1p) for more generic
+information about the Nix language and what the above constructs mean.
+
+# Stability
+
+The current API of Yants is **not yet** considered stable, but it works fine and
+should continue to do so even if used at an older version.
+
+Yants' tests use Nix versions above 2.2 - compatibility with older versions is
+not guaranteed.
-- 
cgit 1.4.1