com.github.aliteralmind.codelet.util

Class NamedDebuggers

java.lang.Object

com.github.aliteralmind.codelet.util.NamedDebuggers

public class NamedDebuggers
extends Object

Collection of names referring to specific debugging tasks, each associated to an arbitrary numeric level.

Author:

Copyright (C) 2014, Jeff Epstein, dual-licensed under the LGPL (version 3.0 or later) or the ASL (version 2.0). See source code for details. http://codelet.aliteralmind.com, https://github.com/aliteralmind/codelet

Constructor Summary

Constructors

Constructor and Description
NamedDebuggers(Map<String,DebugLevel> map_toAddToIfNonNull, Iterator<String> configFile_lineItr, String itr_VarName, Appendable debugAll_ifNonNull) Create a new instance from a configuration file's line iterator.
NamedDebuggers(Map<String,DebugLevel> map_toAddToIfNonNull, String configFile_path, String path_varName, Appendable debugAll_ifNonNull) Create a new instance from the path of a configuration file.

Method Summary

Methods

Modifier and Type	Method and Description
TextAppenter	getAllQueriesDebugAptr() Get the text appenter for debugging each query.
Appendable	getAppendableIfActive(String name, TextAppenter debug_aptr, DebugLevel actual_level1, DebugLevel... actualLevels_2AndUp) If a named-level is active, get an appendable for it.
TextAppenter	getAppenterIfActive(String name, TextAppenter debug_aptr, DebugLevel actual_level1, DebugLevel... actualLevels_2AndUp) If a named-level is active, get an appenter for it.
Map<String,DebugLevel>	getMap() Unmodifiable name-to-level map.
boolean	isActive(String name, DebugLevel actual_level1, DebugLevel... actualLevels_2AndUp) Is a named level active?.
static Map<String,DebugLevel>	newMapFromConfigFile(Map<String,DebugLevel> map_toAddToIfNonNull, Iterator<String> configFile_lineItr, String itr_VarName, Appendable debugAll_ifNonNull) Creates a new map associated level names to level numbers, as read in from a configuration text file.
static Map<String,DebugLevel>	newMapFromConfigFile(Map<String,DebugLevel> map_toAddToIfNonNull, String configFile_path, String path_varName, Appendable debugAll_ifNonNull) Creates a new map associated level names to level numbers, as read in from a configuration text file.
void	setAllQueriesDebug(Appendable debugEachQuery_ifNonNull) Set debugging for outputting all isActive queries.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NamedDebuggers

public NamedDebuggers(Map<String,DebugLevel> map_toAddToIfNonNull,
              String configFile_path,
              String path_varName,
              Appendable debugAll_ifNonNull)

Create a new instance from the path of a configuration file.

This sets getMap() to an immutable version of

NamedDebuggers.newMapFromConfigFile(map_toAddToIfNonNull, configFile_path, path_varName,
debugAll_ifNonNull)

See Also:

NamedDebuggers(Map, Iterator, String, Appendable)

NamedDebuggers

public NamedDebuggers(Map<String,DebugLevel> map_toAddToIfNonNull,
              Iterator<String> configFile_lineItr,
              String itr_VarName,
              Appendable debugAll_ifNonNull)

Create a new instance from a configuration file's line iterator.

This sets getMap() to an immutable version of

NamedDebuggers.newMapFromConfigFile(map_toAddToIfNonNull, configFile_path, path_varName,
debugAll_ifNonNull)

See Also:

NamedDebuggers(Map, String, String, Appendable)

Method Detail

getMap

public Map<String,DebugLevel> getMap()

Unmodifiable name-to-level map.

setAllQueriesDebug

public void setAllQueriesDebug(Appendable debugEachQuery_ifNonNull)

Set debugging for outputting all isActive queries. This is useful for determining levels that may be unused.

Parameters:

debugEachQuery_ifNonNull - Get with getAllQueriesDebugAptr().

See Also:

isActive

getAllQueriesDebugAptr

public TextAppenter getAllQueriesDebugAptr()

Get the text appenter for debugging each query.

Returns:

A non-null appenter.

See Also:

setAllQueriesDebug(Appendable)

isActive

public boolean isActive(String name,
               DebugLevel actual_level1,
               DebugLevel... actualLevels_2AndUp)

Is a named level active?.

If each-query debugging is on, this outputs name, regardless the value returned by this function.

Parameters:

name - Must be an existing name.

actual_level1 - The actual debugging level is the highest level in this or any of the elements in actualLevels_2AndUp. May not be null.

actualLevels_2AndUp - If multiple levels make up "the level" (the highest one between all of them), these are those additional level elements.

Returns:

If getMap().get(name) is

• null: false
• OFF: true

Otherwise:
(getMap}().get(name).compareTo(actualLevel) <= 0)
Where actualLevel is equal to
actual_level1.getHighestLevel(actualLevels_2AndUp)

