At Thu, 29 Sep 2016 16:16:00 +0900 (Tokyo Standard Time), Kyotaro HORIGUCHI 
<> wrote in 
> That looks better. I'll change the API as the following.
> COMPLETE_WITH_QUERY_KW(query, kwlist);

Done on my environment.

> > >> 4. Introduce word shift and removal feature to psql-completion
> > >>
> > >>   This is the second core for the flexibility of completion code.
> > >>   The word shift feature is the ability to omit first several
> > >>   words in *MatchesN macros. For example this allows complete
> > >>   create-schema's schema elements in a natural code. (Currently
> > >>   those syntaxes that can be a schema elements are using
> > >>   TailMatches instead of Matches, as the result HeadMatches are
> > >>   not available there). The words removing feature is the ability
> > >>   to (desructively) clip multiple suceessive words in the
> > >>   previous_words list. This feature allows suceeding completion
> > >>   code not to care about the removed words, such like UNIQUE,
> > >>   CONCURRENTLY, VERBOSE and so on.
> > >>
> > >
> > I am thinking so commit's description should be inside README
> Currently psql or tab-complete.c/psql_completion() have no such
> document. If this should be written as README, perhaps I should
> write about completion in general. On the other hand, per-macro
> explanations are written in tab-complete-macros.h but the usages
> are not. I'll try to write README.

Before proposing new patch including this. Since I'm totally
inconfident for my capability to write a documentation, I'd like
to ask anyone here of what shape we are to aim..

The following is the first part of the document I have written up
to now. Please help me by giving me any corrections, suggestions,
opinions, or anything else!

# The completion macro part would be better to be moved as
# comments for the macros in tab-complete-macros.h.


Word completion of interactive psql

psql supports word completion on interactive input. The core function
of the feature is psql_completion_internal in tab-complete.c. A bunch
of macros are provided in order to make it easier to read and maintain
the completion code. The console input to refer is stored in char **
previous_words in reverse order but maintaiers of
psql_completion_internal don't need to be aware of the detail of
it. Most of the operation can be described using the provided macros.

Basic structure of the completion code

The main part of the function is just a series of completion
definitions, where the first match wins. Each definition basically is
in the following shape.

   if (*matching expression*)
      *corresponding completion, then return*

The matching expression checks against all input words before the word
currently being entered. Completion chooses the words prefixed by
letters already entered. For example, for "CREATE <tab>" the word list
to be matched is ["CREATE"] and the prefix for completion is
nothing. For "CREATE INDEX id", the list is ["CREATE", "INDEX"] and
the prefix is "id".

Matching expression macros
There are four types of matching expression macros.

- MatchesN(word1, word2 .. , wordN)

 true iff the word list is exactly the same as the paremeter.

- HeadMatchesN(word1, word2 .., wordN)

 true iff the first N words in the word list matches the parameter.

- TailMatchesN(word1, word2 .., wordN)

 true iff the last N words in the word list matches the parameter.

- MidMatchesN(pos, word1, word2 .., wordN)

 true iff N successive words starts from pos in the word list matches
 the parameter. The position is 1-based.

Completion macros
There are N types of completion macros.


  Suggest completion words acquired using the given query. The details
  of the query is seen in the comment for _complete_from_query(). Word
  matching is case-sensitive.

  The latter takes an additional parameter, which should be a fragment
  of query starts with " UNION " followed by a query string which
  gives some additional words. This addon can be ADDLISTN() macro for
  case-sensitive suggestion.


  Suggest based on a "schema query", which is a struct containing
  parameters. You will see the details in the comment for
  _complete_from_query(). Word maching is case-sensitive.

  Just same as COMPLETE_WITH_QUERY_KW, the latter form takes a
  fragment query same to that for COMPLETE_WITH_QUERY_KW.


  Suggest completion words given as an array of strings. Word matching
  is case-sensitive.




  Same as COMPLETE_WITH_LIST_CS except that word matching is
  case-insensitive and the letter case of suggestions is decided
  according to COMP_KEYWORD_CASE.


  Shortcut for COMPLETE_WITH_LIST.


  Same as COMPLETE_WITH_LIST but with just one suggestion.

- COMPLETE_WITH_ATTR(relation, addon)

  Suggest completion attribute names for the given relation. Word
  matching is case-sensitve.

  Suggest function name for the given SQL function. Word matching is

Additional keywords for COMPLETE_WITH(_SCHEMA)_QUERY

(snip, or done till here..)


Kyotaro Horiguchi
NTT Open Source Software Center

Sent via pgsql-hackers mailing list (
To make changes to your subscription:

Reply via email to