/* -----------------------------------------------------------------------------
Copyright 2019-2021 Kevin P. Barry

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.
----------------------------------------------------------------------------- */

// Author: Kevin P. Barry [ta0kira@gmail.com]

// Built-in boolean type.
//
// Literals are true and false.
concrete Bool {
  refines AsBool
  refines AsInt
  refines AsFloat
  refines Formatted

  defines Default
  defines Equals<Bool>
}

// Built-in character type. (ASCII only.)
//
// Literals:
// - Printable: 'a', '0', etc.
// - Escapes:   '\n', '\r', etc. ('\0' must be '\000', however)
// - Hex:       '\xAB' (always 2 digits)
// - Oct:       '\012' (always 3 digits)
concrete Char {
  refines AsBool
  refines AsChar
  refines AsInt
  refines AsFloat
  refines Formatted

  defines Default
  defines Equals<Char>
  defines LessThan<Char>
}

// Built-in double-precision floating point.
//
// Literals:
// - . required, with at least one digit on either side, e.g., 0.1
// - Scientific notation: 0.1E-10, etc.
concrete Float {
  refines AsBool
  refines AsInt
  refines AsFloat
  refines Formatted

  defines Default
  defines Equals<Float>
  defines LessThan<Float>
}

// Built-in 64-bit signed integer.
//
// Literals:
// - Decimal: 1234, -1234, etc.
// - Hex:    \xABCD, etc.
// - Octal:  \o7772, etc.
// - Binary: \b0110, etc.
//
// Notes:
// - Overflow will cause a compilation error.
// - Hex, oct, and binary escapes can go up to 2^64-1 to allow use of all 64
//   bits, but they will still be used as signed values.
concrete Int {
  refines AsBool
  refines AsChar
  refines AsInt
  refines AsFloat
  refines Formatted

  defines Default
  defines Equals<Int>
  defines LessThan<Int>
}

// Built-in string of characters. (ASCII only.)
//
// Literals: Quote Char sequence with ".
concrete String {
  refines AsBool
  refines DefaultOrder<Char>
  refines Formatted
  refines ReadAt<Char>
  refines SubSequence

  defines Default
  defines Equals<String>
  defines LessThan<String>

  // Create a new String as an immutable copy of a CharBuffer.
  //
  // Notes:
  // - Changing the data in the CharBuffer after copying will not result in
  //   modifications to the String returned here.
  // - Data will be copied verbatim, even if some characters are null.
  @type fromCharBuffer (CharBuffer) -> (String)

  // Get a builder to create a string using concatenation.
  //
  // Example:
  //
  //   String.builder().append("foo").append("bar").build()
  @type builder () -> ([Append<String>&Build<String>])
}

// Built-in fixed-size buffer of byte data.
//
// Literals: None.
concrete CharBuffer {
  refines ReadAt<Char>
  refines WriteAt<Char>

  // Create a new buffer with a fixed size.
  //
  // Notes:
  // - The implementation does not guarantee that the values will be zeroed.
  @type new (Int) -> (CharBuffer)

  // Resize the buffer to the specified size.
  //
  // Notes:
  // - The implementation does not guarantee that the values will be zeroed.
  //   Specifically, resizing down and then back up again could either preserve
  //   or overwrite any of the data.
  @value resize (Int) -> (CharBuffer)
}

// Convertible to Bool.
@value interface AsBool {
  // Convert the value to Bool.
  asBool () -> (Bool)
}

// Convertible to Char.
@value interface AsChar {
  // Convert the value to Char.
  asChar () -> (Char)
}

// Convertible to Float.
@value interface AsFloat {
  // Convert the value to Float.
  asFloat () -> (Float)
}

// Convertible to Int.
@value interface AsInt {
  // Convert the value to Int.
  asInt () -> (Int)
}

// Formattable as a String.
@value interface Formatted {
  // Format the value as a String. (Does not need to be reversible.)
  formatted () -> (String)
}

// Supports appending.
//
// Params:
// - #x: The value type to append.
@value interface Append<#x|> {
  // Append a value and return self.
  append (#x) -> (#self)
}

// Supports building a value from the current state.
//
// Params:
// - #x: The value type to build.
@value interface Build<|#x> {
  // Build and return a value from the current state.
  build () -> (#x)
}

// Ordered data, primarily used for the traverse built-in.
//
// Example:
//
//   traverse (someIntOrder -> Int i) {
//     // code that uses index i
//   }
@value interface Order<|#x> {
  // Returns an updated instance, or empty if the end was reached.
  //
  // Notes:
  // - This can return either a mutated self or a new copy. The caller should
  //   assume that next() will mutate the instance.
  // - This should not generally be used directly; use the traverse built-in.
  next () -> (optional #self)

  // Returns the value at the current position.
  get () -> (#x)
}

// Provides a default Order for a container.
//
// Notes:
// - The return value is primarily intended for use with the traverse built-in.
// - Also see the documentation for Order and traverse.
@value interface DefaultOrder<|#x> {
  // Returns the default Order for the container.
  defaultOrder () -> (optional Order<#x>)
}

// Contains a flexible number of values of some type.
@value interface Container {
  // Return the number of values.
  size () -> (Int)
}

// Random-access reading from a container.
//
// Params:
// - #x: The value type contained.
@value interface ReadAt<|#x> {
  refines Container

  // Return the value at the given index.
  readAt (Int) -> (#x)
}

// Random-access writing to a container.
//
// Params:
// - #x: The value type contained.
@value interface WriteAt<#x|> {
  refines Container

  // Write the value at the given index and return self.
  writeAt (Int,#x) -> (#self)
}

// Sequence that can be subsequenced.
@value interface SubSequence {
  refines Container

  // Return a copy of a subsequence.
  subSequence (Int,Int) -> (#self)
}

// The type has a default value.
@type interface Default {
  // Return a new copy of the default value.
  default () -> (#self)
}

// The type can compare values for equality.
//
// Params:
// - #x: The value type to be compared.
@type interface Equals<#x|> {
  // Returns true iff the two values are equal. Must be symmetric.
  equals (#x,#x) -> (Bool)
}

// The type can compare values for less-than.
//
// Params:
// - #x: The value type to be compared.
@type interface LessThan<#x|> {
  // Returns true iff the first value is less than the second.
  lessThan (#x,#x) -> (Bool)
}