rc1

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"
      }
    },

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

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)
+