From b78b81ea15e42c74400e3590f47555ad72739f2a Mon Sep 17 00:00:00 2001 From: Iryna Cherniavska Date: Mon, 19 Jan 2015 15:26:38 -0800 Subject: [PATCH] Added a section about meta-commands to developer documentation. --- DEVELOP.rst | 34 +++++++++++++++++++++++++++++++--- TODO | 2 +- 2 files changed, 32 insertions(+), 4 deletions(-) diff --git a/DEVELOP.rst b/DEVELOP.rst index 42667fd1..2d163a4f 100644 --- a/DEVELOP.rst +++ b/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 `_ 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. \ No newline at end of file diff --git a/TODO b/TODO index fc322cba..af633995 100644 --- a/TODO +++ b/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.