Re: IF (NOT) EXISTS in psql-completion

At Thu, 29 Sep 2016 16:16:00 +0900 (Tokyo Standard Time), Kyotaro HORIGUCHI <horiguchi(dot)kyotaro(at)lab(dot)ntt(dot)co(dot)jp> wrote in <20160929(dot)161600(dot)224338668(dot)horiguchi(dot)kyotaro(at)lab(dot)ntt(dot)co(dot)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 matches
the 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 query string 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 decided
according 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