Packages

  • package root
    Definition Classes
    root
  • package grizzled

    The Grizzled Scala Library contains a variety of miscellaneous, general purpose utility classes and objects.

    The Grizzled Scala Library contains a variety of miscellaneous, general purpose utility classes and objects.

    The home page for the Grizzled Scala Library is http://software.clapper.org/grizzled-scala/. Please see that page for complete details, including installation instructions.

    Definition Classes
    root
  • package ScalaCompat

    Compatibility definitions for Scala 2.13+ vs.

    Compatibility definitions for Scala 2.13+ vs. Scala 2.12 and lesser. This object is conceptually similar to scala.collection.compat. For Scala 2.12 and earlier, it provides a type alias and compatibility functions for LazyList. For Scala 2.13 and greater, it's empty. Thus, all code can use LazyList throughout.

    Definition Classes
    grizzled
  • package collection

    Some collection-related helpers.

    Some collection-related helpers.

    Definition Classes
    grizzled
  • package config

    Classes and objects to aid in the parsing of INI-style configuration files.

    Classes and objects to aid in the parsing of INI-style configuration files. This package is similar, in concept, to the Python ConfigParser module (though its implementation and capabilities differ quite a bit).

    Definition Classes
    grizzled
  • Configuration
  • ConfigurationException
  • ConfigurationOptionException
  • Section
  • ValueConverter
  • package datetime
    Definition Classes
    grizzled
  • package file

    File-related classes and utilities.

    File-related classes and utilities. This package is distinguished from the grizzled.io package in that this package operates on files and paths, not on open streams or sources.

    Definition Classes
    grizzled
    See also

    grizzled.io

  • package io

    I/O-related classes and utilities.

    I/O-related classes and utilities. This package is distinguished from the grizzled.file package in that this package operates on already-open Java InputStream, OutputStream, Reader and Writer objects, and on Scala Source objects.

    See grizzled.file

    Definition Classes
    grizzled
  • package math

    Miscellaneous math and statistics utilities.

    Miscellaneous math and statistics utilities.

    Definition Classes
    grizzled
  • package net

    Network-related utility methods and classes.

    Network-related utility methods and classes.

    Definition Classes
    grizzled
  • package parsing

    Methods and classes useful for parsing various things.

    Methods and classes useful for parsing various things.

    Definition Classes
    grizzled
  • package random
    Definition Classes
    grizzled
  • package security
    Definition Classes
    grizzled
  • package string

    String- and text-related classes.

    String- and text-related classes.

    Definition Classes
    grizzled
  • package util

    Miscellaneous utility functions and methods not otherwise categorized.

    Miscellaneous utility functions and methods not otherwise categorized.

    Definition Classes
    grizzled
  • package zip

    The grizzled.zip package contains classes and functions to make it easier to operate on zip and jar files.

    The grizzled.zip package contains classes and functions to make it easier to operate on zip and jar files.

    Definition Classes
    grizzled
p

grizzled

config

package config

Classes and objects to aid in the parsing of INI-style configuration files. This package is similar, in concept, to the Python ConfigParser module (though its implementation and capabilities differ quite a bit).

Linear Supertypes
AnyRef, Any
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. config
  2. AnyRef
  3. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. All

