From d148466879f89c1e9b75206da6ec9f4188550c72 Mon Sep 17 00:00:00 2001
From: Lacanoid <lacanoid@ljudmila.org>
Date: Sat, 29 May 2021 22:42:58 +0200
Subject: [PATCH] rc1

---
 META.json      |  4 ++--
 README.md      |  2 +-
 docs/primer.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 53 insertions(+), 3 deletions(-)
 create mode 100644 docs/primer.md

diff --git a/META.json b/META.json
index 5e8281b..316721b 100644
--- a/META.json
+++ b/META.json
@@ -2,7 +2,7 @@
    "name": "datalink",
    "abstract": "SQL/MED DATALINK type and functions",
    "description": "A toy implementation SQL/MED datalinks",
-   "version": "0.11",
+   "version": "0.12",
    "maintainer": [
       "Ziga Kranjec <ziga@ljudmila.org>"
    ],
@@ -25,7 +25,7 @@
      "datalink": {
        "file": "datalink.sql",
        "docfile": "README.md",
-       "version": "0.11",
+       "version": "0.12",
        "abstract": "SQL/MED DATALINK type and functions"
      }
    },
diff --git a/README.md b/README.md
index 482b10a..952add7 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@ This extension uses a number of advanced PostgreSQL features for implementation,
 including transactions, jsonb, event and instead-of triggers, listen/notify, plperlu...
  
 Currently, it implements the following:
-- SQL/MED DATALINK type
+- SQL/MED DATALINK type, currently defined as domain over jsonb
 - SQL/MED DATALINK constructors DLVALUE, DLPREVIOUSCOPY and DLNEWCOPY
 - SQL/MED functions DLURLCOMPLETE, DLURLCOMPLETEONLY
 - SQL/MED functions DLURLSCHEME, DLURLSERVER
diff --git a/docs/primer.md b/docs/primer.md
new file mode 100644
index 0000000..d5ecf0a
--- /dev/null
+++ b/docs/primer.md
@@ -0,0 +1,50 @@
+Here are some examples on how to use datalink
+
+##Creating datalink values
+
+You can create datalink values from URLs by using `dlvalue()` function.
+
+ select dlvalue('http://www.github.io/');
+              dlvalue              
+ ----------------------------------
+  {"url": "http://www.github.io/"}
+ (1 row)
+
+URLs are checked for syntax and wrong ones throw errors.
+
+ postgres=# select dlvalue('foo bar');
+ ERROR:  invalid input syntax for type uri at or near " bar"
+ CONTEXT:  PL/pgSQL function dlvalue(text,datalink.dl_linktype,text) line 15 at assignment
+
+URLs are normalized before they are converted to datalinks.
+
+ select dlvalue('http://www.github.io/a/b/c/d/../../e');
+                dlvalue                
+ ---------------------------------------
+  {"url": "http://www.github.io/a/b/e"}
+ (1 row)
+
+Use `dlurlcompleteonly()` function to convert a datalink back to URL.
+
+ select dlurlcompleteonly(dlvalue('http://www.github.io/a/b/c/d/../../e'));
+      dlurlcompleteonly      
+ ----------------------------
+  http://www.github.io/a/b/e
+ (1 row)
+
+You can also use dlvalue() with absolute paths for file links.
+
+ select dlvalue('/var/www/datalink/index.html');
+                     dlvalue                     
+ ------------------------------------------------
+  {"url": "file:///var/www/datalink/index.html"}
+ (1 row)
+
+Use `dlurlpatheonly()` function to get file path from a datalink.
+
+ select dlurlpathonly(dlvalue('/var/www/datalink/index.html'));
+         dlurlpathonly         
+ ------------------------------
+  /var/www/datalink/index.html
+ (1 row)
+