Permalink
Browse files

[doc] opadoc: open sourcing opadoc resources

  • Loading branch information...
Aqua-Ye committed Mar 21, 2012
1 parent ae17609 commit c8784653e361714a564e6cbea78a9313b613750b
Showing with 14,999 additions and 0 deletions.
  1. +218 −0 opadoc/cheat-sheet-db.omd
  2. +208 −0 opadoc/manual.omd/about.omd
  3. +387 −0 opadoc/manual.omd/example.omd
  4. +636 −0 opadoc/manual.omd/hello_bindings.omd
  5. +779 −0 opadoc/manual.omd/hello_chat.omd
  6. +302 −0 opadoc/manual.omd/hello_database.omd
  7. +235 −0 opadoc/manual.omd/hello_distribution.omd
  8. +758 −0 opadoc/manual.omd/hello_recaptcha.omd
  9. +343 −0 opadoc/manual.omd/hello_web_services.omd
  10. +549 −0 opadoc/manual.omd/hello_web_services_client.omd
  11. +515 −0 opadoc/manual.omd/hello_wiki.omd
  12. +19 −0 opadoc/manual.omd/index
  13. +217 −0 opadoc/manual.omd/install.omd
  14. +50 −0 opadoc/manual.omd/missing
  15. +1,317 −0 opadoc/manual.omd/ref_core_language.omd
  16. +360 −0 opadoc/manual.omd/ref_database.omd
  17. +380 −0 opadoc/manual.omd/ref_execution.omd
  18. +249 −0 opadoc/manual.omd/ref_filenames.omd
  19. +1,018 −0 opadoc/manual.omd/ref_mongodb.omd
  20. +2,262 −0 opadoc/manual.omd/ref_type_system.omd
  21. +801 −0 opadoc/manual.omd/ref_web_language.omd
  22. +214 −0 opadoc/manual.omd/tour.omd
  23. +36 −0 opadoc/manual.src/Makefile
  24. +23 −0 opadoc/manual.src/git
  25. +15 −0 opadoc/manual.src/hello-opa/.gitignore
  26. +10 −0 opadoc/manual.src/hello-opa/README.markdown
  27. +18 −0 opadoc/manual.src/hello-opa/hello-opa.opa
  28. +13 −0 opadoc/manual.src/hello_chat/.gitignore
  29. +10 −0 opadoc/manual.src/hello_chat/README.markdown
  30. +104 −0 opadoc/manual.src/hello_chat/hello_chat.opa
  31. +80 −0 opadoc/manual.src/hello_chat/hello_chat_min.opa
  32. +42 −0 opadoc/manual.src/hello_chat/resources/css.css
  33. BIN opadoc/manual.src/hello_chat/resources/opa-logo.png
  34. BIN opadoc/manual.src/hello_chat/resources/user.png
  35. +14 −0 opadoc/manual.src/hello_recaptcha/.gitignore
  36. +5 −0 opadoc/manual.src/hello_recaptcha/Makefile
  37. +14 −0 opadoc/manual.src/hello_recaptcha/README.markdown
  38. +247 −0 opadoc/manual.src/hello_recaptcha/hello_recaptcha.opa
  39. +42 −0 opadoc/manual.src/hello_recaptcha/hello_recaptcha_app.opa
  40. +140 −0 opadoc/manual.src/hello_recaptcha/hello_recaptcha_test.opa
  41. +35 −0 opadoc/manual.src/hello_recaptcha/recaptcha.js
  42. +13 −0 opadoc/manual.src/hello_web_services/.gitignore
  43. +14 −0 opadoc/manual.src/hello_web_services/README.markdown
  44. +88 −0 opadoc/manual.src/hello_web_services/hello_wiki_rest.opa
  45. +111 −0 opadoc/manual.src/hello_web_services/hello_wiki_rest_client.opa
  46. +128 −0 opadoc/manual.src/hello_web_services/hello_wiki_rest_client_customizable.opa
  47. +13 −0 opadoc/manual.src/hello_web_services/resources/css.css
  48. BIN opadoc/manual.src/hello_web_services/resources/opa-logo.png
  49. +13 −0 opadoc/manual.src/hello_wiki/.gitignore
  50. +10 −0 opadoc/manual.src/hello_wiki/README.markdown
  51. +143 −0 opadoc/manual.src/hello_wiki/hello_wiki.opa
  52. +196 −0 opadoc/manual.src/hello_wiki/hello_wiki_mongo.opa
  53. +142 −0 opadoc/manual.src/hello_wiki/hello_wiki_simple.opa
  54. +13 −0 opadoc/manual.src/hello_wiki/resources/css.css
  55. BIN opadoc/manual.src/hello_wiki/resources/opa-logo.png
  56. +15 −0 opadoc/manual.src/opa_binding_examples/.gitignore
  57. +13 −0 opadoc/manual.src/opa_binding_examples/Makefile
  58. +10 −0 opadoc/manual.src/opa_binding_examples/README.markdown
  59. +18 −0 opadoc/manual.src/opa_binding_examples/c_binding/Makefile
  60. +2 −0 opadoc/manual.src/opa_binding_examples/c_binding/c_binding.ml
  61. +54 −0 opadoc/manual.src/opa_binding_examples/c_binding/freq.c
  62. +2 −0 opadoc/manual.src/opa_binding_examples/c_binding/freq.opa
  63. +10 −0 opadoc/manual.src/opa_binding_examples/external_types/Makefile
  64. +37 −0 opadoc/manual.src/opa_binding_examples/external_types/bigint.ml
  65. +82 −0 opadoc/manual.src/opa_binding_examples/external_types/bigint.opa
  66. +41 −0 opadoc/manual.src/opa_binding_examples/hello_bindings.opa
  67. +17 −0 opadoc/manual.src/opa_binding_examples/opa_types/Makefile
  68. +134 −0 opadoc/manual.src/opa_binding_examples/opa_types/dbm.ml
  69. +106 −0 opadoc/manual.src/opa_binding_examples/opa_types/dbm.opa
  70. +9 −0 opadoc/manual.src/opa_binding_examples/plugin.js
  71. +4 −0 opadoc/manual.src/opa_binding_examples/plugin.ml
  72. +1 −0 opadoc/opadoc.apix
  73. +895 −0 opadoc/refcard.omd
