search

fabiojose / snip

The easiest way to scaffold projects
Apache License 2.0
4 stars 0 forks source link

readme

Snip

The easiest way to scaffold projects

Are you tired of complex placeholders that breaks your code?

🤲 If you (like me) is tired to losing your time with magical scaffolding tools with weird syntaxes and tons of useless functions, install Snip and scaffold now a new application.

because at the of the day we just want a new app based on some template to start our programming

💡 Why use ${placeholder}, {{placeholder}} or [placeholder] if we can just use __placeholder_?

🦊 In any modern language, underscore _ is a valid name identifier, because of that we just employ it in the placeholder syntax.

🧠 But Snip is not limited only to programming languages. We are able to process any file that is not binary.

can you imagine the possibilities?

👟 With Snip we...:

Getting Started

Install Snip

sh -c "$(curl -fsSL https://raw.githubusercontent.com/kattlo/snip/main/install.sh)"

Scaffold

Placeholders

Every placeholder must follow this pattern:

Simplifying...:

And you may use placeholders in directory names, file names and file content.

}


### Built-in Placeholders

- `__namespace_`: project's namespace (aka package)
- `__name_`: project's name
- `__version_`: project's version

#### Processing of `__namespace_`

When `__namespace_` is used in directories names, there is a special
processing.

__Example__:

When the templation has a directory structure like this:

. └── src └── _namespace


And `__namespace_=com.example`. After Snip scaffolding, the
new directory structure will be:

. └── src └── com └── example


### Custom Placeholders

As long as you follow the [placeholder pattern](#placeholders) and do not use
any [built-in placeholders](#built-in-placeholders), you may define your own
placeholders.

You must make clear in the templation docs what are the placeholders names
and the expected values.

To pass your custom placeholder to Snip scaffold is so simple, just use the
`-p` option as many as you want.

```bash
snip c <options> \
  -p '__comment_=Some comments to use' \
  -p "__author_=$USER" \
  -p '__domain__=payments' \
  -t <templation> \
  'my-new-project-name'

How to Create a Templation? 💡

To create your templation is so simple, you must refactor an existing project to use some of built-in placeholders and your own.

Done! 🤗 You have a templation to use.

Examples:

TODO

.snipignore

Always there are files and folders that you want to ignore during the scaffolding process, for this you may create a .snipignore file.

Example:

## Folders ##
.git/
.gradle/
build/

## Files ##
.project
.classpath
my-file.txt

## Wildcards ##
*.png
*.iml
*.iws

.snip.yml

To declare your custom placeholders and post scaffold scripts to execute, you may create the .snip.yml within your templation repository.

Example:

description: |
  Java 11 with Gradle
placeholders:
  strict: yes # Every placeholder in the spec must be present
  spec:
    - name: __c_author_
      pattern: ".+" # [optional] Java Regex to validate the value: https://cutt.ly/OxOZBZY
      label: Author Name
    - name: __c_domain_
      pattern: '[A-Z][\w]+' # [optional] Java Regex to validate the value: https://cutt.ly/OxOZBZY
      label: Class name for Domain
post:
  script: # The base directory for scripts is --directory
    linux: # To run on Linux & MacOS
      - ls -alh .
      - ./gradlew clean test --info
    windows: # to run on Windows
      - .\gradlew.bat clean test --info

Installation

The following instructions per O.S. may be used to brand new installations or updates.

Linux

Binary

Method Command
curl sh -c "$(curl -fsSL https://raw.githubusercontent.com/kattlo/snip/main/install.sh)"
wget sh -c "$(wget -O- https://raw.githubusercontent.com/kattlo/snip/main/install.sh)"
fetch sh -c "$(fetch -o - https://raw.githubusercontent.com/kattlo/snip/main/install.sh)"

Manual inspection

It's a good idea to inspect the install script from projects you don't yet know. You can do that by downloading the install script first, looking through it so everything looks normal, then running it:

wget https://raw.githubusercontent.com/kattlo/snip/main/install.sh
sh install.sh

Packages

MacOS

Windows

Using the Setup

Binary

All

Quarkus

Packaging and Running Snip from Source

If you want to build an über-jar, execute the following command:

./gradlew build -Dquarkus.package.type=uber-jar -PossrhUsername=inv4lid -PossrhPassword=inv4lid

The application is now runnable using java -jar cli/build/snip.jar.

Creating a native executable

You can create a native executable using:

./gradlew clean build \
  -Dquarkus.package.type=native \
  -Dquarkus.native.additional-build-args=-H:EnableURLProtocols=https,-H:IncludeResources='.*json$' \
  -PossrhUsername=inv4lid -PossrhPassword=inv4lid

Or, if you don't have GraalVM installed, you can run the native executable build in a container using:

./gradlew clean build \
  -Dquarkus.package.type=native \
  -Dquarkus.native.container-build=true \
  -Dquarkus.native.additional-build-args=-H:EnableURLProtocols=https,-H:IncludeResources='.*json$' \
  -PossrhUsername=inv4lid -PossrhPassword=inv4lid

You can then execute your native executable with: .cli/build/snip

If you want to learn more about building native executables, please consult https://quarkus.io/guides/gradle-tooling.

Related guides

Notes