Throws:

NoSuchElementException - If getMap().Map.containsKey(Object)(name) is false.

getAppenterIfActive

public TextAppenter getAppenterIfActive(String name,
                               TextAppenter debug_aptr,
                               DebugLevel actual_level1,
                               DebugLevel... actualLevels_2AndUp)

If a named-level is active, get an appenter for it.

Returns:

(isActive(name, actual_level1, actualLevels_2AndUp)
? debug_aptr : null)

See Also:

getAppendableIfActive(String, TextAppenter, DebugLevel, DebugLevel...)

getAppendableIfActive

public Appendable getAppendableIfActive(String name,
                               TextAppenter debug_aptr,
                               DebugLevel actual_level1,
                               DebugLevel... actualLevels_2AndUp)

If a named-level is active, get an appendable for it.

Returns:

(isActive(name, actual_level1, actualLevels_2AndUp)
? debug_aptr.getAppendable() : null)

See Also:

getAppendableIfActive(String, TextAppenter, DebugLevel, DebugLevel...)

newMapFromConfigFile

public static final Map<String,DebugLevel> newMapFromConfigFile(Map<String,DebugLevel> map_toAddToIfNonNull,
                                          String configFile_path,
                                          String path_varName,
                                          Appendable debugAll_ifNonNull)

Creates a new map associated level names to level numbers, as read in from a configuration text file.

Returns:

newMapFromConfigFile(map_toAddToIfNonNull,
PlainTextFileUtil.getLineIterator(configFile_path, path_varName),
path_varName, debugAll_ifNonNull)

newMapFromConfigFile

public static final Map<String,DebugLevel> newMapFromConfigFile(Map<String,DebugLevel> map_toAddToIfNonNull,
                                          Iterator<String> configFile_lineItr,
                                          String itr_VarName,
                                          Appendable debugAll_ifNonNull)

Creates a new map associated level names to level numbers, as read in from a configuration text file.

Configuration file format

Overall:

• Whitespace at the ends of lines is permissible.
• Lines (after trimming) that start with a hash ('#') are ignored.
• Empty lines are permissible.

Each line is in the format

[level-name]=[level-number]

• [level-name] is the descriptive name of the level. Must be non-null, and must be in the same format as a valid Java package name--that is, it must match
  JavaRegexes.PACKAGE_NAME
  Names must be unique.
• [level-number] is a number between -1 and 5, inclusive.
  • -1: Never output.
  • 0: Always output (even if OFF).
  • 1: Output only when the actual level on--equal to or greater than ONE.
  • 2: Output when the actual level is TWO or greater.
  • 3: Output when the actual level is THREE or greater.
  • 4: Output when the actual level is FOUR or FIVE.
  • 5: Output only when the actual level is FIVE.
  When a named level is output, it is "active".

Example config file

### Possible values are -1, 0, 1, 2, 3, 4, 5
BasicCustomizers.eliminateCmtBlocksPkgLineAndPkgReferences.alterers=3
BasicCustomizers.lineRange.alterers.eliminateIndentationOrNull=5
BasicCustomizers.lineRange.alterers=3
BasicCustomizers.lineRange.filter=1
BasicCustomizers.lineRange.template=2
CodeletTemplateBase.newTemplateFromPath.templateparseandfill=3
CodeletTemplateBase.templateparseandfill=3
ConsoleOutProcessor.consoleoutputfromexamplecodestringsig=1
SourceAndOutProcessor.template=2
SourceCodeProcessor.progress=1
TagletOfTypeProcessor.classcustomizersplit=2
TagletOfTypeProcessor.getCustomizerSigFromString=1
TagletOfTypeProcessor.newInstructionsForDefaults.tabtospacealterer=3
TagletOfTypeProcessor.newInstructionsForDefaults.templateparseandfill=3
TagletProcessor.codeletfound=0
configuration.allvaluessummary=1
configuration.progress=0
configuration.templateoverrides.allentriespostloaded=3

Parameters:

map_toAddToIfNonNull - If non-null, the lines read in from the configuration file are added to this map. Must allow put, and may not contain any names in the configuration file.

configFile_lineItr - May not be null, and must refer to a validly-formatted configuration file.

itr_VarName - Descriptive name of configFile_lineItr. Should not be null or empty.

debugAll_ifNonNull - If non-null, each line is output via this, before being added to the map. The current size of the map is also output.

Throws:

NamedDebuggerFormatException - If a line is badly formatted or contains illegal values.

BadDuplicateException - If two lines contain the same name.

UnsupportedOperationException - If put is unsupported by map_toAddToIfNonNull.

See Also:

newMapFromConfigFile(Map, String, String, Appendable), NamedDebuggers(Map, String, String, Appendable), NamedDebuggers(Map, Iterator, String, Appendable)