paper.tex

\documentclass[sigplan,nonacm]{acmart}
\settopmatter{printfolios=false,printccs=false,printacmref=false}
\usepackage{ffcode}
\usepackage{natbib}
\usepackage{doi}
\usepackage{eolang}
\usepackage[capitalize]{cleveref}
\usepackage{to-be-determined}
\usepackage{csquotes}
\usepackage[utf8]{inputenc}
\usepackage[T2A]{fontenc}
\usepackage[russian,english]{babel}
  \DeclareFontFamilySubstitution{T2A}{LinuxBiolinumT-TLF}{LibertinusSans-TLF}
  \renewcommand\ttdefault{cmtt}
% see https://tex.stackexchange.com/a/256190/1449
\usepackage{url}
  \def\UrlBreaks{\do\/\do-}
\usepackage{breakurl}

\setlength{\footskip}{13.0pt}

\title{On the Origins of Objects by Means of Careful Selection}

\author{Yegor Bugayenko}
\orcid{0000-0001-6370-0678}
\email{yegor256@gmail.com}
\affiliation{
  \institution{Huawei}
  \country{Russia}
  \city{Moscow}
}

\ccsdesc[100]{Object-Oriented Programming}
\keywords{Object-Oriented Programming}

\newcommand\aff[1]{\ff{\textcolor{gray}{\(\star\)}#1}}
\newcommand\deff[1]{\ff{\textcolor{blue!50!black}{\textbf{#1}}}}
\newcommand\adeff[1]{\aff{\textcolor{blue!50!black}{\textbf{#1}}}}
\newcommand\eohex[1]{\ff{#1}}

\tolerance=2000
\raggedbottom

\begin{document}

\begin{abstract}
We introduce a taxonomy of objects for \eolang{} programming language.
This taxonomy is designed with a few principles in mind: non-redundancy,
simplicity, and so on. The taxonomy is supposed to be used as a navigation map
by \eolang{} programmers. It may also be helpful as a guideline for designers of
other object-oriented languages or libraries for them.
\end{abstract}

\maketitle

\section{Introduction}

Each object-oriented programming language offers its own set of objects, classes, types, functions, constants, traits, templates, and so on, which programmers can use off-the-shelf to model their specific use cases:
``Development Kit'' in Java~\citep{jdk2024,java2024},
``Standard Library'' in
  C++~\citep{cpp2024,cpp2012},
  Python~\citep{python2024,python2017},
  Swift~\citep{swift2024,swift2015},
  Rust~\citep{rust2024,rust2021},
  and
  Ruby,
``.NET Standard'' in C\#~\citep{net2023,net2005},
``Built-in Objects'' in JavaScript~\citep{js2024,js2008},
and so on.

Each Standard Library (SL) freely defines its own principles of abstraction. For
example, to get an absolute value of a numeric object \ff{x} in Java, one has
to call a static method of another class \ff{Math.abs(x)}, while in Ruby it
would be a property of the same object \ff{x.abs}. For example, in Java, an
attempt to get a value from a hash map by a key will produce \ff{null} in case
of its absence, while in C++ it will return an empty iterator. There are many
similar examples demonstrating the absence of common ground between SLs.

Earlier, \citet{booch1990design} suggested their own components for OOP. We
suggest our own taxonomy of objects for
EO\footnote{\url{https://www.eolang.org}},
a strictly formal~\citep{kudasov2021} object-oriented programming language with an intentionally
reduced feature set~\citep{bugayenko2021eolang}.
All objects are grouped as such:

\begin{itemize}
    \item Primitives (\cref{sec:bytes})
    \item Primitives (\cref{sec:primitives})
    \item Tuple (\cref{sec:tuple})
    \item Error handling (\cref{sec:errors})
    \item Flow control abstractions (\cref{sec:flow})
    \item Non-standard bit-width numbers (\cref{sec:digits})
    \item Memory abstractions (\cref{sec:memory})
    \item Math functions and algorithms (\cref{sec:math})
    \item String manipulations (\cref{sec:strings})
    \item Structs (\cref{sec:structs})
    \item I/O Streams (\cref{sec:streams})
    \item File System abstractions (\cref{sec:fs})
    \item Net Sockets (\cref{sec:sockets})
    \item HTTP request and response (\cref{sec:http})
    \item Synchronization in multi-threading (\cref{sec:synchronization})
\end{itemize}

An object in \eolang{} is either a composition of other objects or an atom, which is a
foreign function interface to a lower-level runtime such as, for example, JVM
or Assembly. In this paper, we denote atoms by a star, for example:
\aff{times}.

Everywhere in the paper we use dark blue color to highlight an object when it is
mentioned for the first time.

In this paper\footnote{%
\LaTeX{} sources of this paper are maintained in the
\href{https://github.com/REPOSITORY}{REPOSITORY} GitHub repository,
the rendered version is \href{https://github.com/REPOSITORY/releases/tag/0.0.0}{\ff{0.0.0}}.}
we don't provide exact specification of each object, in order to avoid
conflicts with their exact definitions in the
Objectionary\footnote{\url{https://www.objectionary.com}}.

\section{Principles}

We adhere to a few principles:
\begin{enumerate}
  \item We tend to minimize the global scope, keeping the number of global objects to the absolute possible minimum.
  \item Wherever possible, objects must be implemented in EO, instead of being atoms.
  \item There should be no functionality implemented two or more times in the entire taxonomy.
  \item Object names must not be abbreviated and must constitute an English sentence when being used through dot notation, for example:
\begin{ffcode}
x.times y > z
\end{ffcode}
means ``\(x\) times \(y\) is \(z\).''
There are a few exceptions though, like \ff{eq}, \ff{seq}, \ff{lt}, and a few others.
\end{enumerate}

In case of any runtime error, an object is supposed to ``return'' an error
object, with the \ff{message} attribute present (attached to any object) and
the \ff{@} attribute absent.

\section{Bytes}\label{sec:bytes}

The center of the taxonomy is the \deff{bytes} data object, which is an abstraction
of a sequence of bytes. The sequence can either be empty or contain a
theoretically unlimited number of bytes. A byte is a unit of information that
consists of eight adjacent binary digits (bits), each of which consists of a \ff{0}
or \ff{1}. In \eolang{} syntax, a sequence of bytes is denoted as either \eohex{--}
(double dash) for an empty one or as a concatenation of \eohex{xx-}, where
\ff{xx} is a hexadecimal representation of a byte. For example, the \ff{2A-} is
a one-byte sequence, where the only byte equals to the number 42.

The \ff{bytes} object has these four attributes, to turn itself into
one of four primitive data objects:
\adeff{as-int},
\adeff{as-bool},
\adeff{as-float},
and
\adeff{as-string}.
The attribute \aff{as-int} expects the size of the sequence to be eight bytes.
The attribute \aff{as-bool} expects exactly one byte in the sequence and is
\ff{FALSE} only if the byte equals to zero.
The attribute \aff{as-float} expects exactly eight bytes.

There are also attributes for bitwise operations:
\adeff{and},
\adeff{or},
\adeff{xor},
\adeff{not},
\adeff{left},
and
\adeff{right}.

The object also has the \adeff{eq} attribute for byte-by-byte comparing
itself with another sequence of bytes.

The \adeff{size} attribute is the total number of bytes in the sequence.

The \adeff{slice} attribute represents a sub-sequence inside the current one.

The \adeff{concat} attribute is a new sequence, which is a concatenation
of two byte sequences: the current and the provided one.

\section{Primitives}\label{sec:primitives}

There are four primitive data objects described below. All of them have
\adeff{as-bytes} attribute, which is an abstraction of their representation as a
sequence of bytes. All primitives also have \deff{as-hash} attribute, which,
being an \ff{int}, is their own implementation of a hash function. They also
have \deff{eq} attribute, which is \ff{TRUE} if the primitive is equal to
another object, through the use of \ff{\^{}.as-bytes.eq}.

\subsection{Int}

The object \deff{int} is an eight-bytes abstraction of a two's complement signed integer in a big-endian order.

The \adeff{plus} attribute is a summary of this number and another \ff{int}.
The \deff{minus} attribute is a subtraction of another \ff{int} from this number.
The \adeff{times} attributes and \adeff{div} are a multiplication and a division of this number and another \ff{int}.
The \deff{neg} attribute is the same number with a different sign.

The \adeff{lt} attribute is a \ff{bool} object \ff{TRUE} if it is ``less than'' another \ff{int} and \ff{FALSE} otherwise. Attributes \deff{gt}, \deff{lte}, and \deff{gte} are ``greater than,'' ``less than or equal,'' and ``greater than or equal'' comparisons respectively.

Integers with a different bit-width are explained in \cref{sec:digits}.
All other manipulations with integers can be done in their decorators. Some of them are explained in \cref{sec:math}.

\subsection{Bool}

The \deff{bool} object is a one-bit abstraction of a Boolean value. Its
\aff{as-bytes} is either \eohex{00-} or \eohex{01-}.

There are two pre-defined objects \deff{TRUE} and \deff{FALSE}.

The \deff{not} attribute is a Boolean inversion. Attributes \deff{and},
\deff{or}, \deff{xor} are logical conjunction, disjunction, and exclusive
disjunction of the object itself with an a array of other Boolean values.

\subsection{Float}

The object \deff{float} is an abstraction of a floating point number, which
takes eight bytes and fills them up according to the format suggested by
\citet{ieee754}.

The \adeff{plus} attribute is a summary of this number and another \ff{float}.
The \deff{minus} attribute is a subtraction of another \ff{float} from this number.
The \adeff{times} attributes and \adeff{div} are a multiplication and a division of this number and another \ff{float}.
The \deff{neg} attribute is the same number with a different sign.

The \adeff{lt} attribute is a \ff{bool} object \ff{TRUE} if it is ``less than'' another \ff{float} and \ff{FALSE} otherwise. Attributes \deff{gt}, \deff{lte}, and \deff{gte} are ``greater than,'' ``less than or equal,'' and ``greater than or equal'' comparisons respectively.

Floating-point numbers with a different bit-width are explained in
\cref{sec:digits}. All other manipulations with floating-point numbers can be done
in their decorators. Some of them are explained in \cref{sec:math}.

\subsection{String}

The \deff{string} object is an abstraction of a piece of Unicode text in UTF-8
encoding, according to \citet{unicode}. UTF-8 uses one byte for the first 128
code points, and up to 4 bytes for other characters.

The \adeff{slice} attribute takes a piece of a string as another \ff{string}.
The \adeff{length} attribute is a total count of characters in the string.

Strings in other encodings, such as UTF-16 or CP1251, may be implemented
through direct manipulations with \ff{bytes}.

All other manipulations with strings are explained in \cref{sec:strings}.

\section{Tuple}\label{sec:tuple}

The \deff{tuple} object is an abstraction of an immutable sequence of objects.
For example, this code represents a two-dimensional tuple \ff{x} of numbers and strings:

\begin{ffcode}
* > x
  * "green" 0x0D1
  * "red" 0xF21
  * "blue" 0x11C
\end{ffcode}

The \adeff{with} attribute is a new \ff{tuple} with all elements
from the current tuple and a new element added to the end of it.

The \adeff{at} attribute is the element of the tuple with
it is associated index number---positive one, zero indexed and starting
from left, and the negative one starting at -1 from the right.

The \adeff{length} attribute is the total amount of elements in the tuple.

All other manipulations with tuples can be implemented in their
decorators. Some of them are explained in \cref{sec:structs}.

\section{Error Handling}\label{sec:errors}

Here we define objects that help handle errors and exceptional situations.

The \adeff{error} object causes program termination at the first attempt to
dataize it. It encapsulates any other object, which can play the role of an
exception that is floating to the upper level:

\begin{ffcode}
[x] > d
  if
    x.eq 0
    error "Can't divide by zero"
    42.div x
\end{ffcode}

The \adeff{try} object enables catching of \aff{error} objects and extracting
exceptions from them. For example, the following code prints "division by zero"
and then "finally":

\begin{ffcode}
try
  []
    42.div 0 > @
  [e]
    QQ.io.stdout > @
      e
  []
    QQ.io.stdout > @
      "finally"
\end{ffcode}

\section{Flow Control}\label{sec:flow}

Here we define objects that help control dataization flow.

The \adeff{seq} object is an abstraction of sequence of objects to be dataized
sequentially. For example, this code prints one message to the console and then
terminates the program due to the inability to dataize the division by zero in
the middle:

\begin{ffcode}
seq
  *
    QQ.io.stdout "Hello, world!
    42.div 0
    QQ.io.stdout "Bye!"
\end{ffcode}

The \adeff{if} object is a branching mechanism, expecting three arguments: a
condition as \ff{bool}, a ``positive'' object, and a ``negative'' object. When
being dataized, the object \aff{if} first dataizes the condition and then,
according to the result obtained, either returns the positive object or the
negative one. Both positive and negative objects must have the same form. This
code give a title to a random number:

\begin{ffcode}
QQ.math.random.pseudo > r
QQ.io.stdout
  QQ.txt.sprintf
    "Coin toss: %s"
    if
      r.gte 0.5
      "heads"
      "tail"
\end{ffcode}

The \adeff{while} object is an iterating mechanism, expecting two attributes: a
condition as \ff{bool} and a body as an abstract object with one free
attribute. When being dataized, the object \aff{while} dataizes the condition
until it is \ff{FALSE}. In the end, it returns the body or \ff{FALSE} if no
iterations happened. This code makes a few attempts to find a random number
that is smaller than 0.1:

\begin{ffcode}
QQ.math.random.pseudo > r
while
  r.gte 0.1
  [i]
    QQ.io.stdout > @
      QQ.txt.sprintf
        "Attempt #%d" i
\end{ffcode}

The \adeff{go} object enables forward and backward ``jumps'' either
immediately finishing dataization or restarting it. For example, this code
won't print a message to the console if \ff{x} is equal to zero:

\begin{ffcode}
go.to
  [g]
    seq > @
      *
        if > y
          x.eq 0
          g.forward 0
          42.div x
        QQ.io.stdout
          QQ.txt.sprintf "42/x = %d" y
\end{ffcode}

In this example, the number will be read from the console again,
if it is equal to zero:

\begin{ffcode}
go.to
  [g]
    seq > @
      *
        as-int. > x
          QQ.txt.parsed
            QQ.io.stdin
        if
          x.eq 0
          g.backward
          QQ.io.stdout
            QQ.txt.sprintf
              "Number %d is OK!" x
\end{ffcode}

The \deff{switch} object is an abstraction of a multi-case branching that
encapsulates \((k, v)\) pairs and the dataization result is equal to \(v\) of
the first pair where \(k\) is \ff{TRUE}, while the last pair is the one to be
used if no other pairs match:

\begin{ffcode}
QQ.io.stdout
  switch
    *
      *
        password.eq "swordfish"
        "password is correct!"
      *
        password.eq ""
        "empty password is not allowed"
      *
        FALSE
        "password is wrong"
\end{ffcode}

\section{Digits}\label{sec:digits}

Here we define objects that represent numbers with smaller or larger bitwise
width comparing with the default 64-bits convention. All objects presented in
this Section belong to the \ff{QQ.digits} package.

The \deff{int8}, \deff{int16}, \deff{int32}, and \deff{int128} objects are decorators
of \ff{bytes} with a predefined size. They implement the same numeric operations
as \ff{int}.
The \deff{float16}, \deff{float32}, and \deff{float128} objects are
also decorators of \ff{bytes}, implementing the same operations as \ff{float}.

\section{Memory}\label{sec:memory}

Here we define objects that manage memory.

The \adeff{memory} object is an abstraction of a read-write memory capable of
storing one of five primitive data objects mentioned in
\cref{sec:primitives}. The \adeff{write} attribute implements writing operation,
while the \aff{memory} object itself decorates the data object stored in it.
Before every writing to the memory, the \adeff{memory} dataizes the argument.
This code writes a number into memory and then reads it back and prints:

\begin{ffcode}
(memory 0).alloc > m
seq
  *
    m.write 42
    QQ.io.stdout
      QQ.txt.sprintf
        "Memory contains %d"
        m.as-int
\end{ffcode}

The \adeff{cage} object is similar to the \aff{memory}, but it stores an object, not the result of its dataization.
The use of \aff{cage} is strongly discouraged. The
following code stores a ``book'' in a \aff{cage}, then retrieves it back, and
prints one of its attribute:

\begin{ffcode}
[title author] > book
book > ot
  "Object Thinking"
  "David West"
(cage book).new > c
seq
  *
    c.encage ot
    QQ.io.stdout
      QQ.txt.sprintf
        "Title is %s" c.title
\end{ffcode}

The \deff{malloc} object is an abstraction of a random-access memory of certain
size. It behaves like the \ff{bytes}, but has an additional \adeff{write} attribute.
In this example, one kilobyte of memory with random data is allocated
when a copy of \ff{malloc} is created, six bytes are written starting with the
200-th byte, and then a string is read back and \ff{"Hello!"} is printed:

\begin{ffcode}
(malloc 1024).pointer > p
seq
  *
    p.write 200 "Hello!"
    QQ.io.stdout
      as-string.
        p.read 200 6
\end{ffcode}

\section{Math}\label{sec:math}

Here we define objects that represent math functions and algorithms.
All objects in this Section belong to the \ff{QQ.math} package.

The \deff{random} object is a abstraction of a random \ff{float} between zero
and one inclusively. It has an additional attribute \adeff{pseudo} that
makes \ff{random} with a pseudorandom seed.

The \deff{angle} object is a decorator of \ff{float}. It assumes that the angle
is in radians and has the following attributes for trigonometric functions:
\deff{sine}, \deff{cosine}, and \deff{tangent}. There are \deff{as-degrees}
and \deff{as-radians} attributes for switching from radians to degrees and backwards.

The \deff{number} object is a decorator of \ff{int} and \ff{float} with the
following additional attributes:

\begin{itemize}
    \item \deff{abs}: absolute value of itself (|\rho|)
    \item \deff{ceil}: round itself up
    \item \deff{floor}: round itself down
    \item \deff{ln}: natural logarithm (\(\ln \rho\))
    \item \deff{log}: logarithm (\(\log_x \rho\))
    \item \deff{max}: the greater of itself and another number
    \item \deff{min}: the smaller of itself and another number
    \item \deff{power}: itself raised to the power (\(\rho^x\))
    \item \deff{signum}: the sign of itself, as \ff{-1}, \ff{0}, or \ff{+1}
    \item \deff{sqrt}: square root of itself (\(\sqrt\rho\))
\end{itemize}

\section{Strings}\label{sec:strings}

All objects presented in this Section belong to the \ff{QQ.txt} package.

The \deff{sscanf} object encapsulates two \ff{string} objects: a format and
a content. It behaves like a tuple of scanned data objects.
For example, this code parses a hexadecimal number from the console:

\begin{ffcode}
at.
  QQ.txt.sscanf
    "%x"
    QQ.io.stdin
  0
\end{ffcode}

The \deff{sprintf} object builds a string according to the format provided and
compliant with \citet[Chapter 5]{posix}, for example:

\begin{ffcode}
QQ.txt.sprintf
  "Hi, %s! The weight is %0.2f."
  "Jeff"
  3.14
\end{ffcode}

The object \deff{text} is a decorator of a \ff{string}, it has the following attributes:

\begin{itemize}
    \item \deff{contains}: checks whether it contains \(x\)
    \item \deff{ends-with}: checks whether it ends with \(x\)
    \item \deff{index-of}: finds the first occurence of a sub-string
    \item \deff{joined}: joins a tuple with this one as a glue
    \item \deff{chained}: concatenates two strings
    \item \deff{low-cased}: makes it lower case
    \item \deff{last-index-of}: finds the last occurence of a sub-string
    \item \deff{left-trimmed}: removes leading spaces
    \item \deff{replaced}: finds and replaces a sub-string
    \item \deff{right-trimmed}: removes trailing spaces
    \item \deff{split}: breaks it into a tuple of strings
    \item \deff{starts-with}: checks whether it starts with \(x\)
    \item \deff{trimmed}: removes both leading and trailing spaces
    \item \deff{up-cased}: makes it upper case
\end{itemize}

The \deff{regex} object is an abstraction of a regular expression, in accordance
with \citet[Part~2]{posix} (Extended Regular Expressions) and full support of
Unicode. The \deff{match} attribute is a split of the \ff{string} into parts:

\begin{ffcode}
QQ.txt.regex "/((*@и@*)([^ ]+))/i" > r
r.match > m
  "(*@Из искры возгорится пламя@*)"
eq.
  m
  *
    *
      "(*@Из@*)"
      0
      *
        "(*@И@*)"
        * "(*@з@*)" 1 *
    * " "
    *
      "(*@искры@*)"
      3
      *
        "(*@и@*)"
        * "(*@скры@*)" 4 *
    * " (*@возгор@*)"
    *
      "(*@ится@*)"
      15
      *
        "(*@и@*)"
        "(*@тся@*)" 16 *
    * " (*@пламя@*)"
\end{ffcode}

\section{Structs}\label{sec:structs}

Here, we discuss abstractions of lists, maps, sets, and other ``structs.''
All objects presented in this Section belong to the \ff{QQ.structs} package.

\subsection{List}

The object \deff{list} is a decorator of \ff{tuple}.

The attribute \deff{is-empty} is \ff{TRUE} if the length of the tuple is zero.

The attribute \deff{eq} is \ff{TRUE} if each element of the tuple is equal to
the corresponding element of another tuple and the lengths of both tuples are
the same.

The attribute \deff{without} is a new tuple with the \(i\)-th element removed.

The attributes \deff{each}, \deff{reduced}, \deff{found}, \deff{filtered}, and \deff{mapped} are respectively similar to \ff{forEach}, \ff{reduce}, \ff{find}, \ff{reduce}, and \ff{map} methods of \ff{Tuple} object in JavaScript~\citep{EcmaScript}. A few ``twin'' attributes \deff{eachi}, \deff{reducedi}, \deff{filteredi}, \deff{foundi}, and \deff{mappedi} are semantically the same, but with an extra \ff{int} argument as a counter of a cycle.

The \deff{slice} attribute is a part of the tuple.

The \deff{sorted} attribute is a new tuple with elements sorted using the \ff{lt} attribute of the elements passed.

The \deff{reversed} attribute is a new tuple with elements positioned in a reverse order.

The \deff{concat} attribute is a new tuple that concatenates the current tuple with the tuple provided as an argument.

\subsection{Map}

The object \deff{map} is a decorator of \ff{tuple} of pairs \((k, v)\). The \ff{map}
ensures that all \(k\) are always unique. It is expected that each \(k\)
has \ff{as-hash} attribute that behaves as \ff{int}.

The attributes \ff{with}, \ff{without}, \ff{found}, and \ff{foundi} are reimplemented in \ff{map}.

\subsection{Set}

The object \deff{set} is a decorator of \ff{tuple}. The \ff{set} ensures that
all elements in the tuple are always unique. It is expected that each
\(k\) has \ff{as-hash} attribute that behaves as \ff{int}.

The attributes \ff{with}, \ff{without}, \ff{found}, and \ff{foundi} are reimplemented in \ff{set}.

\section{I/O Streams}\label{sec:streams}

Here we define manipulations with input and output streams. All objects
presented in this Section belong to the \ff{QQ.io} package.

It is expected that an input stream has the following interface:

\begin{ffcode}
[] > input
  data > @
  [max-count] > read /input
  [] > close
\end{ffcode}

It is expected that an output stream has the following interface:

\begin{ffcode}
[] > output
  [bytes-to-write] > write /input
  [] > close
\end{ffcode}

The \adeff{stdout} object is an ``output'' that prints a \ff{string} to the
standard output stream, while the \adeff{stderr} object is an ``output'' that
prints to the standard error stream.

The \adeff{stdin} object is an abstraction of a \ff{string} currently available
in the standard input stream until the EOL character (\ff{\char`\\n}) and is an
``input.'' If there is no string in the stream, the object blocks dataization
and waits. This code endlessly reads strings from the console and immediately
prints them back:

\begin{ffcode}
while
  TRUE
  [i]
    QQ.io.stdout > @
      QQ.io.stdin
\end{ffcode}

The object \adeff{bytes-as-input} is an ``input'' made from \ff{bytes}.

The object \adeff{memory-as-output} is an ``output'' directed towards a copy of \ff{memory}.

The object \adeff{copied} is channel between an ``input'' and an ``output,''
which moves all available bytes from the former to the latter when being
dataized. For example, this code write a text to a temporary file:

\begin{ffcode}
QQ.io.copied
  QQ.io.bytes-as-input
    as-bytes.
      "Hello, world!"
  as-output.
    QQ.fs.file "/tmp/foo.txt"
    "w+"
\end{ffcode}

The object \deff{content} is a \ff{string} representation of the entire content of an ``input.''

\section{File System}\label{sec:fs}

Here we define manipulations with files and directories.
All objects presented in this Section belong to \ff{QQ.fs} package.

The object \deff{file} is an abstraction of a file and is a decorator of \ff{string}, which is the path of the file.
%
The attribute \adeff{exists} is \ff{TRUE} if the file exists.
%
The attribute \adeff{is-dir} is \ff{TRUE} if the file is a directory.
%
The attribute \adeff{touch} makes sure the file exists.
%
The attribute \adeff{rm} removes the file.
%
The attribute \adeff{mv} renames or moves the file to a new place.
%
The attribute \adeff{size} is the size of the file in bytes.
%
The attribute \adeff{as-output} is an output stream for this file, while the attribute \adeff{as-input} is an input stream.

The object \deff{directory} is an abstraction of a directory.
%
The attribute \deff{mkdir} creates the directory with all its parent directories.
%
The attribute \deff{rm-rf} deletes the directory recursively with all its subdirectories.
%
The attribute \deff{walk} finds files in the directory using glob pattern matching.
%
The attribute \deff{tmpfile} is a temporary file in the directory.

The object \adeff{tmpdir} is a system \ff{directory} of temporary files.

The object \deff{path} is a decorator of a \ff{string} and is a path of a file.
%
The attribute \adeff{resolve} is a new path with a suffix appended to the current one.
%
The attribute \adeff{dir-name} is the name of the directory in the path.
%
The attribute \adeff{ext-name} is the extension in the path.
%
The attribute \adeff{base-name} is the name of the file in the path.

\section{Sockets}\label{sec:sockets}

Here we define objects used for both server-side and client-side TCP sockets in
accordance with \citet{posix}. All objects presented in this Section belong
to the \ff{QQ.net} package.

The \deff{socket} object is an abstraction of a TCP socket. The \adeff{connect} attribute
establishes a connection and makes a copy of the socket object. Then,
its \adeff{as-input} and \adeff{as-output} attributes may be used for reading
from the socket and for writing to it. For example, this code opens a
connection to the 80th TCP port of \ff{google.com} and then reads the entire
stream as a Unicode string:

\begin{ffcode}
connect. > s
  QQ.net.socket
    "google.com"
    80
seq
  *
    QQ.io.stdout
      QQ.io.content
        s.as-input
    s.close
\end{ffcode}

The \adeff{listen} attribute makes a copy of the socket and establishes a server
connection. Then, the \adeff{accept} attribute can be used to wait for an
incoming connection and then make a copy when it arrives. For example, this
code binds to the 8080th port on a ``localhost'' and when a connection arrives,
prints a message into it:

\begin{ffcode}
listen. > s
  QQ.net.socket
    "127.0.0.1"
    8080
QQ.io.copied
  QQ.io.bytes-as-input
    "Hello, world!".as-bytes
  s.accept.as-output
s.close
\end{ffcode}

The attribute \adeff{close} terminates the connection and makes the
closed \aff{socket} object impossible to use anymore.

\section{HTTP}\label{sec:http}

Here we define objects used for parsing and printing HTTP requests and
responses in accordance with \citet{rfc2616}. All objects presented in this
Section belong to the \ff{QQ.http} package.

The objects \deff{http-request} and \deff{http-response} are abstractions of
HTTP request and response respectively. They have attributes that help building
them; they both have the \deff{as-string} attribute to turn them into a
\ff{string}:

\begin{ffcode}
http-request
.with-method 'GET'
.with-address '/index.html'
.with-header 'Accept-Encoding' 'utf-8'
.with-cookie 'Session-Id' '8F09A4E438C'
.with-content-type 'plain/text'
.as-string > r
\end{ffcode}

They both have the \deff{from-string} attribute to create objects from a \ff{string}.
They also have attributes that represent the pieces, which request and response are built of:

\begin{ffcode}
http-response.from-string "..." > r
r.status
r.header 'Content-Type'
r.cookie 'Session-Id'
\end{ffcode}

\section{Synchronization}\label{sec:synchronization}

Here we define objects used for explicit synchronization between threads.
All objects presented in this Section belong to the \ff{QQ.sync} package.

The \deff{semaphore} object is a counting semaphore with two attributes: \adeff{capture} and \adeff{release}.

The \deff{atomic-memory} object is a synchronized decorator of \ff{memory} with a binary \ff{semaphore} encapsulated.

\raggedright
\bibliographystyle{ACM-Reference-Format}
\bibliography{main}

\end{document}