include.d

// // // //
// // //
// ////// ////// // // // ////// ////// //////
// // // // // // // // // ////// // //
// // // ////// // ////// ////// ////// // //////


Include.d is a library of classes, functions, and constants for
inclusion in larger scripts. If you plan to make use of include.d, or
especially if you plan to make pull requests to include.d, it could be
helpful to understand the naming and other conventions we use here.

== this file ==
This file is meant as a plain text file. Gogs, the software used by
Volatile Git and NotABug.og, mistakingly interprets it as a Markdown
file on some pages and condenses the spacing on other pages. This file
should be readable in either case, but is formated for view in a plain
text viewer using a fixed-width font. Any mangling of the ASCII art
above or strange line lengths when viewed using other methods are not
something that can be fixed on our end.

== licensing ==
Include.d is released under the GNU GPLv3+. This fact MUST be included
in the comments at the top of each class, function, and constant file.
Individual files may instead be under a GNU GPL-compatible other
license, but this license MUST be mentioned in the comments at the top
of the file also or instead.

== case insensitivity ==
Unfortunately, PHP handles namespace, class, and function names in a
case-insensitive manor. for compatibility with \spl_autoload(),
namespace directories and class file names must be spelled using
lower-case letters. For consistency between the file tree structure and
the class files, this also means that namespace and class names are
specified in lower case. Although functions cannot be autoloaded, for
consistency, this rule applies to function names as well, though not
necessarily method names. Because constant names are case-sensitive
like they should be, files containing constants may contain upper- or
lower-case letters, but the case much match what is declared in the
file.

== directory structure ==
Include.d is structured such that if include.d is in your include path
and you have run \spl_autoload_register() without any arguments,
autoloading of classes will function without any further effort. This
means that namespaces are mapped to directories of the same name and
nested namespaces are mapped to nested directories. Class files are
named ".php". Unfortunately, functions and constants are
not automatically loadable. To keep them from accedentally being loaded
when searching for a class of the same name, they are placed in
subdirectories of their respective namespace directories. Constants are
placed in the "const" directory and functions are placed in the
"function" directory. Because the strings "const" and "function" are
PHP keywords, they will not appear in any namespace path and will not
be accidentally autoloaded. It also makes sense to have this extra
directory because functions and constants are imported using "use
function" and "use const" respectively, while classes (and namespaces)
are imported using only the keyword "use". These functions and
constants can be easily included in a script if include.d is in your
include path by including
"/<'const' or 'function'>/.php".

== in-file limitations ==
Each file may only define one class, function, or constant, and it must
be the one that is expected given our file- and directory-naming
conventions. If there is a set of related functions, they must either
be split and placed in different files or must be made into class
methods. If a group of constants is related, they COULD be implemented
as class constants, but if no functions are involved, they SHOULD be
implemented as a constant array. It is recommended that files ONLY
include code for defining a given class, function, or constant and not
include any function calls or variable assignments outside of a
function/method/class definition. As function calls are discouraged,
use of define() to define constants is discouraged and the const
keyword is preferred.

== namespacing ==
All code within this library MUST be namespaced to prevent name
collision with other libraries. The preferred namespace naming
mechanism for code in this library is to use the segment-reversed name
of a domain that the author controls. For example, if you control the
domain "example.com.", your code should be placed within the
\com\example namespace. Typically, when someone controls a domain name,
they also control all subdomains of that domain, so the owner of
"example.com." could also place code in the \com\example\subspace
namespace. If you do not already have a domain name and do not want to
pay yearly domain fees, you may generate an onion address (you do not
have to actually put the onion address into use) or select a subdomain
of the "local." TLD. Special-use domains are taken into account and the
\localhost namespace is reserved for defining classes, functions, and
especially constants that are different on a per-system basis. Such
constants are useful for defining user settings, for example. Names in
the root name space that are considered special, such as the function
name "__autoload", are the exception to this. A special functionality
shouldn't be avoided simply on the grounds that using it requires use
of a name in the root namespace.


