Merge pull request #129 from j-bennet/master

Documentation and an addition to smart completion for ON keyword.

DEVELOP.rst

@@ -38,9 +38,14 @@ It is highly recommended to use virtualenv for development. If you don't know
 what a virtualenv is, this `guide <http://docs.python-guide.org/en/latest/dev/virtualenvs/#virtual-environments>`_
 will help you get started.
 
-Create a virtualenv (let's call it pgcli-dev). Once the virtualenv is activated
-`cd` into the local clone of pgcli folder and install pgcli using pip as
-follows:
+Create a virtualenv (let's call it pgcli-dev). Activate it:
+
+::
+
+    source ./pgcli-dev/bin/activate
+
+Once the virtualenv is activated, `cd` into the local clone of pgcli folder
+and install pgcli using pip as follows:
 
 ::
 
@@ -56,3 +61,26 @@ we've linked the pgcli installation with the working copy. So any changes made
 to the code is immediately available in the installed version of pgcli. This
 makes it easy to change something in the code, launch pgcli and check the
 effects of your change. 
+
+Adding PostgreSQL Special (Meta) Commands
+-----------------------------------------
+
+If you want to work on adding new meta-commands (such as `\dp`, `\ds`, `dy`),
+you'll be changing the code of `packages/pgspecial.py`. Search for the
+dictionary called `CASE_SENSITIVE_COMMANDS`. The special command us used as
+the dictionary key, and the value is a tuple.
+
+The first item in the tuple is either a string (sql statement) or a function.
+The second item in the tuple is a list of strings which is the documentation
+for that special command. The list will have two items, the first item is the
+command itself with possible options and the second item is the plain english
+description of that command.
+
+For example, `\l` is a meta-command that lists all the databases. The way you
+can see the SQL statement issued by PostgreSQL when this command is executed
+is to launch `psql -E` and entering `\l`.
+
+That will print the results and also print the sql statement that was executed
+to produce that result. In most cases it's a single sql statement, but sometimes
+it's a series of sql statements that feed the results to each other to get to
+the final result.

TODO

@@ -6,7 +6,7 @@
 * [ ] Refactor to sqlcompletion to consume the text from left to right and use a state machine to suggest cols or tables instead of relying on hacks.
 * [ ] Add a few more special commands. (\l pattern, \dp, \ds, \dy, \z etc)
 * [ ] Refactor pgspecial.py to a class. 
-* [ ] Write a doc about how to add new pgspecial commands.(psql -E)
+* [X] Write a doc about how to add new pgspecial commands.(psql -E)
 * [ ] Show/hide docs for a statement using a keybinding.
 * [ ] Check how to add the name of the table before printing the table.
 * [ ] Add a new trigger for M-/ that does naive completion.

pgcli/packages/sqlcompletion.py

@@ -81,7 +81,7 @@ def suggest_based_on_last_token(token, text_before_cursor, full_text):
         return 'tables', []
     elif token_v.lower() in ('c', 'use'):  # \c
         return 'databases', []
-    elif token_v.endswith(','):
+    elif token_v.endswith(',') or token_v == '=':
         prev_keyword = find_prev_keyword(text_before_cursor)
         if prev_keyword:
             return suggest_based_on_last_token(prev_keyword, text_before_cursor, full_text)

tests/test_smart_completion.py

@@ -197,6 +197,16 @@ def test_suggested_aliases_after_on(completer, complete_event):
         Completion(text='u', start_position=0),
         Completion(text='o', start_position=0)])
 
+def test_suggested_aliases_after_on_right_side(completer, complete_event):
+    text = 'SELECT u.name, o.id FROM users u JOIN orders o ON o.user_id = '
+    position = len('SELECT u.name, o.id FROM users u JOIN orders o ON o.user_id = ')
+    result = set(completer.get_completions(
+        Document(text=text, cursor_position=position),
+        complete_event))
+    assert set(result) == set([
+        Completion(text='u', start_position=0),
+        Completion(text='o', start_position=0)])
+
 def test_suggested_tables_after_on(completer, complete_event):
     text = 'SELECT users.name, orders.id FROM users JOIN orders ON '
     position = len('SELECT users.name, orders.id FROM users JOIN orders ON ')
@@ -207,6 +217,16 @@ def test_suggested_tables_after_on(completer, complete_event):
         Completion(text='users', start_position=0),
         Completion(text='orders', start_position=0)])
 
+def test_suggested_tables_after_on_right_side(completer, complete_event):
+    text = 'SELECT users.name, orders.id FROM users JOIN orders ON orders.user_id = '
+    position = len('SELECT users.name, orders.id FROM users JOIN orders ON orders.user_id = ')
+    result = set(completer.get_completions(
+        Document(text=text, cursor_position=position),
+        complete_event))
+    assert set(result) == set([
+        Completion(text='users', start_position=0),
+        Completion(text='orders', start_position=0)])
+
 def test_table_names_after_from(completer, complete_event):
     text = 'SELECT * FROM '
     position = len('SELECT * FROM ')

tests/test_sqlcompletion.py

@@ -127,3 +127,17 @@ def test_on_suggests_tables():
         'select abc.x, bcd.y from abc join bcd on ')
     assert category == 'tables-or-aliases'
     assert set(scope) == set(['abc', 'bcd'])
+
+def test_on_suggests_aliases_right_side():
+    category, scope = suggest_type(
+        'select a.x, b.y from abc a join bcd b on a.id = ',
+        'select a.x, b.y from abc a join bcd b on a.id = ')
+    assert category == 'tables-or-aliases'
+    assert set(scope) == set(['a', 'b'])
+
+def test_on_suggests_tables_right_side():
+    category, scope = suggest_type(
+        'select abc.x, bcd.y from abc join bcd on ',
+        'select abc.x, bcd.y from abc join bcd on ')
+    assert category == 'tables-or-aliases'
+    assert set(scope) == set(['abc', 'bcd'])