com.sshtools.jini.package-info Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jini-lib Show documentation
The newest version!
/**
 * Copyright © 2023 JAdaptive Limited ([email protected])
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * This package contains classes for reading, querying, building and writing
 * INI files.
 * Usage
 * 
 * The general pattern for reading an INI document is ..
 * 

 * Create a configured {@link com.sshtools.jini.INIReader} via {@link com.sshtools.jini.INIReader.Builder}.
 * Get an {@link com.sshtools.jini.INI} instance using {@link com.sshtools.jini.INIReader#read(String)} and other read methods.
 * Query the {@link com.sshtools.jini.INI} instance for sections, properties etc.
 * 
 * 
 * And for writing an INI document ..
 * 

 * Either use an {@link com.sshtools.jini.INI} document you have obtained from an {@link com.sshtools.jini.INIReader}, create a
 * default document (order preserved, case insensitive keys) using {@link com.sshtools.jini.INI#create()},
 * or use {@link com.sshtools.jini.INI.Builder} to configure behaviour.
 * Create a configured {@link com.sshtools.jini.INIWriter} via {@link com.sshtools.jini.INIWriter.Builder}.
 * Write the instance to some target using {@link com.sshtools.jini.INIWriter#write(INI)} and other write methods.
 * 
 * Examples
 * Write A New INI Document
 * {@code 
 * var ini = INI.create();
 * ini.put("Name", "Alice");
 * ini.put("Age", 34);
 * ini.put("Registered", false);
 *   
 * var sec = ini.create("Address");
 * sec.put("Street", "15 Stone Lane");
 * sec.put("Area", "");
 * sec.put("City", "Arbington");
 * sec.put("County", "Inishire");
 * sec.put("PostCode", "ABC 123");
 *   
 * var wrt = new INIWriter.Builder().build();
 *   
 * try(var out = Files.newBufferedWriter(Paths.get("data.ini"))) {
 *     wrt.write(ini, out);
 * }
 * }
 * Read An INI Document From A File
 * {@code 
 * var ini = INI.fromFile(Paths.get("data.ini"));
 * System.out.format("Name: %s%n". ini.get("Name")); 
 * System.out.format("Age: %d%n". ini.getInt("Age"));
 * if(ini.getBoolean("Registered"))
 *     System.out.println("Is registered%n");
 *   
 * ini.sectionOr("Address").ifPresent(s -> {  
 *     System.out.println("Address");
 *     System.out.format("  Street: %s%n". s.get("Street"));
 *     System.out.format("  Area: %s%n". s.get("Area"));
 *     System.out.format("  City: %s%n". s.get("City"));
 *     System.out.format("  County: %s%n". s.get("County"));
 *     System.out.format("  PostCode: %s%n". s.get("PostCode"));
 *     System.out.format("  Tel: %s%n". s.getOr("PostCode", "N/A"));
 * });
 * }
 */
package com.sshtools.jini;