docs update

docs/ref-ch03-create.md

@@ -31,6 +31,8 @@ This command mutates the state of the Obelisk agent.
 
 ## Produced Metadata
 
+## Example
+
 INSERT `name`, `<timestamp>` into `sys.sys.databases`
 Create all `<database>.sys` tables
 
@@ -43,7 +45,7 @@ This command creates an index over selected column(s) of an existing table.
 
 ```
 <create-index> ::=
-  CREATE [ UNIQUE ] [ NONCLUSTERED | CLUSTERED ] INDEX <index>
+  CREATE [ UNIQUE ] [ LOOK-UP | CLUSTERED ] INDEX <index>
     ON [ <db-qualifer> ] <table>
     ( <column> [ ASC | DESC ] [ ,...n ] )
 ```
@@ -75,7 +77,7 @@ CREATE INDEX ix_vendor-id3 ON purchasing..product-vendor (vendor-id);
 **`UNIQUE`**
 Specifies that no two rows are permitted to have the same index key value.
 
-**`NONCLUSTERED | CLUSTERED`**
+**`LOOK-UP | CLUSTERED`**
 `CLUSTERED` creates an index in which the logical order of the key values determines the physical order of the corresponding rows in a table. A `<table>` or `<view>` can have only one clustered index at a time.
 
 **`<index>`**
@@ -97,7 +99,9 @@ _NOTE_: Further investigation is required to determine how "clustering" works in
 
 ## Produced Metadata
 
-INSERT `table name`, `namespace` `index-name`, `NONCLUSTERED | CLUSTERED`, `is-unique`, `<timestamp>` into `<database>.sys.indices`
+## Example
+
+INSERT `table name`, `namespace` `index-name`, `LOOK-UP | CLUSTERED`, `is-unique`, `<timestamp>` into `<database>.sys.indices`
 
 ## Exceptions
 
@@ -134,6 +138,10 @@ This command mutates the state of the Obelisk agent.
 
 ## Produced Metadata
 
+sys and data timestamps
+
+## Example
+
 INSERT `name`, `<timestamp>` into `<database>.sys.namespaces`
 
 ## Exceptions
@@ -169,7 +177,7 @@ _NOTE_: Further investigation is needed to understand if there's a reason to spe
     [ <db-qualifer> ]<table>
     ( <column> <aura>
       [ ,... n ] )
