Merge branch 'east825/py3-docstring-formatter'
[idea/community.git] / python / src / com / jetbrains / commandInterface / package-info.java
1 /*
2  * Copyright 2000-2015 JetBrains s.r.o.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17 /**
18  * <h1>Command-line interface</h1>
19  * <h2>What is the purpose of this package?</h2>
20  * <p>
21  *   This package is based on ideas of command-line with command, positional arguments, options and their arguments.
22  *   Initial idea is taken from <a href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html#tag_12_02">POSIX</a>
23  *   and enhanced by <a href="http://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html">GNU</a>.
24  *   It also supported by Python in <a href="https://docs.python.org/2/library/optparse.html">optparse</a> package.
25  *   Command-line is something like
26  *   <pre>my_command positional_argument -s --long-option --another-long-option=arg1 arg2 some_other_arg</pre>
27  *   and this package helps you to parse command lines, highlight errors, display a console-like interface and execute commands.
28  * </p>
29  * <h2>What this package consists of?</h2>
30  * <p>
31  *   This package has 3 subpackages:
32  *   <ol>
33  *     <li>{@link com.jetbrains.commandInterface.command}  contains classes to describe commands, arguments and options.
34  *     It is up to you where to obtain list of available commands, but you should implement {@link com.jetbrains.commandInterface.command.Command}
35  *     first, and create list of it with arguments and options. See package info for more details</li>
36  *     <li>{@link com.jetbrains.commandInterface.commandLine} is language based on
37  *     <a href="http://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html">GNU</a> command line representation.
38  *     It has PSI, so it parses command lines into tree of PsiElements. But this package <strong>is not only for parsing</strong>:
39  *     If you provide list of
40  *     {@link com.jetbrains.commandInterface.command.Command commands} to {@link com.jetbrains.commandInterface.commandLine.psi.CommandLineFile}
41  *      (see {@link com.jetbrains.commandInterface.commandLine.psi.CommandLineFile#setCommandsAndDefaultExecutor(java.util.List, com.jetbrains.commandInterface.command.CommandExecutor)}}), it will inject references
42  *      (to provide autocompletion) and activate inspection to validate options and arguments. </li>
43  *      <li>{@link com.jetbrains.commandInterface.console} displays console-like interface at the bottom of the screen to give user
44  *      ability to wotk with your command-line.</li>
45  *   </ol>
46  * </p>
47  * <h2>How to use this package?</h2>
48  *   <ol>
49  *     <li>Implement {@link com.jetbrains.commandInterface.command.Command}</li>
50  *     <li>Create list of {@link com.jetbrains.commandInterface.command.Command commands}</li>
51  *     <li>Provide it to {@link com.jetbrains.commandInterface.console.CommandLineConsoleApi#createConsole(com.intellij.openapi.module.Module, java.lang.String, java.util.List)}</li>
52  *   </ol>
53  * @author Ilya.Kazakevich
54  */
55 package com.jetbrains.commandInterface;