Skip to content

Commit

Permalink
refactor: move repo to sudoblockio
Browse files Browse the repository at this point in the history
  • Loading branch information
robcxyz committed Dec 6, 2022
1 parent 9970987 commit 33b3a6d
Show file tree
Hide file tree
Showing 5 changed files with 52 additions and 45 deletions.
64 changes: 32 additions & 32 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,44 +12,44 @@

[//]: # ([![main-tests](https://github.com/robcxyz/tackle/actions/workflows/main.yml/badge.svg)](https://github.com/robcxyz/tackle/actions))

* [Documentation](https://robcxyz.github.io/tackle)
* [Documentation](https://sudoblockio.github.io/tackle)
* [Discord](https://discord.gg/7uVUfUVD7K)
* [PyPI](https://pypi.org/project/tackle/)
* [BSD License](LICENSE)

[//]: # (* [Slack](https://join.slack.com/t/slack-y748219/shared_invite/zt-1cqreswyd-5qDBE53QlY97mQOI6DhcKw))

Tackle is an experimental DSL for building modular code generators and declarative CLIs. Built as a fork of [cookiecutter](https://github.com/cookiecutter/cookiecutter), it can make any config file dynamic or into a CLI with both strong and weakly typed programmable flow control common to a general purpose programming language. Basically you can write a fully functional Turing-complete program out of a config file. It's wild.
Tackle is an experimental general purpose configuration for building modular code generators and declarative CLIs. Built as a fork of [cookiecutter](https://github.com/cookiecutter/cookiecutter), it can make any config file dynamic or into a CLI with both strong and weakly typed programmable flow control common to a general purpose programming language. Basically you can write a fully functional Turing-complete program out of a config file. It's wild.

**With tackle, you can build:**
- Modular code generators / repo scaffolding tools that can be updated over time
- Interactive glue code for infrastructure-as-code deployment strategies
- Generic utilities like SSH registries and dotfile managers
- Generic utilities like SSH helpers and dotfile managers
- Combinations of all of the above and anything else you can think of

[//]: # (- Declarative makefile alternatives for advanced toolchain management)

> If this project gets enough adoption / stars, it will be re-written in a compiled language.
> If this project gets enough adoption / stars, it will be re-written in a compiled language, either Go or Rust. Give it a star if you'd like to see that.
### Features

- Makes arbitrary yaml / json / toml [dynamic](https://robcxyz.github.io/tackle/hook-methods/)
- Makes arbitrary yaml / json / toml [dynamic](https://sudoblockio.github.io/tackle/hook-methods/)
- Embed loops, conditionals, and other custom logic
- Self documenting CLI to call logic
- Ships with a collection of over [100 hooks](https://robcxyz.github.io/tackle) that act like plugins within your config file
- [Prompt user for inputs](https://robcxyz.github.io/tackle)
- [Generate code from templates](https://robcxyz.github.io/tackle/providers/Generate/)
- Read and write [yaml](https://robcxyz.github.io/tackle/providers/Yaml/) / [toml](https://robcxyz.github.io/tackle/providers/Toml/) / [json](https://robcxyz.github.io/tackle/providers/Json/) [files](https://robcxyz.github.io/tackle/providers/Files/)
- [Make http calls](https://robcxyz.github.io/tackle/providers/Web/)
- [Run arbitrary system commands](https://robcxyz.github.io/tackle/providers/Command/)
- [Manipulate the context](https://robcxyz.github.io/tackle/providers/Context/)
- [Run other tackle files](https://robcxyz.github.io/tackle/providers/Tackle/tackle/)
- Ships with a collection of over [100 hooks](https://sudoblockio.github.io/tackle) that act like plugins within your config file
- [Prompt user for inputs](https://sudoblockio.github.io/tackle)
- [Generate code from templates](https://sudoblockio.github.io/tackle/providers/Generate/)
- Read and write [yaml](https://sudoblockio.github.io/tackle/providers/Yaml/) / [toml](https://sudoblockio.github.io/tackle/providers/Toml/) / [json](https://sudoblockio.github.io/tackle/providers/Json/) [files](https://sudoblockio.github.io/tackle/providers/Files/)
- [Make http calls](https://sudoblockio.github.io/tackle/providers/Web/)
- [Run arbitrary system commands](https://sudoblockio.github.io/tackle/providers/Command/)
- [Manipulate the context](https://sudoblockio.github.io/tackle/providers/Context/)
- [Run other tackle files](https://sudoblockio.github.io/tackle/providers/Tackle/tackle/)
- Modular design allows creating / importing new hooks easy
- Supports both [python](https://robcxyz.github.io/tackle/python-hooks/) and [declarative](https://robcxyz.github.io/tackle/declarative-hooks/) hooks which can be imported / called / defined in-line or within jinja templates
- Supports both [python](https://sudoblockio.github.io/tackle/python-hooks/) and [declarative](https://sudoblockio.github.io/tackle/declarative-hooks/) hooks which can be imported / called / defined in-line or within jinja templates

### Install

> Note: tackle can install dependencies on its own. Check [docs](https://robcxyz.github.io/tackle/installation#best-installation-method) for advanced installation methods to isolate tackle from your system python.
> Note: tackle can install dependencies on its own. Check [docs](https://sudoblockio.github.io/tackle/installation#best-installation-method) for advanced installation methods to isolate tackle from your system python.
```shell
python -m venv env && source env/bin/activate
Expand All @@ -60,17 +60,17 @@ pip install tackle

### Hello world

Check out the [docs](https://robcxyz.github.io/tackle/hello-worlds/) for >10 hello worlds that demonstrate the various aspects of the syntax with the simplest one using the [print](https://robcxyz.github.io/tackle/providers/Console/print/) hook, one of [>100 hooks](https://robcxyz.github.io/tackle/installation#best-installation-method).
Check out the [docs](https://sudoblockio.github.io/tackle/hello-worlds/) for >10 hello worlds that demonstrate the various aspects of the syntax with the simplest one using the [print](https://sudoblockio.github.io/tackle/providers/Console/print/) hook, one of [>100 hooks](https://sudoblockio.github.io/tackle/installation#best-installation-method).

**hello.yaml**
```yaml
# Any time a key ends with `->`, we are calling a hook
hw->: print Hello world!
```

To run, call `tackle hello.yaml`. Can also be [version controlled](https://robcxyz.github.io/tackle/creating-providers/) -> [`tackle robcxyz/tackle-hello-world`](https://github.com/robcxyz/tackle-hello-world).
To run, call `tackle hello.yaml`. Can also be [version controlled](https://sudoblockio.github.io/tackle/creating-providers/) -> [`tackle robcxyz/tackle-hello-world`](https://github.com/robcxyz/tackle-hello-world).

Can also use [loops, conditionals, and other base methods](https://robcxyz.github.io/tackle/hook-methods/).
Can also use [loops, conditionals, and other base methods](https://sudoblockio.github.io/tackle/hook-methods/).

**hello.yaml**
```yaml
Expand All @@ -90,7 +90,7 @@ multiple lines:
# Or combinations of the above with other methods like try/except
```

New hooks can be [made in python](https://robcxyz.github.io/tackle/python-hooks/) which under the hood is a [pydantic](https://github.com/pydantic/pydantic) model.
New hooks can be [made in python](https://sudoblockio.github.io/tackle/python-hooks/) which under the hood is a [pydantic](https://github.com/pydantic/pydantic) model.

```python
from tackle import BaseHook
Expand All @@ -105,7 +105,7 @@ class Greeter(BaseHook):
return expression
```

Or can be [defined inline within your tackle file.](https://robcxyz.github.io/tackle/declarative-hooks/).
Or can be [defined inline within your tackle file, imported remotely, or in a `hooks` directory.](https://sudoblockio.github.io/tackle/declarative-hooks/).

```yaml
# Keys ending with `<-` mean we are creating a hook / method
Expand All @@ -118,7 +118,7 @@ greeter<-:
return: expression
```

And both can be [called the same way](https://robcxyz.github.io/tackle/writing-tackle-files/).
And both can be [called the same way](https://sudoblockio.github.io/tackle/writing-tackle-files/).

```yaml
hello: world!
Expand Down Expand Up @@ -179,7 +179,7 @@ Hooks can be imported, linked, and/or combined creating a web of CLIs.

### Use Cases

- [Code Generation](https://robcxyz.github.io/tackle/tutorials/code-generation/)
- [Code Generation](https://sudoblockio.github.io/tackle/tutorials/code-generation/)

**WIP Tutorials**

Expand All @@ -192,21 +192,21 @@ Hooks can be imported, linked, and/or combined creating a web of CLIs.

### Topics

- [Writing Tackle Files](https://robcxyz.github.io/tackle/writing-tackle-files/)
- [Creating Providers](https://robcxyz.github.io/tackle/creating-providers/)
- [Python Hooks](https://robcxyz.github.io/tackle/python-hooks/)
- [Declarative Hooks](https://robcxyz.github.io/tackle/declarative-hooks/)
- [Blocks](https://robcxyz.github.io/tackle/writing-tackle-files/#blocks) and [Flow Control](https://robcxyz.github.io/tackle/hook-methods/)
- [Memory Management](https://robcxyz.github.io/tackle/memory-management/)
- [Special Variables](https://robcxyz.github.io/tackle/special-variables/)
- [Declarative CLIs](https://robcxyz.github.io/tackle/declarative-cli/)
- [Writing Tackle Files](https://sudoblockio.github.io/tackle/writing-tackle-files/)
- [Creating Providers](https://sudoblockio.github.io/tackle/creating-providers/)
- [Python Hooks](https://sudoblockio.github.io/tackle/python-hooks/)
- [Declarative Hooks](https://sudoblockio.github.io/tackle/declarative-hooks/)
- [Blocks](https://sudoblockio.github.io/tackle/writing-tackle-files/#blocks) and [Flow Control](https://sudoblockio.github.io/tackle/hook-methods/)
- [Memory Management](https://sudoblockio.github.io/tackle/memory-management/)
- [Special Variables](https://sudoblockio.github.io/tackle/special-variables/)
- [Declarative CLIs](https://sudoblockio.github.io/tackle/declarative-cli/)

### Contributing

Contributions are welcome but please be advised of the following notes.

- This project uses [conventional commits](https://www.conventionalcommits.org/) which generates the [changelog](./CHANGELOG.md) with [release-please-action]() in the [release]() CI workflow. If commits have been made outside of this convention they will be squashed accordingly.
- For making changes to providers, please include test coverage using the existing fixtures and patterns from prior tests or communicate any suggestions that deviate from this style. Tests should be runnable from the test's directory and via `make test`.
- This project uses [conventional commits](https://www.conventionalcommits.org/) which generates the [changelog](./CHANGELOG.md) with [release-please-action](https://github.com/google-github-actions/release-please-action) in the [release](https://github.com/sudoblockio/tackle/blob/main/.github/workflows/release.yml) CI workflow. If commits have been made outside of this convention they will be squashed accordingly.
- For making changes to providers, please include test coverage using the existing fixtures and patterns from prior tests or communicate any suggestions that deviate from this style. It definitely can be improved but consistency is more important than making directed improvements. Tests should be runnable from the test's directory and via `make test`.
- For making changes to the core parser, please create a proposal first outlining your suggestions with examples before spending time working on code.

It is very easy to create new providers / hooks with tackle. Over time, it will adopt the same import pattern of what Ansible does where all provider / hooks (modules) are stored in version controlled locations. In the meantime, please feel free to contribute to this repository for hooks that have general applicability or create your own hooks in other repositories that are more bespoke / opinionated in nature.
Expand Down
7 changes: 7 additions & 0 deletions docs/cookbook/flow-control.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,13 @@ hello:
things->: print foo
```

And of course it can be expressed in a single line.

```yaml
name->: input What is your name?
hello->: print "Hello {{ name }}!" --if "name != 'Rob'" --else "Hello me"
```

### When

`when` takes effect before for loops which `if` operates after.
Expand Down
18 changes: 9 additions & 9 deletions docs/hello-worlds.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ tackle robcxyz/tackle-hello-world

### Single line print

Simply use the [print](https://robcxyz.github.io/tackle/providers/Console/print/) hook.
Simply use the [print](https://sudoblockio.github.io/tackle/providers/Console/print/) hook.
```yaml
hw->: print Hello world!
```
Expand All @@ -40,7 +40,7 @@ Anytime a key is suffixed with an arrow going to the right, it means the key is

### Print with variables

Using [jinja templating](https://robcxyz.github.io/tackle/jinja), the print hook can be called in [three different ways](https://robcxyz.github.io/tackle/jinja) using a variable.
Using [jinja templating](https://sudoblockio.github.io/tackle/jinja), the print hook can be called in [three different ways](https://sudoblockio.github.io/tackle/jinja) using a variable.
```yaml
words: Hello world!
expanded:
Expand All @@ -55,7 +55,7 @@ jinja_extension->: "{{ print(words) }}"
### Interactive prompts

There are several types of [prompt](https://robcxyz.github.io/tackle/providers/Prompts/) hooks which can also be used.
There are several types of [prompt](https://sudoblockio.github.io/tackle/providers/Prompts/) hooks which can also be used.

```yaml
name->: input
Expand All @@ -78,7 +78,7 @@ Which looks like this before printing.

### Loops and conditionals

Hooks can have [loops](https://robcxyz.github.io/tackle/hook-methods/#loops), [conditionals](https://robcxyz.github.io/tackle/hook-methods/#conditionals), and [other base methods](https://robcxyz.github.io/tackle/hook-methods/#methods).
Hooks can have [loops](https://sudoblockio.github.io/tackle/hook-methods/#loops), [conditionals](https://sudoblockio.github.io/tackle/hook-methods/#conditionals), and [other base methods](https://sudoblockio.github.io/tackle/hook-methods/#methods).
```yaml
words:
- Hello
Expand Down Expand Up @@ -147,7 +147,7 @@ output:
### Python hooks

Hooks can be [written in python](https://robcxyz.github.io/tackle/python-hooks/). Simply add your code to a `hooks` directory and the hook will be available to be called from a tackle file.
Hooks can be [written in python](https://sudoblockio.github.io/tackle/python-hooks/). Simply add your code to a `hooks` directory and the hook will be available to be called from a tackle file.
```python
from tackle import BaseHook

Expand All @@ -161,7 +161,7 @@ class Greeter(BaseHook):

### Declarative hooks

Hooks can be [declaratively created](https://robcxyz.github.io/tackle/declarative-hooks/) with tackle. Arrows going to the left are basically reusable functions / methods.
Hooks can be [declaratively created](https://sudoblockio.github.io/tackle/declarative-hooks/) with tackle. Arrows going to the left are basically reusable functions / methods.

```yaml
greeter<-:
Expand All @@ -184,7 +184,7 @@ jinja_filter->: "{{ hello | greeter }}"

### Strongly typed declarative hooks

Declarative hooks are strongly typed objects with many [declarative fields](https://robcxyz.github.io/tackle/declarative-hooks#input-fields).
Declarative hooks are strongly typed objects with many [declarative fields](https://sudoblockio.github.io/tackle/declarative-hooks#input-fields).
```yaml
words<-:
hi:
Expand All @@ -201,7 +201,7 @@ Here we are also using the [values](providers/Context/values.md) hook which can
### Declarative hook methods

Declarative hooks can have [methods](https://robcxyz.github.io/tackle/declarative-hooks#methods) that extend the base.
Declarative hooks can have [methods](https://sudoblockio.github.io/tackle/declarative-hooks#methods) that extend the base.

```yaml
words<-:
Expand All @@ -216,7 +216,7 @@ p->: words.say --hi Hello --target world!

### Declarative hooks inheritance

Declarative hooks also support [inheritance](https://robcxyz.github.io/tackle/declarative-hooks#extending-hooks).
Declarative hooks also support [inheritance](https://sudoblockio.github.io/tackle/declarative-hooks#extending-hooks).
```yaml
base<-:
hi:
Expand Down
6 changes: 3 additions & 3 deletions docs/hook-methods.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ printer:
type: things
```

Additionally, jinja hooks can be used to do some logic that could help with some patterns. For instance the [keys](https://robcxyz.github.io/tackle/providers/Context/keys/) hook can be used to create a list of keys from a map which can be used as an iterand.
Additionally, jinja hooks can be used to do some logic that could help with some patterns. For instance the [keys](https://sudoblockio.github.io/tackle/providers/Context/keys/) hook can be used to create a list of keys from a map which can be used as an iterand.

```yaml
inputs:
Expand Down Expand Up @@ -172,7 +172,7 @@ hello:

> Currently only jinja hooks are supported as string values. Future could add support for `else->/else_>` compact hook calls.
> Checkout the [match](https://robcxyz.github.io/tackle/providers/Logic/match/) hook if needing to do a lot of conditionals which can satisfy regexes when catching cases.
> Checkout the [match](https://sudoblockio.github.io/tackle/providers/Logic/match/) hook if needing to do a lot of conditionals which can satisfy regexes when catching cases.
## Methods

Expand All @@ -188,7 +188,7 @@ contents:

### `merge`

If the output of the hook call is a map, then one can merge that map into the parent keys. For instance given this [`block` hook](https://robcxyz.github.io/tackle/providers/Tackle/block/):
If the output of the hook call is a map, then one can merge that map into the parent keys. For instance given this [`block` hook](https://sudoblockio.github.io/tackle/providers/Tackle/block/):

```yaml
stuff: things
Expand Down
2 changes: 1 addition & 1 deletion docs/tutorials/code-generation/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ For those that learn best via examples, here are a few that should get the gener
- [tackle-license](https://github.com/robcxyz/tackle-license)
- A tackle provider for creating license files
- [Tackle provider docs](https://github.com/robcxyz/tackle/blob/main/docs/docs-gen.yaml)
- Tackle's [provider docs](https://robcxyz.github.io/tackle/creating-providers/#autogenerated-docs) are generated with tackle
- Tackle's [provider docs](https://sudoblockio.github.io/tackle/creating-providers/#autogenerated-docs) are generated with tackle
- This example uses the [provider_docs](../../providers/Tackle/provider_docs.md) hook from [a tackle-file](https://github.com/robcxyz/tackle/blob/main/docs/docs-gen.yaml) which then calls a [mkdocs.yaml](https://github.com/robcxyz/tackle/blob/main/mkdocs.tackle.yml#L109)
- The most important resource is the [testing providers](../../testing-providers.md) docs which goes into details about how to test hooks and tackle files.

0 comments on commit 33b3a6d

Please sign in to comment.