-    PRIMARY KEY [ CLUSTERED | NONCLUSTERED ] ( <column> [ ,... n ] )
+    PRIMARY KEY [ CLUSTERED | LOOK-UP ] ( <column> [ ,... n ] )
     [ { FOREIGN KEY <foreign-key> ( <column> [ ASC | DESC ] [ ,... n ] )
       REFERENCES [ <namespace>. ] <table> ( <column> [ ,... n ] )
         [ ON DELETE { NO ACTION | CASCADE | SET DEFAULT } ]
@@ -177,15 +185,6 @@ _NOTE_: Further investigation is needed to understand if there's a reason to spe
       [ ,... n ] ]`
 ```
 
-## Example
-```
-CREATE TABLE order-detail
-(invoice-nbr @ud, line-item @ud, product-id @ud, special-offer-id @ud, message @t)
-PRIMARY KEY CLUSTERED (invoice-nbr, line-item)
-FOREIGN KEY fk-special-offer-order-detail (product-id, specialoffer-id)
-REFERENCES special-offer (product-id, special-offer-id)
-```
-
 ## API
 ```
 +$  create-table
@@ -209,8 +208,8 @@ If not explicitly qualified, it defaults to the Obelisk agent's current database
 The list of user-defined column names and associated auras. Names must adhere to the hoon term naming standard.
 For more details, refer to [ref-ch02-types](ref-ch02-types.md)
 
-**`[ CLUSTERED | NONCLUSTERED ] ( <column> [ ,... n ]`**
-These are column names in the required unique primary index. Defining the index as `NONCLUSTERED` is optional.
+**`[ CLUSTERED | LOOK-UP ] ( <column> [ ,... n ]`**
+These are column names in the required unique primary index. Defining the index as `LOOK-UP` is optional.
 
 **`<foreign-key> ( <column> [ ASC | DESC ] [ ,... n ]`**
 This is a user-defined name for `<foreign-key>`. It must adhere to the hoon term naming standard.
@@ -265,12 +264,6 @@ NOTE: The specific definition of `CLUSTERED` in Hoon, possibly an ordered map, i
 
 ## Produced Metadata
 
-INSERT `table name`, `namespace`, `<timestamp>` INTO `<database>.sys.tables`
-INSERT `table name`, `namespace`, `<ordinal>`, `column name`, `aura`, `<timestamp>` INTO `<database>.sys.table-columns`
-INSERT `table name`, `namespace`, `delete | update`, `<action>`, `<timestamp>` INTO `<database>.sys.table-ref-integrity`
-CREATE INDEX on Primary Key
-CREATE INDEX on Foreign Keys
-
 ## Exceptions
 
 name within namespace already exists for table
@@ -278,6 +271,15 @@ table referenced by FOREIGN KEY does not exist
 table column referenced by FOREIGN KEY does not exist
 aura mis-match in FOREIGN KEY
 
+## Example
+```
+CREATE TABLE order-detail
+(invoice-nbr @ud, line-item @ud, product-id @ud, special-offer-id @ud, message @t)
+PRIMARY KEY CLUSTERED (invoice-nbr, line-item)
+FOREIGN KEY fk-special-offer-order-detail (product-id, specialoffer-id)
+REFERENCES special-offer (product-id, special-offer-id)
+```
+
 # CREATE TRIGGER
 
 A trigger automatically runs when a specified table or view event occurs in the Obelisk agent. It runs a previously defined `<procedure>`.
@@ -346,6 +348,8 @@ Views cannot be defined on foreign ship databases.
 
 ## Produced Metadata
 
+## Examples
+
 INSERT `name`, `<transform>`, `<timestamp>` INTO `<database>.sys.views`
 INSERT `name`, `<ordinal>`, `<column>` INTO `<database>.sys.view-columns`
 

docs/ref-ch04-data-manipulation.md

@@ -57,7 +57,7 @@ Inserts rows into a `<table-set>`.
 <insert> ::=
   INSERT INTO <table-set>
     [ ( <column> [ ,...n ] ) ]
-    { VALUES (<scalar-expression> [ ,...n ] ) [ ,...n ]
+    { VALUES (<scalar-expression> [ ,...n ] ) [ ...n ]
       | <transform> }
 ```
 
@@ -117,6 +117,8 @@ When the target `<table-set>` is a `<table>`, the input `<row-type>` must match
 
 When target `<table-set>` is not a `<table>` and the input is from a `<transform>` then the target `<table-set>` and `<transform>` `<table-set>` must have the same all-column `<row-type>`. New `<row-type>` sub-types may be introduced.
 
+Note that multiple parentheses enclosed rows of column values are NOT comma separated.
+
 ## Produced Metadata
 
 `@@ROWCOUNT` returns the total number of rows inserted

docs/ref-ch07-transform.md

@@ -34,7 +34,7 @@ A `<transform>` in a CTE cannot include a `WITH` clause.
   | <update>
 ```
 
-A `<cmd>` is considered terminal when it operates on a `<table>` and potentially mutates its state, whether it mutates `<table>` state or not. A terminal `<cmd>` must be the last step in a `<transform>`, it cannot be grouped by parentheses, and it is not the only `<cmd>` it must have been preceded by a `<pass-thru-op>`. 
+A `<cmd>` is considered terminal when it operates on a `<table>` and potentially mutates its state, whether it mutates `<table>` state or not. A terminal `<cmd>` must be the last step in a `<transform>`, it cannot be grouped by parentheses, and if is not the only `<cmd>` it must have been preceded by a `<pass-thru-op>`. 
 
 The `<query>` command by itself is never terminal. It is terminal when it is followed by `INTO <table>`.
 
@@ -110,7 +110,7 @@ API:
   $:
   %transform
   ctes=(list <common-table-expression>)
-  (tree <set-functions>)
+  set-functions=(tree <set-functions>)
   ==
 ```
 
@@ -118,9 +118,7 @@ API:
 
 **`WITH [ <common-table-expression> [ ,...n ] ]`**
 
-`<transform>`s within a CTE may not have their own `WITH` clause.
-
-The `WITH` clause makes the result `<table-set>` of a `<transform>` statement available to the subsequent `<transform>` statements in the `WITH` clause and `<cmd>`s in the main `<transform>` by `<alias>`. `<transform>`s in the `WITH` clause cannot have their own internal `WITH`, rather any preceding CTEs are available.
+The `WITH` clause makes the result `<table-set>` of a `<transform>` statement available to the subsequent `<transform>` statements in the `WITH` clause and `<cmd>`s in the main `<transform>` by `<alias>`. `<transform>`s in the `WITH` clause cannot have their own `WITH` clause, rather preceding CTEs within the clause are available and function as a virtual `WITH` clause.
 
 When used as a `<common-table-expression>`, `<transform>` output must be a pass-thru virtual-table.
 

utilities/file-to-tape.fsx

@@ -0,0 +1,17 @@
+// file-to-tape.fsx
+open System
+open System.IO
+
+let args = Environment.GetCommandLineArgs()
+let inFile = 
+ //   File.ReadAllLines(Path.Combine([|args.[2]|]))
+  File.ReadAllLines(fsi.CommandLineArgs.[1])
+
+let outString (inString : string)  = 
+    "\" " + inString + " \"."
+
+let output =
+  inFile
+  |> Array.map outString
+
+File.WriteAllLines(Path.Combine(fsi.CommandLineArgs.[1] + "x"), output)