Merge pull request #292 from typesafehub/parser-package

Parser package

config/src/main/java/com/typesafe/config/impl/AbstractConfigNode.java

@@ -3,7 +3,7 @@
  */
 package com.typesafe.config.impl;
 
-import com.typesafe.config.ConfigNode;
+import com.typesafe.config.parser.ConfigNode;
 import java.util.Collection;
 
 abstract class AbstractConfigNode implements ConfigNode {

config/src/main/java/com/typesafe/config/impl/Parseable.java

@@ -22,6 +22,7 @@ import java.net.URLConnection;
 import java.util.*;
 
 import com.typesafe.config.*;
+import com.typesafe.config.parser.*;
 
 /**
  * Internal implementation detail, not ABI stable, do not touch.

config/src/main/java/com/typesafe/config/impl/SimpleConfigDocument.java

@@ -1,6 +1,6 @@
 package com.typesafe.config.impl;
 
-import com.typesafe.config.ConfigDocument;
+import com.typesafe.config.parser.ConfigDocument;
 import com.typesafe.config.ConfigException;
 import com.typesafe.config.ConfigParseOptions;
 import com.typesafe.config.ConfigValue;

config/src/main/java/com/typesafe/config/parser/ConfigDocument.java

@@ -1,8 +1,12 @@
-package com.typesafe.config;
+package com.typesafe.config.parser;
+
+import com.typesafe.config.ConfigParseOptions;
+import com.typesafe.config.ConfigValue;
 
 /**
- * An object parsed from the original input text, which can be used to
- * replace individual values and exactly render the original text of the
+ * Represents an individual HOCON or JSON file, preserving all
+ * formatting and syntax details.  This can be used to replace
+ * individual values and exactly render the original text of the
  * input.
  *
  * <p>
@@ -10,7 +14,7 @@ package com.typesafe.config;
  * there's no need for "defensive copies."
  *
  * <p>
- * <em>Do not implement interface {@code ConfigNode}</em>; it should only be
+ * <em>Do not implement interface {@code ConfigDocument}</em>; it should only be
  * implemented by the config library. Arbitrary implementations will not work
  * because the library internals assume a specific concrete implementation.
  * Also, this interface is likely to grow new methods over time, so third-party

config/src/main/java/com/typesafe/config/parser/ConfigDocumentFactory.java

@@ -1,4 +1,6 @@
-package com.typesafe.config;
+package com.typesafe.config.parser;
+
+import com.typesafe.config.ConfigParseOptions;
 
 import com.typesafe.config.impl.ConfigImpl;
 import com.typesafe.config.impl.Parseable;
@@ -7,8 +9,8 @@ import java.io.File;
 import java.io.Reader;
 
 /**
- * Factory for automatically creating a ConfigDocument from a given input. Currently
- * only supports files and strings.
+ * Factory for creating {@link
+ * com.typesafe.config.parser.ConfigDocument} instances.
  */
 public final class ConfigDocumentFactory {
 
@@ -20,7 +22,7 @@ public final class ConfigDocumentFactory {
      * @param options
      *       parse options to control how the reader is interpreted
      * @return the parsed configuration
-     * @throws ConfigException on IO or parse errors
+     * @throws com.typesafe.config.ConfigException on IO or parse errors
      */
     public static ConfigDocument parseReader(Reader reader, ConfigParseOptions options) {
         return Parseable.newReader(reader, options).parseConfigDocument();
@@ -34,7 +36,7 @@ public final class ConfigDocumentFactory {
      * @param reader
      *       the reader to parse
      * @return the parsed configuration
-     * @throws ConfigException on IO or parse errors
+     * @throws com.typesafe.config.ConfigException on IO or parse errors
      */
     public static ConfigDocument parseReader(Reader reader) {
         return parseReader(reader, ConfigParseOptions.defaults());
@@ -48,7 +50,7 @@ public final class ConfigDocumentFactory {
      * @param options
      *       parse options to control how the file is interpreted
      * @return the parsed configuration
-     * @throws ConfigException on IO or parse errors
+     * @throws com.typesafe.config.ConfigException on IO or parse errors
      */
     public static ConfigDocument parseFile(File file, ConfigParseOptions options) {
         return Parseable.newFile(file, options).parseConfigDocument();
@@ -62,7 +64,7 @@ public final class ConfigDocumentFactory {
      * @param file
      *       the file to parse
      * @return the parsed configuration
-     * @throws ConfigException on IO or parse errors
+     * @throws com.typesafe.config.ConfigException on IO or parse errors
      */
     public static ConfigDocument parseFile(File file) {
         return parseFile(file, ConfigParseOptions.defaults());

config/src/main/java/com/typesafe/config/parser/ConfigNode.java

@@ -1,11 +1,10 @@
 /**
  *   Copyright (C) 2015 Typesafe Inc. <http://typesafe.com>
  */
-package com.typesafe.config;
+package com.typesafe.config.parser;
 
 /**
- * An immutable node that makes up the ConfigDocument AST, and which can be
- * used to reproduce part or all of the original text of an input.
+ * A node in the syntax tree for a HOCON or JSON document.
  *
  * <p>
  * Because this object is immutable, it is safe to use from multiple threads and

config/src/main/java/com/typesafe/config/parser/package.html

@@ -0,0 +1,33 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<html>
+<head>
+<!--
+ Copyright (C) 2015 Typesafe Inc. <http://typesafe.com>
+-->
+
+</head>
+<body bgcolor="white">
+
+<p>
+This package supplies a raw parser and syntax tree for individual HOCON and JSON
+files. You do not want this package for everyday config in your app: see
+the <code>com.typesafe.config</code> package instead. You would use the raw
+parser if you're doing something like reading, modifying, and re-saving a config
+file. For info on the main config API this parser is a part of,
+see <a href="https://github.com/typesafehub/config/">the project site</a>.
+</p>
+
+<p>
+    For working with the raw syntax tree, some important classes are:
+    <ul>
+        <li>{@link com.typesafe.config.parser.ConfigDocument} - a loaded HOCON
+            or JSON document</li>
+        <li>{@link com.typesafe.config.parser.ConfigDocumentFactory} -
+            static methods to instantiate a document</li>
+        <li>{@link com.typesafe.config.parser.ConfigNode} - syntax node
+            in a document</li>
+    </ul>
+</p>
+
+</body>
+</html>

config/src/test/scala/com/typesafe/config/impl/ConfigDocumentTest.scala

@@ -5,6 +5,7 @@ import java.nio.charset.StandardCharsets
 import java.nio.file.{ Paths, Files }
 
 import com.typesafe.config._
+import com.typesafe.config.parser._
 import org.junit.Assert._
 import org.junit.Test