View
@@ -0,0 +1,218 @@
+WARNING : MOST OF THE FEATURES DESCRIBED BELOW HAVE NOT YET IMPLEMENTED BY DB3
+
+Overview
+============
+Since Opa S4, the compiler handles several database
+backends. Depending (for moment) on the '--database' parameter the compiler
+generates different database accessors.
+
+Currently, the compiler handles two database backends :
+- db3 : Opa database
+- mongo : [http://www.mongodb.org/](http://www.mongodb.org/)
+
+Independently from the database backend, Opa allows :
+- Definition of a database schema, made of a set of typed paths
+- Generic database paths accessors
+- An API that manipulates database paths
+
+But some features can be backend specific. That's why there are also specific API(s)
+
+
+Databases declaration
+===============
+ type stored = {int x, int y, string v, list(string) lst}
+
+ database dbname {
+ int /i
+ float /f
+ string /s
+ stored /r
+ list(string) /l
+ intmap(stored) /imap
+ stored /set[{x}]
+ }
+
+This piece of code declares the database _dbname_ and defines :
+- 3 paths containing basic values (/i, /f, /s)
+- 1 path containing a record (/r)
+- 1 path containing a list of string
+- 1 path to an intmap
+- 1 path to a database collection of _stored_ record. The key of the declared collection is _x_.
+
+Updating
+============
+One of the new things available with Opa S4 is the way one can update a
+database path. Indeed, previously it was only possible to overwrite a path,
+like this :
+
+ /path/to/data <- x
+
+With _x_ a value with its type equals to that of _/path/to/data_
+
+Opa S4 defined new and most powerful ways to update a path. An update
+operation should be atomic.
+
+Int updating
+--------
+ // Set
+ /dbname/i <- 42
+
+ // Increment
+ /dbname/i ++
+ /dbname/i += 10
+
+ // Decrement
+ /dbname/i --
+ /dbname/i -= 10
+
+ // Sure we can go across records
+ /dbname/r/x ++
+
+Record updating
+--------
+ // Overwrite an entire record
+ x = {x : 1, y : 2, v : "Hello, world", lst:[]}
+ /dbname/r <- x
+
+ // Update a subset of record fields
+ /dbname/r <- {x++, y--}
+
+ /dbname/r <- {x++, v : "I just want to update z and incr x"}
+
+List updating
+--------
+ // Overwrite an entire list
+ /dbname/l <- ["Hello", ",", "world", "."]
+
+ // Removes first element of a list
+ /dbname/l pop
+
+ // Removes last element of a list
+ /dbname/l shift
+
+ // Append an element
+ /dbname/l <+ "element"
+
+ // Append several elements
+ /dbname/l <++ ["I", "love", "Opa"]
+
+Database set/map updating
+--------
+The values stored inside database sets and maps can be updated as we see above.
+The difference is how we access to the elements (more details on [querying section](#Querying).
+Futhermore updates can operates on several paths.
+
+ //Increment the field y of the record stored at position 9 of imap
+ /dbname/imap[9] <- {y++}
+
+ //Increment fields y of records stored with key smaller than 9
+ /dbname/imap[< 9] <- {y++}
+
+ //Increment the field y of record where the field x is equals 9
+ /dbname/set[x == 9] <- {y++}
+
+ //Increment the field y of all records where the field x is smaller than 9
+ /dbname/set[x < 9] <- {y++}
+
+Querying
+============
+In the previous section we saw how to update data with Opa S4. Other
+novelties concern the way to access to data stored inside collections.
+
+Previously the database collections were intmap and stringmap, and the
+way to access to data stored inside database map was :
+
+ // Access to the element stored at position 9
+ /dbname/imap[9]
+
+But it was impossible to access all the elements within a path, except by
+using Db.*_fold_range. But it was just a fold on collection keys
+(not on value) and it was not really user friendly.
+
+Opa S4 introduces database sets and a most powerful way to access to
+a subset of database collections.
+
+Querying operators
+--------
+- == expr : equals expr
+- != expr : not equals expr
+- < expr : lesser than expr
+- <= expr : lesser than or equals expr
+- > expr : greater than expr
+- >= expr : greater than or equals expr
+- in expr : in expr where expr is a list
+- q1 or q2 : satisfy query q1 or q2
+- q1 and q2 : satisfy queries q1 and q2
+- not q : doesn't satisfy q
+- {f1 q1, f2 q2, ...} : the record field f1 satisfy q1 and field f2 satisfy q2
+
+Querying options
+--------
+- skip n : where expr should be an expression of type int, skip the first
+- limit n : where expr should be an expression of type int, returns maximum n results
+- order fld (, fld)+ : where fld specify an order. fld can be <ident> or
+ +<ident> to specify staticaly fld ident should be sorted by incr, -<ident> by
+ decr. Or choose dynamicaly by <ident>=<expr> where <expr> should type of {up}
+ or {down}.
+
+Querying set
+--------
+ k = {x : 9}
+ stored x = /dbname/set[k] // k should be type of set keys, returns a uniq value
+ stored x = /dbname/set[x == 10] // Returns a uniq value because {x} is primary key of set
+
+ dbset(stored, _) x = /dbname/set[y == 10] // Returns a database set because y is not a primary key
+
+ dbset(stored, _) x = /dbname/set[x > 10, y > 0, v in ["foo", "bar"]]
+
+ dbset(stored, _) x = /dbname/set[x > 10, y > 0, v in ["foo", "bar"]; skip 10; limit 15; order +x, -y]
+
+ it = DbSet.iterator(x); // then use Iter module.
+
+Querying map
+--------
+ //Access to a uniq value (like S3)
+ stored x = /dbname/imap[9]
+
+ //Access to a submap where keys are lesser than 9 and greater than 4
+ intmap(stored) submap = /dbname/imap[< 9 and > 4]
+
+
+API(s)
+============
+Some features are available on all backends like read, write, remove, etc
+while other feature has available only on one backend (example : path history).
+That's why we have commons types (and API stdlib.core.database module Db) :
+
+ Db.val_path('a, 'engine)
+ Db.ref_path('a, 'engine)
+
+Where 'a corresponding to type of value stored, then 'engine depending to the backend.
+ //Using db3 backend, Db3.val_path is an instance of Db.val_path
+ Db3.val_path(int) vpath = !/dbname/i
+ //You can use the common API
+ x = Db.read(vpath)
+ //And specific db3 API
+ h = Db3.history(vpath)
+
+
+
+ //But if you use mongo backend, DbMongo.val_path is an instance of Db.val_path
+ DbMongo.val_path(int) vpath = !/dbname/i
+ //You can use the common API
+ x = Db.read(vpath)
+ //But you will have a TYPE ERROR if you use specific db3 API
+ h = Db3.history(vpath)
+
+
+Restriction/Todo
+============
+
+db3
+--------
+- dbset are not yet implemeted
+- Most of updating and querying operations are not yet implemented
+
+mongo
+--------
+- Nothing about migration of database schema
Oops, something went wrong.

0 comments on commit c878465

Please sign in to comment.