Specification.ckav.txt

text/ckav; charset=UTF-8

SEPARATOR-CHAR = ';'
QUOTE-CHAR = '"'

(? ;" CKAV VERSION " ;(?.t.semver-date ;"0.3.0" ;"2023-04-11")
)


(?.typedef ;?.t.semver-date
	;(?.t.ver.semver-2 ;?.t.str.iso-8601)
)
(?.typedescribe ;?.t.semver-date
	;("SemVer string"
		;"last update date of the SemVer version of related document in iso-8601 format"
	)
)


(?	;" <[ RULE ]> "

	;"First 2 non-blank lines of the file afer the type specifier (MIME) "
	;"must describe separator-char and quote-char as it is done in this file."
	;"They can be defined in any order. (SEPARATOR-CHAR first or QUOTE-CHAR first)"
    ;"İf ' needs to be used, it should be quoted as it is defined by CSV format."
)

(?	;" <[ RULE ]> "

	;"? is a system reserved character."
	;"Users who want to start their ?.typedef, reference, string etc. must"
	;"quote the string that starts with ? character."
	;"Any ?.typedef, reference, string... that starts with ? is defined"
	;"in CKAV specification."
)

(?	;" <[ RULE ]> "

	;"Every data is a ?.t.data except those that start"
	;"with a QUOTE-CHAR (let's call them X)"
	;"The type of X is always ?.t.str.utf-8 unless stated otherwise explicitly."
	
	;("abcd")
	;"Above is a ?.t.data value that contains a ?.t.str.utf-8"
	
	;"A ?.t.data has multiple elements. The first element always denotes "
	;"the type of the ?.t.data"
	;"A ?.t.data is always between ( and ) characters."
)

(?  ;" <[ RULE ]> "

    ;"An ?.t.data element is always either"
	;"a primitive type defined by CKAV"
	;"or it is a combination of primitive types and ?.t.data values."
	
	;"The first data element of every ?.t.data"
	;"always denotes the type of that ?.t.data"
)

(?	;" <[ RULE ]> "

	;" By default, anything starts with QUOTE-CHAR is processed as a"
	;" ?.t.str.utf-8 value "
	;" use another type if you want it to be processed differently. "
	
	;" For example, if you want to tell that duckduckgo.com is an url,"
	;" You must use"
	;" (?.t.url ; duckduckgo.com) "
	;" if its type is not specified, it will lose its meaning as an url "
)

(?	;" <[ RULE ]> "

	;"First data element of every ?.t.data (X) that starts with TID"
	;"must have a ID field defined which is unique in X."
	
	;"For example, all TID.5 data must have IDs unique among themselves."
	;"TID.6 data can use ID values of TID.5 type data as long as no "
	;"TID.6 type data ID is the same in TID.6"
)

(?	;" <[ RULE ]> "

	;"System (CKAV) reserved types and strings always start with ?"
	;" Quote your type and string if they begin with ? "
)

(?	;" <[ RULE ]> "

	;"SEPARATOR-CHAR and QUOTE-CHAR is used as they are used in csv data "
	;"format (https://www.ietf.org/rfc/rfc4180.txt)"
)

(?	;" <[ RULE ]> "

	;"Graph created by type definitions"
	;"must not create any cycles."
	
	;"For example, the following is forbidden:"
	;"?.typedef ; type.1; type.2 ; ?.t.num.int"
	;"?.typedef ; type.2; type.1 ; ?.t.num.real"
)

(?	;"<[ DEFINITION ]>"
	
	;" ?.= operator is alias operator "
	;" It takes two positional arguments. First is a ?.t.str"
	;" second is an immutable value. "
	;" After this operation, first value can be used instead of the second value. "
)

(? ;" '?.typedef' template" ;"?.typedef ; UNIQUE TYPE ID ; value type 1; value type 2 ; ..."
)

(? ;" '?.typedescribe' template" ;"?.typedescribe ; UNIQUE TYPE ID ; "
	;"Explaining data types for humans."
	;"For each data element, explain what that elements meaning for the data."
)

