summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authoraelred <>2017-01-10 16:21:00 (GMT)
committerhdiff <hdiff@hdiff.luite.com>2017-01-10 16:21:00 (GMT)
commit5e4be71d8473c3fedef4f176421eb846742091eb (patch)
tree7ecae704c776baba28fd5665f3d63853aa3e8800
version 0.1.0.00.1.0.0
-rw-r--r--LICENSE202
-rw-r--r--Setup.hs2
-rw-r--r--graql.cabal47
-rw-r--r--src/Graql.hs38
-rw-r--r--src/Graql/Pattern.hs62
-rw-r--r--src/Graql/Property.hs151
-rw-r--r--src/Graql/Query.hs41
-rw-r--r--src/Graql/Shell.hs65
-rw-r--r--src/Graql/Util.hs20
-rw-r--r--test/Example.lhs58
-rw-r--r--test/Main.hs81
11 files changed, 767 insertions, 0 deletions
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..d645695
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,202 @@
+
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright [yyyy] [name of copyright owner]
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
diff --git a/Setup.hs b/Setup.hs
new file mode 100644
index 0000000..9a994af
--- /dev/null
+++ b/Setup.hs
@@ -0,0 +1,2 @@
+import Distribution.Simple
+main = defaultMain
diff --git a/graql.cabal b/graql.cabal
new file mode 100644
index 0000000..bb355f2
--- /dev/null
+++ b/graql.cabal
@@ -0,0 +1,47 @@
+name: graql
+version: 0.1.0.0
+synopsis: Execute Graql queries on a Grakn graph
+description: A library for building and executing Graql queries on a
+ Grakn knowledge graph.
+license: Apache-2.0
+license-file: LICENSE
+homepage: https://github.com/graknlabs/graql-haskell
+author: Felix Chapman
+maintainer: felix@grakn.ai
+category: Database,Graphs
+build-type: Simple
+extra-source-files: test/Example.lhs
+cabal-version: >=1.10
+
+library
+ build-depends: base >= 4.7 && < 5
+ , containers == 0.5.*
+ , process == 1.4.*
+ , aeson == 1.0.*
+ , scientific == 0.3.*
+ , text == 1.2.*
+ , regex-posix == 0.95.*
+ hs-source-dirs: src
+ exposed-modules: Graql
+ , Graql.Shell
+ other-modules: Graql.Util
+ , Graql.Query
+ , Graql.Pattern
+ , Graql.Property
+ default-language: Haskell2010
+
+ default-extensions: OverloadedStrings
+
+test-suite test
+ type: exitcode-stdio-1.0
+ main-is: Main.hs
+ hs-source-dirs: test
+ build-depends: base >= 4.7 && < 5
+ , graql
+ , hspec
+ , text == 1.2.*
+ , markdown-unlit
+ other-modules: Example
+ default-language: Haskell2010
+ ghc-options: -pgmL markdown-unlit
+ default-extensions: OverloadedStrings
diff --git a/src/Graql.hs b/src/Graql.hs
new file mode 100644
index 0000000..d3d750a
--- /dev/null
+++ b/src/Graql.hs
@@ -0,0 +1,38 @@
+module Graql
+ ( MatchQuery
+ , Var
+ , Name
+ , Value (..)
+ , match
+ , select
+ , distinct
+ , limit
+ , var
+ , name
+ , isa
+ , (-:)
+ , (.:)
+ , rp
+ , (<:)
+ , rel
+ , has
+ , hasText
+ , var_
+ ) where
+
+import Graql.Property
+import Graql.Pattern
+import Graql.Query
+import Data.Text (Text)
+
+-- |Specify a property has a particular type
+(-:) :: (IsPattern p, IsVarOrName a) => p -> a -> Pattern
+(-:) = isa
+
+-- |Shorthand to define a relation
+rel :: IsRolePlayer a => [a] -> Pattern
+rel = (var_ <:)
+
+-- |Specify a property has a resource
+hasText :: (IsPattern p) => p -> Name -> Text -> Pattern
+hasText = has
diff --git a/src/Graql/Pattern.hs b/src/Graql/Pattern.hs
new file mode 100644
index 0000000..a1b9d5a
--- /dev/null
+++ b/src/Graql/Pattern.hs
@@ -0,0 +1,62 @@
+module Graql.Pattern
+ ( Pattern
+ , IsPattern
+ , var_
+ , isa
+ , (<:)
+ , has
+ , toPattern
+ ) where
+
+import Graql.Util
+import Graql.Property
+
+-- |A pattern to find in the graph
+data Pattern = Pattern (Maybe VarOrName) [Property]
+
+-- |Represents things that can be patterns
+class IsPattern a where
+ toPattern :: a -> Pattern
+
+-- |Create an anonymous variable
+var_ :: Pattern
+var_ = Pattern Nothing []
+
+-- |Specify a property has a particular type
+isa :: (IsPattern p, IsVarOrName a) => p -> a -> Pattern
+patt `isa` x = addProperty patt (Isa $ toVarOrName x)
+
+-- |Specify a property is a relation between other variables
+(<:) :: (IsPattern p, IsRolePlayer a) => p -> [a] -> Pattern
+patt <: cs = addProperty patt (Rel $ map toRolePlayer cs)
+
+-- |Specify a property has a resource
+has :: (IsPattern p, IsResource a) => p -> Name -> a -> Pattern
+has patt rt v = addProperty patt (Has rt $ toResource v)
+
+
+showProps :: Show a => [a] -> String
+showProps = spaces . reverse
+
+addPropToPattern :: Pattern -> Property -> Pattern
+addPropToPattern (Pattern name props) prop = Pattern name (prop : props)
+
+addProperty :: IsPattern a => a -> Property -> Pattern
+addProperty = addPropToPattern . toPattern
+
+
+instance Show Pattern where
+ show (Pattern v [] ) = v `with` "" ++ ";"
+ show (Pattern v props) = v `with` " " ++ showProps props ++ ";"
+
+instance IsPattern Pattern where
+ toPattern = id
+
+instance IsPattern Var where
+ toPattern = toPattern . toVarOrName
+
+instance IsPattern Name where
+ toPattern = toPattern . toVarOrName
+
+instance IsPattern VarOrName where
+ toPattern v = Pattern (Just v) []
diff --git a/src/Graql/Property.hs b/src/Graql/Property.hs
new file mode 100644
index 0000000..c055d75
--- /dev/null
+++ b/src/Graql/Property.hs
@@ -0,0 +1,151 @@
+module Graql.Property
+ ( Property (..)
+ , Var
+ , Name
+ , VarOrName
+ , Value (..)
+ , IsVarOrName
+ , IsRolePlayer
+ , IsResource
+ , var
+ , name
+ , (.:)
+ , rp
+ , toVarOrName
+ , toRolePlayer
+ , toResource
+ ) where
+
+import Graql.Util
+import Data.Text (Text, unpack)
+import Data.Scientific (Scientific)
+import Text.Regex.Posix ((=~))
+import Control.Applicative (empty)
+import Data.Aeson (FromJSON, FromJSONKey,
+ FromJSONKeyFunction (FromJSONKeyText),
+ parseJSON)
+import qualified Data.Aeson as Aeson
+
+-- |A property of a concept
+data Property = Isa VarOrName
+ | NameProperty Name
+ | Rel [RolePlayer]
+ | Has Name (Either Value Var)
+
+-- |A variable name wildcard that will represent a concept in the results
+data Var = Var Text deriving (Eq, Ord)
+
+-- |A name of something in the graph
+data Name = Name Text
+
+-- |Something that may be a variable name or a type name
+data VarOrName = VarName Var | TypeName Name
+
+-- |A value of a resource
+data Value = ValueString Text | ValueNumber Scientific | ValueBool Bool
+
+-- |A casting, relating a role type and role player
+data RolePlayer = RolePlayer (Maybe VarOrName) Var
+
+-- |Something that can be converted into a variable or a type name
+class IsVarOrName a where
+ toVarOrName :: a -> VarOrName
+
+-- |Something that can be converted into a casting
+class IsRolePlayer a where
+ toRolePlayer :: a -> RolePlayer
+
+-- |Something that can be converted into a resource value or variable
+class IsResource a where
+ toResource :: a -> Either Value Var
+
+-- |Create a variable
+var :: Text -> Var
+var = Var
+
+-- |Create a name of something in the graph
+name :: Text -> Name
+name = Name
+
+-- |A casting in a relation between a role type and a role player
+(.:) :: IsVarOrName a => a -> Var -> RolePlayer
+rt .: player = RolePlayer (Just $ toVarOrName rt) player
+
+-- |A casting in a relation without a role type
+rp :: Var -> RolePlayer
+rp = RolePlayer Nothing
+
+
+nameRegex :: String
+nameRegex = "^[a-zA-Z_][a-zA-Z0-9_-]*$"
+
+instance Show Property where
+ show (Isa varOrName ) = "isa " ++ show varOrName
+ show (NameProperty n) = "type-name " ++ show n
+ show (Rel castings ) = "(" ++ commas castings ++ ")"
+ show (Has rt value ) = "has " ++ show rt ++ " " ++ showEither value
+
+instance Show RolePlayer where
+ show (RolePlayer roletype player) = roletype `with` ": " ++ show player
+
+instance Show Value where
+ show (ValueString text) = show text
+ show (ValueNumber num ) = show num
+ show (ValueBool bool) = show bool
+
+instance Show Name where
+ show (Name text)
+ | str =~ nameRegex = str
+ | otherwise = show text
+ where str = unpack text
+
+instance Show Var where
+ show (Var v) = '$' : unpack v
+
+instance Show VarOrName where
+ show (VarName v) = show v
+ show (TypeName t) = show t
+
+instance IsVarOrName Var where
+ toVarOrName = VarName
+
+instance IsVarOrName Name where
+ toVarOrName = TypeName
+
+instance IsRolePlayer RolePlayer where
+ toRolePlayer = id
+
+instance IsRolePlayer Var where
+ toRolePlayer = rp
+
+instance IsResource Var where
+ toResource = Right
+
+instance IsResource Text where
+ toResource = Left . ValueString
+
+instance IsResource Scientific where
+ toResource = Left . ValueNumber
+
+instance IsResource Bool where
+ toResource = Left . ValueBool
+
+instance FromJSON Value where
+ parseJSON (Aeson.String s) = return $ ValueString s
+ parseJSON (Aeson.Number n) = return $ ValueNumber n
+ parseJSON (Aeson.Bool b) = return $ ValueBool b
+ parseJSON _ = empty
+
+instance FromJSON Name where
+ parseJSON (Aeson.String s) = return $ name s
+ parseJSON _ = empty
+
+instance FromJSON Var where
+ parseJSON (Aeson.String s) = return $ var s
+ parseJSON _ = empty
+
+instance FromJSONKey Var where
+ fromJSONKey = FromJSONKeyText var
+
+showEither :: (Show a, Show b) => Either a b -> String
+showEither = either show show
diff --git a/src/Graql/Query.hs b/src/Graql/Query.hs
new file mode 100644
index 0000000..4c77422
--- /dev/null
+++ b/src/Graql/Query.hs
@@ -0,0 +1,41 @@
+module Graql.Query
+ ( MatchQuery
+ , match
+ , select
+ , limit
+ , distinct
+ ) where
+
+import Graql.Util
+import Graql.Pattern
+import Graql.Property
+
+-- |A Graql 'match' query that finds a pattern in the graph
+data MatchQuery = Match [Pattern]
+ | Select MatchQuery [Var]
+ | Limit MatchQuery Integer
+ | Distinct MatchQuery
+
+-- |Create a match query by providing a list of patterns
+match :: IsPattern a => [a] -> MatchQuery
+match = Match . map toPattern
+
+-- |Select variables from a match query, intended to be used infix
+select :: [Var] -> MatchQuery -> MatchQuery
+select = flip Select
+
+-- |Limit a match query, intended to be used infix
+limit :: Integer -> MatchQuery -> MatchQuery
+limit = flip Limit
+
+-- |Retrieve only distinct results from a match query
+distinct :: MatchQuery -> MatchQuery
+distinct = Distinct
+
+
+instance Show MatchQuery where
+ show (Match patts ) = "match " ++ spaces patts
+ show (Select mq vars) = show mq ++ " select " ++ commas vars ++ ";"
+ show (Limit mq lim ) = show mq ++ " limit " ++ show lim ++ ";"
+ show (Distinct mq ) = show mq ++ " distinct;"
+
diff --git a/src/Graql/Shell.hs b/src/Graql/Shell.hs
new file mode 100644
index 0000000..167e9cd
--- /dev/null
+++ b/src/Graql/Shell.hs
@@ -0,0 +1,65 @@
+module Graql.Shell
+ ( Concept
+ , Result
+ , cid
+ , ctype
+ , value
+ , runFile
+ , runMatch
+ , migrateCsv
+ ) where
+
+import Control.Applicative (empty)
+import Data.Aeson (FromJSON, eitherDecodeStrict, parseJSON,
+ (.:), (.:?))
+import qualified Data.Aeson as Aeson
+import Data.Map (Map)
+import Data.Text (Text, pack)
+import Data.Text.Encoding (encodeUtf8)
+import Graql hiding ((.:))
+import System.Process (callProcess, readProcessWithExitCode)
+
+-- |A concept in the graph
+data Concept = Concept { cid :: Text, cname :: Maybe Name, ctype :: Maybe Name, value :: Maybe Value }
+ deriving Show
+
+-- |A result of a match query, binding variables to concepts
+type Result = Map Var Concept
+
+-- |Run the given file path on the database, ignoring the output
+runFile :: FilePath -> IO ()
+runFile path = callProcess "graql.sh" ["-f", path]
+
+-- |Run a match query on the graph
+runMatch :: MatchQuery -> IO [Result]
+runMatch q = do
+ result <- parseResults <$> runGraql q
+ either fail return result
+
+-- |Run the CSV migrator using the given csv file, template file and separator
+migrateCsv :: FilePath -> FilePath -> String -> IO ()
+migrateCsv file template separator =
+ callProcess "migration.sh" args
+ where args = ["csv", "-i", file, "-t", template, "-s", separator]
+
+
+type Error = String
+
+runGraql :: MatchQuery -> IO String
+runGraql q = do
+ (_, stdout, stderr) <- readProcessWithExitCode "graql.sh" args ""
+ if length (lines stderr) <= 1
+ then return stdout
+ else fail stderr
+ where args = ["-e", show q, "-o", "json"]
+
+parseResults :: String -> Either Error [Result]
+parseResults = mapM parseResult . lines
+
+parseResult :: String -> Either Error Result
+parseResult = eitherDecodeStrict . encodeUtf8 . pack
+
+instance FromJSON Concept where
+ parseJSON (Aeson.Object obj) =
+ Concept <$> (obj .: "id") <*> (obj .:? "name") <*> (obj .:? "isa") <*> (obj .:? "value")
+ parseJSON _ = empty
diff --git a/src/Graql/Util.hs b/src/Graql/Util.hs
new file mode 100644
index 0000000..4f6610a
--- /dev/null
+++ b/src/Graql/Util.hs
@@ -0,0 +1,20 @@
+module Graql.Util
+ ( with
+ , commas
+ , spaces
+ ) where
+
+import Data.List (intercalate)
+
+with :: Show a => Maybe a -> String -> String
+(Just val) `with` suffix = show val ++ suffix
+Nothing `with` _ = ""
+
+commas :: Show a => [a] -> String
+commas = interList ", "
+
+spaces :: Show a => [a] -> String
+spaces = interList " "
+
+interList :: Show a => String -> [a] -> String
+interList sep = intercalate sep . map show
diff --git a/test/Example.lhs b/test/Example.lhs
new file mode 100644
index 0000000..e9ad47e
--- /dev/null
+++ b/test/Example.lhs
@@ -0,0 +1,58 @@
+A simple library for building and executing Graql queries.
+
+Import the modules:
+
+```haskell
+module Example where
+
+import Graql
+import Graql.Shell
+
+import Data.Function ((&))
+```
+
+Define the type names:
+
+```haskell
+person = name "person"
+husband = name "husband"
+wife = name "wife"
+marriage = name "marriage"
+```
+
+Define the variables:
+
+```haskell
+x = var "x"
+y = var "y"
+```
+
+We can translate the following query into Haskell:
+
+```graql
+match $x isa person, (husband: $x, wife: $y) isa marriage; select $y;
+```
+
+```haskell
+query = match
+ [ x `isa` person
+ , rel [husband .: x, wife .: y] `isa` marriage
+ ] & select [y]
+```
+
+We can also use infix functions like `(-:)` instead of `isa`:
+
+```haskell
+otherQuery = match
+ [ x -: person
+ , rel [husband .: x, wife .: y] -: marriage
+ ] & select [y]
+```
+
+To execute and print the results of our query:
+
+```haskell
+main = do
+ result <- runMatch query
+ print result
+```
diff --git a/test/Main.hs b/test/Main.hs
new file mode 100644
index 0000000..2c209d7
--- /dev/null
+++ b/test/Main.hs
@@ -0,0 +1,81 @@
+module Main where
+
+import Data.Function ((&))
+import Test.Hspec
+import Graql
+import qualified Example
+
+main :: IO ()
+main = hspec $ do
+
+ it "a simple query string representation" $
+ match [x `isa` person] ~= "match $x isa person;"
+
+ it "a relation query string representation" $
+ match [rel [x, y]] ~= "match ($x, $y);"
+
+ it "a relation query string representation with types" $
+ match [rel [husband.: x, wife.: y] -: marriage]
+ ~= "match (husband: $x, wife: $y) isa marriage;"
+
+ it "a resource query string representation" $
+ match [x `hasText` firstName $ "Bob"]
+ ~= "match $x has first-name \"Bob\";"
+
+ it "multiple patterns" $
+ match [x-:person, y-:firstName]
+ ~= "match $x isa person; $y isa first-name;"
+
+ it "select query with type" $
+ match [x -: y] & select [x, y]
+ ~= "match $x isa $y; select $x, $y;"
+
+ it "mix role types" $
+ match [rel [husband.: x, rp y]] ~= "match (husband: $x, $y);"
+
+ it "limit and distinct" $
+ match [x -: person] & distinct & limit 10
+ ~= "match $x isa person; distinct; limit 10;"
+
+ it "type of type" $
+ match [person -: x] ~= "match person isa $x;"
+
+ it "reify a relation" $
+ match [x <: [y, z]] ~= "match $x ($y, $z);"
+
+ it "match just a variable" $
+ match [x] ~= "match $x;"
+
+ it "example query output" $
+ Example.query
+ ~= "match $x isa person; (husband: $x, wife: $y) isa marriage; select $y;"
+
+
+x :: Var
+x = var "x"
+
+y :: Var
+y = var "y"
+
+z :: Var
+z = var "z"
+
+person :: Name
+person = name "person"
+
+firstName :: Name
+firstName = name "first-name"
+
+marriage :: Name
+marriage = name "marriage"
+
+husband :: Name
+husband = name "husband"
+
+wife :: Name
+wife = name "wife"
+
+infixr 0 ~=
+
+(~=) :: MatchQuery -> String -> Expectation
+(~=) = shouldBe . show