Re: IF (NOT) EXISTS in psql-completion - Mailing list pgsql-hackers

At Thu, 29 Sep 2016 16:16:00 +0900 (Tokyo Standard Time), Kyotaro HORIGUCHI <horiguchi.kyotaro@lab.ntt.co.jp> wrote in
<20160929.161600.224338668.horiguchi.kyotaro@lab.ntt.co.jp>
> That looks better. I'll change the API as the following.
> 
> COMPLETE_WITH_QUERY(query);
> COMPLETE_WITH_QUERY_KW(query, kwlist);
> COMPLETE_WITH_SCHEMA_QUERY(squery);
> COMPLETE_WITH_SCHEMA_QUERY_KW(squery, 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.

======================
src/bin/psql/README.completion

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 matchesthe parameter. The position is 1-based.


Completion macros
-----------------
There are N types of completion macros.

- COMPLETE_WITH_QUERY(query), COMPLETE_WITH_QUERY_KW(query, addon)
 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
querystring which gives some additional words. This addon can be ADDLISTN() macro for case-sensitive suggestion.
 

- COMPLETE_WITH_SCHEMA_QUERY(squery), COMPLETE_WITH_SCHEMA_QUERY_KW(squery, addon)
 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.

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

- COMPLETE_WITH_LIST_CSN(s1, s2.. ,sN)
 Shortcut for COMPLETE_WITH_LIST_CS.

- COMPLETE_WITH_LIST(list)
 Same as COMPLETE_WITH_LIST_CS except that word matching is case-insensitive and the letter case of suggestions is
decidedaccording to COMP_KEYWORD_CASE.
 

- COMPLETE_WITH_LISTN(s1, s2.. ,sN)
 Shortcut for COMPLETE_WITH_LIST.

- COMPLETE_WITH_CONST(string)
 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. 
- COMPLETE_WITH_FUNCTION_ARG(function)
 Suggest function name for the given SQL function. Word matching is case-sensitve.


Additional keywords for COMPLETE_WITH(_SCHEMA)_QUERY
----------------------------------------------------

(snip, or done till here..)

regards,

-- 
Kyotaro Horiguchi
NTT Open Source Software Center