001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.marshall.csv;
018
019import java.io.*;
020
021import org.apache.juneau.marshall.*;
022import org.apache.juneau.marshall.serializer.*;
023
024/**
025 * Specialized writer for serializing CSV.
026 *
027 * <h2 class='section'>Notes:</h2><ul>
028 *    <li class='note'>
029 *       This class is not intended for external use.
030 * </ul>
031 */
032@SuppressWarnings({
033   "java:S3776", // Cognitive complexity acceptable for CSV cell quoting/escaping logic
034   "resource" // Writer resource managed by calling code
035})
036public class CsvWriter extends SerializerWriter<CsvWriter> {
037
038   private boolean neutralizeFormulas;
039
040   /**
041    * Constructor.
042    *
043    * @param out The writer being wrapped.
044    * @param useWhitespace If <jk>true</jk>, tabs and spaces will be used in output.
045    * @param maxIndent The maximum indentation level.
046    * @param quoteChar The quote character to use (i.e. <js>'\''</js> or <js>'"'</js>)
047    * @param trimStrings If <jk>true</jk>, strings will be trimmed before being serialized.
048    * @param uriResolver The URI resolver for resolving URIs to absolute or root-relative form.
049    */
050   protected CsvWriter(Writer out, boolean useWhitespace, int maxIndent, char quoteChar, boolean trimStrings, UriResolver uriResolver) {
051      super(out, useWhitespace, maxIndent, trimStrings, quoteChar, uriResolver);
052   }
053
054   /**
055    * Enables neutralization of spreadsheet formulas.
056    *
057    * <p>
058    * When enabled, string values that begin with <js>'='</js>, <js>'+'</js>, <js>'-'</js>, <js>'@'</js>, a tab or a carriage return
059    * are written with a leading single quote so that spreadsheet applications treat them as text.
060    * Non-string values (numbers, booleans) are never modified.
061    *
062    * @param value The new value for this setting.
063    * @return This object.
064    */
065   public CsvWriter neutralizeFormulas(boolean value) {
066      neutralizeFormulas = value;
067      return this;
068   }
069
070   /**
071    * Writes an entry to the writer.
072    *
073    * <p>
074    * Follows RFC 4180 quoting rules:
075    * <ul>
076    *   <li>Values containing commas, double-quote characters, or newlines are enclosed in double quotes.
077    *   <li>Double-quote characters within a quoted field are escaped by preceding them with another double-quote.
078    *   <li>The literal string {@code null} is written unquoted; the string value {@code "null"} is quoted.
079    * </ul>
080    *
081    * @param value The value to write.
082    *    <br>Can be <jk>null</jk> (written as the literal <js>"null"</js>).
083    */
084   public void writeEntry(Object value) {
085      if (value == null) {
086         w("null");
087      } else {
088         var s = value.toString();
089         if (neutralizeFormulas && value instanceof CharSequence && ! s.isEmpty() && "=+-@\t\r".indexOf(s.charAt(0)) >= 0)
090            s = "'" + s;
091         var mustQuote = false;
092         for (var i = 0; i < s.length() && !mustQuote; i++) {
093            var c = s.charAt(i);
094            if (c == ',' || c == '"' || c == '\r' || c == '\n')
095               mustQuote = true;
096         }
097         if (mustQuote) {
098            w('"');
099            for (var i = 0; i < s.length(); i++) {
100               var c = s.charAt(i);
101               if (c == '"')
102                  w('"');  // RFC 4180: escape embedded quote by doubling it
103               w(c);
104            }
105            w('"');
106         } else {
107            w(s);
108         }
109      }
110   }
111}