Andrey - New pages [en]

My coding style

Andrey — Sat, 22 Oct 2011 22:35:41 GMT

Summary:

When coding, I try to make it as readable as possible - and encourage others to do the same. Here is an utility class I wrote to for use in command line applications. It is surprising how often command line apps directly validate their argument arrays, while it is possible to delegate at least some logic to some kind of rule-driven parser. Here's the helping hand:

[[CommandLineParser.java]]

[[CommandLineParserTest.java]]

CommandLineParserTest.java

Andrey — Sat, 22 Oct 2011 22:31:57 GMT

Summary:

<pre><nowiki>

package com.taitl.world.commandline;

import java.util.List;

import junit.framework.TestCase;

import org.junit.After;
import org.junit.Before;
import org.junit.Test;

/*
* Copyright 2011 Taitl Design. All rights reserved.
*/

/**
* Tests for CommandLineParser class.
*
* @author Andrey Potekhin
*
*/
public class CommandLineParserTest extends TestCase
{

CommandLineParser commandLineParser = null;
CommandLineParser newCommandLineParser = null;

// Error strings
static final String MISSING_EXCEPTION = "Exception not thrown where it should";
static final String ERRONEOUS_EXCEPTION = "Exception thrown where it shouldn't";

// Trivial command lines
static final String cmdlineNULL = null;
static final String cmdlineEmpty = "";
static final String cmdlineUsage = "--prev --usage --next";
static final String cmdlineVersion = "--prev --version --next";
static final String cmdlineHelp = "--prev --help --next";
static final String cmdlineHelpWithArgument = "--prev --help general --next";

// Values of switches
static final String cmdlineNoValue = "--novalue --next";
static final String cmdlineOneValue = "--onevalue val --next";
static final String cmdlineOneValueOnEnd = "--prev --onevalue val";
static final String cmdlineTwoValues = "--twovalues val1 val2 --next";
static final String cmdlineTwoValuesOnEnd = "--prev --twovalues val1 val2";

static final String cmdlineThreeValues = "--threevalues val1 val2 val3 --next";
static final String cmdlineThreeValuesOnEnd = "--prev --threevalues val1 val2 val3";
static final String cmdlineOneToThree = "--prev --onetothree val1 val2 --next";
static final String cmdlineOneToThreeTooFew = "--prev --onetothree --next";
static final String cmdlineOneToThreeTooMany = "--prev --onetothree val1 val2 val3 val4 --next";

// Multiple values of a switch
static final String cmdlineMultiValues = "--prev --multi val1 val2 val3 val4 val5 --next";
static final String cmdlineMultiValuesOnEnd = "--prev --multi val1 val2 val3 val4 val5";
static final String cmdlineMany = "--prev --many val1 val2 \"val3\" val4 val5 val6 --next";
static final String cmdlineManyTooFew = "--prev --many val1 \"val2\" --next";

// Default switch
static final String cmdlineImplicitSwitch = "--prev file.txt --next";
static final String cmdlineImplicitSwitchTooManyValues = "--prev file.txt file2.txt --next";

// Quoted arguments
static final String cmdlineQuote = "--prev --onevalue \"val1 --next val2 val3\" --next";

// Switchless arguments
static final String cmdlineSwitchlessArguments1 = "--prev file1.txt --next file2.txt file3.txt file4.txt";
static final String cmdlineSwitchlessArguments2 = "file1.txt --prev file2.txt file3.txt --next file4.txt";

static final String possibleSwitches = "--usage(0) --version(0) --help(0-1) --prev(0) --next(0)"
+ " --novalue(0) --onevalue(1) --twovalues(2) --threevalues(3) --onetothree(1-3)"
+ " --multi(*) --many(3-*)";
static final String possibleThreeSwitches = "--prev(0) --next(0) --onevalue(1)";
static final String incorrectPossibleSwitches1 = "--usage";
static final String incorrectPossibleSwitches2 = "--usage(?)";
static final String incorrectPossibleSwitches3 = "--usage(3-2)";
static final String incorrectPossibleSwitches4 = "--usage[0]";
static final String implicitSwitch = "--file(1)";
static final String implicitSwitchAlternative = "--file";

/** Sets up test class object. */
@Override
@Before
public void setUp() throws Exception
{
commandLineParser = new CommandLineParser();
commandLineParser.setPossibleSwitches(possibleSwitches);
commandLineParser.setImplicitSwitch(implicitSwitch);
newCommandLineParser = new CommandLineParser(); // Not to be initialized
}

/**
* Performs cleanup of objects created in setUp() method.
*
* @throws Exception
* An exception to indicate problems during tear-down.
*/
@Override
@After
public void tearDown() throws Exception
{
commandLineParser = null;
}

/*
* Trivial tests
*/

/** */
@Test
public final void testCommandLineParser()
{
assertFalse(commandLineParser.isInitialized());
}

/** */
@Test
public final void testSetPossibleSwitches()
{
commandLineParser.setPossibleSwitches(possibleThreeSwitches);
final int requiredNumberOfSwitches = 3;
assertEquals(requiredNumberOfSwitches, commandLineParser
.getPossibleSwitches().size());
}

/** */
@Test
public final void testSetCommandLine()
{
commandLineParser.setCommandLine(cmdlineUsage);
assertEquals(cmdlineUsage, commandLineParser.getOriginalCommandLine());
}

/** */
@Test
public final void testSetArguments()
{
String commandLine;
String[] arguments;
arguments = new String[] { "--prev", "--usage", "--next" };
commandLineParser.setArguments(arguments);
assertEquals("--prev --usage --next",
commandLineParser.getOriginalCommandLine());

arguments = new String[] { "--prev", "--usage",
"usagevalue1 usagevalue2", "--next" };
commandLineParser.setArguments(arguments);
commandLine = commandLineParser.getOriginalCommandLine();
assertEquals("--prev --usage \"usagevalue1 usagevalue2\" --next",
commandLine);
arguments = commandLineParser.getArguments();
assertTrue(arguments.length == 4);
}

/** */
@Test
public final void testParse()
{
// String[] arguments = new String[] { "--prev", "--usage", "--next" };

// commandLineParser.setCommandLine(cmdlineUsage); // Calls parse()
// method
// assertTrue(commandLineParser.isInitialized());

newCommandLineParser.setPossibleSwitches(possibleSwitches);

// Try parsing without specifying command line arguments
try
{
newCommandLineParser.parse();
fail(MISSING_EXCEPTION);
}
catch (IllegalStateException ise)
{
}

try
{
newCommandLineParser.doParsing(null);
fail(MISSING_EXCEPTION);
}
catch (IllegalArgumentException ise)
{
}

newCommandLineParser.setCommandLine(cmdlineUsage);
assertTrue(newCommandLineParser.isInitialized());
}

/** */
@Test
public final void testGetArguments()
{
commandLineParser.setCommandLine(cmdlineQuote);
String[] arguments = commandLineParser.getArguments();
assertTrue(arguments.length == 4);
}

/** */
@Test
public final void testAddPossibleSwitch()
{
commandLineParser.setPossibleSwitches(possibleThreeSwitches);
assertTrue(commandLineParser.isPossibleSwitch("--prev"));
assertFalse(commandLineParser.isPossibleSwitch("--usage"));

// Try adding a malformed switch
try
{
commandLineParser.addPossibleSwitch("--usage");
fail(MISSING_EXCEPTION);
}
catch (IllegalArgumentException iae)
{
}

commandLineParser.addPossibleSwitch("--usage(0)");
assertTrue(commandLineParser.isPossibleSwitch("--usage"));
}

/** */
@Test
public final void testRemovePossibleSwitch()
{
commandLineParser.setPossibleSwitches(possibleThreeSwitches);

// Try removing a non-existing switch
try
{
commandLineParser.removePossibleSwitch("--nonexisting");
fail(MISSING_EXCEPTION);
}
catch (IllegalArgumentException iae)
{
}

// Remove switch with fully-specified name (including cardinality)
commandLineParser.removePossibleSwitch("--next(0)");
int requiredNumberOfSwitches = 2;
assertEquals(requiredNumberOfSwitches, commandLineParser
.getPossibleSwitches().size());

// Try removing a malformed switch
try
{
commandLineParser.removePossibleSwitch("--prev(0");
fail(MISSING_EXCEPTION);
}
catch (IllegalArgumentException iae)
{
}

// Try removing a malformed switch
try
{
commandLineParser.removePossibleSwitch("--prev0)");
fail(MISSING_EXCEPTION);
}
catch (IllegalArgumentException iae)
{
}

// Remove switch with omitted cardinality
commandLineParser.removePossibleSwitch("--prev");
requiredNumberOfSwitches = 1;
assertEquals(requiredNumberOfSwitches, commandLineParser
.getPossibleSwitches().size());
}

/** */
@Test
public final void testIsSwitchPresent()
{
commandLineParser.setCommandLine(cmdlineUsage);
assertTrue(commandLineParser.isSwitchPresent(commandLineParser
.getUsageSwitchName()));
assertFalse(commandLineParser.isSwitchPresent(commandLineParser
.getHelpSwitchName()));
}

/** */
@Test
public final void testGetSwitchValue()
{
String switchValue = null;

commandLineParser.setCommandLine(cmdlineNoValue);
assertTrue(commandLineParser.isSwitchPresent("--novalue"));
assertTrue(commandLineParser.isSwitchPresent("--next"));
assertFalse(commandLineParser.isSwitchPresent("--prev"));

try
{
commandLineParser.getSwitchValue("--prev");
fail(MISSING_EXCEPTION);
}
catch (IllegalArgumentException iae)
{
}

switchValue = commandLineParser.getSwitchValue("--novalue");
assertEquals(switchValue, "");

commandLineParser.setCommandLine(cmdlineOneValue);
assertTrue(commandLineParser.isSwitchPresent("--onevalue"));
switchValue = commandLineParser.getSwitchValue("--onevalue");
assertEquals(switchValue, "val");

commandLineParser.setCommandLine(cmdlineOneValueOnEnd);
assertTrue(commandLineParser.isSwitchPresent("--onevalue"));
switchValue = commandLineParser.getSwitchValue("--onevalue");
assertEquals(switchValue, "val");

commandLineParser.setCommandLine(cmdlineTwoValues);
assertTrue(commandLineParser.isSwitchPresent("--twovalues"));
try
{
// An exception must be thrown if switch has more than one value
switchValue = commandLineParser.getSwitchValue("--twovalues");
fail(MISSING_EXCEPTION);
}
catch (IllegalArgumentException iae)
{
}
}

/** */
@Test
public final void testGetSwitchValues()
{
List<String> switchValues = null;

commandLineParser.setCommandLine(cmdlineNoValue);
assertTrue(commandLineParser.isSwitchPresent("--novalue"));
assertTrue(commandLineParser.isSwitchPresent("--next"));
assertFalse(commandLineParser.isSwitchPresent("--prev"));
switchValues = commandLineParser.getSwitchValues("--novalue");
assertEquals(switchValues.size(), 0);

commandLineParser.setCommandLine(cmdlineOneValue);
switchValues = commandLineParser.getSwitchValues("--onevalue");
assertEquals(switchValues.size(), 1);
commandLineParser.setCommandLine(cmdlineOneValueOnEnd);
assertEquals(switchValues.size(), 1);

commandLineParser.setCommandLine(cmdlineTwoValues);
switchValues = commandLineParser.getSwitchValues("--twovalues");
assertEquals(switchValues.size(), 2);
commandLineParser.setCommandLine(cmdlineTwoValuesOnEnd);
switchValues = commandLineParser.getSwitchValues("--twovalues");
assertEquals(switchValues.size(), 2);

commandLineParser.setCommandLine(cmdlineThreeValues);
switchValues = commandLineParser.getSwitchValues("--threevalues");
assertEquals(switchValues.size(), 3);
commandLineParser.setCommandLine(cmdlineThreeValuesOnEnd);
switchValues = commandLineParser.getSwitchValues("--threevalues");
assertEquals(switchValues.size(), 3);

commandLineParser.setCommandLine(cmdlineOneToThree);
switchValues = commandLineParser.getSwitchValues("--onetothree");
assertEquals(switchValues.size(), 2);

commandLineParser.setCommandLine(cmdlineMultiValues);
switchValues = commandLineParser.getSwitchValues("--multi");
assertTrue(switchValues.size() >= 4);
commandLineParser.setCommandLine(cmdlineMultiValuesOnEnd);
switchValues = commandLineParser.getSwitchValues("--multi");
assertTrue(switchValues.size() >= 4);

commandLineParser.setCommandLine(cmdlineMany);
switchValues = commandLineParser.getSwitchValues("--many");
assertTrue(switchValues.size() >= 4);
}

/** */
@Test
public final void testCreateSwitch()
{
Switch s;

s = commandLineParser.createSwitch("--prev(0)");
assertTrue(s != null && s.getMinValues() == 0 && s.getMaxValues() == 0);
// Now try creating the switch by only specifying its name - without
// cardinality
s = commandLineParser.createSwitch("--prev");
assertTrue(s != null && s.getMinValues() == 0 && s.getMaxValues() == 0);

// Attempt to redefine cardinality of existing switch ("--prev(0)")
try
{
commandLineParser.addPossibleSwitch("--prev(1)");
fail(MISSING_EXCEPTION);
}
catch (IllegalArgumentException iae)
{
}

// Try creating a switch with malformed specification
try
{
commandLineParser.createSwitch("--prev(0");
fail(MISSING_EXCEPTION);
}
catch (IllegalArgumentException iae)
{
}

try
{
commandLineParser.createSwitch("--prev0)");
fail(MISSING_EXCEPTION);
}
catch (IllegalArgumentException iae)
{
}

// Try creating a switch with incorrect cardinality (different from
// what was specified in setPossibleSwitches()
try
{
commandLineParser.createSwitch("--prev(1)");
fail(MISSING_EXCEPTION);
}
catch (IllegalArgumentException iae)
{
}

// Try creating a switch with incorrect cardinality (non-number)
try
{
commandLineParser.addPossibleSwitch("--myswitch1(x)");
commandLineParser.createSwitch("--myswitch1(x)");
fail(MISSING_EXCEPTION);
}
catch (IllegalArgumentException iae)
{
}
try
{
commandLineParser.addPossibleSwitch("--myswitch2(1-x)");
commandLineParser.createSwitch("--myswitch2(1-x)");
fail(MISSING_EXCEPTION);
}
catch (IllegalArgumentException iae)
{
}
try
{
commandLineParser.addPossibleSwitch("--myswitch3(x-100)");
commandLineParser.createSwitch("--myswitch3(x-100)");
fail(MISSING_EXCEPTION);
}
catch (IllegalArgumentException iae)
{
}

// Try creating a switch which does not exist among possible switches
try
{
commandLineParser.createSwitch("--nonexisting(0)");
fail(MISSING_EXCEPTION);
}
catch (IllegalArgumentException iae)
{
}

}

/*******************************
* Trivial tests
*******************************/

/** */
@Test
public final void testGetSwitchValueCount()
{
commandLineParser.setCommandLine(cmdlineThreeValues);
assertEquals(commandLineParser.getSwitchValueCount("--threevalues"), 3);
}

/** */
@Test
public final void testGetOriginalCommandLine()
{
commandLineParser.setCommandLine(cmdlineUsage);
assertEquals(cmdlineUsage, commandLineParser.getOriginalCommandLine());
}

/** */
@Test
public final void testIsUsageRequested()
{
commandLineParser.setCommandLine(cmdlineHelp);
assertFalse(commandLineParser.isUsageRequested());
commandLineParser.setCommandLine(cmdlineUsage);
assertTrue(commandLineParser.isUsageRequested());
}

/** */
@Test
public final void testIsHelpRequested()
{
commandLineParser.setCommandLine(cmdlineUsage);
assertFalse(commandLineParser.isHelpRequested());
commandLineParser.setCommandLine(cmdlineHelp);
assertTrue(commandLineParser.isHelpRequested());
}

/** */
@Test
public final void testIsVersionRequested()
{
commandLineParser.setCommandLine(cmdlineEmpty);
assertFalse(commandLineParser.isVersionRequested());
commandLineParser.setCommandLine(cmdlineVersion);
assertTrue(commandLineParser.isVersionRequested());
}

/** */
@Test
public final void testGetUsageSwitch()
{
commandLineParser.setUsageSwitchName("a");
assertEquals("a", commandLineParser.getUsageSwitchName());
}

/** */
@Test
public final void testSetUsageSwitch()
{
commandLineParser.setUsageSwitchName("a");
assertEquals("a", commandLineParser.getUsageSwitchName());
}

/** */
@Test
public final void testGetHelpSwitch()
{
commandLineParser.setHelpSwitchName("a");
assertEquals("a", commandLineParser.getHelpSwitchName());
}

/** */
@Test
public final void testSetHelpSwitch()
{
commandLineParser.setHelpSwitchName("a");
assertEquals("a", commandLineParser.getHelpSwitchName());
}

/** */
@Test
public final void testGetVersionSwitch()
{
commandLineParser.setVersionSwitchName("a");
assertEquals("a", commandLineParser.getVersionSwitchName());
}

/** */
@Test
public final void testSetVersionSwitch()
{
commandLineParser.setVersionSwitchName("a");
assertEquals("a", commandLineParser.getVersionSwitchName());
}

/** */
@Test
public final void testRequireInitialization()
{
try
{
newCommandLineParser.requireInitialization();
fail(MISSING_EXCEPTION);
}
catch (IllegalStateException iae)
{
}

try
{
newCommandLineParser.setPossibleSwitches(possibleSwitches);
newCommandLineParser.requireInitialization();
fail(MISSING_EXCEPTION);
}
catch (IllegalStateException iae)
{
}

try
{
// Specify erroneous command line to prevent parse() from completing
newCommandLineParser.setCommandLine(cmdlineUsage + " --unknown");
// newCommandLineParser.requireInitialization();
fail(MISSING_EXCEPTION);
}
catch (IllegalArgumentException iae)
{
// fail(ERRONEOUS_EXCEPTION);
}

try
{
newCommandLineParser.requireInitialization();
fail(MISSING_EXCEPTION);
}
catch (IllegalStateException iae)
{
// fail(ERRONEOUS_EXCEPTION);
}

try
{
commandLineParser.requireInitialization();
fail(MISSING_EXCEPTION);
}
catch (IllegalStateException iae)
{
}

// Initialize
commandLineParser.setCommandLine(cmdlineUsage);
commandLineParser.parse();

try
{
commandLineParser.requireInitialization();
}
catch (IllegalStateException iae)
{
fail(ERRONEOUS_EXCEPTION);
}
}

/** */
@Test
public final void testForbidNullString()
{
try
{
commandLineParser.forbidNullString("", "No error message");
}
catch (IllegalArgumentException iae)
{
fail(ERRONEOUS_EXCEPTION);
}

try
{
commandLineParser.forbidNullString(null, "Error message");
fail(MISSING_EXCEPTION);
}
catch (IllegalArgumentException iae)
{
assertTrue(iae.getMessage().contains("Error message"));
}
}

/** */
@Test
public final void testForbidEmptyString()
{
try
{
commandLineParser.forbidEmptyString("Non-empty string",
"No error message");
}
catch (IllegalArgumentException iae)
{
fail(ERRONEOUS_EXCEPTION);
}

try
{
commandLineParser.forbidEmptyString(null, "Error message");
fail(MISSING_EXCEPTION);
}
catch (IllegalArgumentException iae)
{
assertTrue(iae.getMessage().contains("Error message"));
}

try
{
commandLineParser.forbidEmptyString("", "Error message");
fail(MISSING_EXCEPTION);
}
catch (IllegalArgumentException iae)
{
assertTrue(iae.getMessage().contains("Error message"));
}
}

/** */
@Test
public final void testForbid()
{
try
{
commandLineParser.forbid(false, "No error message");
}
catch (IllegalArgumentException iae)
{
fail(ERRONEOUS_EXCEPTION);
}

try
{
commandLineParser.forbid(true, "Error message");
fail(MISSING_EXCEPTION);
}
catch (IllegalArgumentException iae)
{
}
}

/** */
@Test
public final void testRemoveCardinality()
{
// String switchSpecification = "--next(1-10)";

// Null string
try
{
commandLineParser.removeCardinality(null);
fail(MISSING_EXCEPTION);
}
catch (IllegalArgumentException iae)
{
}

// Forgotten left brace
try
{
commandLineParser.removeCardinality("--next(1-10");
fail(MISSING_EXCEPTION);
}
catch (IllegalArgumentException iae)
{
}

// Forgotten right brace
try
{
commandLineParser.removeCardinality("--next1-10)");
fail(MISSING_EXCEPTION);
}
catch (IllegalArgumentException iae)
{
}

assertEquals(commandLineParser.removeCardinality("--next(1-10)"),
"--next");

// If cardinality is not specified, return unmodified string
assertEquals(commandLineParser.removeCardinality("--next"), "--next");
}

/*******************************
* Initialization sequence tests
*******************************/

/** */
@Test
public final void testInitSequence()
{
// Disallowed operations on an uninitialized command line parser

// Require setPossibleSwitches() before setCommandLine()
try
{
newCommandLineParser.setCommandLine(cmdlineUsage);
fail(MISSING_EXCEPTION);
}
catch (IllegalStateException iae)
{
}
}

/** */
@Test
public final void testGetters()
{
CommandLineParser p = newCommandLineParser;

// Require setPossibleSwitches() before getPossibleSwitches()
try
{
p.getPossibleSwitches();
fail(MISSING_EXCEPTION);
}
catch (IllegalStateException ise)
{
}
// Require setImplicitSwitch() before getImplicitSwitch()
try
{
p.getImplicitSwitch();
fail(MISSING_EXCEPTION);
}
catch (IllegalStateException ise)
{
}
// Require setCommandLine() before getCommandLine()
try
{
p.getOriginalCommandLine();
fail(MISSING_EXCEPTION);
}
catch (IllegalStateException ise)
{
}
// Require setArguments() before getArguments()
try
{
p.getArguments();
fail(MISSING_EXCEPTION);
}
catch (IllegalStateException ise)
{
}
p.setPossibleSwitches(possibleSwitches);
assertTrue(p.isPossibleSwitch("--prev"));
p.setImplicitSwitch("--file(1)");
assertEquals("--file", p.getImplicitSwitch());
p.setCommandLine(cmdlineOneValue);
assertEquals(cmdlineOneValue, p.getOriginalCommandLine());
assertEquals(p.getSwitchMap().size(), 2);
}

/*********************
* Less trivial tests
*********************/

/** Test command line with quotes in arguments */
@Test
public final void testDoubleQuotesInCommandLine()
{
String s;
s = "--onevalue \"val\" --next";
commandLineParser.setCommandLine(s);
assertEquals(commandLineParser.getSwitchValue("--onevalue"), "val");
s = "--onevalue \"val1 val2\" --next";
commandLineParser.setCommandLine(s);
assertEquals(commandLineParser.getSwitchValue("--onevalue"),
"val1 val2");
s = "--onevalue \"val1 --next val2\" --next";
commandLineParser.setCommandLine(s);
assertEquals(commandLineParser.getSwitchValue("--onevalue"),
"val1 --next val2");
s = "--onevalue \"val3 val4\"";
commandLineParser.setCommandLine(s);
assertEquals(commandLineParser.getSwitchValue("--onevalue"),
"val3 val4");
}

/** Test command line with several switch values per switch */
@Test
public final void testSwitchCardinality()
{
List<String> switchValues = null;

// Require an exception in case of too few switch values
try
{
commandLineParser.setCommandLine(cmdlineOneToThreeTooFew);
fail(MISSING_EXCEPTION);
}
catch (IllegalArgumentException iae)
{
}
try
{
commandLineParser.setCommandLine(cmdlineManyTooFew);
fail(MISSING_EXCEPTION);
}
catch (IllegalArgumentException iae)
{
}
// Require an exception in case of too many switch values
try
{
commandLineParser
.setCommandLine(cmdlineImplicitSwitchTooManyValues);
fail(MISSING_EXCEPTION);
}
catch (IllegalStateException iae)
{
String message = iae.getMessage();
assertTrue(message != null
&& message.contains("already has a value"));
assertTrue(message != null && message.contains("implicit"));
}

// In case of too many switch values, assure that the 'overflow' values
// get assigned to implicit switch and to switchless arguments:
commandLineParser.setCommandLine(cmdlineOneToThreeTooMany);
switchValues = commandLineParser.getSwitchValues("--onetothree");
assertTrue(switchValues.size() == 3);
String implicitSwitchValue = commandLineParser
.getSwitchValue(commandLineParser.getImplicitSwitch());
assertEquals(implicitSwitchValue, "val4");
String[] switchlessArguments = commandLineParser
.getSwitchlessArguments();
assertEquals(switchlessArguments[0], "val4");

commandLineParser.setCommandLine(cmdlineMany);
switchValues = commandLineParser.getSwitchValues("--many");
assertTrue(switchValues.size() == 6);
}

/** Test command line with a switch-less value */
@Test
public final void testSwitchlessValue()
{
String s;
s = "--onevalue val1 val2 --next";
commandLineParser.setCommandLine(s);
assertEquals(commandLineParser.getSwitchValue("--onevalue"), "val1");
assertEquals(commandLineParser.getSwitchValue(commandLineParser
.getImplicitSwitch()), "val2");
String[] switchlessArguments = commandLineParser
.getSwitchlessArguments();
assertEquals(switchlessArguments[0], "val2");
}

/** Test succession of command lines */
@Test
public final void testCommandLineSuccession()
{
String s;
s = "--onevalue val1 val2 --next";
commandLineParser.setCommandLine(s);
assertEquals(commandLineParser.getSwitchValue("--onevalue"), "val1");
assertEquals(commandLineParser.getSwitchValue(commandLineParser
.getImplicitSwitch()), "val2");
s = "--onevalue val3 val4 --next";
commandLineParser.setCommandLine(s);
assertEquals(commandLineParser.getSwitchValue("--onevalue"), "val3");
assertEquals(commandLineParser.getSwitchValue(commandLineParser
.getImplicitSwitch()), "val4");
}

/** Test succession of possible parameters */
@Test
public final void testSuccessionOfPossibleParameters()
{
String s;
commandLineParser.setPossibleSwitches("--one(1) --next(0)");
s = "--one val1 val2 --next";
commandLineParser.setCommandLine(s);
assertEquals(commandLineParser.getSwitchValue("--one"), "val1");
assertEquals(commandLineParser.getSwitchValue(commandLineParser
.getImplicitSwitch()), "val2");
commandLineParser.setPossibleSwitches("--another(1) --prev(0)");
// Require old switch to be invalid
try
{
s = "--another val3 val4 --next";
commandLineParser.setCommandLine(s);
fail(MISSING_EXCEPTION);
}
catch (IllegalArgumentException iae)
{
}
s = "--prev --another val3 val4";
commandLineParser.setCommandLine(s);
assertEquals(commandLineParser.getSwitchValue("--another"), "val3");
assertEquals(commandLineParser.getSwitchValue(commandLineParser
.getImplicitSwitch()), "val4");
}
}

</nowiki></pre>

CommandLineParser.java

Andrey — Sat, 22 Oct 2011 22:30:30 GMT

Summary:

<pre><nowiki>

package com.taitl.world.commandline;

import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;

/*
* Copyright 2011 Taitl Design. All rights reserved.
*/

/**
* CommandLineParser class takes command line arguments and parses them into a
* map of [switch, list of values] pairs. A switch on the command line can have
* no, one, or many values. The command line can also have arguments that are
* not related to any switches.
* 
* Usage:
* 
*
* <pre>
* public static void main(String[] arguments)
* {
* CommandLineParser commandLineParser = new CommandLineParser();
* commandLineParser.setPossibleSwitches("--version(0) --usage(0)"
* + " --help(0) --multi(*)");
* commandLineParser.setEmptyCommandLineSwitch("--usage");
* commandLineParser.setImplicitSwitch("--file(1)");
* commandLineParser.setArguments(arguments);
* // ...same as commandLineParser.parse(arguments);
*
* if (commandLineParser.isUsageRequested())
* {
* System.out.println(usageText);
* }
* else if (commandLineParser.isVersionRequested())
* {
* System.out.println(VERSION_STRING);
* }
* else if (commandLineParser.isHelpRequested())
* {
* System.out.println(helpText);
* }
* else if (commandLineParser.isSwitchPresent("--multi"))
* {
* // Process custom switch
* List<String> switchValues = commandLineParser
* .getSwitchValues("--multi");
* String[] arguments = commandLineParser.getSwitchlessArguments();
* // ...
* }
* }
* </pre>
*
* @author Andrey Potekhin, 03/08/2011
*/
public class CommandLineParser
{

/** Default usage switch name: --usage. */
static final String DEFAULT_USAGE_SWITCH = "--usage";

/** Default help switch name: --help. */
static final String DEFAULT_HELP_SWITCH = "--help";

/** Default version switch name: --version. */
static final String DEFAULT_VERSION_SWITCH = "--version";

/** Default switch name prefixes: -- and -. */
static final String DEFAULT_SWITCH_PREFIXES = "(--|-)";

/** Default value of usage switch, defaulted to --usage. */
private String usageSwitchName = DEFAULT_USAGE_SWITCH;

/** Default value of usage switch, defaulted to --help. */
private String helpSwitchName = DEFAULT_HELP_SWITCH;

/** Default value of usage switch, defaulted to --version. */
private String versionSwitchName = DEFAULT_VERSION_SWITCH;

/** Default value of switch prefixes, defaulted to (--|-). */
private String switchPrefixesMask = DEFAULT_SWITCH_PREFIXES;

/** The original command line. */
private String originalCommandLine = null;

/** The original arguments array, as usually passed in the main() method. */
private String[] arguments = null;

/**
* The command line arguments that do not have a switch corresponding to
* them.
*/
private String[] switchlessArguments = null;

/**
* Has this object been properly initialized? This is false unless both
* setPossibleSwitches() and setArguments()/parse() has been called.
*/
private boolean isInitialized = false;

/** The set of possible switches. */
private Set<String> possibleSwitches = new LinkedHashSet<String>();

/**
* The default (implicit) switch to which all switchless arguments are
* attributed.
*
* @see CommandLineParser#setImplicitSwitch
*/
private String implicitSwitch = null;

/**
* Main structure to hold information about the parsed command line switches
* and their values and switchless arguments.
*/
private Map<String, List<String>> switchMap = new LinkedHashMap<String, List<String>>();

/** Command line switches as result of parsing. */
private Map<String, Switch> switches = new LinkedHashMap<String, Switch>();

/**
* Default constructor.
*/
public CommandLineParser()
{
originalCommandLine = null;
isInitialized = false;
}

/**
* Sets command line arguments form the array of arguments passed to Java
* program's main() method, and parses them into map of [switch-list of
* values] pairs by calling
* 
* According to Java documentation, the arguments that are passed to mail()
* method conform to the following rules:
* 
* 
* - On the command line, Java program arguments are separated by spaces and
* tabs, except when an argument is enclosed by double-quotes.
* 
* - Leading and trailing whitespace characters are removed from the values
* stored in the arguments array.
* 
* - The double-quoted argument is not broken into several separate
* arguments.
* 
* - For arguments enclosed with double-quotes, the double-quotes are
* removed.
* 
*
* @param args
* Command line arguments to parse.
*/
public final void setArguments(final String[] args)
{
forbid(args == null, "Args argument must not be null.");

StringBuffer commandLine = new StringBuffer();
String arg;

for (String arg2 : args)
{
forbid(arg2 == null, "Null value in argument array.");

arg = arg2.trim();

// If argument has spaces in it, enclose it in double quotes
if (arg.matches(".*\\s.*"))
{
arg = "\"" + arg + "\"";
}
if (commandLine.length() > 0 && arg.length() > 0)
{
commandLine.append(" ");
}
commandLine.append(arg);
}

originalCommandLine = commandLine.toString();
arguments = args;
switches.clear();
switchlessArguments = null;

// Uninitialize the object
isInitialized = false;

// Immediately parse
parse();
}

/**
* An alternative to <code>setArguments()</code> method, sets arguments
* using a command line string.
* 
* According to Java documentation, the arguments that are passed to mail()
* method conform to the following rules:
* 
* 
* - On the command line, Java program arguments are separated by spaces and
* tabs, except when an argument is enclosed by double-quotes.
* 
* - Leading and trailing whitespace characters are removed from the values
* stored in the arguments array.
* 
* - The double-quoted argument is not broken into several separate
* arguments.
* 
* - For arguments enclosed with double-quotes, the double-quotes are
* removed.
* 
*
* @param commandLine
* Command line to parse.
*/
public void setCommandLine(String commandLine)
{
forbidNullString(commandLine, "commandLine");
originalCommandLine = commandLine;

// String[] args = commandLine.split("\\s");

// Go over command line, splitting it into whitespace-separated
// arguments, preserving arguments enclosed with double quotes,
// treating them as a single argument, while also removing their
// enclosing double quotes.
boolean insideDoubleQuotes = false;
boolean inWord = false;
boolean isWhitespace = false;
StringBuffer arg = new StringBuffer();
List<String> args = new ArrayList<String>();

for (int i = 0; i < commandLine.length(); i++)
{
char c = commandLine.charAt(i);
boolean finalizeArgument = false;
boolean isClosingDoubleQuote = false;

if (c == '"')
{
if (!insideDoubleQuotes)
{
insideDoubleQuotes = true;
continue;
}
else
{
insideDoubleQuotes = false;
isClosingDoubleQuote = true;
finalizeArgument = true;
}
}

if (insideDoubleQuotes)
{
arg.append(c);
continue;
}

isWhitespace = Character.isWhitespace(c);

if (isWhitespace)
{
if (inWord)
{
inWord = false;
finalizeArgument = true;
}
}
else
{
if (!inWord && !isClosingDoubleQuote)
{
inWord = true;
}
}

if (inWord)
{
arg.append(c);
}

if (finalizeArgument)
{
// Finalize argument
args.add(arg.toString());
arg.setLength(0);
}
}

// Finalize last argument
if (arg.length() > 0)
{
args.add(arg.toString());
}

// Convert to String[]
String[] argArray = new String[args.size()];
for (int i = 0; i < args.size(); i++)
{
argArray[i] = args.get(i);
}

// Immediately parse
setArguments(argArray);
}

/**
* Gets command line arguments previously set by call to
* <code> setArguments()</code> or <code>setCommandLine()</code>.
* 
*
* @return String array of arguments previously set by a call to
* setArguments() or setCommandLine(). Throws IllegalStateException
* if user tries to get arguments that have not yet been set.
*/
public final String[] getArguments()
{
forbidState(arguments == null,
"You must call setArguments() or setCommandLine() before calling this method.");
return arguments;
}

/**
* Returns the set of possible command line switches previously specified
* with a call to setPossibleSwitches().
*
* @return The set of possible switches previously specified with a call to
* setPossibleSwitches().
*/
public Set<String> getPossibleSwitches()
{
forbidState(possibleSwitches.isEmpty(),
"You must call setPossibleSwitches() before calling this method.");
return possibleSwitches;
}

/**
* This method lets the CommandLineParser object know of the legitimate
* switches. You are required to call this method after you constructed the
* CommandLineParser object, and before proceeding with any further work
* with it.
* 
* Each switch is succeed by parenthesis indicating the potential number of
* it arguments, for example:
* 
* (0) - no arguments,
* 
* (1) - one argument,
* 
* (0-3) - from zero to three arguments,
* 
* (*) - any number of arguments,
* 
* (3-*) - from three to any greater number of arguments, and so on.
* 
* Example:
* 
* <code>setPossibleSwitches("--version(0) --usage(0)"
* + " --help(0-1) --multi(1-*)");</code>
*
* @param possibleSwitchesList
* Space-separated list of allowed command line switches, each of
* which is followed by parenthesized number of switch values.
* This can be either a precise number, a min-max expression, or
* expression involving an asterisk (*), which stands for any
* number of arguments.
*/
public final void setPossibleSwitches(String possibleSwitchesList)
{
forbidEmptyString(possibleSwitchesList, "possibleSwitchesList");

// Forget old switches that were specified earlier
possibleSwitches.clear();

// Parse comma-separated list into hash map
for (String switchSpecification : possibleSwitchesList.split(" "))
{
addPossibleSwitch(switchSpecification);
}

// The implicit switch, if specified, must be a part of possible
// switch collection. Since we have emptied the set of
// possible switches in the beginning of this method, we
// need to add the implicit switch again to it.
if (implicitSwitch != null)
{
setImplicitSwitch(implicitSwitch);
}
}

/**
* Sets the implicit switch, that is, the switch to which the argument value
* attributed of the first argument that is not preceded by any switch.
* Example:
* 
* If you call setImplicitSwitch("--file(1)") and process command line
* 
* <code>myprogram --vertical --split myfile.txt</code>
* 
* then CommandLineParser will attribute "myfile.txt" value to the "--file"
* switch, and you will be able to retrieve this value by calling
* <code>getSwitchValue("--file")</code>.
* 
* 
* Note: you don't have to specify the implicit switch in the call to
* <code>setPossibleSwitches()</code>.
*
* @param implicitSwitchSpecification
* Default (implicit) switch will correspond to command line
* parameter that is not preceded with any switch. If there are
* several such parameters, they are united in a list and this
* list is set a list of values that correspond to this implicit
* switch.
*/
public void setImplicitSwitch(String implicitSwitchSpecification)
{
assert possibleSwitches != null;
forbid(possibleSwitches.isEmpty(),
"You must call setPossibleSwitches() before calling this method.");
forbidEmptyString(implicitSwitchSpecification,
"implicitSwitchSpecification");

/*
* if (implicitSwitch != null &&
* isPossibleSwitch(removeCardinality(implicitSwitch))) {
* removePossibleSwitch(implicitSwitch); }
*/

implicitSwitch = implicitSwitchSpecification;
// addPossibleSwitch(implicitSwitch);
}

/**
* Returns the implicit command line switch, that is, the implicit switch
* (set earlier with a call to setImplicitSwitch()), which corresponds to
* command line parameter(s) that are not part of values of any other
* switch. Example:
*
* <pre>
* command line: myprogram --verbose file.txt
* ...
* setPossibleSwitches("--verbose(0)");
* setImplicitSwitch("--file");
* ...
* String filename = getSwitchValue(getImplicitSwitch());
* </pre>
* 
* A call to this method must be preceded by a call to setImplicitSwitch(),
* otherwise an IllegalStateException is thrown.
* 
* To get the implicit switch value(s), call <code>getSwitchValue()</code>
* or <code>getSwitchValues()</code> with the name of implicit switch.
*
* @return The name of the implicit switch, e.g. "--file".
* @throws IllegalArgumentException
* when this method is not preceded by a call to
* setImplicitSwitch()
*/
public String getImplicitSwitch() throws IllegalArgumentException
{
forbidState(
implicitSwitch == null,
"Null in implicit switch value. You need to call setImplicitSwitch() before calling this method.");
return removeCardinality(implicitSwitch);
}

/**
* Parses command line arguments specified in a call to setArguments() or
* setCommandLine() and prepares as a result the data that reflect which
* command line switches were specified and with which values. This data can
* be retrieved with calls to getSwitchValue(), getSwitchValues(),
* getSwitchValueCount(), isSwitchPresent().
*
* @throws IllegalArgumentException
* - when a violation of parsing rules is encountered, for
* example, when a switch is present on command line which was
* not specified in a call to setPossibleSwitches().
* @throws IllegalStateException
* when the CommandLineParser object is not initialized, for
* instance, when its the command line arguments have not been
* set yet. You must at a minimum call setPossibleSwitches(),
* setArguments() or setCommandLine() before calling this
* method.
*/
protected void parse() throws IllegalArgumentException,
IllegalStateException
{
forbidState(
originalCommandLine == null || arguments == null,
"You must call setArguments() or setCommandLine() method before calling parse() method without arguments.");

// Here happens the magic!
doParsing(arguments);

isInitialized = true;

// Make sure the object is now properly initialized
requireInitialization();
}

/**
* Is command line switch present?
*
* @param switchString
* The command line switch, e.g. --version.
* @return True or false depending on whether the switch is present on the
* command line.
*/
public boolean isSwitchPresent(String switchString)
{
requireInitialization();
forbidEmptyString(switchString, "switchString");
forbid(!looksLikeSwitch(switchString),
"Switch must start with one of switch prefixes defined by the switchPrefixesMask mask.");
boolean returnValue = switches.containsKey(switchString);
return returnValue;
}

/**
* Returns switch value.
* 
* Example:
* 
* For command line <code>myprogram --version</code>
* 
* <code>getSwitchValue("--version")</code> will return an empty string.
* 
* For command line <code>myprogram --version ver</code>
* 
* <code>getSwitchValue("--version")</code> will return string "ver".
* 
* 
* If the switch is not present, the <code>IllegalArgumentException</code>
* is thrown.
* 
* 
*
* @param switchString
* The name of command line switch.
* @return The value of command line switch, empty string if switch has no
* value (as, for example, in case with --version switch).
*/
public String getSwitchValue(String switchString)
{
String returnValue = null;

requireInitialization();
forbidEmptyString(switchString, "switchString");
forbid(!isSwitchPresent(switchString),
"Switch "
+ switchString
+ " is not present on the command line. Use isSwitchPresent() to check for a switch.");
List<String> valueList = getSwitchValues(switchString);
assert valueList != null;
if (valueList.size() == 0)
{
returnValue = "";
}
else
{
returnValue = valueList.get(0);
}
forbid(valueList.size() > 1,
"Switch "
+ switchString
+ " has several values. Use getSwitchValueCount() to check for number of switch values."
+ " Use getSwitchValues() to get the list of switch values.");
assert returnValue != null; // Make sure we didn't skip any branches in
// logic
return returnValue;
}

/**
* Returns the list of values of command switch. In the command line, the
* values are assigned to a switch until either the next switch is
* encountered. Next switch is not considered such if it appears inside a
* single or double quoted string.
*
* The arguments that
* 
* Example:
* 
* For command line <code>myprogram --version</code>
* 
* <code>getSwitchValue("--version")</code> will return an empty list.
* 
* For command line myprogram --version ver
* 
* <code>getSwitchValue("--version")</code> will return a list with one
* element, string "ver".
* 
* For command line <code>myprogram --version ver ber</code>
* 
* <code>getSwitchValue("--version")</code> will return a list with two
* elements: strings "ver" and "ber".
* 
* 
* If the switch is not present, the <code>IllegalArgumentException</code>
* is thrown.
* 
* 
*
* @param switchString
* The name of command line switch.
* @return The list of values of command line switch.
*/
public List<String> getSwitchValues(String switchString)
{
List<String> returnValue = null;

requireInitialization();
forbidEmptyString(switchString, "switchString");
forbid(!isSwitchPresent(switchString),
"Switch "
+ switchString
+ " is not present on the command line. Use isSwitchPresent() to check for a switch.");

List<String> valueList = switchMap.get(switchString);
assert valueList != null;
returnValue = valueList;
assert returnValue != null; // Make sure we didn't skip any branches in
// logic
return returnValue;
}

/**
* Returns value count of switch.
* 
* Example:
* 
* For command line <code>myprogram --version</code>
* 
* <code>getSwitchValueCount("--version")</code> will return 0.
* 
* For command line <code>myprogram --version ver</code>
* 
* <code>getSwitchValueCount("--version")</code> will return 1.
* 
* 
* If the switch is not present, the <code>IllegalArgumentException</code>
* is thrown.
* 
* 
*
* @param switchString
* The name of command line switch.
* @return The number of values of command line switch.
*/
public int getSwitchValueCount(String switchString)
{
Integer returnValue = null;

requireInitialization();
forbidEmptyString(switchString, "switchString");
forbid(!isSwitchPresent(switchString),
"Switch "
+ switchString
+ " is not present on the command line. Use isSwitchPresent() to check for a switch.");

List<String> valueList = switchMap.get(switchString);
assert valueList != null;
returnValue = new Integer(valueList.size());
assert returnValue != null; // Make sure we didn't skip any branches in
// logic
return returnValue.intValue();
}

/**
* Returns the original command line that was parsed.
*
* @return The command line that has been passed to setCommandLine() method,
* or to setArguments() as array of arguments.
*/
public String getOriginalCommandLine()
{
forbidState(originalCommandLine == null,
"You must call setCommandLine() or setArguments() before calling this method.");
return originalCommandLine;
}

/**
* Returns true if usageSwitchName (default --usage) is present on the
* command line.
*
* @return True if usageSwitchName is present on command line.
*/
public boolean isUsageRequested()
{
requireInitialization();
return isSwitchPresent(usageSwitchName);
}

/**
* Returns true if helpSwitchName (default --help) is present on the command
* line.
*
* @return True if helpSwitchName is present on command line.
*/
public boolean isHelpRequested()
{
requireInitialization();
return isSwitchPresent(helpSwitchName);
}

/**
* Returns true if versionSwitchName (default --version) is present on the
* command line.
*
* @return True if versionSwitchName is present on command line.
*/
public boolean isVersionRequested()
{
requireInitialization();
return isSwitchPresent(versionSwitchName);
}

/**
* Returns the default value of usageSwitchName (default --usage).
*
* @return The default value of usageSwitchName.
*/
public String getUsageSwitchName()
{
return usageSwitchName;
}

/**
* Sets the default value of usageSwitchName.
*
* @param usageSwitch
* New default value of usageSwitchName.
*/
public void setUsageSwitchName(String usageSwitch)
{
forbid(looksLikeSwitch(usageSwitch),
"Switch must start with an appropriate switch prefix.");
this.usageSwitchName = usageSwitch;
}

/**
* Returns the default value of helpSwitchName (default --help).
*
* @return The default value of helpSwitchName.
*/
public String getHelpSwitchName()
{
return helpSwitchName;
}

/**
* Sets the default value of helpSwitchName.
*
* @param helpSwitch
* New default value of helpSwitchName.
*/
public void setHelpSwitchName(String helpSwitch)
{
this.helpSwitchName = helpSwitch;
}

/**
* Returns the default value of versionSwitchName (default --version).
*
* @return The default value of versionSwitchName.
*/
public String getVersionSwitchName()
{
return versionSwitchName;
}

/**
* Sets the default value of versionSwitchName.
*
* @param versionSwitch
* New default value of versionSwitchName.
*/
public void setVersionSwitchName(String versionSwitch)
{
this.versionSwitchName = versionSwitch;
}

/**
* Checks if CommandLineParser has not been properly initialized, that is,
* the methods <code>setPossibleSwitches()</code> and
* <code>setArguments()</code> have been called, and therefore, the parsing
* process has been carried out.
*
* Throws <code>IllegalStateException</code> exception if the
* <code>CommandLineParser</code> has not been initialized, that is, the
* methods <code>setPossibleSwitches()</code> and
* <code>setArguments()</code> have not been called.
*
* @throws IllegalStateException
* if CommandLineParser has not been initialized.
*/
protected void requireInitialization() throws IllegalStateException
{
assert possibleSwitches != null;

if (possibleSwitches.isEmpty())
{
throw new IllegalStateException(
"This class must be initialized first by calling setPossibleSwitches() and setArguments() method.");
}
if (arguments == null)
{
throw new IllegalStateException(
"This class must be initialized first by calling setArguments() or setCommandLine() method.");
}
if (!isInitialized)
{
throw new IllegalStateException(
"This class must be initialized first by calling setArguments() or parse() method.");
}
}

/**
* Throws IllegalArgumentException if the specified string is null.
*
* @param s
* The string to check for nullability.
* @param parameterName
* The name of parameter of the caller method that we want to
* include in exception description if the tested string is null.
*
* @throws IllegalArgumentException
* if passed-in string is null.
*/
protected void forbidNullString(String s, String parameterName)
throws IllegalArgumentException
{
if (s == null)
{
throw new IllegalArgumentException(
"Non-null value required in parameter " + parameterName
+ ".");
}
}

/**
* Throws IllegalArgumentException if the specified string is a null or
* empty string.
*
* @param s
* The string to check for nullability or emptiness.
* @param parameterName
* The name of parameter of the caller method that we want to
* include in exception description if the tested string is null
* or empty.
*
* @throws IllegalArgumentException
* if passed-in string is null or empty.
*/
protected void forbidEmptyString(String s, String parameterName)
throws IllegalArgumentException
{
if (s == null)
{
throw new IllegalArgumentException(
"Non-null value required in parameter " + parameterName
+ ".");
}
if (s.length() == 0)
{
throw new IllegalArgumentException(
"Non-empty value required in parameter " + parameterName
+ ".");
}
}

/**
* Throws IllegalArgumentException if the specified boolean condition is
* false.
*
* @param condition
* The boolean condition string to check for falseness.
* @param message
* The message to set to the thrown IllegalArgumentException.
*
* @throws IllegalArgumentException
* if passed-in boolean condition is false.
*/
protected void forbid(boolean condition, String message)
throws IllegalArgumentException
{
if (condition)
{
throw new IllegalArgumentException(message);
}
}

/**
* Throws IllegalStateException if the specified boolean condition is false.
* Same as forbid() except an IllegalStateException is thrown rather than
* IllegalArgumentException.
*
* @param condition
* The boolean condition string to check for falseness.
* @param message
* The message to set to the thrown IllegalArgumentException.
*
* @throws IllegalStateException
* if passed-in string is null or empty.
*/
protected void forbidState(boolean condition, String message)
throws IllegalStateException
{
if (condition)
{
throw new IllegalStateException(message);
}
}

/**
* Returns command line arguments that do not have any switch corresponding
* to them.
* 
*
* Alternatively, you can use <code>getValues(getImlicitSwitchName())</code>.
*
* @return The string array consisting of values of switchless arguments in
* the order they appear in the command line.
*/
public String[] getSwitchlessArguments()
{
requireInitialization();
forbidState(switchlessArguments == null,
"Member switchlessArguments must not be null.");
// forbidState(switchlessArguments.length == 0,
// "Member switchlessArguments must not be empty.");
return switchlessArguments;
}

/*
* Deep implementation methods
*/

/**
* Implements the algorithm for parsing command line arguments into
* meaningful pairs of switch name - switch value(s).
* 
*
* This method considers the argument array to follow Java rules for the
* array of arguments passed into Java program's main() method:
* 
* - On the command line, Java program arguments are separated by spaces and
* tabs, except when an argument is enclosed in double quotes.
* 
* - Leading and trailing whitespace characters are removed from the values
* stored in the arguments array.
* 
* - The double-quoted argument is not broken into several separate
* arguments.
* 
* - For arguments enclosed with double quotes, the double quotes are
* removed.
* 
*
* @param args
* Command line arguments.
* @throws IllegalArgumentException
* when a violation of parsing rules is encountered, for
* example, when a switch is present on command line which was
* not specified in a call to setPossibleSwitches().
* @throws IllegalStateException
* when the CommandLineParser object is not initialized, for
* instance, when its the command line arguments have not been
* set yet. You must at a minimum call setPossibleSwitches(),
* setArguments() or setCommandLine() before calling this
* method.
*/
protected void doParsing(String[] args) throws IllegalArgumentException,
IllegalStateException
{
assert possibleSwitches != null;

if (possibleSwitches.isEmpty())
{
throw new IllegalStateException(
"This class must be initialized first by calling setPossibleSwitches() and setArguments() method.");
}
if (args == null)
{
throw new IllegalArgumentException(
"This arguments array must not be null.");
}

// Process array elements one by one, accumulating
// the found switches and their values into switch-to-value list map.

Switch curSwitch = null;
Map<String, Switch> switchByName = new LinkedHashMap<String, Switch>();
List<String> switchless = new ArrayList<String>();

// Implicit switch to hold the switchless arguments
Switch implicit = null;
if (implicitSwitch != null)
{
implicit = createSwitch(implicitSwitch);
implicit.setImplicit(true);
}

// MAIN LOOP: go over arguments one by one, making decisions
for (String arg : args)
{
String argument = arg;
// boolean isLastArgument = (i == args.length - 1);
boolean isSwitch = looksLikeSwitch(argument);
String switchName = isSwitch ? argument : null;
boolean needToFinalizePreviousSwitch = (curSwitch != null)
&& isSwitch;
boolean needToInilializeNewSwitch = isSwitch;

// Parsing rule 1: forbid unknown switches. All switches must be
// declared in a call to setPossibleSwitches().
forbid(isSwitch && !isPossibleSwitch(argument),
"Unknown switch found: "
+ argument
+ ". You must specify this switch in a call to setPossibleSwitches() first.");

if (needToFinalizePreviousSwitch)
{
// Finalize previous switch
if (curSwitch != null)
{
curSwitch = null;
}
}
if (needToInilializeNewSwitch)
{
// Initialize data structures for newly discovered switch
curSwitch = createSwitch(argument);
switchByName.put(switchName, curSwitch);
}

if (isSwitch)
{
// Next will come the switch value, if any
continue;
}
else
{
boolean tooManyArguments = false;

if (curSwitch != null)
{
tooManyArguments = (curSwitch.getValues().size() >= curSwitch
.getMaxValues());
}

if (curSwitch != null && !tooManyArguments)
{
curSwitch.addValue(argument);
}
else
{
// Assign argument to switchless arguments
switchless.add(argument);

// If there is an implicit switch, assign argument to it,
// too.
if (implicitSwitch != null)
{
implicit.addValue(argument);
}
}
}
}
// END OF MAIN LOOP

// Add implicit switch values, if any
if (implicitSwitch != null && implicit.getValues().size() > 0)
{
switchByName.put(getImplicitSwitch(), implicit);
}

// Copy accumulated switch map to CommandLineParser's switch
// collection.
switches.clear();
switchMap.clear();

try
{
for (String switchName : switchByName.keySet())
{
Switch sw = switchByName.get(switchName);
sw.validate();
switches.put(switchName, sw);
List<String> values = new ArrayList<String>(sw.getValues());
// Collections.copy(values, sw.getValues());
switchMap.put(switchName, values);
}
}
catch (IllegalStateException ise)
{
switches.clear();
switchMap.clear();
throw new IllegalArgumentException(ise.getMessage());
}

// Not to forget the rest of the arguments
switchlessArguments = new String[switchless.size()];
for (int i = 0; i < switchless.size(); i++)
{
switchlessArguments[i] = switchless.get(i);
}

// Considered all possible switches?

forbidState(switches == null,
"Post-condition failure: member 'switches' is null");
forbidState(switchMap == null,
"Post-condition failure: member 'switchMap' is null");
forbidState(
switchMap.size() != switches.size(),
"Post-condition failure: member 'switchMap' has different size from member 'switches'");

}

/**
* Returns true if CommandLineParser has been initialized, that is the
* setPossibleSwitches() and setArguments() methods have been called.
*
* @return True if CommandLineParser has been initialized.
*/
public boolean isInitialized()
{
return isInitialized;
}

/**
* Returns the mapping of switch names to list of their corresponding
* values. Example: for command line "--version major minor" a call to
* getSwitchMap() will return a map consisting of one element which maps
* switch "--version" to list of two values, "major" and "minor" (without
* quotes).
*
* @return The mapping of command line switch names to lists of their
* corresponding values.
*/
public Map<String, List<String>> getSwitchMap()
{
return switchMap;
}

/**
* Adds a switch to the required switches.
* 
* Example:
*
* <pre>
* addPossibleSwitch("--switch(0-*)");
* </pre>
*
* will allow for the command line switch <code>--switch</code> with zero to
* infinite number of arguments.
*
* @param switchSpecification
* Name and cardinality of switch, e.g. --file(1), meaning that
* the --file switch requires exactly one argument.
*/
protected void addPossibleSwitch(String switchSpecification)
{
forbidEmptyString(switchSpecification, "switchSpecification");
switchSpecification = switchSpecification.trim();
String switchName = removeCardinality(switchSpecification);
forbid(isPossibleSwitch(switchName), "The possible switch "
+ switchName + " is already defined for this object.");

if (!possibleSwitches.contains(switchSpecification))
{
if (!switchSpecification.endsWith(")"))
{
throw new IllegalArgumentException(
"Incorrect format of switch:"
+ " each switch must be followed by numbers in parenthesis specifying the required number"
+ " of its values, e.g. \"--version(0), --file(1) --twomore(2-*) --any(*)\"");
}

possibleSwitches.add(switchSpecification);
}
}

/**
* Removes a previously specified with a call to
* <code>addPossibleSwitch()</code> or <code>setPossibleSwitches()</code>
* switch from the set of required switches.
* 
* Example:
*
* <pre>
* removePossibleSwitch("--switch(0-*)");
* -or-
* removePossibleSwitch("--switch");
* </pre>
*
* will remove the switch <code>--switch</code> from the set of possible
* command line switches.
*
* @param switchSpecification
* Name and cardinality of switch, e.g. --file(1), specifying the
* --file switch which requires exactly one argument.
*/
protected void removePossibleSwitch(String switchSpecification)
{
forbidEmptyString(switchSpecification, "switchSpecification");
switchSpecification = switchSpecification.trim();
int firstBrace = switchSpecification.indexOf("(");
boolean bracePresent = firstBrace != -1;
String switchName = bracePresent ? switchSpecification.substring(0,
firstBrace).trim() : switchSpecification;
boolean found = false;

if (bracePresent && !switchSpecification.endsWith(")"))
{
throw new IllegalArgumentException(
"Incorrect format of switch:"
+ " each switch must be followed by numbers in parenthesis specifying the required number"
+ " of its values, e.g. \"--version(0), --file(1) --twomore(2-*) --any(*)\"");
}

for (String possibleSwitch : possibleSwitches)
{
int brace = possibleSwitch.indexOf("(");
assert brace != -1;
String name = possibleSwitch.substring(0, brace).trim();

if (bracePresent && possibleSwitch.equals(switchSpecification)
|| !bracePresent && switchName.equals(name))
{
possibleSwitches.remove(possibleSwitch);
found = true;
break;
}
}

if (!found)
{
throw new IllegalArgumentException(
"Switch "
+ switchSpecification
+ " is not found in the collection of possible switches. You must first call "
+ " setPossibleSwitches() or setImplicitSwitch(), or check the spelling of the argument.");
}
}

/**
* Creates a new Switch object for the specified switchName. Switch name
* must be one of possible switches (see
* {@link CommandLineParser#setPossibleSwitches}() method)
*
* @param switchName
* The name of switch, e.g. --file, or its specification, e.g.
* --file(1).
* @return The newly created Switch object.
*/
public Switch createSwitch(String switchName)
{
boolean switchSpecificationFound = false;
String name = null;
int minValues = -1;
int maxValues = -1;

Set<String> switchCandidates = new LinkedHashSet<String>(
possibleSwitches);

if (implicitSwitch != null)
{
switchCandidates.add(implicitSwitch);
}

for (String switchSpecification : switchCandidates)
{
assert switchSpecification.endsWith(")");
if (switchSpecification.startsWith(switchName))
{
boolean nameIsSpecification = switchName
.equals(switchSpecification);
int leftBrace = switchSpecification.lastIndexOf("(");
int rightBrace = switchSpecification.lastIndexOf(")");
forbid(leftBrace == -1,
"Malformed switch specification: missing left brace.");
forbid(rightBrace == -1,
"Malformed switch specification: missing right brace.");
forbid(leftBrace > rightBrace,
"Malformed switch specification: left brace found after right brace.");
forbid(leftBrace == rightBrace - 1,
"Malformed switch specification: a number or an interval"
+ " must be specified between left and right braces.");
name = switchSpecification.substring(0, leftBrace);

if (switchSpecificationFound)
{
break;
}
}
}

forbid(!switchSpecificationFound,
"Switch "
+ switchName
+ " is not found among the possible switches or implicit switch. "
+ " Check if this switch is specified in a call to setPossibleSwitches() or setImplicitSwitch()");

Switch newSwitch = new Switch(name, minValues, maxValues);
return newSwitch;
}

/**
* Returns true if switch name looks like a switch, that is, starts with one
* of the prefixes specified by the <code>switchPrefixesMask</code>.
*
* @param switchName
* Name of switch.
* @return True if switch name starts with one of the prefixes specified by
* the <code>switchPrefixesMask</code>.
*/
protected boolean looksLikeSwitch(String switchName)
{
boolean looksLikeSwitch = switchName.matches("^" + switchPrefixesMask
+ ".*");
return looksLikeSwitch;
}

/**
* Returns true if switch is among possible switches that are specified with
* a call to <code>setPossibleSwitches()</code> or
* <code>setImplicitSwitch()</code>.
*
* @param switchName
* Name of switch, e.g. --file
* @return True if switch is among possible switches.
*/
public boolean isPossibleSwitch(String switchName)
{
boolean result = false;

for (String possibleSwitch : possibleSwitches)
{
int leftBrace = possibleSwitch.indexOf("(");
forbid(leftBrace == -1, "Misformed possible switch element: "
+ possibleSwitch);
String name = possibleSwitch.substring(0, leftBrace);
if (switchName.equals(name))
{
result = true;
break;
}
}
return result;
}

/**
* Removes switch cardinality (the numbers in braces in the end of switch
* specification) from switch specification. If cardinality is not present,
* returns the same string as the passed-in argument.
* 
* Example: <code>removeCardinality("--file(0-*)")</code> will return string
* "--file"
*
* @param switchSpecification
* Name and cardinality of switch, e.g. --file(0-*)
* @return Name of switch without cardinality, e.g. --file.
*/
protected String removeCardinality(String switchSpecification)
{
forbidNullString(switchSpecification, "switchSpecification");

String result;

int leftBrace = switchSpecification.indexOf("(");
int rightBrace = switchSpecification.indexOf(")");

if (leftBrace != -1)
{
forbid(rightBrace == -1,
"Malformed switch specification: must have left and right braces");
forbid(rightBrace < leftBrace,
"Malformed switch specification: must have right brace after left brace");
result = switchSpecification.substring(0, leftBrace);
}
else
{
forbid(rightBrace != -1,
"Malformed switch specification: must have left and right braces or have neither");
result = switchSpecification;
}

return result;
}
}