(? ;"Operations defined by CKAV:"
	;" ?.op.... = operation on data. "
	;" ?.op.num.root{deg=X} = Xth degree root operation. Accepts one ?.t.num "
	;" (?.op.num.root{deg=2} ; 4) == 2 "
	;" ?.op.num.sqrt ?.= ?.op.num.r?.t.{deg=2} "
	;" (?.op.num.sqrt ; 4) == 2 "
)


(? ;"Definitions by CKAV (reserved types):"
	;" primitive type = An irreducible typed value defined by CKAV, not by user ;
        Quoted primitive datas are utf-8 strings by default unless 
        their encoding is not specified explicitly using ( ) "
    ;" compound type = Can be constructed by primitive datas and compound datas. "
    ;" ?.t.data = Contains typed element(s) (primitive or compound) ; Elements are seperated by SEPARATOR-CHAR ; Starts with ( ends with ) ; first element always denotes the type of that particular data"
	;" ?.t.list = A ?.t.data ; Can contain different types of values. ; Can contain duplicates"
	;" ?.t.set = ?.t.list ; Can NOT contain duplicate elements"
	;" ?.t.tuple = A ?.t.list ; Positional ?.t.data values "
    ;" ?.t.array = A ?.t.tuple ; Forbids different kinds of values. Only one type can be used for its elements. "
	
    ;" ?.t.bottom = Has no values. Sub-type of all other types. "
	;" ?.t.any = Any type except ?.t.bottom "
	;" ?.t.top = Super-type of all other types. "
	
	;" ?.t.num = Any kind of number "
	;" ?.t.num.zero = The number 0 ; Represented as (?.num.zero)"
	;" ?.t.num.nat = Counting numbers starting from 1 (0 excluded) "
	;" ?.t.num.whole = Set of ?.t.num.nat joined with ?.t.num.zero "    
	;" ?.t.num.int = ?.t.num.whole set adjoined with their negatives. "
	;" ?.t.num.cpst = A composite number "
	;" ?.t.num.prime = A prime number "
	;" ?.t.num.ratio = A number which can be written as a fraction. "
	;" ?.t.num.irrat = A number which can not be written as a fraction. "
	;" ?.t.num.float = IEEE Standard for Floating-Point Arithmetic (IEEE 754) value "
	;" ?.t.num.real = ?.t.num.ratio and ?.t.num.irrat sets adjoined. Unlimited version of ?.t.num.float "
	;" ?.t.num.complex = a+bi where a and b are ?.t.num.real and i = square root of -1 "
	
	;" By default, quoted strings are processed as utf-8 strings. Use ?.t.str.{encoding=utf-16} type or a custom type to process your string differently. "
	;" ?.t.str.{encoding=X} = Any kind of character sequence. Encoded as X. Default encoding is utf-8"
	;" ?.t.str.utf-8 = ?.t.str.{encoding=utf-8} "
	;" ?.t.str.iso-8601 = iso-8601 date string. "
	;" ?.t.url = A url (uniform resource locator) string.  As defined in https://www.w3.org/Addressing/URL/url-spec.txt "
	;" ?.t.ver.semver-2 = Semantic versioning string. Semantic Versioning 2.0.0 (https://semver.org/) "
	
	;" Properties: "
	;" ?.prop.uniq = unique data "
	;" ?.prop.non-neg = non negative value "
	;" ?.prop.non-pos = non positive value "
	;" ?.prop.finite = finite data "
	;" ?.prop.infinite = finite data "
	
	;" ?.t.digit.{base=X} = A symbol that represents a ?.t.num.whole in base X. One symbol can only represent X different numbers. "
	;" ?.t.bit = ?.t.digit.{base=2} == One bit. A binary digit. "
	;" ?.t.byte = ?.t.digit.{base=256} == One byte. Can represent 2^8 different values. (1 byte == 8 bits)"
	
	;" ?.t.seq.{digit_base=X ;digit_count=Y} = A positional sequence of ?.t.digit{base=X} values with size Y that represents a numerical value. "
	;" ?.t.seq.bit = ?.t.seq.{base=2} "
	;" ?.t.seq.byte = ?.t.seq.{base=256} "
	
	
	;""
)


