=========================================== Language Introduction ------------------------------------------- Below is a quick introduction that should be enough to get you started. A higher-level description of the type system is available at [http://cakoose.com/wiki/data_representation]. By convention, type definitions go in ".tcks" files and value definitions go in ".cks" files. Samples are in the "Data/" directory. The examples in this document are available as individual files in "Data/Intro/" The type system consists of a set of primitive types (strings, integers, etc.) and two kinds of compound types. ---------------------- Comments Single-line comments start with the "//" and continue until the end of the line. Block comments start with "/*" and end with "*/". ---------------------- Primitives The basic primitive types are "Boolean", "Integer", "String", and void. Boolean values are written either "True" or "False" (without the quotes). Integer values are written as a sequence of base-10 digits. You can use base-16 if you prefix the number with "0x". String values are written as a sequence of letters enclosed in double-quotes. The void type and void value are both written "()". ---------------------- Records The first kind of compound type is the record. Record types are defined by enclosing a set of fields in braces. // "Person" type { FirstName: String LastName: String Age: Integer } Multiple fields can be placed on the same line if separated by commas: { FirstName: String, LastName: String, Age: Integer } Record values are defined by providing a value for all of the type's fields: { FirstName = "Scooby" LastName = "Doo" Age = 45 } ---------------------- Variants The second kind of compound type is the variant. It is a type where only one of the members is active in any given value. Variant types are defined by enclosing a set of options in angle brackets: // "Color" type < Black: () Orange: () HtmlColor: String Rgb: { Red: Integer, Green: Integer, Blue: Integer } > Variant values are defined by selecting one of the options and writing its tag name and value. Below are four separate values of type "Color", one per line: Orange () HtmlColor "#ffb" Black () Rgb { Red = 12, Green = 24, Blue = 0 } As a shortcut, the "()" can be ommitted in type and value definitions. // "Color" type < Black Orange HtmlColor: String Rgb: { Red: Integer, Green: Integer, Blue: Integer } > // "Color" values Orange HtmlColor "#ffb" Black Rgb { Red = 12, Green = 24, Blue = 0 } ---------------------- Aliases You can create type aliases within records and variants using "def": // "AddressBookEntry" type { Name: String DaytimeContact: Contact EveningContact: Contact def Contact = < Cell: PhoneNumber Fax: PhoneNumber ICQ: Integer AIM: Handle } def PhoneNumber = String def Handle = String } ---------------------- Lists As far as the core type system is concerned, lists aren't really special. However, because they are so common, they have special syntax. To define a list whose elements are of type "String", write: [String] List values are written within square brackets as well. ["Dog", "Cat", "Mouse"] [ "Dog", "Cat" "Mouse" ] As with record values, commas are only needed when multiple entries appear on the same line. More generally, enclose any type in square brackets to create a list whose elements are of the enclosed type. // The type for a list of colors [ < Black, Orange, HtmlColor: String Rgb: { Red: Integer, Green: Integer, Blue: Integer } > ] // A list of colors [ Orange Orange, HtmlColor "#faa" Black, Black, Rgb { Red = 12, Green = 24, Blue = 0 } ] // The type for a list of people [{ FirstName: String, LastName: String, Age: Integer }] // A list of people [ { FirstName = "Scooby", LastName = "Doo", Age = 45 } { FirstName = "Shaggy", LastName = "Rogers", Age = 47 } ] ---------------------- Parameterized Types Defining a parameterized type is similar to defining an alias. The difference is that the definition includes a list of type parameters: def Pair(A,B) = { First: A Second: B } def Point = Pair(Integer,Integer) The above definition of "Point" is roughly equivalent to: def Point = { First: Integer Second: Integer } ------------------------------------------- Markup Syntax For Values WARNING! The implementation may not yet implement match the description below. There is an alternative syntax for CKS values that looks like HTML. The goal is not to be compatible with HTML or XML but to represent document-style data in a syntax that is easy to read and write. I used HTML's syntax as a guideline because it seems to work well for document-style data. ---------------------- Records A record's fields can be represented in one of two ways: either as an attribute or as child element. For example, take the following value (written in the standard syntax): { FirstName = "Scooby" LastName = "Doo" Age = 45 } This can be written in the markup syntax using one of many equivalent representations: 45 Scooby Doo 45 One variation from HTML is that the closing tag need not repeat the opening tag's name: Scooby Doo 45 Another variation is that the type name need not be specified when the parser can infer it. For example, a "Person" value will often appear in a context where no other value type is allowed. In such cases, the opening tag name can be replaced with a dot: <.> Scooby Doo 45 Attributes can contain complex data. For example if you had the following value: { Name = { First: "Scooby" Last: "Doo" } Age = 45 } It could be written: Scooby Doo Age=45 /> Once in an attribute, the standard syntax can also be used. So, the above could be written: ---------------------- Variants To write a variant like you would an XML tag, simply use the selected option as the tag name. For example, take the three example variant values from before: Orange HtmlColor "#ffb" Black Rgb { Red = 12, Green = 24, Blue = 0 } Written in markup syntax: #ffb <.> 12 24 0 If a variant option's value is a record type, the tags can be fused. For example, the last value above can be written in other ways: 0 12 24 0 ---------------------- Lists TODO: ---------------------- Mixed Content TODO: