#3 Support for Source Maps

- use shorter class names
- map Source Map options in LessOptions
- extract LineNumbersValue to standalone class
- remove nonsense methods from LessCompiler (source map methods always require additional configuration)
- extend JavaDocs (always print default value)
- upgrade mockito-core to 2.7.18

Author: agabrys

pom.xml

@@ -95,7 +95,7 @@
         <dependency>
             <groupId>org.mockito</groupId>
             <artifactId>mockito-core</artifactId>
-            <version>2.7.12</version>
+            <version>2.7.18</version>
             <scope>test</scope>
         </dependency>
     </dependencies>

src/main/java/biz/gabrys/lesscss/compiler2/LessCompiler.java

@@ -20,9 +20,9 @@
  * Represents <a href="http://lesscss.org/usage/index.html#command-line-usage-options">Less compiler options</a>
  * responsible for controlling the {@link LessCompiler} compilation process.
  * @since 2.0.0
- * @see LessCompilerOptionsBuilder
+ * @see LessOptionsBuilder
  */
-public class LessCompilerOptions {
+public class LessOptions {
 
     private boolean silent;
     private boolean strictImports;
@@ -36,11 +36,16 @@ public class LessCompilerOptions {
     private boolean strictMath;
     private boolean strictUnits;
 
+    private String sourceMapRootPath;
+    private String sourceMapBasePath;
+    private boolean sourceMapLessInline;
+    private String sourceMapUrl;
+
     /**
      * Constructs a new instance.
      * @since 2.0.0
      */
-    public LessCompilerOptions() {
+    public LessOptions() {
         ieCompatibility = true;
         javaScript = true;
         includePaths = Collections.emptyList();
@@ -50,10 +55,10 @@ public LessCompilerOptions() {
     /**
      * Constructs a new instance as a copy of an another options object.
      * @param options the another options object (cannot be {@code null}).
-     * @throws IllegalArgumentException if options is equal to {@code null}.
+     * @throws IllegalArgumentException if options is {@code null}.
      * @since 2.0.0
      */
-    public LessCompilerOptions(final LessCompilerOptions options) {
+    public LessOptions(final LessOptions options) {
         if (options == null) {
             throw new IllegalArgumentException("Options cannot be null");
         }
@@ -68,6 +73,11 @@ public LessCompilerOptions(final LessCompilerOptions options) {
         relativeUrls = options.relativeUrls;
         strictMath = options.strictMath;
         strictUnits = options.strictUnits;
+
+        sourceMapRootPath = options.sourceMapRootPath;
+        sourceMapBasePath = options.sourceMapBasePath;
+        sourceMapLessInline = options.sourceMapLessInline;
+        sourceMapUrl = options.sourceMapUrl;
     }
 
     /**
@@ -134,7 +144,7 @@ public void setCompress(final boolean compress) {
      * @return {@code true} whether the CSS code should be compatible with IE browser, otherwise {@code false}.
      * @since 2.0.0
      */
-    public boolean isIeCompatability() {
+    public boolean isIeCompatibility() {
         return ieCompatibility;
     }
 
@@ -169,9 +179,10 @@ public void setJavaScript(final boolean javaScript) {
     }
 
     /**
-     * Returns available include paths (default: empty collection). If the file in an &#64;import rule does not exist at
-     * that exact location, a compiler will look for it at the location(s) passed to this option. You might use this for
-     * instance to specify a path to a library which you want to be referenced simply and relatively in the less files.
+     * Returns available include paths (default: {@code empty collection}). If the file in an &#64;import rule does not
+     * exist at that exact location, a compiler will look for it at the location(s) passed to this option. You might use
+     * this for instance to specify a path to a library which you want to be referenced simply and relatively in the
+     * less files.
      * @return the available include paths (never {@code null}).
      * @since 2.0.0
      */
@@ -180,10 +191,11 @@ public List<String> getIncludePaths() {
     }
 
     /**
-     * Sets available include paths (default: empty collection). If the file in an &#64;import rule does not exist at
-     * that exact location, a compiler will look for it at the location(s) passed to this option. You might use this for
-     * instance to specify a path to a library which you want to be referenced simply and relatively in the less files.
-     * @param includePaths the available include paths ({@code null} is treated as empty collection).
+     * Sets available include paths (default: {@code empty collection}). If the file in an &#64;import rule does not
+     * exist at that exact location, a compiler will look for it at the location(s) passed to this option. You might use
+     * this for instance to specify a path to a library which you want to be referenced simply and relatively in the
+     * less files.
+     * @param includePaths the available include paths ({@code null} is treated as an empty collection).
      * @since 2.0.0
      */
     public void setIncludePaths(final List<String> includePaths) {
@@ -372,6 +384,7 @@ public void setRelativeUrls(final boolean relativeUrls) {
      * @return {@code true} whether the compiler should try and process all maths in the Less code, otherwise
      *         {@code false}.
      * @since 2.0.0
+     * @see #isStrictUnits()
      */
     public boolean isStrictMath() {
         return strictMath;
@@ -415,6 +428,7 @@ public boolean isStrictMath() {
      * @param strictMath {@code true} whether the compiler should try and process all maths in the Less code, otherwise
      *            {@code false}.
      * @since 2.0.0
+     * @see #setStrictUnits(boolean)
      */
     public void setStrictMath(final boolean strictMath) {
         this.strictMath = strictMath;
@@ -438,6 +452,7 @@ public void setStrictMath(final boolean strictMath) {
      * @return {@code true} whether the compiler should guess units in the Less code when it does maths, otherwise
      *         {@code false}.
      * @since 2.0.0
+     * @see #isStrictMath()
      */
     public boolean isStrictUnits() {
         return strictUnits;
@@ -461,52 +476,159 @@ public boolean isStrictUnits() {
      * @param strictUnits {@code true} whether the compiler should guess units in the Less code when it does maths,
      *            otherwise {@code false}.
      * @since 2.0.0
+     * @see #setStrictMath(boolean)
      */
     public void setStrictUnits(final boolean strictUnits) {
         this.strictUnits = strictUnits;
     }
 
     /**
-     * Available values of the {@code line numbers} option.
+     * Returns a path that will be prepended to each of the Less file paths inside the Source Map and also to the path
+     * to the map file specified in your output CSS.
+     * <p>
+     * Use it if for instance you have a CSS file generated in the root on your web server but have your source
+     * less/css/map files in a different folder.
+     * </p>
+     * <p>
+     * Example: if you have a follow file structure:
+     * </p>
+     * 
+     * <pre>
+     * output.css
+     * dev-files/output.css.map
+     * dev-files/output.less
+     * </pre>
+     * <p>
+     * then you should set the Source Map root path to {@code dev-files/}.
+     * </p>
+     * <p>
+     * This option is the opposite of the {@link #getSourceMapBasePath() Source Map base path} option.
+     * </p>
+     * @return the path which will be added.
      * @since 2.0.0
-     * @see LessCompilerOptions#setLineNumbers(LineNumbersValue)
+     * @see #getSourceMapBasePath()
+     * @see #getSourceMapUrl()
      */
-    public enum LineNumbersValue {
+    public String getSourceMapRootPath() {
+        return sourceMapRootPath;
+    }
 
-        /**
-         * Line numbers won't be put in CSS code.
-         * @since 2.0.0
-         */
-        OFF(""),
-        /**
-         * Line numbers will be put in CSS comments blocks.
-         * @since 2.0.0
-         */
-        COMMENTS("comments"),
-        /**
-         * Line numbers will be put in &#64;media queries.
-         * @since 2.0.0
-         */
-        MEDIA_QUERY("mediaquery"),
-        /**
-         * Line numbers will be put in CSS comments blocks and &#64;media queries.
-         * @since 2.0.0
-         */
-        ALL("all");
+    /**
+     * Sets a path that will be prepended to each of the Less file paths inside the Source Map and also to the path to
+     * the map file specified in your output CSS (default: {@code null}).
+     * <p>
+     * Use it if for instance you have a CSS file generated in the root on your web server but have your source
+     * less/css/map files in a different folder.
+     * </p>
+     * <p>
+     * Example: if you have a follow file structure:
+     * </p>
+     * 
+     * <pre>
+     * output.css
+     * dev-files/output.css.map
+     * dev-files/output.less
+     * </pre>
+     * <p>
+     * then you should set the Source Map root path to {@code dev-files/}.
+     * </p>
+     * <p>
+     * This option is the opposite of the {@link #setSourceMapBasePath(String) Source Map base path} option.
+     * </p>
+     * @param sourceMapRootPath the path which will be added.
+     * @since 2.0.0
+     * @see #setSourceMapBasePath(String)
+     * @see #setSourceMapUrl(String)
+     */
+    public void setSourceMapRootPath(final String sourceMapRootPath) {
+        this.sourceMapRootPath = sourceMapRootPath;
+    }
 
-        private final String value;
+    /**
+     * Returns a path that will be removed from each of the Less file paths inside the Source Map and also from the path
+     * to the map file specified in your output CSS (default: {@code null}).
+     * <p>
+     * It specifies a path which should be removed from the output paths. For instance if you are compiling a file in
+     * the less-files directory but the source files will be available on your web server in the root or current
+     * directory, you can specify this to remove the additional less-files part of the path.
+     * </p>
+     * <p>
+     * This option is the opposite of the {@link #getSourceMapRootPath() Source Map root path} option.
+     * </p>
+     * @return the path which will be removed.
+     * @since 2.0.0
+     * @see #getSourceMapRootPath()
+     * @see #getSourceMapUrl()
+     */
+    public String getSourceMapBasePath() {
+        return sourceMapBasePath;
+    }
 
-        LineNumbersValue(final String value) {
-            this.value = value;
-        }
+    /**
+     * Sets a path that will be removed from each of the Less file paths inside the Source Map and also from the path to
+     * the map file specified in your output CSS (default: {@code null}).
+     * <p>
+     * It specifies a path which should be removed from the output paths. For instance if you are compiling a file in
+     * the less-files directory but the source files will be available on your web server in the root or current
+     * directory, you can specify this to remove the additional less-files part of the path.
+     * </p>
+     * <p>
+     * This option is the opposite of the {@link #setSourceMapRootPath(String) Source Map root path} option.
+     * </p>
+     * @param sourceMapBasePath the path which will be removed.
+     * @since 2.0.0
+     * @see #setSourceMapRootPath(String)
+     * @see #setSourceMapUrl(String)
+     */
+    public void setSourceMapBasePath(final String sourceMapBasePath) {
+        this.sourceMapBasePath = sourceMapBasePath;
+    }
 
-        /**
-         * Returns a value assigned to {@code this} object.
-         * @return the value assigned to {@code this} object.
-         * @since 2.0.0
-         */
-        public String getValue() {
-            return value;
-        }
+    /**
+     * Checks whether a compiler should include all of the Less files in to the Source Map (default: {@code false}).
+     * This means that you only need your map file to get to your original source.
+     * @return {@code true} whether the compiler should include all of the Less files in to the Source Map, otherwise
+     *         {@code false}.
+     * @since 2.0.0
+     */
+    public boolean isSourceMapLessInline() {
+        return sourceMapLessInline;
+    }
+
+    /**
+     * Sets whether a compiler should include all of the Less files in to the Source Map (default: {@code false}). This
+     * means that you only need your map file to get to your original source.
+     * @param sourceMapLessInline {@code true} whether the compiler should include all of the Less files in to the
+     *            Source Map, otherwise {@code false}.
+     * @since 2.0.0
+     */
+    public void setSourceMapLessInline(final boolean sourceMapLessInline) {
+        this.sourceMapLessInline = sourceMapLessInline;
+    }
+
+    /**
+     * Returns a path which will overwrite the URL in the CSS that points at the Source Map map file (default:
+     * {@code null}). This is for cases when the {@link #getSourceMapRootPath() root path} and the
+     * {@link #getSourceMapBasePath() base path} options are not producing exactly what you need.
+     * @return the Source Map URL.
+     * @since 2.0.0
+     * @see #getSourceMapBasePath()
+     * @see #getSourceMapRootPath()
+     */
+    public String getSourceMapUrl() {
+        return sourceMapUrl;
+    }
+
+    /**
+     * Sets a path which will overwrite the URL in the CSS that points at the Source Map map file (default:
+     * {@code null}). This is for cases when the {@link #setSourceMapRootPath(String) root path} and the
+     * {@link #setSourceMapBasePath(String) base path} options are not producing exactly what you need.
+     * @param sourceMapUrl the Source Map URL.
+     * @since 2.0.0
+     * @see #setSourceMapBasePath(String)
+     * @see #setSourceMapRootPath(String)
+     */
+    public void setSourceMapUrl(final String sourceMapUrl) {
+        this.sourceMapUrl = sourceMapUrl;
     }
 }