Skip to content

Commit

Permalink
Improved javadoc comments
Browse files Browse the repository at this point in the history
  • Loading branch information
@mattirn
mattirn committed Feb 4, 2020
1 parent 31b3ea1 commit cea2ea9
Show file tree
Hide file tree
Showing 3 changed files with 68 additions and 63 deletions.
37 changes: 19 additions & 18 deletions builtins/src/main/java/org/jline/builtins/CommandRegistry.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ public interface CommandRegistry {

/**
* Aggregate SystemCompleters of commandRegisteries
* @param commandRegistries command registeries which completers is to be aggregated
* @return uncompiled SystemCompleter
*/
static Completers.SystemCompleter aggregateCompleters(CommandRegistry ... commandRegistries) {
Expand All @@ -41,6 +42,7 @@ static Completers.SystemCompleter aggregateCompleters(CommandRegistry ... comman

/**
* Aggregate and compile SystemCompleters of commandRegisteries
* @param commandRegistries command registeries which completers is to be aggregated and compile
* @return compiled SystemCompleter
*/
static Completers.SystemCompleter compileCompleters(CommandRegistry ... commandRegistries) {
Expand All @@ -51,7 +53,7 @@ static Completers.SystemCompleter compileCompleters(CommandRegistry ... commandR

/**
* Returns the name of this registry.
* @return name
* @return the name of the registry
*/
default String name() {
return this.getClass().getSimpleName();
Expand Down Expand Up @@ -93,7 +95,6 @@ default List<String> commandInfo(String command) {
/**
* Returns a {@code SystemCompleter} that can provide detailed completion
* information for all registered commands.
*
* @return a SystemCompleter that can provide command completion for all registered commands
*/
Completers.SystemCompleter compileCompleters();
Expand All @@ -118,11 +119,11 @@ default Widgets.CmdDesc commandDescription(String command) {
/**
* Execute a command that have only string parameters and options. Implementation of the method is required
* when aggregating command registries using SystemRegistry.
* @param session
* @param command
* @param args
* @return result
* @throws Exception
* @param session the data of the current command session
* @param command the name of the command
* @param args arguments of the command
* @return result of the command execution
* @throws Exception in case of error
*/
default Object execute(CommandSession session, String command, String[] args) throws Exception {
throw new IllegalArgumentException("CommandRegistry method execute(String command, String[] args) is not implemented!");
Expand All @@ -131,11 +132,11 @@ default Object execute(CommandSession session, String command, String[] args) th
/**
* Execute a command. If command has other than string parameters a custom implementation is required.
* This method will be called only when we have ConsoleEngine in SystemRegistry.
* @param session
* @param command
* @param args
* @return result
* @throws Exception
* @param session the data of the current command session
* @param command the name of the command
* @param args arguments of the command
* @return result of the command execution
* @throws Exception in case of error
*/
default Object invoke(CommandSession session, String command, Object... args) throws Exception {
String[] _args = new String[args.length];
Expand All @@ -147,13 +148,13 @@ default Object invoke(CommandSession session, String command, Object... args) th
}
return execute(session, command, _args);
}

public static class CommandSession {
private final Terminal terminal;
private final InputStream in;
private final PrintStream out;
private final PrintStream err;

public CommandSession() {
this.in = System.in;
this.out = System.out;
Expand All @@ -164,22 +165,22 @@ public CommandSession() {
public CommandSession(Terminal terminal) {
this(terminal, terminal.input(), new PrintStream(terminal.output()), new PrintStream(terminal.output()));
}

public CommandSession(Terminal terminal, InputStream in, PrintStream out, PrintStream err) {
this.terminal = terminal;
this.in = in;
this.out = out;
this.err = err;
}

public Terminal terminal() {
return terminal;
}

public InputStream in() {
return in;
}

public PrintStream out() {
return out;
}
Expand Down
49 changes: 27 additions & 22 deletions builtins/src/main/java/org/jline/builtins/ConsoleEngine.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,9 +26,9 @@
public interface ConsoleEngine extends CommandRegistry {

/**
* Removes command first character if it is colon
* @param command name to complete
* @return command name without colon
* Removes the command name first character if it is colon
* @param command the name of the command to complete
* @return command name without starting colon
*/
static String plainCommand(String command) {
return command.startsWith(":") ? command.substring(1) : command;
Expand All @@ -42,63 +42,63 @@ static String plainCommand(String command) {

/**
* Sets systemRegistry
* @param systemRegistry
* @param systemRegistry SystemRegistry
*/
void setSystemRegistry(SystemRegistry systemRegistry);

/**
* Substituting args references with their values.
* @param args
* @return Substituted args
* @param args the arguments to be expanded
* @return expanded arguments
* @throws Exception in case of error
*/
Object[] expandParameters(String[] args) throws Exception;

/**
* Returns all scripts found from PATH
* @return script names
* @return script file names
*/
List<String> scripts();

/**
* Sets file name extension used by console scripts
* @param console script file extension
* @param extension console script file extension
*/
public void setScriptExtension(String extension);

/**
* Returns true if alias 'name' exists
* @param alias name
* @param name alias name
* @return true if alias exists
*/
boolean hasAlias(String name);

/**
* Returns alias 'name' value
* @param alias name
* @param name alias name
* @return value of alias
*/
String getAlias(String name);

/**
* Returns script and variable completers
* @return script completers
* @return script and variable completers
*/
List<Completer> scriptCompleters();

/**
* Executes parsed line that does not contain known command by the system registry.
* If parsed line is neither JLine or ScriptEngine script it will be evaluated
* as ScriptEngine statement.
* @param parsed command line
* @param parsedLine parsed command line
* @return command line execution result
* @throws Exception in case of error
*/
Object execute(ParsedLine parsedLine) throws Exception;

/**
* Executes either JLine or ScriptEngine script.
* @param script file
* @param script script file
* @return script execution result
* @throws Exception in case of error
*/
Expand All @@ -108,9 +108,9 @@ default Object execute(File script) throws Exception {

/**
* Executes either JLine or ScriptEngine script.
* @param script file
* @param script script file
* @param cmdLine complete command line
* @param script arguments
* @param args script arguments
* @return script execution result
* @throws Exception in case of error
*/
Expand All @@ -119,28 +119,29 @@ default Object execute(File script) throws Exception {
/**
* Post processes execution result. If result is to be assigned to the console variable
* then method will return null.
* @param command line
* @param result to process
* @param line command line
* @param result command result to process
* @param output command redirected output
* @return processed result
*/
Object postProcess(String line, Object result, String output);

/**
* Displays object.
* @param object to print
* @param object object to print
*/
void println(Object object);

/**
* Displays object.
* @param options println options
* @param object to print
* @param object object to print
*/
void println(Map<String, Object> options, Object object);

/**
* Get variable value
* @param name of variable
* @param name name of the variable
* @return variable value
*/
Object getVariable(String name);
Expand All @@ -152,8 +153,12 @@ default Object execute(File script) throws Exception {
*/
boolean executeWidget(Object function);

/**
*
* @return true if consoleEngine is executing script
*/
boolean isExecuting();

static class WidgetCreator implements Widget {
private ConsoleEngine consoleEngine;
private Object function;
Expand All @@ -169,7 +174,7 @@ public WidgetCreator(ConsoleEngine consoleEngine, String function) {
public boolean apply() {
return consoleEngine.executeWidget(function);
}

@Override
public String toString() {
return name;
Expand Down
45 changes: 22 additions & 23 deletions builtins/src/main/java/org/jline/builtins/SystemRegistry.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,6 @@
import java.util.Map;

import org.jline.reader.Completer;
import org.jline.reader.ParsedLine;
import org.jline.terminal.Terminal;
import org.jline.utils.AttributedStringBuilder;
import org.jline.utils.AttributedStyle;
Expand All @@ -27,13 +26,13 @@ public interface SystemRegistry extends CommandRegistry {

/**
* Set command registeries
* @param commandRegistries defined in app
* @param commandRegistries command registeries used by the application
*/
void setCommandRegistries(CommandRegistry... commandRegistries);

/**
* Initialize consoleEngine environment by executing console script
* @param initialization script
* @param script initialization script
*/
void initialize(File script);

Expand All @@ -45,49 +44,49 @@ public interface SystemRegistry extends CommandRegistry {

/**
* Returns a command, method or syntax description for use in the JLine Widgets framework.
* @param command line whose description to return
* @param line command line whose description to return
* @return command description for JLine TailTipWidgets to be displayed
* in the terminal status bar.
*/
Widgets.CmdDesc commandDescription(Widgets.CmdLine line);

/**
* Execute a command, script or evaluate scriptEngine statement
* @param command line
* @param line command line to be executed
* @return execution result
* @throws Exception
* @throws Exception in case of error
*/
Object execute(String line) throws Exception;

/**
*
*
* @return terminal
*/
Terminal terminal();

/**
* Execute command with args
* @param command to execute
* @param args command arguments
* @return execution result
* Execute command with arguments
* @param command command to be executed
* @param args arguments of the command
* @return command execution result
* @throws Exception in case of error
*/
Object execute(String command, String[] args) throws Exception;

/**
* Execute command with args
* @param command to execute
* @param args command arguments
* @return execution result
* Execute command with arguments
* @param command command to be executed
* @param args arguments of the command
* @return command execution result
* @throws Exception in case of error
*/
Object invoke(String command, Object... args) throws Exception;

/**
* Print exception
* @param print stack trace if stack true otherwise message
* @param JLine terminal
* @param exception to print
* Print exception
* @param stack print stack trace if stack true otherwise message
* @param terminal JLine terminal
* @param exception exception to be printed
*/
static void println(boolean stack, Terminal terminal, Exception exception) {
if (exception instanceof Options.HelpException) {
Expand All @@ -104,7 +103,7 @@ static void println(boolean stack, Terminal terminal, Exception exception) {
asb.append(exception.getClass().getCanonicalName(), AttributedStyle.DEFAULT.foreground(AttributedStyle.RED));
}
asb.toAttributedString().println(terminal);
}
}
}

/**
Expand Down

0 comments on commit cea2ea9

Please sign in to comment.