Type Members

  1. final class Configuration extends AnyRef

    An INI-style configuration file parser.

    An INI-style configuration file parser.

    Configuration implements an in-memory store for a configuration file whose syntax is reminiscent of classic Windows .INI files, though with many extensions.

    Syntax

    A configuration file is broken into sections, and each section is introduced by a section name in brackets. For example:

    [main]
    installation.directory=/usr/local/foo
    program.directory: /usr/local/foo/programs
    
    [search]
    searchCommand: find /usr/local/foo -type f -name '*.class'
    
    [display]
    searchFailedMessage=Search failed, sorry.

    Notes and caveats:

    At least one section is required.

    Sections may be empty.

    It is an error to have any variable definitions before the first section header.

    The section names "system" and "env" are reserved. They don't really exist, but they're used during variable substitution (see below) to substitute from System.properties and the environment, respectively.

    Section Name Syntax

    There can be any amount of whitespace before and after the brackets in a section name; the whitespace is ignored. Section names may consist of alphanumeric characters and underscores. Anything else is not permitted.

    Variable Syntax

    Each section contains zero or more variable settings. Similar to a Java Properties file, the variables are specified as name/value pairs, separated by an equal sign ("=") or a colon (":"). Variable names are case-sensitive by default, though the case-sensitivity (and other aspects of the variable name) may be changed by subclassing Configuration and providing your own version of the transformOptionName() method. Variable names may contain alphanumerics, underscores, and hyphens (-). Variable values may contain anything at all. The parser ignores whitespace on either side of the "=" or ":"; that is, leading whitespace in the value is skipped. The way to include leading whitespace in a value is escape the whitespace characters with backslashes. (See below).

    Continuation Lines

    Variable definitions may span multiple lines; each line to be continued must end with a backslash ("\") character, which escapes the meaning of the newline, causing it to be treated like a space character. The following line is treated as a logical continuation of the first line. Unlike Java properties files, however, leading whitespace is not removed from continued lines.

    Only variable definition lines may be continued. Section header lines, comment lines (see below) and include directives (see below) cannot span multiple lines.

    Expansions of Variable Values

    The configuration parser preprocesses each variable's value, replacing embedded metacharacter sequences and substituting variable references. You can use backslashes to escape the special characters that the parser uses to recognize metacharacter and variable sequences; you can also use single quotes. See Suppressing Metacharacter Expansion and Variable Substitution, below, for more details.

    Metacharacters

    The parser recognizes Java-style ASCII escape sequences \t, \n, \r, \\, \ (a backslash and a space), and \uxxxx are recognized and converted to single characters. Note that metacharacter expansion is performed before variable substitution.

    Variable Substitution

    A variable value can interpolate the values of other variables, using a variable substitution syntax. The general form of a variable reference is ${sectionName.varName}.

    sectionName is the name of the section containing the variable to substitute; if omitted, it defaults to the current section. varName is the name of the variable to substitute.

    If a variable reference specifies a section name, the referenced section must precede the current section. It is not possible to substitute the value of a variable in a section that occurs later in the file.

    The section names "system" and "env" are reserved for special "pseudosections."

    The "system" pseudosection is used to interpolate values from System.properties For instance, ${system.user.home} substitutes the value of the user.home system property (typically, the home directory of the user running the program). Similarly, ${system.user.name} substitutes the user's name.

    The "env" pseudosection is used to interpolate values from the environment. On UNIX systems, for instance, ${env.HOME} substitutes user's home directory (and is, therefore, a synonym for ${system.user.home}. On some versions of Windows, ${env.USERNAME} will substitute the name of the user running the program. Note: On UNIX systems, environment variable names are typically case-sensitive; for instance, ${env.USER} and ${env.user} refer to different environment variables. On Windows systems, environment variable names are typically case-insensitive; ${env.USERNAME} and ${env.username} are equivalent.

    Notes and caveats:

    Configuration uses the grizzled.string.template.UnixShellVariableSubstituter class to do variable substitution, so it honors all the syntax conventions supported by that class.

    Variable substitutions are only permitted within variable values. They are ignored in variable names, section names, include directives and comments.

    Variable substitution is performed after metacharacter expansion (so don't include metacharacter sequences in your variable names).

    To include a literal "$" character in a variable value, escape it with a backslash, e.g., "var=value with \$ dollar sign"

    Suppressing Metacharacter Expansion and Variable Substitution

    To prevent the parser from interpreting metacharacter sequences, variable substitutions and other special characters, use the "->" assignment operator, instead of ":" or "=".

    For example, suppose you want to set variable "prompt" to the literal value "Enter value. To specify a newline, use \n." The following configuration file line will do the trick:

    prompt -> Enter value. To specify a newline, use \n

    Similarly, to set variable "abc" to the literal string "${foo}" suppressing the parser's attempts to expand "${foo}" as a variable reference, you could use:

    abc -> ${foo}

    Note: It's also possible, though hairy, to escape the special meaning of special characters via the backslash character. For instance, you can escape the variable substitution lead-in character, '$', with a backslash. e.g., "\$". This technique is not recommended, however, because you have to double-escape any backslash characters that you want to be preserved literally. For instance, to get "\t", you must specify "\\\\t". To get a literal backslash, specify "\\\\". (Yes, that's four backslashes, just to get a single unescaped one.) This double-escaping is a regrettable side effect of how the configuration file parses variable values: It makes two separate passes over the value (one for metacharacter expansion and another for variable expansion). Each of those passes honors and processes backslash escapes. This problem would go away if the configuration file parser parsed both metacharacter sequences and variable substitutions itself, in one pass. It doesn't currently do that, because it uses the separate grizzled.string.template.UnixShellStringTemplate class grizzled.GrizzledString.translateMetachars() method to do the variable substitution and metacharacter translation. In general, you're better off just sticking with the "->" assignment operator.

    Includes

    A special include directive permits inline inclusion of another configuration file. The include directive takes two forms:

    %include "path"
    %include "URL"

    For example:

    %include "/home/bmc/mytools/common.cfg"
    %include "http://configs.example.com/mytools/common.cfg"

    If the include path is not a URL, and is not an absolute path, its location is relative to the file that's trying to include it.

    The included file may contain any content that is valid for this parser. It may contain just variable definitions (i.e., the contents of a section, without the section header), or it may contain a complete configuration file, with individual sections. Since Configuration recognizes a variable syntax that is essentially identical to Java's properties file syntax, it's also legal to include a properties file, provided it's included within a valid section.

    Note: Attempting to include a file from itself, either directly or indirectly, will cause the parser to throw an exception.

    Comments and Blank Lines

    A comment line is a one whose first non-whitespace character is a "#". A blank line is a line containing no content, or one containing only white space. Blank lines and comments are ignored.

    Caller-supplied Predefined Sections

    Calling applications may supply predefined sections and options, in the form of a map. These sections may then be used by other sections, via variable references. The predefined sections are defined in a map of maps. The outer map is keyed by predefined section name. The inner maps consist of options and their values. For instance, to read a configuration file, giving it access to certain command line parameters, you could do something like this:

    def main(args: Array[String]): Unit = {
      val configFile = args(0)
      val name = args(1)
      val ipAddress = args(2)
      val sections = Map("args" -> Map("name" -> name, "ip" -> ipAddress))
      val config = Configuration(configFile, sections)
      ...
    }
    

    Note that contents of the configuration file can override the predefined sections.

    Applications may also provide a "not found" function that is called to resolve options that are not found in the table. Such a function can be used to supply on-demand sections and values. For example, suppose you want to do something crazy, such as look up any not-found values in a database. (This is probably a very bad idea, but it makes a good example.) You might do something like this:

    def findInDatabase(sectionName: String, optionName: String):
      Either[String, Option[String]] = {
    
      val select = "SELECT value FROM config WHERE section = ? and option = ?"
      ...
    }
    
    val config = Configuration(configFile, notFoundFunction = findInDatabase)
  2. class ConfigurationException extends Exception

    A configuration-related exception, used primarily inside Failure objects.

    A configuration-related exception, used primarily inside Failure objects.

    Annotations
    @SuppressWarnings()
  3. class ConfigurationOptionException extends ConfigurationException

    A specific kind of configuration exception, tied to a specific section and option.

    A specific kind of configuration exception, tied to a specific section and option.

    Annotations
    @SuppressWarnings()
  4. class Section extends AnyRef

    Used as a wrapper to pass a section to callbacks.

  5. trait ValueConverter[T] extends AnyRef

    To create your own value converter, implement this trait.

    To create your own value converter, implement this trait.

    T

    the type the converter returns

Value Members

  1. object Configuration

    Companion object for the Configuration class

  2. object ConfigurationException extends Serializable

Inherited from AnyRef

Inherited from Any

Ungrouped