The Ecosystem

The Ecosystem (Eco for short) represents all packages and their versions used by your application at runtime, including dependency resolution and panicking if there are conflicts/unavailable packages.

Installed packages go straight to ~/.eco - binaries go to ~/.eco/bin (so you should put that in your $PATH), and libraries go to ~/.eco/lib/(package name)/(version).

Eco

Eco  Object

A global object that manages available and loaded packages. Your application should initialize it at startup.

Eco load  @ok

Scan all installed packages in ~/.eco/lib. This is automatically done at startup.

Eco initialize  @ok

"Initialize" the ecosystem. Loads your package's package.eco file and initializes each of its dependencies, recursively.

After the initialization stage, the only packages possible to load with use: will be the ones determined to be "safe" by the dependency resolution.

If a required package is not available, @package-unavailable:needed: is raised.

If no versions of a package satisfy given constraints, @no-versions-of:satisfy:for: is raised.

Eco path-to: pkg  String
  | (pkg is-a?: Eco Package) || (pkg is-a?: String)

Returns the full path to ~/.eco/lib/(package name).

Eco path-to: pkg version: v  String
  | (pkg is-a?: Eco Package) || (pkg is-a?: String)
  | v is-a?: Version

Returns the full path to ~/.eco/lib/(package name)/(version).

Eco executable: name  String
  | name is-a?: String

Returns the full path to ~/.eco/bin/(executable name).

Eco install: path  @ok
  | path is-a?: String

Install the package at path to ~/.eco.

Required files: main.atomo, package.eco.

The two required files and anything listed in the package's include: field are recursively copied to ~/.eco/(package name)/(package version).

Files listed in the package's executables: field are copied to ~/.eco/bin and their executable flag is set to True (ie, +x).

Eco uninstall: name version: version  @ok
  | name is-a?: String
  | version is-a?: Version

Uninstall a package version. Removes its directory from ~/.eco/lib, and removes any executables.

Eco uninstall: name  @ok
  | name is-a?: String

Uninstalls all versions of a package.

top use: name  @ok
  | name is-a?: String

Alias for top use: name version: { True } (that is, a constraint always yielding True).

Example:

use: "ehtml"
top use: name version: constraint  @ok
  | name is-a?: String
  | (constraint is-a?: Block) || (constraint is-a?: Version)

Load the highset version of package name satisfying the constraint (or matching the version) constraint onto top.

Note that this should be called after Eco initialize, which filters out versions that do not satisfy the package's dependency constraints.

Example:

use: "ecss" version: { < (0 . 2) }

Four possible exceptions may be raised:

@(package-unavailable: name)

if the package is not installed.

@(no-package-versions: name)

if the package is installed, but no versions are valid (this should never happen).

@(no-versions-of: (name -> versions) satisfy: constraint)

if none of the package versions installed are satisfactory.

@(incompatible-version-loaded: name needed: constraint)

if the package was already loaded, but the version that was loaded does not satisfy constraint. This may happen if you don't use Eco initialize and just use use:version: everywhere, which is not recommended.

Packages

Eco Package  Object

Represents a package, of a particular version, in the ecosystem.

Eco Package load-from: filename  Eco Package
  | file is-a?: String

Loads a package from filename, typically named package.eco.

Example file:

name: "ehtml"
description: "embedded html dsl"
version: (0 . 1)
author: "Alex Suraci"

Note that filename should be valid Atomo source code; that's all it is. The file is loaded as-is on a new Eco Package; each of those lines is a dispatch.

Eco Package name: n  String
  | n is-a?: String

Sets the package's name to n.

Eco Package description: d  String
  | d is-a?: String

Sets the package's description to d.

Eco Package version: v  Version
  | v is-a?: Version

Sets the package's version to v.

Eco Package author: n  String
  | n is-a?: String

Sets the package's author to n.

Eco Package include: filenames  String
  | filenames is-a?: List

Sets the package's include field to filenames.

Eco Package depends-on: dependencies  String
  | dependencies is-a?: List

Sets the package's dependencies field to dependencies.

Values in the list should be either Associations from package names to a block for checking the package version, or just package names.

For example, to depend on any version of ehtml, and versions greater than 0.1 of ecss:

depends-on: ["ehtml", "eccs" -> { > (0 . 1) }]
Eco Package executables: filenames  String
  | filenames is-a?: List

Sets the package's executables field to filenames.

Versions

Proper comparable version numbers. All of the usual suspects for anything that's comparable are implemented: ==, >, <, >=, and <=. These methods are defined for all combinations of Version and Integer.

Example:

> (0 . 1) < (0 . 2)
True
> 2 > (1 . 9)
True
> (0 . 1) <= (0 . 1 . 1)
True
> (0 . 1) == (0 . 1)
True
> (0 . 1) == (0 . 1 . 0)
True
> 2 == (2 . 0)
True

Note that the parentheses used in version constructors below are not necessary; they are merely here because the documentation scanner parses Atomo source and pretty-prints it, which makes the parentheses explicit.

Version  Object

A version number.

major . minor  Version
  | major is-a?: Integer
  | (minor is-a?: Integer) || (minor is-a?: Version)

The primary Version constructor.

Example:

> 0 . 1
0 . 1
> 1 . 2 . 0 . 3
1 . 2 . 0 . 3
v as: String  String
  | v is-a?: Version

Converts a Version to the typical textual representation of version numbers.

Example:

> (0 . 1 . 2) as: String
"0.1.2"
n to: Version  Version
  | (n is-a?: Integer) || (n is-a?: String)

Conversion from String is the converse of Version as: String.

Example:

> "0.1.2" to: Version
0 . 1 . 2
> (0 . 1 . 2) (as: String) (to: Version)
0 . 1 . 2

Conversion from Integer simply uses it as major and 0 as minor.

Example:

> 1 as: Version
1 . 0