Merge branch 'master' of github.com:/antirez/redis-doc

README.md

@@ -1,84 +1,123 @@
-Redis documentation
-===
+# Redis documentation
 
+## Clients
 
-Clients
----
+All clients are listed in the `clients.json` file.
+Each key in the JSON object represents a single client library.
+For example:
 
-All clients are listed in the `clients.json` file. Each key in the JSON
-object represents a single client library. For example:
+```
+"Rediska": {
 
-    "Rediska": {
+  # A programming language should be specified.
+  "language": "PHP",
 
-      # A programming language should be specified.
-      "language": "PHP",
+  # If the project has a website of its own, put it here.
+  # Otherwise, lose the "url" key.
+  "url": "http://rediska.geometria-lab.net",
 
-      # If the project has a website of its own, put it here.
-      # Otherwise, lose the "url" key.
-      "url": "http://rediska.geometria-lab.net",
+  # A URL pointing to the repository where users can
+  # find the code.
+  "repository": "http://github.com/Shumkov/Rediska",
 
-      # A URL pointing to the repository where users can
-      # find the code.
-      "repository": "http://github.com/Shumkov/Rediska",
+  # A short, free-text description of the client.
+  # Should be objective. The goal is to help users
+  # choose the correct client they need.
+  "description": "A PHP client",
 
-      # A short, free-text description of the client.
-      # Should be objective. The goal is to help users
-      # choose the correct client they need.
-      "description": "A PHP client",
+  # An array of Twitter usernames for the authors
+  # and maintainers of the library.
+  "authors": ["shumkov"]
 
-      # An array of Twitter usernames for the authors
-      # and maintainers of the library.
-      "authors": ["shumkov"]
+}
+```
 
-    }
-
-
-Commands
----
+## Commands
 
 Redis commands are described in the `commands.json` file.
 
 For each command there's a Markdown file with a complete, human-readable
