The Ecosystem

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).

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.

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.

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.

Version → Object

A version number.

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

The primary Version constructor.

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

> (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.

> "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.

> 1 as: Version
1 . 0