JLSC Guide.txt

Introduction
	This document is intended to aid users of the JLSC configuration format.

Preliminary
	Background
		JLSC stands for JSON-Like Structured Configuration. JSON stands for JavaScript Object Notation, and information about it can be found at json.org. JLSC is partially based off of JSON, as well as HOCON and YAML, two other
	configuration formats. The goal of the JLSC project is to simultaneously provide the best experience for the user, and the easiest development for the coder. JLSC has the same data structure of JSON, but it has more advanced
	parsing and programitic interaction.

	Java Basics
		Some topics discussed in this document, such as Object serialization, require you have a base understanding of some Java concepts/parts:
			Class - A 'blue print' for an Object. In addition a class has a fully-qualified name, an identifier which defines its location.
			Object - An Object is the basis of everything in Java, multiple Objects can be created from the same class, and each Object holds its own data. For example 'Integer' is one type of object, as is 'File.'
			String - A string of characters
			Integer - 4 byte integer number
			Float - 4 byte decimal number
			Short - 2 byte integer number
			Long - 8 byte integer number
			Double - 8 byte decimal number
			Byte - 1 byte

Concept
	JLSC is made up of three parts, Arrays, Compounds, and Values. Both arrays and compounds are special types of values, so anyhwere this document discusses 'values,' it is also discussing arrays and compounds. The term 'converted values'
will be used to refer to values other than compunds and arrays. Each value can have metadata.

	Compounds
		A compound is a set of strings and values. Each string is a 'key' to the value, as in, it specifies the values location.

	Arrays
		An array is a set of values. It is simply a 'list' of values, its keys are simply the index the value has in the list.

	Convertible Values
		Convertible values are values that can be stored in one line, such as numbers or strings.

	Metadata
		Metadata, in and of itself, means 'data about oneself.' Metadata is used to help determine what each value is. Metadata could also be used for other purposes, but it is most important for 'type specifying' or the process
	of determining what type a value is. JLSC Has quite a few type specifiers:
		- integer (@integer:) - represents an integer type
		- float (@float:) - represents a float type
		- short (@short:) - represents a short type
		- long (@long:) - represents a long type
		- double (@double:) - represents a double type
		- byte (@byte:) - represents a byte type
		- boolean (@boolean:) - represents a true/false type
		- null (@null:) - represents a null type
		- string (@string:) - represents a string type
		- serialized (@serialized:) - represents a serialized object type (discussed in 'Object Serailization')
		- listed (@listed:) - represents a listed object type (discussed in 'Object Serailization')
		Oftentimes you do not have to specify the type - JLSC can usually figure it out on its own, however with numbers it may be useful to specifiy the type. Although the programmer may consider the different types, it is possible
	they require a 'byte' type, however JLSC will read numbers as either a long or a double, so you would have to specify the type.

Grammar & Syntax
	Special Characters:
		- '{' and '}' enclose a compound
		- '[' and ']' enclose an array
		- '=' seperates keys and values in a compound
		- '@' and ':' enclose a value metadata
		- '#' starts a comment
		- new lines mark the end of a value in a compound
		- commans mark the end of an value in an array'

	Compounds
		All compounds are enclosed in curly braces, an example is as follows:
		{
			string= "value"
			string2= "value2"
		}

	Arrays
		All arrays are enclosed in square brackets, an example is as follows:
		[
			"value",
			"value2"
		}

	Note
		Both arrays and compounds can contain arrays and compunds:
		[
			"value",
			{
				string= "value2"
				array= [
					2,
					"value"
				]
			}
		]

		According to the special characters section, a new line marks the end of a map value, meaning that 'array= [' would be the entire value, however, in addition to a new line
	being the ending character, brackets must also be balanced at that ending character, so 'array= [' has a bracket that is not balanced out until the ']' closing bracket is reached.
	The same logic is applied to sub compounds, compounds in arrays, and arrays in arrays.

	Metadata
		Metadata is appeneded to the start of a value, for example:
		{
			key= @byte:100
			key2= @integer:100
		}
		Although both key and key2 have a value of 100, programatically, key represents a BYTE with the value 100, and key2 represents an INTEGER with a value 100.

Object Serialization
	JLSC Provides two ways to save objects, serialization and conversion. Conversion saves 'convertible values' to single strings, and serialization saves object to a compound. Converted values often follow the listed format:
		<class_name>(<val>, <val2>, etc)
	the listed format provides a simple way to save simpler objects, such as a point. An example listed object is as follows:
		com.gmail.socraticphoenix.plasma.math.geometry.PlasmaPoint3D(0, 0, 0)
	this point represents the origin on a 3 dimensional graph. Many objects can be represented in listed form, including fractions, 2d points, and java arrays. However, more complex objects follow the serialized format, which is a compound structured like so:
		@serialized("<type>, <serializer>, <raw_type>"):{
			serializer= "<serializer_class_name>"
			type= "serialized_object_class_name>"
			values= {
				<data>
			}
		}
	an example serialized object is as followed:
		@serialized("com.gmail.socraticphoenix.plasma.base.Triple, com.gmail.socraticphoenix.plasma.file.jlsc.serializati.JLSCAnnotatedSerializer, compound"):{
			a-value= "Property 1"
			b-value= "Property 2"
			c-value= "Property 3"
		}
	the object serialized is a triple, all a triple does is contain three other objects, in this case, three strings.