{"action":"created","comment":{"url":"https://api.github.com/repos/directembedding/directembedding/pulls/comments/23219883","id":23219883,"diff_hunk":"@@ -1,4 +1,274 @@\n-Direct Embedding for Scala [![Build Status](https://travis-ci.org/directembedding/directembedding.png?branch=master)](https://travis-ci.org/directembedding/directembedding)\n+DirectEmbedding [![Build Status](https://travis-ci.org/directembedding/directembedding.png?branch=master)](https://travis-ci.org/directembedding/directembedding)\n ===============\n \n-A library for macro based direct embedding of DSLs.\n+An experimental macro-based library for Embedded DSLs.\n+\n+# DirectEmbedding for DSLs\n+\n+\n+DirectEmbedding is an experimental project that attempts to provide direct embedding in Scala for Domain Specific Languages (DSLs). Although, this project is currently exploratory, this library could become a very useful tool. For instance, it could replace the complex shadow embedding of [Yin-Yang](https://github.com/scala-yinyang/scala-yinyang/tree/cbfaf02405c5e273498c15ce943965eeba8afa31) library in existing or future projects such as [Slick](http://slick.typesafe.com/).\n+\n+This library provides **one** effortless logic for the reification of embedded DSLs in Scala. This comes along many **advantages**:\n+\n+- no knowledge of the [Reflection API](http://en.wikipedia.org/wiki/Reflection_%28computer_programming%29)\n+- no overloading resolution\n+- no dependence with types and count of arguments\n+- no verbosity\n+- no duplication of code\n+\n+Our solution makes use of [annotations](http://docs.scala-lang.org/overviews/reflection/annotations-names-scopes.html) and [macros](http://www.scala-lang.org/api/2.11.0/scala-reflect/index.html#scala.reflect.macros.blackbox.Context) to achieve this goal.\n+\n+##Table of contents:\n+\n+1. [Overview of the concept](#overview)\n+2. [Details](#details)\n+3. [Project Structure](#project-structure)\n+4. [Usage](#usage)\n+5. [References](#references)\n+6. [Licence](#licence)\n+\n+--\n+\n+# Overview\n+Writing embedding DSLs implies to go though the difficult task of reification. \n+Reification means when a function *take(x: Int): Query[T]* is written in Scala it will be converted to a corresponding DSL object *Take*. *Take* is the Intermediate Representation (IR) of the function *take()*. The naive method would code conditional statements in order to **identify** which function has been called. Identifying is strenuous and redundant because it must check many criteria, take in account aspects such as overriding of the function and this for all functions or classes. It is not a best practices and it creates as much logics of reification than there is cases to reify.\n+Hopefully, this can be facilitated by libraries and DirectEmbedding is one of them.\n+\n+*[More details in  Quasiquotes](#quasiquotes)*\n+\n+### Attach Metadata\n+The idea developed by DirectEmbedding is to attach metadata about the corresponding IR and thus it gets rid of the demanding task of identification. It becomes straight forward to solve the previous issues. When it was required to verify the name of the function, its types, its types arguments, its arguments count, now this is declared along the function. Overriding? It is also very simple, it simply needs to attach the corresponding IR.\n+\n+### Annotate\n+Scala annotations can attribute an object to declarations. Thus, annotations permit to attach metadata, that is to say, the IR. The annotation is accessible through the symbol of the AST.\n+\n+### Reify\n+DirectEmbedding reifies the DSL while the compilation. This means that the given AST for an annotated function will be reified into the DSL representation at compile-time. In order to do so, there is the need to *pattern match* all the different ASTs that can be generated by an annotated declaration. Once the arguments, the types arguments and the symbol of the annotated code are extracted from the AST then the reification occurs via a macro. The macro applies the arguments and types arguments to the obtained IR from the symbol. The macro returns the reified tree i.e. the IR with the arguments and types arguments correctly applied. \n+\n+With DirectEmbedding, there is not special difficulty for the identification, it does the hard task of *pattern matching* the ASTs and using the macros, the solution is elegant and proposes only one reification logic. **Pretty simple!**\n+\n+\n+\n+### An example\n+**On the side of the DSL's developper**\n+\n+* Let's imagine, we want to define for a DSL a function take() that returns a Query[T]:\n+\n+\t```scala\n+\t\tclass Query[T] {\n+\t\t\tval take(x: Int): Query[T] = ???\n+\t\t}\n+\t```\n+\n+* For this DSL, the function take() should be reified into the following IR:\n+\n+\t```scala\n+\t\tcase class Take[T](self: Exp[QueryIR[T]], n: Exp[Int])\n+\t\t   extends Exp[Query[T]]\n+\t```\n+\n+* Thus, the function take() needs to be annotated:\n+\n+\t```scala\n+\t\tclass Query[T] {\n+\t\t\t@reifyAs(Take) //Annotation with its corresponding IR\n+\t\t\tval take(x: Int): Query[T] = ???\n+\t\t}\n+\t```\n+\n+**On the DSL's user side**\n+\n+* One user calls the function take() in his code:\n+\n+\t```scala\n+\t   lift {\n+\t      \tnew Query[Movie].take(3)\n+\t   }\n+\t```\n+\n+* The function is reified inside at compile-time into:\n+\n+\t```scala\n+\t   Expr[T](Take.apply[Int](QueryIR.apply[Movie], 3))\n+\t```\n+\n+**What happened?**\n+\n+* A Scala AST is generated and caught\n+* The annotation, the arguments and the type arguments are extracted\n+* A macro reified the AST into the result\n+\n+\n+# Details\n+## Quasiquotes?\n+\n+```scala\n+\tcase q\"$a.take($b)\" if a.tpe =:= typeOf[Query[_]]\n+  \t \t\t&& b.tpe =:= typeOf[Int] => Take(a, b)\n+```\n+\t\n+The code above shows what would be reification without DirectEmbedding. Although, in this case, we use quasiquotes, there is none of the advantages of DirectEmbedding:\n+\t\n+1. **no knowledge of the [Reflection API](http://en.wikipedia.org/wiki/Reflection_%28computer_programming%29)**\n+\t- this code obviously necessitates knowledge of the Reflection API\n+- **no overloading resolution**\n+\t- if *take(x: Int, b: Boolean): Query[T]* overrides *take(x: Int): Query[T]* then another conditional statement would be needed.\n+\n+\t```scala\n+\t\tcase q\"$a.take($b, $c)\" if a.tpe =:= typeOf[Query[_]]\n+  \t \t\t&& b.tpe =:= typeOf[Int]\n+  \t \t\t&& c.tpe =:= typeOf[Boolean] => Take(a, b, c)\n+\t```\n+- **no dependence with types and count of arguments**\n+\t- as shown in the previous example, a new argument implies a new code\n+- **no verbosity**\n+\t- this kind of code can become illegible","path":"README.md","position":127,"original_position":127,"commit_id":"53396da6a2e3ae08022477a1d7650146eb1f118c","original_commit_id":"53396da6a2e3ae08022477a1d7650146eb1f118c","user":{"login":"vjovanov","id":352820,"avatar_url":"https://avatars.githubusercontent.com/u/352820?v=3","gravatar_id":"","url":"https://api.github.com/users/vjovanov","html_url":"https://github.com/vjovanov","followers_url":"https://api.github.com/users/vjovanov/followers","following_url":"https://api.github.com/users/vjovanov/following{/other_user}","gists_url":"https://api.github.com/users/vjovanov/gists{/gist_id}","starred_url":"https://api.github.com/users/vjovanov/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/vjovanov/subscriptions","organizations_url":"https://api.github.com/users/vjovanov/orgs","repos_url":"https://api.github.com/users/vjovanov/repos","events_url":"https://api.github.com/users/vjovanov/events{/privacy}","received_events_url":"https://api.github.com/users/vjovanov/received_events","type":"User","site_admin":false},"body":"What do you mean by that?","created_at":"2015-01-20T12:56:37Z","updated_at":"2015-01-20T12:56:37Z","html_url":"https://github.com/directembedding/directembedding/pull/17#discussion_r23219883","pull_request_url":"https://api.github.com/repos/directembedding/directembedding/pulls/17","_links":{"self":{"href":"https://api.github.com/repos/directembedding/directembedding/pulls/comments/23219883"},"html":{"href":"https://github.com/directembedding/directembedding/pull/17#discussion_r23219883"},"pull_request":{"href":"https://api.github.com/repos/directembedding/directembedding/pulls/17"}}},"pull_request":{"url":"https://api.github.com/repos/directembedding/directembedding/pulls/17","id":27674972,"html_url":"https://github.com/directembedding/directembedding/pull/17","diff_url":"https://github.com/directembedding/directembedding/pull/17.diff","patch_url":"https://github.com/directembedding/directembedding/pull/17.patch","issue_url":"https://api.github.com/repos/directembedding/directembedding/issues/17","number":17,"state":"open","locked":false,"title":"Readme PR","user":{"login":"joriscode","id":2750485,"avatar_url":"https://avatars.githubusercontent.com/u/2750485?v=3","gravatar_id":"","url":"https://api.github.com/users/joriscode","html_url":"https://github.com/joriscode","followers_url":"https://api.github.com/users/joriscode/followers","following_url":"https://api.github.com/users/joriscode/following{/other_user}","gists_url":"https://api.github.com/users/joriscode/gists{/gist_id}","starred_url":"https://api.github.com/users/joriscode/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/joriscode/subscriptions","organizations_url":"https://api.github.com/users/joriscode/orgs","repos_url":"https://api.github.com/users/joriscode/repos","events_url":"https://api.github.com/users/joriscode/events{/privacy}","received_events_url":"https://api.github.com/users/joriscode/received_events","type":"User","site_admin":false},"body":"","created_at":"2015-01-20T12:48:56Z","updated_at":"2015-01-20T12:56:37Z","closed_at":null,"merged_at":null,"merge_commit_sha":"b76a14b0e28c3c35249b129485a413b192b4e3f3","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/directembedding/directembedding/pulls/17/commits","review_comments_url":"https://api.github.com/repos/directembedding/directembedding/pulls/17/comments","review_comment_url":"https://api.github.com/repos/directembedding/directembedding/pulls/comments/{number}","comments_url":"https://api.github.com/repos/directembedding/directembedding/issues/17/comments","statuses_url":"https://api.github.com/repos/directembedding/directembedding/statuses/53396da6a2e3ae08022477a1d7650146eb1f118c","head":{"label":"joriscode:master","ref":"master","sha":"53396da6a2e3ae08022477a1d7650146eb1f118c","user":{"login":"joriscode","id":2750485,"avatar_url":"https://avatars.githubusercontent.com/u/2750485?v=3","gravatar_id":"","url":"https://api.github.com/users/joriscode","html_url":"https://github.com/joriscode","followers_url":"https://api.github.com/users/joriscode/followers","following_url":"https://api.github.com/users/joriscode/following{/other_user}","gists_url":"https://api.github.com/users/joriscode/gists{/gist_id}","starred_url":"https://api.github.com/users/joriscode/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/joriscode/subscriptions","organizations_url":"https://api.github.com/users/joriscode/orgs","repos_url":"https://api.github.com/users/joriscode/repos","events_url":"https://api.github.com/users/joriscode/events{/privacy}","received_events_url":"https://api.github.com/users/joriscode/received_events","type":"User","site_admin":false},"repo":{"id":26022332,"name":"directembedding","full_name":"joriscode/directembedding","owner":{"login":"joriscode","id":2750485,"avatar_url":"https://avatars.githubusercontent.com/u/2750485?v=3","gravatar_id":"","url":"https://api.github.com/users/joriscode","html_url":"https://github.com/joriscode","followers_url":"https://api.github.com/users/joriscode/followers","following_url":"https://api.github.com/users/joriscode/following{/other_user}","gists_url":"https://api.github.com/users/joriscode/gists{/gist_id}","starred_url":"https://api.github.com/users/joriscode/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/joriscode/subscriptions","organizations_url":"https://api.github.com/users/joriscode/orgs","repos_url":"https://api.github.com/users/joriscode/repos","events_url":"https://api.github.com/users/joriscode/events{/privacy}","received_events_url":"https://api.github.com/users/joriscode/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/joriscode/directembedding","description":"A library for macro based direct embedding of DSLs","fork":true,"url":"https://api.github.com/repos/joriscode/directembedding","forks_url":"https://api.github.com/repos/joriscode/directembedding/forks","keys_url":"https://api.github.com/repos/joriscode/directembedding/keys{/key_id}","collaborators_url":"https://api.github.com/repos/joriscode/directembedding/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/joriscode/directembedding/teams","hooks_url":"https://api.github.com/repos/joriscode/directembedding/hooks","issue_events_url":"https://api.github.com/repos/joriscode/directembedding/issues/events{/number}","events_url":"https://api.github.com/repos/joriscode/directembedding/events","assignees_url":"https://api.github.com/repos/joriscode/directembedding/assignees{/user}","branches_url":"https://api.github.com/repos/joriscode/directembedding/branches{/branch}","tags_url":"https://api.github.com/repos/joriscode/directembedding/tags","blobs_url":"https://api.github.com/repos/joriscode/directembedding/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/joriscode/directembedding/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/joriscode/directembedding/git/refs{/sha}","trees_url":"https://api.github.com/repos/joriscode/directembedding/git/trees{/sha}","statuses_url":"https://api.github.com/repos/joriscode/directembedding/statuses/{sha}","languages_url":"https://api.github.com/repos/joriscode/directembedding/languages","stargazers_url":"https://api.github.com/repos/joriscode/directembedding/stargazers","contributors_url":"https://api.github.com/repos/joriscode/directembedding/contributors","subscribers_url":"https://api.github.com/repos/joriscode/directembedding/subscribers","subscription_url":"https://api.github.com/repos/joriscode/directembedding/subscription","commits_url":"https://api.github.com/repos/joriscode/directembedding/commits{/sha}","git_commits_url":"https://api.github.com/repos/joriscode/directembedding/git/commits{/sha}","comments_url":"https://api.github.com/repos/joriscode/directembedding/comments{/number}","issue_comment_url":"https://api.github.com/repos/joriscode/directembedding/issues/comments/{number}","contents_url":"https://api.github.com/repos/joriscode/directembedding/contents/{+path}","compare_url":"https://api.github.com/repos/joriscode/directembedding/compare/{base}...{head}","merges_url":"https://api.github.com/repos/joriscode/directembedding/merges","archive_url":"https://api.github.com/repos/joriscode/directembedding/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/joriscode/directembedding/downloads","issues_url":"https://api.github.com/repos/joriscode/directembedding/issues{/number}","pulls_url":"https://api.github.com/repos/joriscode/directembedding/pulls{/number}","milestones_url":"https://api.github.com/repos/joriscode/directembedding/milestones{/number}","notifications_url":"https://api.github.com/repos/joriscode/directembedding/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/joriscode/directembedding/labels{/name}","releases_url":"https://api.github.com/repos/joriscode/directembedding/releases{/id}","created_at":"2014-10-31T15:47:30Z","updated_at":"2015-01-20T11:19:51Z","pushed_at":"2015-01-20T11:19:50Z","git_url":"git://github.com/joriscode/directembedding.git","ssh_url":"git@github.com:joriscode/directembedding.git","clone_url":"https://github.com/joriscode/directembedding.git","svn_url":"https://github.com/joriscode/directembedding","homepage":null,"size":328,"stargazers_count":0,"watchers_count":0,"language":"Scala","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"directembedding:master","ref":"master","sha":"8dbad101d260e1a0adc178db935caf8961912e32","user":{"login":"directembedding","id":9320661,"avatar_url":"https://avatars.githubusercontent.com/u/9320661?v=3","gravatar_id":"","url":"https://api.github.com/users/directembedding","html_url":"https://github.com/directembedding","followers_url":"https://api.github.com/users/directembedding/followers","following_url":"https://api.github.com/users/directembedding/following{/other_user}","gists_url":"https://api.github.com/users/directembedding/gists{/gist_id}","starred_url":"https://api.github.com/users/directembedding/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/directembedding/subscriptions","organizations_url":"https://api.github.com/users/directembedding/orgs","repos_url":"https://api.github.com/users/directembedding/repos","events_url":"https://api.github.com/users/directembedding/events{/privacy}","received_events_url":"https://api.github.com/users/directembedding/received_events","type":"Organization","site_admin":false},"repo":{"id":25468693,"name":"directembedding","full_name":"directembedding/directembedding","owner":{"login":"directembedding","id":9320661,"avatar_url":"https://avatars.githubusercontent.com/u/9320661?v=3","gravatar_id":"","url":"https://api.github.com/users/directembedding","html_url":"https://github.com/directembedding","followers_url":"https://api.github.com/users/directembedding/followers","following_url":"https://api.github.com/users/directembedding/following{/other_user}","gists_url":"https://api.github.com/users/directembedding/gists{/gist_id}","starred_url":"https://api.github.com/users/directembedding/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/directembedding/subscriptions","organizations_url":"https://api.github.com/users/directembedding/orgs","repos_url":"https://api.github.com/users/directembedding/repos","events_url":"https://api.github.com/users/directembedding/events{/privacy}","received_events_url":"https://api.github.com/users/directembedding/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/directembedding/directembedding","description":"A library for macro based direct embedding of DSLs","fork":false,"url":"https://api.github.com/repos/directembedding/directembedding","forks_url":"https://api.github.com/repos/directembedding/directembedding/forks","keys_url":"https://api.github.com/repos/directembedding/directembedding/keys{/key_id}","collaborators_url":"https://api.github.com/repos/directembedding/directembedding/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/directembedding/directembedding/teams","hooks_url":"https://api.github.com/repos/directembedding/directembedding/hooks","issue_events_url":"https://api.github.com/repos/directembedding/directembedding/issues/events{/number}","events_url":"https://api.github.com/repos/directembedding/directembedding/events","assignees_url":"https://api.github.com/repos/directembedding/directembedding/assignees{/user}","branches_url":"https://api.github.com/repos/directembedding/directembedding/branches{/branch}","tags_url":"https://api.github.com/repos/directembedding/directembedding/tags","blobs_url":"https://api.github.com/repos/directembedding/directembedding/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/directembedding/directembedding/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/directembedding/directembedding/git/refs{/sha}","trees_url":"https://api.github.com/repos/directembedding/directembedding/git/trees{/sha}","statuses_url":"https://api.github.com/repos/directembedding/directembedding/statuses/{sha}","languages_url":"https://api.github.com/repos/directembedding/directembedding/languages","stargazers_url":"https://api.github.com/repos/directembedding/directembedding/stargazers","contributors_url":"https://api.github.com/repos/directembedding/directembedding/contributors","subscribers_url":"https://api.github.com/repos/directembedding/directembedding/subscribers","subscription_url":"https://api.github.com/repos/directembedding/directembedding/subscription","commits_url":"https://api.github.com/repos/directembedding/directembedding/commits{/sha}","git_commits_url":"https://api.github.com/repos/directembedding/directembedding/git/commits{/sha}","comments_url":"https://api.github.com/repos/directembedding/directembedding/comments{/number}","issue_comment_url":"https://api.github.com/repos/directembedding/directembedding/issues/comments/{number}","contents_url":"https://api.github.com/repos/directembedding/directembedding/contents/{+path}","compare_url":"https://api.github.com/repos/directembedding/directembedding/compare/{base}...{head}","merges_url":"https://api.github.com/repos/directembedding/directembedding/merges","archive_url":"https://api.github.com/repos/directembedding/directembedding/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/directembedding/directembedding/downloads","issues_url":"https://api.github.com/repos/directembedding/directembedding/issues{/number}","pulls_url":"https://api.github.com/repos/directembedding/directembedding/pulls{/number}","milestones_url":"https://api.github.com/repos/directembedding/directembedding/milestones{/number}","notifications_url":"https://api.github.com/repos/directembedding/directembedding/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/directembedding/directembedding/labels{/name}","releases_url":"https://api.github.com/repos/directembedding/directembedding/releases{/id}","created_at":"2014-10-20T13:53:30Z","updated_at":"2014-12-12T09:20:58Z","pushed_at":"2014-12-12T09:20:57Z","git_url":"git://github.com/directembedding/directembedding.git","ssh_url":"git@github.com:directembedding/directembedding.git","clone_url":"https://github.com/directembedding/directembedding.git","svn_url":"https://github.com/directembedding/directembedding","homepage":null,"size":203,"stargazers_count":0,"watchers_count":0,"language":"Scala","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":2,"mirror_url":null,"open_issues_count":7,"forks":2,"open_issues":7,"watchers":0,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/directembedding/directembedding/pulls/17"},"html":{"href":"https://github.com/directembedding/directembedding/pull/17"},"issue":{"href":"https://api.github.com/repos/directembedding/directembedding/issues/17"},"comments":{"href":"https://api.github.com/repos/directembedding/directembedding/issues/17/comments"},"review_comments":{"href":"https://api.github.com/repos/directembedding/directembedding/pulls/17/comments"},"review_comment":{"href":"https://api.github.com/repos/directembedding/directembedding/pulls/comments/{number}"},"commits":{"href":"https://api.github.com/repos/directembedding/directembedding/pulls/17/commits"},"statuses":{"href":"https://api.github.com/repos/directembedding/directembedding/statuses/53396da6a2e3ae08022477a1d7650146eb1f118c"}}}}