DSL

The doit-specific language provides some declarative shortcuts to techniques that usually require more complex Python or shell.

${} Get Environment Variables

Get the value of an environment variable. Usually executed before any other parsers. All config sources share the same namespace.

flowchart LR any-before --> dollar-leftbrace --> var-name --> rightbrace --> any-after any-before([<i>any text</i>]) dollar-leftbrace(["<code>${</code>"]) rightbrace(["<code>}</code>"]) var-name([<i>a variable name</i>]) any-after([<i>any text</i>])

Environment variables are shared across all doitoml configuration files.

Examples

TODO

:get Get File Data

Read a piece of data from a path in a structured file: the result is usally cast to a JSON string, if neccessary.

flowchart LR get --> defaults --> parsers --> paths --> selectors get([<code>:get</code>]) subgraph defaults [0 or 1 default] default(["<code>|</code> <i>value</i>"]) end subgraph parsers [1 parser] direction LR json([<code>::json</code>]) toml([<code>::toml</code>]) yaml([<code>::yaml</code>]) end subgraph paths [1 path] path([<code>::</code><i>path</i>]) end subgraph selectors [1+ selectors] selector([<code>::</code><i>string or int</i>]) end

Use this to get data from a predictable location in a structured data file, such as a software package version.

Examples

pyproject.toml

Get a version number.

[project]
version = "0.1.0"

[tool.doitoml.env]
PY_VERSION = ":get::toml::pyproject.toml::project::version"

package.json

Get a version number.

{
  "version": "0.1.0",
  "doitoml": {
    "env": {
      "JS_VERSION": ":get::json::package.json::version"
    }
  }
}

:: Reference a path or token

Get the value of any paths or tokens, either in the same doitoml configuration file, or with a named prefix (including fnmatch wildcards).

flowchart LR colon-colon --> prefixes --> token_or_path token_or_path -.-> path & tokens prefix & prefix-wildcard -.-> source-prefix colon-colon([<code>::</code>]) token_or_path([<code>::</code><i>token or path</i>]) subgraph prefixes [0 or 1 prefix] prefix([<code>::</code><i>prefix</i>]) prefix-wildcard(["<code>::</code>[<i>fragment, <code>?</code>, or <code>*</code>] ...</i>"]) end subgraph doitoml ["<code>doitoml</code> configuration"] source-prefix("<code>prefix = ...</code>") subgraph paths ["<code>.paths</code>"] path("<code>some_path = [...]</code>") end subgraph tokens ["<code>.tokens</code>"] token("<code>some_token = [...]</code>") end end

Examples

TODO

:glob Find files

flowchart LR glob & rglob --> roots --> matches --> excludes --> subs glob([<code>:glob</code>]) rglob([<code>:rglob</code>]) subgraph roots [1 root] root([<code>::</code><i>path/to/root</i>]) end subgraph matches [1+ matches] match([<code>::</code><i>path/with/*</i>]) end subgraph excludes [0+ excludes] exclude([<code>::!</code>a regex]) end subgraph subs [0+ substitutions] sub([<code>::/s/</code>]) sub-find([<code>::</code><i>a regex</i>]) sub-replace([<code>::</code><i>replacement</i>]) sub --> sub-find --> sub-replace end

Examples

TODO