== namespace resolution ==
Due to the way that namespaces are resolved when working from within a
namespace, ALL function and constant names MUST be qualified or
fully-qualified. Use of unqualified function and constant names within
this library is prohibited.

== errors ==
All code in this library must assume that ANY error, even those as
minor as E_WARNING, may lead to script termination. The "@"
error-suppression operator does not change this fact and must not be
used. Errors may be emitted if an error actually occurs, but they MUST
NOT be emitted as part of normal execution. If needed, be sure to
perform data checks before calling any functions within your functions
instead of using the error-suppression operator.

== coding conventions ==
These conventions are not enforced, but if followed, will help our
library look more unified.
* When indenting code, tabs are preferred over spaces.
* "if(): <...> endif;" is preferred over "if { <...> }". To be clear,
this applies to all available "end*" keywords, not just "endif".
* "/** **/"-style comments are preferred only to document code in
phpDocumentor format.
* "/* */"-style comments are preferred only in places where it's
useful to place code after the comment on the same line. These
comments shouldn't span multiple lines, as they look too much like
documentation comments.
* "//"-style comments are preferred for comments that shouldn't be
rendered as documentation. These comments will probably be seen
only by people looking at the code, and should be used anywhere in
which we're writing notes to ourselves and other developers about
why something is done or how it works, among other things.
* "#"-style comments are preferred for commenting out lines that are
otherwise valid code. Usually, this lines will probably be removed
from the library, but they may be left in for future uncommenting
or to show examples.

== exception codes ==
Every exception thrown from the include.d library has a unique
exception code, which is potentially useful for debugging. To insure
that exception codes are not reused, five- or six-character strings are
encoded as integers using the \sy\y\string_to_code() function. The
string is added to the known exception code registry and the integer is
used as the exception code. This exception code registry is a file
included in the debug code repository.

== documentation ==
All of our classes, methods, class constants, properties, functions,
and constants are documented using phpDocumentor-style comments. At a
minimum, classes, functions, and constants must use the @category,
@package, @subpackage, and @since tags, where @since is the include.d
version in which the named structure was added. Methods, class
constants, and properties shouldn't use the @category, @package, and
@subpackage tags, but must use the @since tag. Additionally, files must
not throw errors when phpDocumentor builds documentation, at least not
based on the comments or lack of information in the comments. To
prevent errors, file-level documentation comments must be provided, but
the file-level documentation should contain only the name of the
library, the fact that it's under the GNU GPLv3+ (or whatever
compatible license that that particular file is under), and the
@category, @package, and @subpackage tags with values copied from the
documentation of the named construct that the file contains.
Additionally, the @author, @copyright, @filesource, and @license tags
should be used, but no other phpDocumentor tags should be used in the
file-level documentation.

== version numbers ==
When merging a branch with master, the version is incremented in the
following way. The number of nested namespaces used by a new named
structure is counted. If the structure is a class, not a constant,
class constant, function, method or property, subtract one. If multiple
new structures were added in the new version, take the structure that
yields the smallest value. If no new named constructs were added,
instead find the highest value produced with the preceding algorithm on
existing structures and add one. Named constructs that cannot be
\namespaced because of special names do not count for calculating this
number.

For example, if the class \org\example\example_class is added, the
number would be two. If the function \org\example\example_function() is
added, the number is three. If the method
\org\example\subnamespace\sample::parse() is added, the number is four.

After finding the number above, we increment the number in that
component place in the version number and remove any less significant
components. As the root namespace is not used by named constructs in
this library outside of those with special names, the most significant
version component, component zero, is never incremented. We will always
be at version 0.*, we will never reach version 1.

== To do lists ==
Normally, when something needs to be done later, a note should be
placed in an appropriate comment using a @todo tag, where phpDocumentor
will find it and remind us of it. However, sometimes something needs to
be done in a non-code file or needs to be done in a file that doesn't
exist yet. In these cases, the @todo tag should be placed in the
comment that documents the \st\y\VERSION constant. This constant
contains information not about itself, but about include.d as a whole,
so it can be used as a centralized place to place to store information
that doesn't fit better in another part of the library when needed.