Recent changes to Home

Home modified by Balázs Vissy

Balázs Vissy — Wed, 14 May 2014 11:32:06 -0000

--- v8
+++ v9
@@ -37,24 +37,7 @@

 [[download_button]]

-To use yacap library in your project, the following steps should be taken:

-  * Download the latest release
-  * Download the dependencies (such as Guava libraries)
-  * Add the jars to your project
+# More info #

-# Future plans #
-
-**Rule based validation support**
-Define your rules over option correlations and restrict the values of your options.
-  * Value set restrictions
-  * Accessibility (required, optional, prohibited) control of correlated options
-  * Overall validity rules
-
-**Multi operation support**
-Use the first command line argument as a selector of function and define individual options sets for each function.
-
-For example: 
-`myprog list `
-`myprog exec `
-
+See [Yacap home](https://code.google.com/p/yacap/)...

Home modified by Balázs Vissy

Balázs Vissy — Wed, 14 May 2014 09:40:12 -0000

--- v7
+++ v8
@@ -31,8 +31,7 @@

 **Needs Java 7 or higher.**

-Guava libraries: [https://code.google.com/p/guava-libraries/]
-
+[Guava libraries](https://code.google.com/p/guava-libraries/)

 # Installation #

Home modified by Balázs Vissy

Balázs Vissy — Wed, 14 May 2014 09:37:22 -0000

--- v6
+++ v7
@@ -31,7 +31,7 @@

 **Needs Java 7 or higher.**

-[https://code.google.com/p/guava-libraries/ Guava]
+Guava libraries: [https://code.google.com/p/guava-libraries/]

 # Installation #

Home modified by Balázs Vissy

Balázs Vissy — Wed, 14 May 2014 09:36:33 -0000

--- v5
+++ v6
@@ -36,16 +36,13 @@

 # Installation #

+[[download_button]]
+
 To use yacap library in your project, the following steps should be taken:

   * Download the latest release
   * Download the dependencies (such as Guava libraries)
   * Add the jars to your project
-
-
-[[download_button]]
-
------

 # Future plans #

Home modified by Balázs Vissy

Balázs Vissy — Wed, 14 May 2014 09:29:10 -0000

--- v4
+++ v5
@@ -45,7 +45,7 @@

 [[download_button]]

-
+-----

 # Future plans #

Home modified by Balázs Vissy

Balázs Vissy — Wed, 14 May 2014 09:25:42 -0000

--- v3
+++ v4
@@ -1,4 +1,3 @@
-
 # Introduction #

 This page introduces the basic usage of yacap.
@@ -43,7 +42,10 @@
   * Download the dependencies (such as Guava libraries)
   * Add the jars to your project

+
 [[download_button]]
+
+

 # Future plans #

Home modified by Balázs Vissy

Balázs Vissy — Wed, 14 May 2014 09:03:09 -0000

--- v2
+++ v3
@@ -1,10 +1,39 @@
-#summary Getting started with yacap

 # Introduction #

 This page introduces the basic usage of yacap.

-[[download_button]]
+[TOC]
+
+# Main features #
+
+##Configuration##
+  * Easy to configure option sets based on builder patterns
+  * Typed options: boolean, string, int, long, double and enum
+  * Dual POSIX short and GNU long parameter names
+  * Support for unnamed (such as file list after options) and internal options (options are unparsed after --)
+
+## Parsing ##
+  * One step parsing
+  * Result set with safe and typed getters
+  * Error messages and warnings returned by result set, so can be handled as you wish
+
+## Text-based help generation ##
+  * Linux-like help structure
+  * Highly configurable, formatted output
+  * Wrapped, justified text in user provided width
+
+# Release history #
+
+0.9 (2014-05-13)
+  * First public release
+
+# Dependencies #
+
+**Needs Java 7 or higher.**
+
+[https://code.google.com/p/guava-libraries/ Guava]
+

 # Installation #

@@ -14,163 +43,20 @@
   * Download the dependencies (such as Guava libraries)
   * Add the jars to your project

-# Understanding command line arguments #
+[[download_button]]

-As far as the parser goes, the command line arguments could be separated into 3 sections:
+# Future plans #

-  * Names options: label-value pairs (or simple labels without values)
-  * Unnamed arguments: Zero, one or more arguments representing a list of input
-  * Possible an internal argument list: they are arguments which have to be passed unparsed (usually they are arguments your program passes to some other, internally called program)
+**Rule based validation support**
+Define your rules over option correlations and restrict the values of your options.
+  * Value set restrictions
+  * Accessibility (required, optional, prohibited) control of correlated options
+  * Overall validity rules

-All three sections are optional.
+**Multi operation support**
+Use the first command line argument as a selector of function and define individual options sets for each function.

-To demonstrate the three sections, look at the following command line:
+For example: 
+`myprog list `
+`myprog exec `

-~~~~
-:::java
-   myapp -abc --max 10 -s sometext file1 file2 -- -x -s othertext
-~~~~
-
-As visible, each option label starts with one or two hyphen(s) and optionally followed by a value. There are two ways to specify arguments:
-
-  * Short (or POSIX) form: the option label starts with a single hyphen (-) and the label is always exactly one character.
-  * Long (or GNU) form: the option label starts with double hyphens (--) and the name is an arbitary long text containing aphanumeric characters or hyphen.
-
-The short form options, when they contain no value, like switches or flags, can be collapsed into one option. (-abc) Other options are supported by value, such as --max or -s.
-
-The named option section ends when the parser first runs into an argument which doesn't start with hyphen. From here, all arguments are regarded as unnamed arguments till the end or till the parse-closing signal of a sole double hyphen (--). So the unnamed arguments here are file1 and file2.
-
-The arguments after the sole double hyphen (--) are regarded as internal and won't be parsed, but will be passed forward the application as is.
-
-
-# Configuring option sets #
-
-To define all possible options of your application you should create an OptionSet.
-
-###Creating option set###
-
-It is simple to create your option set:
-
-~~~~
-:::java 
-   myOptionSet = new OptionSet(); 
-~~~~
-
-and then register your options into.
-
-The options are immutable objects and they should be created through their builders. Each option you register should have a unique long name and if you specify a short for as well, it has to be unique also. 
-
-###Creating a simple option###
-
-For example, let's create a simple flag option with no value, and add it a short form:
-
-~~~~
-:::java 
-   BooleanOption boolOption = new BooleanOption.Builder("bool")
-       .withShortForm('b')
-      .getInstance();
-~~~~
-
-This option will be accessible from command line by either the short form -b or the long form --bool. It will be optional.
-
-###Register an option###
-
-To register the option to your set, use the registerOption function:
-
-
-   myOptionSet.registerOption(boolOption);
-
-
-###The types of the options###
-
-The following option types are provided by yacap:
-
- **Class** |  **Has value**  | **Description** 
- ----------|-----------------|-----------------------------------------------------------
- BooleanOption |  no  | Represents a logical choice, such as flags.  Specifying the option means true, omiting means false. 
- StringOption |  yes  | A common string option. 
- IntegerOption | yes | A 4-byte, signed integer option. Accepts any value that the `Integer.parseInt()` can convert. 
- LongOption | yes | A 8-byte, signed integer option. Accepts any value that the `Long.parseLong()` can convert. 
- DoubleOption | yes | A floating point option. Accepts any value that the `Double.parseDouble()` can convert. 
- EnumOption`<`E`>` | yes | An option of predefined value set. Accepts the values of the associated enum. 
-
-
-###Creating an option with value###
-
-To create an option with parameter you have to do nothing special. The type of the option defines whether it requires a value or not.
-
-The following code will create an optional string option with no short form:
-
-~~~~
-:::java 
-   StringOption stringOption = new StringOption.Builder("str").getInstance();
-~~~~
-
-###Setting option policy###
-
-When it isn't specified otherwise, an option is marked as optional. To change this you can define the policy:
-
-~~~~
-:::java 
-   StringOption stringOption = new StringOption.Builder("str")
-      .withDefaultOptionPolicy(OptionPolicy.REQUIRED)
-     .getInstance();
-~~~~
-
-These are the possible option policies:
-
-**Policy** | **Behaviour** 
-----------|-----------------
-HIDDEN | The option is regarded as a default option always set to its default value. The user can't specify it, the help won't contain it. 
-OPTIONAL| The option is optional. If the user doesn't specify it, the result set will not contain it. This is the default policy. 
-OPTIONAL_AUTO | It is similar to OPTIONAL, but it will always be included in result set with its default value if it was not specified otherwise in command line. *This option policy requires a default value to be set.* 
-REQUIRED | The command line should contain this option. 
-
-###Setting value policy###
-
-Usually an option clearly defines whether it requires a value or not. However, there is sometimes meaningful defaul value for the option and one would like to let the user to omit the value and only specifies the option itself. To achieve it, you can override value policy:
-
-~~~~
-:::java
-   StringOption stringOption = new StringOption.Builder("str")
-       .withValueOptional()
-       .withDefaultValue("defval")
-       .getInstance();
-~~~~
-
-###Setting the default value###
-
-By default, an option has no default value, but you can specify one.
-
-~~~~
-:::java
-   StringOption stringOption = new StringOption.Builder("str")
-       .withDefaultValue("defval")
-       .getInstance();
-~~~~
-
-Default value is used when
-
-  * either the value policy is set to OPTIONAL and the user hasn't specified a value in command line
-  * or if the option policy is OPTIONAL_AUTO and the user hasn't specified this option in command line.
-
-###Decoupling command line from code###
-
-By default, the key used in result set is identical to the long form of the option. It tightly couples the command line option names to your code. 
-
-To reduce this dependency one can either use constants or could separate the two keys:
-
-~~~~
-:::java
-   StringOption stringOption = new StringOption.Builder("str")
-       .withValueKey("internalKey")
-       .getInstance();
-~~~~
-
-In the example above, the options will appear as `str` in command line, but you can refer to it in result set as `internalKey`.
-
-###Providing information for help renderer###
-
-Yacap is not only able to parse the command line, but shipped with a highly configurable help renderer. To 
-
-To be continued...

Home modified by Balázs Vissy

Balázs Vissy — Wed, 14 May 2014 08:55:20 -0000

--- v1
+++ v2
@@ -1,8 +1,176 @@
-Welcome to your wiki!
+#summary Getting started with yacap

-This is the default page, edit it as you see fit. To add a new page simply reference it within brackets, e.g.: [SamplePage].
+# Introduction #

-The wiki uses [Markdown](/p/yacap/wiki/markdown_syntax/) syntax.
+This page introduces the basic usage of yacap.

-[[members limit=20]]
 [[download_button]]
+
+# Installation #
+
+To use yacap library in your project, the following steps should be taken:
+
+  * Download the latest release
+  * Download the dependencies (such as Guava libraries)
+  * Add the jars to your project
+
+# Understanding command line arguments #
+
+As far as the parser goes, the command line arguments could be separated into 3 sections:
+
+  * Names options: label-value pairs (or simple labels without values)
+  * Unnamed arguments: Zero, one or more arguments representing a list of input
+  * Possible an internal argument list: they are arguments which have to be passed unparsed (usually they are arguments your program passes to some other, internally called program)
+
+All three sections are optional.
+
+To demonstrate the three sections, look at the following command line:
+
+~~~~
+:::java
+   myapp -abc --max 10 -s sometext file1 file2 -- -x -s othertext
+~~~~
+
+As visible, each option label starts with one or two hyphen(s) and optionally followed by a value. There are two ways to specify arguments:
+
+  * Short (or POSIX) form: the option label starts with a single hyphen (-) and the label is always exactly one character.
+  * Long (or GNU) form: the option label starts with double hyphens (--) and the name is an arbitary long text containing aphanumeric characters or hyphen.
+
+The short form options, when they contain no value, like switches or flags, can be collapsed into one option. (-abc) Other options are supported by value, such as --max or -s.
+
+The named option section ends when the parser first runs into an argument which doesn't start with hyphen. From here, all arguments are regarded as unnamed arguments till the end or till the parse-closing signal of a sole double hyphen (--). So the unnamed arguments here are file1 and file2.
+
+The arguments after the sole double hyphen (--) are regarded as internal and won't be parsed, but will be passed forward the application as is.
+
+
+# Configuring option sets #
+
+To define all possible options of your application you should create an OptionSet.
+
+###Creating option set###
+
+It is simple to create your option set:
+
+~~~~
+:::java 
+   myOptionSet = new OptionSet(); 
+~~~~
+
+and then register your options into.
+
+The options are immutable objects and they should be created through their builders. Each option you register should have a unique long name and if you specify a short for as well, it has to be unique also. 
+
+###Creating a simple option###
+
+For example, let's create a simple flag option with no value, and add it a short form:
+
+~~~~
+:::java 
+   BooleanOption boolOption = new BooleanOption.Builder("bool")
+       .withShortForm('b')
+      .getInstance();
+~~~~
+
+This option will be accessible from command line by either the short form -b or the long form --bool. It will be optional.
+
+###Register an option###
+
+To register the option to your set, use the registerOption function:
+
+
+   myOptionSet.registerOption(boolOption);
+
+
+###The types of the options###
+
+The following option types are provided by yacap:
+
+ **Class** |  **Has value**  | **Description** 
+ ----------|-----------------|-----------------------------------------------------------
+ BooleanOption |  no  | Represents a logical choice, such as flags.  Specifying the option means true, omiting means false. 
+ StringOption |  yes  | A common string option. 
+ IntegerOption | yes | A 4-byte, signed integer option. Accepts any value that the `Integer.parseInt()` can convert. 
+ LongOption | yes | A 8-byte, signed integer option. Accepts any value that the `Long.parseLong()` can convert. 
+ DoubleOption | yes | A floating point option. Accepts any value that the `Double.parseDouble()` can convert. 
+ EnumOption`<`E`>` | yes | An option of predefined value set. Accepts the values of the associated enum. 
+
+
+###Creating an option with value###
+
+To create an option with parameter you have to do nothing special. The type of the option defines whether it requires a value or not.
+
+The following code will create an optional string option with no short form:
+
+~~~~
+:::java 
+   StringOption stringOption = new StringOption.Builder("str").getInstance();
+~~~~
+
+###Setting option policy###
+
+When it isn't specified otherwise, an option is marked as optional. To change this you can define the policy:
+
+~~~~
+:::java 
+   StringOption stringOption = new StringOption.Builder("str")
+      .withDefaultOptionPolicy(OptionPolicy.REQUIRED)
+     .getInstance();
+~~~~
+
+These are the possible option policies:
+
+**Policy** | **Behaviour** 
+----------|-----------------
+HIDDEN | The option is regarded as a default option always set to its default value. The user can't specify it, the help won't contain it. 
+OPTIONAL| The option is optional. If the user doesn't specify it, the result set will not contain it. This is the default policy. 
+OPTIONAL_AUTO | It is similar to OPTIONAL, but it will always be included in result set with its default value if it was not specified otherwise in command line. *This option policy requires a default value to be set.* 
+REQUIRED | The command line should contain this option. 
+
+###Setting value policy###
+
+Usually an option clearly defines whether it requires a value or not. However, there is sometimes meaningful defaul value for the option and one would like to let the user to omit the value and only specifies the option itself. To achieve it, you can override value policy:
+
+~~~~
+:::java
+   StringOption stringOption = new StringOption.Builder("str")
+       .withValueOptional()
+       .withDefaultValue("defval")
+       .getInstance();
+~~~~
+
+###Setting the default value###
+
+By default, an option has no default value, but you can specify one.
+
+~~~~
+:::java
+   StringOption stringOption = new StringOption.Builder("str")
+       .withDefaultValue("defval")
+       .getInstance();
+~~~~
+
+Default value is used when
+
+  * either the value policy is set to OPTIONAL and the user hasn't specified a value in command line
+  * or if the option policy is OPTIONAL_AUTO and the user hasn't specified this option in command line.
+
+###Decoupling command line from code###
+
+By default, the key used in result set is identical to the long form of the option. It tightly couples the command line option names to your code. 
+
+To reduce this dependency one can either use constants or could separate the two keys:
+
+~~~~
+:::java
+   StringOption stringOption = new StringOption.Builder("str")
+       .withValueKey("internalKey")
+       .getInstance();
+~~~~
+
+In the example above, the options will appear as `str` in command line, but you can refer to it in result set as `internalKey`.
+
+###Providing information for help renderer###
+
+Yacap is not only able to parse the command line, but shipped with a highly configurable help renderer. To 
+
+To be continued...

Home modified by Balázs Vissy

Balázs Vissy — Wed, 14 May 2014 06:55:51 -0000

Welcome to your wiki!

This is the default page, edit it as you see fit. To add a new page simply reference it within brackets, e.g.: [SamplePage].

The wiki uses Markdown syntax.

Project Members:

Balázs Vissy (admin)