-description. We process this Markdown to provide a better experience, so
-some things to take into account:
+description.
+We process this Markdown to provide a better experience, so some things to take
+into account:
+
+*   Inside text, all commands should be written in all caps, in between
+    backticks.
+    For example: `INCR`.
+
+*   You can use some magic keywords to name common elements in Redis.
+    For example: `@multi-bulk-reply`.
+    These keywords will get expanded and auto-linked to relevant parts of the
+    documentation.
+
+There should be at least two predefined sections: description and return value.
+The return value section is marked using the @return keyword:
+
+```
+Returns all keys matching the given pattern.
+
+@return
+
+@multi-bulk-reply: all the keys that matched the pattern.
+```
+
+## Styling guidelines
+
+Please use the following formatting rules:
+
+* Wrap lines to 80 characters.
+* Start every sentence on a new line.
+
+Luckily, this repository comes with an automated Markdown formatter.
+To only reformat the files you have modified, first stage them using `git add`
+(this makes sure that your changes won't be lost in case of an error), then run
+the formatter:
 
-* Inside text, all commands should be written in all caps, in between
-backticks. For example: <code>`INCR`</code>.
+```
+$ rake format:cached
+```
 
-* You can use some magic keywords to name common elements in Redis. For
-example: `@multi-bulk-reply`. These keywords will get expanded and
-auto-linked to relevant parts of the documentation.
+The formatter has the following dependencies:
 
-There should be at least two predefined sections: description and
-return value. The return value section is marked using the @return
-keyword:
+* Redcarpet
+* Nokogiri
+* The `par` tool
 
-    Returns all keys matching the given pattern.
+Installation of the Ruby gems:
 
-    @return
+```
+gem install redcarpet nokogiri
+```
 
-    @multi-bulk-reply: all the keys that matched the pattern.
+Installation of par (OSX):
 
+```
+brew install par
+```
 
-Styling guidelines
----
+Installation of par (Ubuntu):
 
-Please wrap your text to 80 characters. You can easily accomplish this
-using a CLI tool called `par`.
+```
+sudo apt-get install par
+```
 
+## Checking your work
 
-Checking your work
----
+Once you're done, the very least you should do is make sure that all files
+compile properly.
+You can do this by running Rake inside your working directory.
 
-Once you're done, the very least you should do is make sure that all
-files compile properly. You can do this by running Rake inside your
-working directory.
+```
+$ rake parse
+```
 
-    $ rake parse
+Additionally, if you have [Aspell][han] installed, you can spell check the
+documentation:
 
-Additionally, if you have [Aspell](http://aspell.net/) installed, you
-can spell check the documentation:
+[han]: http://aspell.net/
 
-    $ rake spellcheck
+```
+$ rake spellcheck
+```
 
 Exceptions can be added to `./wordlist`.

Rakefile

@@ -39,3 +39,44 @@ task :spellcheck do
     puts "#{file}: #{words.uniq.sort.join(" ")}" if words.any?
   end
 end
+
+namespace :format do
+
+  require "./remarkdown"
+
+  def format(file)
+    return unless File.exist?(file)
+
+    STDOUT.print "formatting #{file}..."
+    STDOUT.flush
+
+    body = File.read(file)
+    body = ReMarkdown.new(body).to_s
+    body = body.gsub(/^\s+$/, "")
+
+    File.open(file, "w") do |f|
+      f.print body
+    end
+
+    STDOUT.puts
+  end
+
+  desc "Reformat single file"
+  task :file, :path do |t, args|
+    format(args[:path])
+  end
+
+  desc "Reformat changes staged for commit"
+  task :cached do
+    `git diff --cached --name-only -- commands/`.split.each do |path|
+      format(path)
+    end
+  end
+
+  desc "Reformat everything"
+  task :all do
+    Dir["commands/*.md"].each do |path|
+      format(path)
+    end
+  end
+end

commands.json

@@ -233,7 +233,7 @@
     "group": "transactions"
   },
   "DUMP": {
-    "summary": "Return a serialized verison of the value stored at the specified key.",
+    "summary": "Return a serialized version of the value stored at the specified key.",
     "complexity": "O(1) to access the key and additional O(N*M) to serialized it, where N is the number of Redis objects composing the value and M their average size. For small string values the time complexity is thus O(1)+O(1*M) where M is small, so simply O(1).",
     "arguments": [
       {
@@ -257,7 +257,7 @@
   },
   "EVAL": {
     "summary": "Execute a Lua script server side",
-    "complexity": "Looking up the script both with EVAL or EVALSHA is an O(1) business. The additional complexity is up to the script you execute.",
+    "complexity": "Depends on the script that is executed.",
     "arguments": [
       {
         "name": "script",
@@ -281,6 +281,32 @@
     "since": "2.6.0",
     "group": "scripting"
   },
+  "EVALSHA": {
+    "summary": "Execute a Lua script server side",
+    "complexity": "Depends on the script that is executed.",
+    "arguments": [
+      {
+        "name": "sha1",
+        "type": "string"
+      },
+      {
+        "name": "numkeys",
+        "type": "integer"
+      },
+      {
+        "name": "key",
+        "type": "key",
+        "multiple": true
+      },
+      {
+        "name": "arg",
+        "type": "string",
+        "multiple": true
+      }
+    ],
+    "since": "2.6.0",
+    "group": "scripting"
+  },
   "EXEC": {
     "summary": "Execute all commands issued after MULTI",
     "since": "1.2.0",

commands/append.md

@@ -1,43 +1,56 @@
-If `key` already exists and is a string, this command appends the `value` at
-the end of the string.  If `key` does not exist it is created and set as an
-empty string, so `APPEND` will be similar to `SET` in this special case.
+If `key` already exists and is a string, this command appends the `value` at the
+end of the string.
+If `key` does not exist it is created and set as an empty string, so `APPEND`
+will be similar to `SET` in this special case.
 
 @return
 
 @integer-reply: the length of the string after the append operation.
 
 @examples
 
-    @cli
-    EXISTS mykey
-    APPEND mykey "Hello"
-    APPEND mykey " World"
-    GET mykey
+```cli
+EXISTS mykey
+APPEND mykey "Hello"
+APPEND mykey " World"
+GET mykey
+```
 
-Pattern: Time series
----
+## Pattern: Time series
 
-the `APPEND` command can be used to create a very compact representation of
-a list of fixed-size samples, usually referred as *time series*.
+the `APPEND` command can be used to create a very compact representation of a
+list of fixed-size samples, usually referred as _time series_.
 Every time a new sample arrives we can store it using the command
 
-    APPEND timeseries "fixed-size sample"
+```
+APPEND timeseries "fixed-size sample"
+```
 
-Accessing to individual elements in the time serie is not hard:
+Accessing individual elements in the time series is not hard:
 
 * `STRLEN` can be used in order to obtain the number of samples.
-* `GETRANGE` allows for random access of elements. If our time series have an associated time information we can easily implement a binary search to get range combining `GETRANGE` with the Lua scripting engine available in Redis 2.6.
+* `GETRANGE` allows for random access of elements.
+  If our time series have an associated time information we can easily implement
+  a binary search to get range combining `GETRANGE` with the Lua scripting
+  engine available in Redis 2.6.
 * `SETRANGE` can be used to overwrite an existing time serie.
 
-The limitations of this pattern is that we are forced into an append-only mode of operation, there is no way to cut the time series to a given size easily because Redis currently lacks a command able to trim string objects. However the space efficiency of time series stored in this way is remarkable.
-
-Hint: it is possible to switch to a different key based on the current unix time, in this way it is possible to have just a relatively small amount of samples per key, to avoid dealing with very big keys, and to make this pattern more
-firendly to be distributed across many Redis instances.
-
-An example sampling the temperature of a sensor using fixed-size strings (using a binary format is better in real implementations).
-
-    @cli
-    APPEND ts "0043"
-    APPEND ts "0035"
-    GETRANGE ts 0 3
-    GETRANGE ts 4 7
+The limitations of this pattern is that we are forced into an append-only mode
+of operation, there is no way to cut the time series to a given size easily
+because Redis currently lacks a command able to trim string objects.
+However the space efficiency of time series stored in this way is remarkable.
+
+Hint: it is possible to switch to a different key based on the current Unix
+time, in this way it is possible to have just a relatively small amount of
+samples per key, to avoid dealing with very big keys, and to make this pattern
+more friendly to be distributed across many Redis instances.
+
+An example sampling the temperature of a sensor using fixed-size strings (using
+a binary format is better in real implementations).
+
+```cli
+APPEND ts "0043"
+APPEND ts "0035"
+GETRANGE ts 0 3
+GETRANGE ts 4 7
+```

commands/auth.md

@@ -1,17 +1,16 @@
 Request for authentication in a password protected Redis server.
-Redis can be instructed to require a password before allowing clients
-to execute commands. This is done using the `requirepass` directive in the
-configuration file.
+Redis can be instructed to require a password before allowing clients to execute
+commands.
+This is done using the `requirepass` directive in the configuration file.
 
-If `password` matches the password in the configuration file, the server replies with
-the `OK` status code and starts accepting commands.
+If `password` matches the password in the configuration file, the server replies
+with the `OK` status code and starts accepting commands.
 Otherwise, an error is returned and the clients needs to try a new password.
 
 **Note**: because of the high performance nature of Redis, it is possible to try
-a lot of passwords in parallel in very short time, so make sure to generate
-a strong and very long password so that this attack is infeasible.
+a lot of passwords in parallel in very short time, so make sure to generate a
+strong and very long password so that this attack is infeasible.
 
 @return
 
 @status-reply
-