</nowiki></pre>

My 2 cents for Humanity

Andrey — Sat, 22 Oct 2011 22:26:26 GMT

Summary:

Here is a utility class I wrote to help writing command line applications. It is surprising how often a command line app directly validates its argument array instead of delegating it to some kind of parser. Use it as you like.

[[CommandLineParser.java]]

[[CommandLineParserTest.java]]

P-Patterns!

Andrey — Mon, 06 Feb 2006 20:09:27 GMT

Summary:

== P-Patterns ==

Some design patterns I came up with.

== Smart Button ==

Suppose you bought a futuristic DVD player - a slick black box with a single tiny hole for the microphone. It does amazing job of recognizing voice commands. To open the drive bay you would say 'Open the drive'. To pause, you would say 'Do pause', and so on. You liked it in the beginning, but unfortunately, you have to always consult the product manual, because you have to memorize exact commands. For example, one day you might say 'Pause' instead of 'Do pause', and it wouldn't react. Finally, you start wanting a more traditional interface - the one with the buttons, so to operate it you wouldn't have to remember commands. With several buttons, you have complete control over the device and do not have to consult the manual!

The design pattern is:

Expose a generic object in the interface in order to simplify class use.

This is the case for exposing an object in the interface. I know that there is opposition for doing so, and even a law ([http://www.ccs.neu.edu/home/lieber/LoD.html Law of Demeter]). However, I choose to say that exposing an object that belongs to a generic, well-known class (in the above case, a button) in the interface provides for simpler, more intuitive designs. Compare this to hiding everything under a monolith interface with a laundry list of methods.

Not being entirely opposed to the Law of Demeter, however I often felt that it stems from assumption that we couldn't fully control an object after exposing it in the interface. While it is true in some OO languages, there are designs and approaches that provide for such control ([[Overriding_in_Owner_Class |Example]]). In the presence of such mechanisms, the Law of Demeter may be less crucial.

On the other hand, I'm definetely not advocating for breaking encapsulation and exposing inner objects in class interface. In our example with a DVD player, it only would make sense to expose some objects (buttons, indicators) while keeping others - the one that really do the job - encapsulated. Therefore, more precisely, we want to only expose very generic objects providing for intuitive control, while keeping implementation-specific parts still hidden inside the class.

== Postponed Validation ==

Let's say we have a setProperty() method which changes the value of an object field. One typically validates method arguments within in the body of the method; and sometimes you need more extensive validations. Extra validations may be taxing on performance, especially when the method is called multiple times. In the Postponed Validation pattern, you perform extra validations in the time of a commit. If a validation rule is broken, perform a rollback. Postponing validations until commit lets you ensure data integrity while maintaining high performance.

Postpone object validation until a checkpoint/commit, so that validations do not hinder performance.

One way to implement postponed validation is '''Detached Validation'''. Create a flag in your class to switch validations on and off, and perform a full validation each time the flag is turned on. While in the 'detached' state (flag is off), skip validations thus improving performance. Enforce each object to be back to its non-detached (flag on) state before a commit/checkpoint.

== Static resolution ==

Hide a class behind a static interface to cut on code verbosity and improve readability. As an alternative to creating a Singleton and retrieving it through getInstance() method, create an extra class that implements same interface through static methods, and provide one instance of your Singleton as a work horse for that class. The client code which looked like

Logging logging = Logging.getInstance();
logging.error("my message");

becomes this:

Log.error("my message");

where Log is a static interface now serving as a facade for the Logging class. Bonus: you get a better English capitalization this way!

== Pure Business Objects ==

Divide model classes into pure business objects and their application-specific implementations related through inheritance. In the client code, only deal with pure business object classes. In instantiating/factory/injection code, only instantiate their application-specific implementations. Utilize Bridge design pattern to decouple inheritance graphs of the two hierarchies, thus separating the model from application-specific behavior.

Conclusion

Andrey — Fri, 03 Feb 2006 07:04:58 GMT

Summary:

The main point of this article is to consider the nature of an '''object's behavior as consisting of two aspects''': the general behavior, provided by its class, and the behavior specific to a particular context in which the object is used. Conceptually, overriding in owner class is the '''''mechanism for separating the object's behavior specific to a particular context (role) from the behavior specific to its class'''''. Thus, overriding in owner class introduces a '''different way to organize the code defining the behavior'''. Looking at the examples within this article, one can see that it can make it easier to accomplish a variety of tasks, such as:

* to enforce class invariants concerning a member, as is done in the example with [[Definition_of_Overriding_in_Owner_Class#Lee_jeans|''lee_jeans'']];
* to create an object managing two-way input and output, as is done in the example with [[Applications_of_Overriding_in_Owner#Visual_cash|''visual_cash'']];
* to solve the updates issue, as is done in the example with [[Applications_of_Overriding_in_Owner#Working_girl|''working_girl'']];
* to write a class for immediate reuse without implementing all the minor details, as in the example with [[Applications_of_Overriding_in_Owner#Circular_gauge|''circular_gauge'']];
* to simplify and "objectify" the interface of a class, as in the example with [[Applications_of_Overriding_in_Owner#Int_property|''int_property'']].

Overriding in owner class can affect the way you create the designs, particularly in how you set up objects of unrelated classes to work together; how the processing of an action is split from its cause; how reusable classes are written. I think that this approach will help minimize dependencies between classes; reduce their need for updates; avoid redundant subclassing and dynamic structures; provide fuller control over class members. The ease with which this mechanism fits into C++ and the fact that it does not, in my opinion, create inconsistencies in the language makes me think that it logically and usefully extends the language.

== Acknowledgments ==
I am grateful to Vitaly Shmatikov for reviewing the draft of this paper and helping in its improvement.

== References ==
[1] A. Potekhin “[[Implementation_of_Overriding_in_Owner_Class|Implementation of Overriding in Owner Class]].”

[2] E. Gamma et al., “Design Patterns, Elements of Reusable Object-Oriented Software”

'''[[Main_Page|To Main Page]]'''

Inside the Overriding Mechanism

Andrey — Fri, 03 Feb 2006 06:59:32 GMT

Summary:

Among possible implementations of overriding in owner class the most natural is to use the same mechanism of dynamic binding through the virtual method tables as for the usual overriding. The implementation described below is simple, straightforward, does not require special data structures, does not interfere with other language features, and does not require additional memory. The efficiency of a call to an overridden member’s method is the same as of a call to a virtual function of an object, when not optimized by knowing the exact type.

The process of overriding in owner class consists of the following steps:

# A new virtual method table is created for the member.
# The new table is initialized with the data from the original table.
# In the new table, the address of the original function(s) is changed to the address of the function override(s).
# The pointer to the virtual method table in the member object is modified to point to the new table.
# When entering the body of the function override, ''this'' pointer value is modified to point to the owner object.

Step 5 needs further explanation. When entering the override, ''this'' points to the member for which the function has is been called. But the code of the override resides in the owner class, and deals with the owner class - its other members, its environment, etc. It requires ''this'' pointer to point to the owner object. Therefore, ''this'' must be modified. It is modified by subtracting the offset between the owner and the member object. The place of the member inside the owner class is known in the compile time, so the modification of ''this'' is merely the subtracting of a constant.

[[Image:Overriding.gif|center]]

The first three steps are done one time, when the owner class is initialized. Step four is done every time the owner class is instantiated. Step five is done every time the overridden function is called, when entering the body of the function override. The result of steps 1-4 is a structure shown above. In the figure, PVTBL is a pointer to a virtual method table from an instance of a class; A VTBL is a virtual method table of class A, and B VTBL for B::a is virtual method table created in step one.

One concern that may arise is about the stability of the pointer to the member’s new virtual method table. Can it suffer when an object of the owner class, or its subclass, is assigned to with an object of the owner class when C++ copies objects "by bits", i.e. when the default assignment operator is used? Fortunately, the answer is no. C++ guarantees that such copying affects neither the pointer to the virtual method table in the owner object, nor the pointers to the virtual method tables in its members.

Algorithm 1-5 was used when implementing overriding in owner class in [1]. [1] contains description of this work, more details, including the information on the modification of ''this'' in case of multiple inheritance, the source code, and the usage sample.

'''Next: [[Conclusion]]'''

Questions

Andrey — Fri, 03 Feb 2006 06:58:15 GMT

Summary:

''Does overriding in owner class break strict type checking?'' No, because the signature of the function override must conform to the signature of the overridden function. The conformity is checked in the compile time.

''Does the new overriding break encapsulation?'' No, because the override has the same access rights to the member as the owner class itself.

''Does it break the logic of the member's use by allowing arbitrary changes to its behavior?'' No, because only a virtual function can be overridden. The presence of a virtual function indicates the class was designed to allow change.

''Can the use of overriding in owner class lead to losing control over an already debugged and tested class?'' New overriding uses only the public interface of the member's class; hence its application is a use of the class, not its extension or modification.

''Is the desire to change an object's behavior without subclassing an indicator of a poor design?'' Yes - when the change in behavior is big enough to form a new class. When the change is minor, this is not the case.

''Some compilers use the knowledge of the exact type of an object to optimize a virtual method call. If methods of a class member can be overridden, the compiler can no longer count on the member’s exact type. This can lead to the generation of slower code.'' This is a very serious question, and losing this kind of optimization would be a big sacrifice. There are several ways to resolve this issue:

* The first method is to limit the depth of overriding to just one level, forbidding overriding the methods of a member’s members. The override will be in the same place as the member, and the compiler will know how to make an explicit call.

* The second way is to introduce another language keyword, something similar to ''volatile'', to indicate that the compiler cannot count on knowing the exact member’s class.

* The third solution, which appeals to me the most, is to reuse an existing language keyword. I would like to use the qualifier ''virtual'' to indicate that the compiler cannot count on knowing the exact member’s class. I leave the question of what way is the best and what other solutions might be for further discussion.

''Does overriding in owner class break legacy code?'' No, because it does not change the member's interface. The behavior of the member changes, and this change, provided that it preserves the type, is the purpose of polymorphism in general and overriding in owner class in particular.

'''Next: [[Inside the Overriding Mechanism]]'''

Discussion of Alternatives

Andrey — Fri, 03 Feb 2006 06:52:17 GMT

Summary:

Let's consider the alternatives that are used in the existing designs for C++. Suppose Helen has a pager:

class motorola2sx{ public: void call(); };

class working_girl{ public: motorola2sx pager; } Helen;

The task is to provide a mechanism that will enable ''working_girl'' class to know that the ''call()'' function of its ''pager'' member has been called. There can be the following solutions:

1. Hide the member and make its interface a subset of the interface of the owner class, not allowing the client to directly access the member:

class working_girl { public: callpager(); protected: motorola2sx pager; };

Drawbacks: it will be necessary to maintain the duplication of the pager interface by ''working_girl'' class. It will also be necessary to rewrite the telephony algorithms to make them work with the ''working_girl'' class (or its base class).

2. Create a pointer to the owner in the member.

motorola2sx::call() { owner->on_incomingcall(); }

This introduces the knowledge about ''working_girl'' into ''motorola2sx'', which is not very logical. This in turn creates two dependencies: a dependency of classes, and a run-time dependency. We could create an abstract class for accepting pager calls with ''working_girl'' inheriting from this class, but that would again increase the number of classes and dependencies in the system.

3. Make motorola2sx a template.

<pre>
class working_girl
{
public:
motorola2sx<working_girl> pager;
void on_incomingcall();
};
</pre>

This requires ''working_girl'' to support a certain interface. The manufacturers of pagers, telephones, etc. will have to agree on a standard protocol for call notification. Any changes in the protocol will involve all the products and all people, which can result in high costs.

4. Create a special custom wrapper class ''working_girl_pager'':

<pre>
class working_girl_pager : public motorola2sx
{ public: void call() { callback(); } };

class working_girl
{ public: working_girl_pager pager; friend class working_girl_pager; };
</pre>

The ''working_girl_pager'' will have unnecessary access to the internals of ''motorola2sx''. It will have to be adjusted every time the interface of motorola2sx changes. ''Working_girl_pager'' will have to have full access to the internals of ''working_girl'', because it has to implement the reaction to a call. Besides, ''working_girl_pager'' is absolutely non-reusable.

5. Encapsulate the concept, which varies. Because the processing of calls is what can be different for different owners, take it outside of ''motorola2sx'', encapsulating it in a separate class:

<pre>
class pager_calls_acceptor { public: virtual void on_call()=0; };

motorola2sx::call() { calls_acceptor->on_call(); }

class working_girl_calls_acceptor : public pager_calls_acceptor {
working_girl* girl;
public:
void on_call() { girl->callback(); }
};
</pre>

Drawbacks: creation and maintenance of the additional dynamic structures (a pager keeps a pointer to a ''pager_calls_acceptor'', pointing to a concrete ''working_girl_calls_acceptor'', which in turn keeps a pointer to ''working_girl'' which owns an instance of the pager as a member).

6. Create a broadcast mechanism and send a message that Helen's pager has been called

motorola2sx::call() { broadcast->message(somebody_is_calling, this); }

The approach can incur a computational overhead, since the message will have to be processed in all of the objects reacting to the broadcast. In addition, the broadcast code is difficult to write and debug. Finally, any object reacting to the broadcast may be able to overhear calls to Helen.

7. Inherit ''working_girl'' from ''motorola2sx''
class working_girl : public motorola2sx { public: void call() { callback(); }};

Although it is logically unsatisfying, let's include this approach as well. It distorts the purpose of ''working_girl'', making it a subtype of ''motorola2sx''. The internals of the base classes are exposed to ''working_girl'', breaking encapsulation. If there is more than one object for ''working_girl'' to control, we need multiple inheritance, possibly opening the door to ambiguity problems.

The approaches 1-7 also have the following traits.
* Approach 1, as the approach 7, distorts the purpose of working_girl, making it a subtype of motorola2sx.
* Approaches 2, 3, 5, and 6, in order to adapt the member pager to work with its owner, modify the class of pager by adding the code for notifications. This leads to problems discussed earlier in “[[Applications_of_Overriding_in_Owner#Problem_of_Dependencies|The Problem of Dependencies]]”, “[[Applications_of_Overriding_in_Owner#Problem_of_Notifications|The Problem of Notifications]]”, and “[[Applications_of_Overriding_in_Owner#Code_Reusability|Code Reusability]]” sections.
* The disadvantages of approach 4 are shown in “[[Applications_of_Overriding_in_Owner#Exporting_a_Member_in_the_Interface|Exporting a Member Object in the Interface]]” section.
* Approaches 1, 2, 4, 5, 6 add new members, functions or classes to the system.

8. Using overriding in owner class differs from most of these approaches by narrower area of application, because an object for which the overriding is done must be included in the owner class as a contained member, while most of the other approaches can be used when the object is accessible through a pointer or a reference. However, in its area of application, overriding in owner class will have certain advantages. ''Override the function in the owner class:''

<pre>
class motorola2sx{ public: virtual void call()=0; };

class working_girl
{
public:
motorola2sx pager;
void pager::call() { callback(); }
};
</pre>

The results of are summarized in the following table. The columns represent the numbers of described solutions:

{| style="width:75%;" border="1" cellpadding="0" cellspacing="0" align="center"
| || width="25" align="center" | 1 || width="25" align="center" | 2 || width="25" align="center" | 3 || width="25" align="center" | 4 || width="25" align="center" | 5 || width="25" align="center" | 6 || width="25" align="center" | 7 || width="25" align="center" | 8
|-
| Increasing class dependencies || || bgcolor=black | || bgcolor=black | || bgcolor=black | || bgcolor=black | || || ||
|-
| Necessity of updates || || bgcolor=black | || bgcolor=black | || || bgcolor=black | || bgcolor=black | || ||
|-
| Breaking encapsulation || || || || bgcolor=black | || || || bgcolor=black | ||
|-
| Client code changes || bgcolor=black | || || || || || || ||
|-
| Creation and maintenance of additional classes || || || || bgcolor=black | || bgcolor=black | || bgcolor=black | || ||
|-
| Creation and maintenance of special dynamic struc-tures || || || || || bgcolor=black | || bgcolor=black | || ||
|-
| Reducing efficiency, redundancy || || || || || || bgcolor=black | || ||
|-
| Complication of debugging || || bgcolor=black | || || || bgcolor=black | || bgcolor=black | || ||
|-
| Changing the logic of use || bgcolor=black | || || || || || || bgcolor=black | ||
|-
| Making it harder to understand the code || bgcolor=black | || || || || || || bgcolor=black | ||
|-
| Undermining reusability || || bgcolor=black | || bgcolor=black | || || bgcolor=black | || bgcolor=black | || ||
|}

'''Next: [[Questions]]'''

Applying to Design Patterns

Andrey — Fri, 03 Feb 2006 06:48:49 GMT

Summary:

Overriding in owner class can also be applied to the design patterns described in [2]. Moreover, it can simplify the applications of some patterns.

=== Pluggable adapter ===

The Pluggable Adapter pattern is used when code requires a special interface from an object. To provide such an interface, a class called adapter is created and passed to the code.

[[Image:Adapter.gif|center]]

Client code works with an abstract adapter, defining the interface. The actual adapter is an instance of a concrete adapter class, working with the particular class it adapts. Process of adaptation consists of creation of the concrete adapter class, overriding the functions of abstract adapter, and giving an instance of a concrete adapter to the client code.

Overriding in owner class allows doing the adaptation without creating a concrete adapter class and an object.

'''Example.''' A pluggable adapter without need for an intermediate class.

<pre>
// abstract adapter
class interview_adapter
{
public:
virtual answer ask(question q) =0;
};

// class to adapt – no concrete adapters
class person
{
public:
interview_adapter interviewee;
answer interviewee::ask(question q) { return think_hard(q); }
};
</pre>

=== Chain Of Responsibility ===

This pattern deals with the situation when an object processing a request is not known to the object initiating a request.

[[Image:Chain.gif|center]]

Suppose the user has pressed a dialog button, such as a help button, but the knowledge about what to do is not in the button class, and not in its owner, the dialog, but is in the class which owns the dialog - the application's main window. The object ‘main window’ is not known to the object ‘button’. To transmit the request to the processing object, Chain Of Responsibility uses inheritance: we make the button, the dialog, and the main window subclasses of a class that is able to process the request (for instance, of the class ''HelpHandler'' with a virtual function ''Help()''). When the request comes, the button uses the default implementation of the handler, which redirects the request to the owner (''owner->Help()''), and it is repeated until the request reaches an object capable of processing it. To apply the Chain Of Responsibility pattern, we have to make the classes in the chain a) share an interface for processing a particular request, and b) know about the owner object. Such requirements mean that the Chain Of Responsibility can be applied only if all its participants were designed to participate in it. It will be necessary to modify all the classes in the chain if we need to process a new type of request (e.g. another button).

Overriding in owner class can help eliminate these drawbacks. Indeed, it is a vehicle for transferring the request from the initiator to the acceptor with no need for the participants to implement any interface(s), and with no need to create additional classes and protocols.

'''Example.''' An example of an application SaveAs dialog.

<pre>
class button
{
public:
virtual void press() =0;
};

class saveas_dialog
{
public:
string new_name;
button OK;
button Help;
};

class main_window
{
public:
saveas_dialog saveas;

saveas::OK::press() { save(active_document(), saveas.new_name); }
saveas::Help::press() { run_help(HLP_SAVEAS); }
};
</pre>

Note, that the code of the intermediate class, ''saveas_dialog'', remains free from processing and transporting the requests. It does not even have to know it participates in the Chain Of Responsibility!

=== Mediator ===

The Mediator pattern is used to decrease dependencies when objects work in a composition. When the objects have to manipulate each other, it may have a negative impact on the reusability of their code. It also complicates the modifications of the composition, “because its behavior is distributed among objects” [2]. As a solution, a mediator object is created, which encapsulates collective behavior, removing the need for the parts of the composition to directly ‘talk’ to each other. All the requests come from and go to the mediator object:

[[Image:Mediator.gif|center]]

The Mediator pattern frees the classes of the participants from needing to know about each other. However, classes still have to know about the mediator class, and how to deal with the mediator object. Applying overriding in owner class to the Mediator pattern lets us to avoid the creation of: a) a special mediator class; b) a run-time mediator object; and c) a protocol participant-to-mediator. This leaves the code of the participant classes not only free from having to know about each other, but also free from knowing about their participation in the composition.

'''Example.''' Consider a form displaying database records, consisting of a list of items in the database (''items'' listbox), a picture representing a currently selected item (''picture'' image), a description of the item (''description'' editbox). The user can edit the description. When the user finishes editing, he/she presses the ''apply'' button to enter the data in the database. The behavior of the parts in the form should be coordinated: picture and description must refresh when the current item selection changes; the ''apply'' button should be disabled until the user changes the item description, after pressing ''apply'', the changes should be written to the database. These interactions are shown in the figure below. The arrows show how the objects influence each other. Underlined objects are the ones that are visible to the user. In the Mediator pattern, we need to create an object that accepts requests from the participants, processes them and issues requests/updates to other participants. Overriding in owner class will allow us to eliminate the mediator class, the mediator object, and the mediator protocol by overriding member functions of the participants in the composition class. '''The classes of the participants will not have to support the protocol of mutual requests and updates. They will not have to deal with some designated object to send the notifications to.''' Instead, the owner class will take care of all the traits in the behavior of its components specific for the work in the form.

[[Image:Form.gif|center]]

<pre>
class dbform
{
database& data;
long current_index;
dbitem current_item;

public:
listbox items; // list of items in stock
bitmap picture; // current item image
editbox description; // current item description
button apply; // apply changes button

// constructor
dbform(database& d) : data(d) {}

// listbox handlers
void items::init()
{
items.source = data.list();
items::change();
}

void items::change()
{
// selecting an item
current_index = items.selection();
current_item = data(current_index);
description.update();
picture.update();
apply.enable(false);
}

// editbox handlers
void description::update()
{
description.set(current_item.description);
}

void description::changed()
{
apply.enable(true);
}

// bitmap handler
void picture::update()
{
picture.set(current_item.picture);
picture.redraw();
}

// button handler
// called when user presses the button
void apply::press()
{
current_item.description = description.get();
data.set(current_index, current_item);
}
};
</pre>

'''Next: [[Discussion of Alternatives]]'''

Applications of Overriding in Owner

Andrey — Fri, 03 Feb 2006 06:12:20 GMT

Summary:

Overriding in owner class can be helpful in the following situations: composing objects for collective work; customizing an object’s behavior for a particular use; propagating requests from components to aggregates; implementing control over manipulations on class members; and others.
We will consider the application of overriding in owner class to the following problems:

== Problem of Dependencies ==
Consider class F with members a and b, belonging to classes A and B respectively. Code C1 works with class B. When changes happen to F::b, F::a must be changed. This means that B, otherwise not tied with A, must know about A's existence to send a notification (the knowledge about A is brought into B, introducing member-to-member dependency). Alternatively, B must know about F's existence, to get F to notify F::a (the knowledge about F is brought into B, introducing member-to-owner dependency). The third solution is to rewrite code C1 to work with F instead of B (the knowledge about F is brought in C1, the interface of B or its part is included in the interface of F).

[[Image:over1.gif|center]]

'''Problem:''' Developing a system from components, one has to make the code of some components depend on the existence, interface, and/or behavior of others.

Overriding in owner class (overriding methods of F::b in F) allows one to leave the code of B and C1 free from the need to know about owners and neighbors. It lets B remain simpler and more reusable, and leaves C1 unchanged. The details specific to F stay where they should: in class F.

<div id="Visual_cash"></div>

'''Example.''' The ''visual_cash'' class is a screen representation of money, made of two parts: ''cash'', providing data for the financial algorithms, and ''editbox'', reflecting changes made by the algorithms on screen and letting the user edit the amounts. Problem: changes made to one part must be reflected in the other. How to write these classes?

<pre>
class visual_cash
{
public:
cash value; // data
editbox face; // representation

// overriden functions connect
// data with representation

void value::set(float l)
{
value.cash::set(l);
face.set_text(value.get());
}

void face::init()
{
face.set_text(value.get());
}

void face::changed()
{
// when the user changes the text
// in the widget, value is updated.
value.cash::set(to_float(face.get_text()));
}
} visual_money;

// Pass visual_money.value to an algotithm,
// and if it is changed, the display is updated.
invest(&visual_money.value);
</pre>

The components of ''visual_cash'' class are coordinated, however classes ''editbox'', ''cash'' and the algorithms like ''create_profit()'' remain free from the need to know about each other. The composition-specific peculiarities remain in the composition class.

== Problem of Notifications ==

There is a class B with a member a, belonging to class A. Code C1 works with objects of class A, in particular with the member of B. B should know what C1 does to B::a. Thus A should notify B about the operations performed on itself, or C1 should be changed to notify B about them.

[[Image:over2.gif|center]]

'''Problem:''' The code that makes changes must issue notifications about them.

Overriding in owner class (overriding methods of B::a in B) allows to one leave the code of A and C1 free from sending notifications to B about what happens to B::a. The code of A remains simpler and more reusable, the code C1 does not change.

<div id="Working_girl"></div>

'''Example.''' Helen has a pager. She has to know about incoming calls.

<pre>
// pager class
class motorola2sx
{
public:
virtual void call();
};

class working_girl
{
public:
motorola2sx pager;

// making owner know about call
void pager::call() { callback(); }
} Helen;

// calling Helen
Helen.pager.call();
</pre>

In this example, thanks to using overriding in owner class, notifications are completely absent. Reacting to the incoming calls is the responsibility of the pager owner, and, according to this, the code reacting to calls resides in the owner class. The ''motorola2sx'' class is focused on solving its own problems. The vendor of ''motorola2sx'' does not have to take care of the need to notify somebody about the calls.

== Code Reusability ==

Class A is adapted for work with B, but the tight coupling to the interface and behavior of B makes it hard to adapt A for work with C.

[[Image:over3.gif|center]]

'''Problem:''' The peculiarities specific to how an object's works with other objects find themselves in the object's class and make the latter less reusable.

With the help of overriding in owner class, the code specific to the role played by B::a in B can be placed in class B, with the result of improving A's reusability.

<div id="Circular_gauge"></div>

'''Example.''' This is an example of a circular gauge that can be used in various devices:

<pre>
class circular_gauge
{
public:
virtual float get_data() =0; // called by draw() to display current value
void draw();
}

class voltmeter
{
public:
circular_gauge face;
float face::get_data() { return voltage(schema, loc); }
};

class compass
{
public:
circular_gauge face;
float face::get_data() { return azimuth(); }
};

class speedometer
{
public:
circular_gauge face;
float face::get_data() { return weel[0].rotationspeed() * weel[0].radius; }
};
</pre>

Because the ''circular_gauge'' class does not contain code specific to the various devices and does not use special protocols, like notifications, it is well suited for use with any of them. Note that even though ''circular_gauge'' has a pure virtual method, in the presence of a new overriding mechanism it is a complete, ‘off the shelf’, ready to use component.

== Exporting a Member in the Interface ==

I want to let the client of B apply code C1 to B's member B::a, but B is not aware of the changes C1 can make.

[[Image:over4.gif|center]]

'''Problem:''' Exporting (making public) class members in C++ is complicated by the absence of mechanisms allowing a class to control what happens to its members.

Currently the necessary job is done by adding new classes and dependencies to the code. For example, one solution is to make B::a belonging to a class A1, inheriting from class A extended to notify B. It has a number of drawbacks, which are discussed later in detail in the “Comparison with Alternatives” section. Overriding in owner class (overriding of the methods of B::a in B) lets B control its members without resorting to subclassing or introducing new dependencies.

<div id="Text_editor"></div>

'''Example.''' Consider an ''editor'' having a ''selected_text'' having a ''font''. When changing the ''font'', it is necessary for the ''editor'' to ''update_display()''. We can do it by overriding the methods of the ''font'' member of the ''editor'' class’s ''selected_text'' member.

<pre>
class text_font
{
int size;
public:
virtual void set_size(int i){ size = i; }
};

class text_run
{
public:
text_font font;
};

class editor_app
{
text_run all_text;
public:
text_run selected_text;

virtual void selected_text::font::set_size(int i)
{
// call the original
selected_text.font.text_font::set_size(i);
// draw changes
update_display(selected_text);
}
} editor;

void some_func(text_run& text)
{
text.font.set_size(default_size);
}

// see changes reflecting on the screen
some_func(editor.selected_text);
</pre>

In this example, the algorithms manipulating the text (''some_func'') need not know about the classes that depend on the changes. The code of ''text_run'' does not have to transmit requests from the receiving object (''text_run::font'') to the object that participates in their handling (''editor''), because it is taken care of by overriding in owner class mechanism. Note that the class ''text_run'' is not required to override functions of its member ''font''.

== Implementing the Concept of Property ==

I want to interpret B::a not simply as a member of B, but as its ''property''. In other words, when one requests the value of B::a, I want some function to get called.

'''Problem:''' There are no mechanisms in C++ allowing hiding a function behind a member's name.

Here is how we can do something like a property with standard C++:

<pre>
// abstract property class
class int_property
{
public:
virtual operator int() =0;
virtual int operator =(int i) =0;
};

class window;

// concrete property class
class window_width : public int_property
{
public:
window *owner;
operator int();
int operator =(int i);
};

class window
{
public:
window_width width;
};

// implementations
window_width::operator int() const { return ::get_window_width(owner); }
int window_width::operator =(int i) { ::set_window_width(owner, i); }
</pre>

The ''window'' class exports an object of the class ''window_width'' in its interface. To begin with, there are disadvantages caused by exporting a member. Secondly, because ''window_width'' knows the interface of the owner class, the approach has the disadvantages described above in “The Problem of Dependencies”. Thirdly, the class ''window_width'' is absolutely non-reusable.

<div id="Int_property"></div>

Overriding in owner class allows us make a more elegant implementation of the property concept:

<pre>
// an abstract class for all integer properties
class int_property
{
public:
virtual operator int() =0;
virtual int operator =(int i) =0;
};

class window
{
public:
int_property width;

// a property customized for the window class
width::operator int() const { return ::get_window_width(this); };
int width::operator =(int i) { ::set_window_width(this, i); } ;
};
</pre>

'''Next: [[Applying to Design Patterns]]'''

Definition of Overriding in Owner Class

Andrey — Fri, 03 Feb 2006 06:08:51 GMT

Summary:

Consider a class A with a public virtual function f():

<pre>
class A {
public:
virtual int f();
};
</pre>

Class B contains a member a belonging to class A:

<pre>
class B {
A a;
};
</pre>

It is necessary to perform certain actions in B at the moment the user code calls method f() of its member B::a.

:'''The mechanism of overriding in the owner class is an extension of polymorphism allowing a virtual function of class A to be overridden in class B which includes an object of A as a member.'''

According to this definition, f() can be overridden ''in class B''

<pre>
class B {
A a;
int a::f();
};
</pre>

so that the following is true:
a.f(); // B::a::f() is called, instead of A::f()
…
A& r = a;
r.f(); // B::a::f() is called, instead of A::f()

Now every time the client calls f() on B::a, B is aware of it. B also has the possibility to adapt f()'s implementation to its own needs.

<div id="Lee_jeans"></div>
'''Example.'''
<pre>
class size
{
long value;
public:
long get() { return value; }
virtual void set(long l) { value == l; }
};

class lee_jeans
{
size waist, inseam;

void waist::set(long l)
{
assert(l > 28 && l <= 36 );
// call the original
waist.size::set(l);
}
void inseam::set(long l)
{
assert(l > 30 && l <= 42 );
// call the original
inseam.size::set(l);
}
};
</pre>

This example shows how overriding in the owner can help a class to control the values assigned to its members.

'''Requirements to participating classes.'''

Overriding in owner has the following requirements to participating classes:

# The first participating class (class A) must declare a public virtual function.
# The second participating class (class B) must provide a function override and include an object of class A as a member.
# The declaration of the override associates the name of the overridden function with the name of the member for which the override is done.

'''Similarities with the usual overriding.'''

New overriding has the following in common with the standard overriding of C++:

* When entering the body of override, ''this'' points to an instance of the overriding class (B), not of the original one (A). However, in our case these classes are not related through the mechanism of inheritance.

* The override is called not only when the original function is called directly on the member, but also when the original function is called on a pointer to, or reference to the member object, a pointer to one of the member's ancestors in the inheritance chain, or a pointer to one of the member's base classes in the multiple inheritance – in other words, when the exact type of the member is not known to the caller.

* The function override is called ''instead'' of the original function, and therefore it must call the original function from its body, if it is not a full substitute. The call should be qualified with the name of the member’s class, to disable the virtual binding and prevent the override from getting called again. In addition, the call should be qualified with the name of the member itself (in our case, a.A::f(), not just A::f()), because an original function can only be called on an object belonging to the type of the member (A).

* A property of transitivity: a class can override not only the functions of its members, but also the functions of the members of its members. If we declare B::a::f() virtual and override it in the class C (suppose C can access methods of B):

<pre>
class C
{
B b;
int b::a::f();
};
</pre>

then the following is true
b.a.f(); // C::b::a::f() is called
b.a.B::a::f(); // B::a::f() is called
b.a.A::f(); // A::f() is called

If f() is not overridden in the class B, expression
b.a.B::a::f();
is equivalent to b.a.A::f().

'''Differences with to the usual overriding.'''

Overriding in owner class is not simply the usual C++ overriding with the owner class playing the role of the derived class. There are some important differences:

* The overriding is done not for a class (A), but for a member of a class (B::a), that is, it does not affect any objects except the member object.
* Only a function belonging to the public interface of the member's class can be overridden.
* In the body of the function override, only the public interface of the member's class can be used. That is, overriding in owner class gives different access rights to its first participating class than the usual override.
* A class can use an abstract class for its member. In this case, one must use overriding in owner class to provide implementation for any pure virtual functions of the member’s class.

Note, that we only consider the overriding of methods of a contained member. Overriding at run time of methods of objects referred to by pointers initially looked very interesting. However, it turned out to be too complicated for debugging, because of its often unpredictable, extremely dynamic nature. I have left such applications outside of the scope of this article. In case of overriding for a contained member, the override declaration is close to the member, making it easy to understand the relationship. Besides, the implementations of the overriding mechanism can rely on the exact type of member object, known at compile time, instead of relying on the dynamic dependencies at run-time.

Overriding in owner class is not extending or modifying the interface of the owner class. Function overrides belong to the interface of the member, not to the interface of the owner. For instance, B::a::f() is part of the interface of B::a, ''not'' B. It cannot be called from an object of class B. Hence, the following calls are syntactically incorrect:

b::a::f();
c.C::b::a::f();

For the same reason, there is an additional rule:

:The access rights of the overrides should be the same as the access rights of the member for which they are done (overrides for a public member should be public, etc.).

An implementation of overriding in owner class in C++ is described in the “Inside the Overriding Mechanism” section later in this text. It is relatively straightforward: it does not require special data structures, does not interfere with other language features, and does not lead to losses in efficiency or memory. The same mechanism of dynamic binding through virtual method tables is used for overriding in owner class as for the usual overriding.

'''Next: [[Applications of Overriding in Owner]]'''

Overriding in Owner Class

Andrey — Fri, 03 Feb 2006 05:48:26 GMT

Summary:

'''''An extension of polymorphism allowing for better integration of objects for common work.'''''

Andrey Potekhin

Subject areas: Object-oriented design techniques; C++ language design; theoretical foundations.

= Abstract =

Classes in C++ are devoid of an important quality: the class is not aware of operations performed on its member objects by code outside of the class. A member of a class may serve as an argument of some algorithm, it may be a widget exposed to the end user, or can be manipulated by other members of the class. The changes happening to the member may require owner class attention. To enable the owner to see these changes, usually either the code of the member's class is modified to send notifications, or a special wrapper for the member is created. This paper introduces an alternative way of providing control over members: an extension of polymorphism that allows one to override a virtual function of member's class in the owner class. This can help objects to work together; the designs may benefit by minimizing class and run-time dependencies, resolving the update issues and improving reusability of code.

= Introduction =

Consider a spell check algorithm making changes to objects representing text. The class representing a text document passes its member text for correction. Because it must reflect the changes to the text, it must know what the spell checker has done to the text. In general, it is often desirable for a class to control the changes that happen to its member objects.

There are several ways to make owner class aware of changes to a member. You can hide the member and embed its interface in the interface of the owner class. It may be necessary to rewrite the code working with member class to start working with the owner class. Alternatively, you can declare a pointer to the owner object inside the member class, and pass notifications about changes to the owner. This approach ties together the otherwise independent classes of owner and member through a pointer and notifications; forcing the member class to know about the owner class. You can also change the member to belong to a class derived from the original member class and implementing the code necessary for notifying the owner class. This will create a new class, giving it access rights to the member class's internals, coupling it with the owner class, and possibly giving it knowledge of the owner class 's internals. You could also derive the owner class from the member class. However, this would make the owner an instance of the member class (''is-a''), instead of intended usage of the member (''has-a''). This may become complicated if the owner class wants to control more than one member belonging to the same class. In an attempt to find a better solution, I decided to re-formulate the problem:

:'''Given a class and its members, it is desirable that when a call is made to a member function of a member, some function of the owner class is called.'''

Following the analogy with the usual overriding of a method in the derived class, I propose to allow the possibility to override a method in the enclosing class.

This approach will be described in the section called “Definition”; its applications to some well-known programming problems in “Applications”; some analysis will be done in “Comparison with the Alternatives” and “Questions”; an implementation for C++ in “Inside the Overriding Mechanism”. And then I will conclude with some summarizing thoughts. By the way, the use of C++ in this text should not imply that the ideas cannot be used in other object-oriented programming languages.

'''Next: [[Definition of Overriding in Owner Class]]'''

The P-Bug

Andrey — Fri, 03 Feb 2006 05:22:39 GMT

Summary:

From: Potekhin, Andrey 
Tuesday, February 01, 2005 10:00 PM 
To: Dev Team 
Subject: The P-bug

Dear colleagues,

Once in a while people put their names on things that they discover - Rorschach spots, Alzheimer's disease, Eiffel tower. Let me introduce '''Potekhin's Bug'''.

Let's put this value into database:
130

Let's retrieve it into a char using a usual ADO call:
char c = (char)(short)f->Item["MyField"]->Value;

In the above code, we need to cast to <code>short</code> since ADO doesn't know how to cast to <code>char</code> directly. Then, we need to cast to <code>char</code> to avoid compiler's warning of a 'possible loss of data'. Since that we are storing values which are not greater than 256, we are sure that no data is lost.

Predictably, the retrieved value, as shown by debugger, is not '''130''', but '''-126'''.

If you think that this is the bug I'm talking about, it is not. This is just a usual signed/unsigned issue. Since c is declared as a (signed) <code>char</code>, the moment the 1 hits its upper bit it becomes a negative value. This is not a bug, this is how it supposed to be. The bits are all the same. It is still '''130''' under the hood. Let's continue.

Retrieve the same value as an integer:
int i = (short)f->Item["MyField"]->Value;

As you probably guessed, this time the debugger shows '''130'''.

=== Now, the question: what do you think will be the result of this code: ===
<pre>
if (c == i)
{
AfxMessageBox("Heaven");
}
else
{
AfxMessageBox("Hell");
}
</pre>

On the one hand, this is a case of '''-126''' vs. '''130'''. On the other, we know that:

- '''Both values have the same bits''' - 10000010, which are read from the same database field.

- '''Both values are signed values''', so there is no signed/unsigned mismatch.

- When evaluating the expression, both values are implicitly converted to same type, '''int'''. So, when compared, they '''are of same size'''. In other words, compiler sees it as <code>if ((int)c == i)</code>.

So, which message will you see? I'll have to tell you. Despite these assumptions, you'll be getting the else branch. This is what we call Potekhin's bug.

== Explanation of the trick ==

One may say, of course, '''130''' is not '''-126''', that's why they don't match. However, this does not explain how did we end up with such results. Here's the explanation. Compare:

Before conversion to int:

(int) 130 == 10000010
(char) -126 == 10000010

After conversion to int:

(int) 130 == 10000010
(int) -126 == 11111111111111111111111110000010

When a char gets converted, its negative bit gets propagated all the way to the left.

Well, I knew it. Kind of. I knew that it gets propagated. The problem is, I didn't realize that it could lead to scenarios like one described above.

Conclusions? Same old rule. Never use a signed char to store anything above 128. Or if you do, don't compare it to an integer :)

'''[[Main_Page|To Main Page]]'''