Workspace.Project (Workspace v0.3.1)

A struct holding a workspace project info.

Workspace project config

Each workspace project may optionally have some workspace related settings defined in it's Mix.Project config. There isn't a comprehensive list of all supported options since various plugins or mix tasks may define their own options that can be read from this configuration.

The following are the global workspace supported settings:

:tags - Tags associated with the current project. A single tags can be either an atom or a tuple of the form {atom, atom}. In the latter case this is considered a scoped tag. For example:
```
tags: [:utils, {:scope, :shared}]
```
The default value is [].
:affected_by (list of String.t/0) - List of file paths that if changed will mark this project as affected. This is useful when a project depends on files outside of its root path. Paths are relative to the project's root directory and support wildcards.
```
affected_by: ["../shared/config.ex", "../../docs/*.md", "config/*.json"]
```
Supported wildcards:
- * matches any characters except path separators
- ? matches a single character
- Directory paths will match any file within that directory
The default value is [].

Summary

Types

t()

Struct holding info about a mix project

tag()

A project's tag.

Functions

affected(project)

Marks the given project as :affected.

affected?(project)

Returns true if the project is affected, false otherwise.

config(mix_path)

Returns the Mix.Project config of the given mix.exs file.

ensure_mix_file!(path)

Ensures that the given path is an existing mix.exs file.

format_tag(tag)

Formats a tag as a binary.

has_any_tag?(project, tags)

Returns true if the project has any of the given tags.

has_scoped_tag?(project, scope)

Returns true if the project has at least one scoped tag with the given scope, false otherwise.

has_tag?(project, tag)

Returns true if the project has the given tag, false otherwise.

in_project(path, fun)

Runs the given function inside the given project.

modified(project, changes)

Marks the given project as :modified.

modified?(project)

Returns true if the project is modified, false otherwise

new(path, workspace_path)

Creates a new project for the given project path.

project_type(config)

Returns the project type of a project given the mix config.

relative_to_workspace(project)

Relative path of the project to the workspace

scoped_tags(project, scope)

Returns all tags with the given scope.

set_root(project, root?)

Flags the given project as root project or not.

set_status(project, status)

Sets the status of the given project.

skip(project)

Marks the given project as skippable.

to_map(project, opts \\ [])

Returns a map including the key properties of the given project.

Types

t()

@type t() :: %Workspace.Project{
  affected_by: [String.t()],
  app: atom(),
  changes: nil | [{Path.t(), Workspace.Git.change_type()}],
  config: keyword(),
  mix_path: binary(),
  module: module(),
  path: String.t(),
  root?: nil | boolean(),
  skip: term(),
  status: :undefined | :unaffected | :modified | :affected,
  tags: [tag()],
  workspace_path: binary()
}

Struct holding info about a mix project

tag()

@type tag() :: atom() | {atom(), atom()}

A project's tag.

It can either be a single atom or a tuple of atoms. In the latter case this is considered a scoped tag.

Functions

affected(project)

@spec affected(project :: t()) :: t()

Marks the given project as :affected.

A project is considered affected if any of it's dependencies (either direct or indirect) is modified.

Notice that if the project is already marked as :modified it's status does not change to :affected since by default modified projects are considered affected.

affected?(project)

@spec affected?(project :: t()) :: boolean()

Returns true if the project is affected, false otherwise.

A project is considered :affected if it is either modified or indirectly affected from a modified dependency.

config(mix_path)

@spec config(mix_path :: binary()) :: keyword()

Returns the Mix.Project config of the given mix.exs file.

The project will be loaded using Mix.Project.in_project/4.

ensure_mix_file!(path)

@spec ensure_mix_file!(path :: String.t()) :: :ok

Ensures that the given path is an existing mix.exs file.

If the file does not exist or the filename is not mix.exs it will raise.

format_tag(tag)

@spec format_tag(tag :: tag()) :: String.t()

Formats a tag as a binary.

has_any_tag?(project, tags)

@spec has_any_tag?(project :: t(), tags :: [tag()]) :: boolean()

Returns true if the project has any of the given tags.

has_scoped_tag?(project, scope)

@spec has_scoped_tag?(project :: t(), scope :: atom()) :: boolean()

Returns true if the project has at least one scoped tag with the given scope, false otherwise.

has_tag?(project, tag)

@spec has_tag?(project :: t(), tag :: tag()) :: boolean()

Returns true if the project has the given tag, false otherwise.

Special tags

:* - matches all tags, it always returns true

in_project(path, fun)

@spec in_project(path :: binary(), fun :: (module() -> result)) :: result
when result: term()

Runs the given function inside the given project.

path can be one of the following:

a path to a mix.exs file
a path to a folder containing a mix.exs file

Both absolute and relative paths are supported.

This function will delegate to Mix.Project.in_project/4. The app name is extracted from the project folder name, so it is expected to match the internal defined :app name in mix.exs.

The return value of this function is the return value of fun

Examples

Mix.Project.in_project("/path/to/my_app/mix.exs", fn module -> module end)
#=> MyApp.MixProject

modified(project, changes)

@spec modified(project :: t(), changes :: []) :: t()

Marks the given project as :modified.

The changes is the list of changed files belonging to the current project that have changed.

An exception will be raised if the changes list is empty.

modified?(project)

@spec modified?(project :: t()) :: boolean()

Returns true if the project is modified, false otherwise

new(path, workspace_path)

@spec new(mix_path :: String.t(), workspace_path :: String.t()) :: t()

Creates a new project for the given project path.

The path can be one of the following:

A path to a mix.exs file
A path to a project containing a mix.exs file

You can pass both absolute and relative paths. All paths will be expanded by default.

This will raise if the path does not correspond to a valid mix project.

project_type(config)

@spec project_type(config :: keyword()) :: nil | atom()

Returns the project type of a project given the mix config.

The project type is defined under a :type attribute in the :workspace config. It can take an arbitrary value. If set to :workspace it indicates that the project is a root workspace project.

relative_to_workspace(project)

@spec relative_to_workspace(project :: t()) :: binary()

Relative path of the project to the workspace

scoped_tags(project, scope)

@spec scoped_tags(project :: t(), scope :: atom()) :: [tag()]

Returns all tags with the given scope.

set_root(project, root?)

@spec set_root(project :: t(), root? :: boolean()) :: t()

Flags the given project as root project or not.

set_status(project, status)

@spec set_status(project :: t(), status :: atom()) :: t()

Sets the status of the given project.

skip(project)

@spec skip(project :: t()) :: t()

Marks the given project as skippable.

to_map(project, opts \\ [])

Returns a map including the key properties of the given project.

Only :app, :module, :mix_path, :path, :workspace_path, :status, :root and :changes are included.

Options

:relative - If set to true the paths will be relative with respect to the workspace path. Notice that the workspace_path attribute will be set to "." if relative is set.