(? ;"Examples of type definitions, example data... can be found below.")

(? ;"User types don't have to start with ?.t."
	;"User defined type identifiers can be anything except CKAV reserved ones."
	;"Reserved characters or char sequences can be used if they are quoted."
)

(?.typedef ;"?" ;?.t.num.complex)
(?.typedescribe ;"?" 
	;"WHAT = Example for how ? can be defined as a type by users."
		;"It must be quoted for user definitions."
	;"VALUES = complex number"
)
("?" ; "3+4i")


(?.typedef ;TID."user defined type name" ;?.t.any.{?.prop.uniq} ;...)

(?.typedescribe ;TID."user defined type name"
	;" WHAT = A ?.t.data with Type and ID. "
	;" VALUES = unique ID, other datas. "
)


(?.typedef ;t.1
	;?.t.num.whole 
	;?.t.num.whole 
	;?.t.num.whole
)

(?.typedescribe ; t.1
	;" WHAT = 3D point" 
	;" VALUES = (x ;y ;z) "

(t.1 ;3 ; 4; 5)


(?.typedef ;t.2
	;?.t.num.whole.{?.prop.uniq}
	;?.t.num.whole 
	;?.t.num.whole 
	;?.t.num.whole
)

(?.typedescribe ; t.2 
	;" WHAT = id and 3D point. " 
	;" VALUES = (point id ;x ;y ;z) "
)

(t.2 ;0 ;3 ; 4; 5)
(t.2 ;1 ;3 ; 100; 5)
(t.2 ;2 ;3 ; 4; 5)


(?.typedef ;TID.1 
	;?.t.num.whole.{?.prop.uniq}
	;?.t.num.real
	;?.t.num.real
)

(TID.1 ;0 ;1 ; 8)
(TID.1 ;1 ;3 ; 3)
(TID.1 ;2 ;2 ; 5)
(TID.1 ;3 ;0 ; 8)


(?.typedescribe ;TID.1 
	;" WHAT = A 2D point with ID value. " 
	;" VALUES = (Unique ID ;x ;y) "
)


(?.typedef ;TID.2 
	;?.t.str.utf-8.{?.prop.uniq}
	;?.t.num.int.t.{?.prop.non-neg} 
	;?.t.num.int.t.{?.prop.non-pos} 
	;?.t.num.zero
)

(TID.2 ;"str ID example 1" ;1 ; -1 ;0)
(TID.2 ;"str ID example 2" ;5 ; -29 ;0)


(?.typedef ;TID."spaced type example" 
	;?.t.num.whole.{?.prop.uniq} 
	;?.t.num.ratio
)

(TID."spaced type example" ;3 ; "22/7")
(TID."spaced type example" ;6 ; 3.14)


(? ;"COMMENT example")


(? ;"TODO" ;"Define reference system (types...)"
	;"Maybe ?/ is a good choice for reference type."
	;"Use uri to locate files."
	;"Way to denote referenced type."
	;"Way to refer to data in referrred file."
)

(? ;"TODO" ;"Use proper data types for examples in this file.")

(? ;"TODO" ;"Create a system for (type) aliasing."
	;"?.typedef already provides this mechanism?"
)

(? ;"TODO" ;"Type property specification."
		;"After choosing a relation of values (a type), a mechanism
		is needed to denote their extra properties."
		;"?.t.num.whole.{?.prop.uniq} seems ok."
		;"Check RUST Language for inspiration"
)

(? ;"TODO(armagan)"
	;" Alias operator ?.= "
	;" Finish work on aliasing. Might use keyword alias instead of ?.= "
)

(? ;"TODO(armagan)"
	;" ?.t.tuple type "
	;" Finish. Is it necessary? Is ?.t.list for different typed values and"
	;" ?.t.array for same typed values enough? "
	;" ?.t.tuple = A ?.t.data ; Positional ?.t.data values of any type. Doesn't allow:  add to, remove from or change the tuple. "
)