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;