001    /* JAPI - (Yet another (hopefully) useful) Java API
002     *
003     * Copyright (C) 2004-2006 Christian Hujer
004     *
005     * This program is free software; you can redistribute it and/or
006     * modify it under the terms of the GNU General Public License as
007     * published by the Free Software Foundation; either version 2 of the
008     * License, or (at your option) any later version.
009     *
010     * This program is distributed in the hope that it will be useful, but
011     * WITHOUT ANY WARRANTY; without even the implied warranty of
012     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
013     * General Public License for more details.
014     *
015     * You should have received a copy of the GNU General Public License
016     * along with this program; if not, write to the Free Software
017     * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
018     * 02111-1307, USA.
019     */
020    
021    package net.sf.japi.io;
022    
023    import java.io.SequenceInputStream;
024    import static net.sf.japi.util.PrintStreamThrowableHandler.STDERR;
025    
026    /** An ARGV InputStream, behaving similar as <code>&lt;ARGV&gt;</code> in Perl.
027     * Just to make life a bit less painful to Perl programmers that were reborn as Java programmers.
028     * <p />
029     * Don't rely on this class being a subclass of {@link SequenceInputStream}.
030     * That is subject to change.
031     * <p />
032     * An <code>ARGVInputStream</code> provides sequential access to one or more files.
033     * To create an <code>ARGVInputStream</code> that is just a synonym on {@link System#in}, just pass an empty String array to its
034     * constructor.
035     * To create an <code>ARGVInputStream</code> that sequentially accesss one file after another (similar as <code>&lt;ARGV&gt;</code> does
036     * in Perl), pass an array with the desired filenames to its constructor.
037     * <p />
038     * Errors that happen due to files that cannot be opened are always reported to {@link System#err} and otherwise silently ignored, i.e. not reported to the main program.
039     * <p />
040     * Usually, you'd use <code>ARGVInputStream</code> like this:
041     * <pre>
042     * // Cat in a similar way the UNIX command cat works like
043     * import java.io.IOException;
044     * import net.sf.japi.io.ARGVInputStream;
045     * import static net.sf.japi.io.IOHelper.copy;
046     *
047     * public class Cat {
048     *     public static void main(final String... args) {
049     *         try {
050     *             copy(new ARGVInputStream(args), System.out);
051     *         } catch (final IOException e) {
052     *             System.err.println(e);
053     *         }
054     *     }
055     * }
056     * </pre>
057     * Internally this class uses {@link ARGVEnumeration} to sequentially access the Stream elements of ARGV.
058     * @note it is not required to invoke {@link #close()}.
059     * @author <a href="mailto:chris@riedquat.de">Christian Hujer</a>
060     * @see ARGVEnumeration
061     */
062    public class ARGVInputStream extends SequenceInputStream {
063    
064        /** Create an ARGVInputStream.
065         * @param args Command line arguments or some other String array containing 0 or more file names.
066         */
067        public ARGVInputStream(final String... args) {
068            super(new ARGVEnumeration(STDERR, args));
069        }
070    
071    } // class ARGVInputStream