README.md in grumlin-0.11.0 vs README.md in grumlin-0.12.0
- old
+ new
@@ -1,13 +1,33 @@
# Grumlin
-[Gremlin](https://tinkerpop.apache.org/gremlin.html) query language DSL for Ruby
+[](https://github.com/zhulik/grumlin/actions/workflows/main.yml)
+[](https://github.com/RichardLitt/standard-readme)
+[](https://lbesson.mit-license.org/)
-**In development. Nothing to write here yet. If you are really interested, check out the source code and the specs.**
+Grumlin is a [Gremlin](https://tinkerpop.apache.org/gremlin.html) graph traversal language DSL and client for Ruby.
+Suitable for and tested with [gremlin-server](http://tinkerpop.apache.org/) and [AWS Neptune](https://aws.amazon.com/neptune/).
-## Installation
+**Important**: Grumlin and it's author are not affiliated with The Apache Software Foundation which develops gremlin
+and gremlin-server.
+**Important**: Grumlin is based on the [async stack](https://github.com/socketry/async) and utilizes
+[async-websocket](https://github.com/socketry/async-websocket). Code using grumlin must be executed in an async
+event loop.
+
+**Warning:** Grumlin is in development, but ready for simple use cases
+
+## Table of contents
+- [Install](#install)
+- [Usage](#usage)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+- [Code Of Conduct](#code-of-conduct)
+
+## Install
+
Add this line to your application's Gemfile:
```ruby
gem 'grumlin'
```
@@ -20,20 +40,80 @@
$ gem install grumlin
## Usage
-TODO: Write usage instructions here
+### Configuration
+```ruby
+Grumlin.configure do |config|
+ config.url = "ws://localhost:8182/gremlin"
+end
+```
+### Traversing graphs
+
+**Warning:** Not all steps and tools described in the standard are supported
+
+#### Sugar
+
+Grumlin provides an easy to use module called `Grumlin::Sugar`. Once included in your class it injects some useful
+constants and methods turning your class into an entrypoint for traversals.
+
+```ruby
+class MyRepository
+ include Grumlin::Sugar
+
+ def nodes(property1:, property2:)
+ g.V()
+ .has(T.label, "node")
+ .has(:property1, property1)
+ .has(:property2, property2)
+ .order.by(:property3, Order.asc).limit(10)
+ .toList
+ end
+end
+```
+
+#### Testing
+
+Grumlin provides a couple of helpers to simplify testing code written with it.
+
+##### RSpec
+
+Make sure you have [async-rspec](https://github.com/socketry/async-rspec) installed.
+
+`spec_helper.rb` or `rails_helper.rb`:
+```ruby
+require 'async/rspec'
+require require "grumlin/test/rspec"
+...
+config.include_context(Async::RSpec::Reactor) # Runs async reactor
+config.include_context(Grumlin::Test::RSpec::GremlinContext) # Injects sugar and makes sure client is closed after every test
+config.include_context(Grumlin::Test::RSpec::DBCleanerContext) # Cleans the database before every test
+...
+```
+
+It is highly recommended to use `Grumlin::Sugar` and not trying to use lower level APIs as they are subject to change.
+
## Development
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+Before running tests make sure you have gremlin-server running on your computer. The simplest way to run it is using
+[docker-compose](https://docs.docker.com/compose/) and provided `docker-compose.yml` and `gremlin_server/Dockerfile`:
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+ $ docker-compose up -d gremlin_server
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update
+the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version,
+push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
## Contributing
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/grumlin. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/grumlin/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/zhulik/grumlin. This project is intended to
+be a safe, welcoming space for collaboration, and contributors are expected to adhere to the
+[code of conduct](https://github.com/zhulik/grumlin/blob/master/CODE_OF_CONDUCT.md).
## License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).