Major refactoring

LICENSE

@@ -0,0 +1,19 @@
+# The MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -1,6 +1,12 @@
 # Stamp
 
-Stamp helps you to generate common repository files like `README.md`, `LICENSE`, `.gitignore`, `Dockerfile` etc.
+Stamp generate files by applying data to templates.
+
+## Use-cases:
+
+* Generate common repository files like README.md, LICENSE, .gitignore, etc (by combining stamp with [metaculous](https://github.com/linkorb/metaculous))
+* Static site generator
+* Documentation generator
 
 ## Installation
 
@@ -10,77 +16,75 @@ Stamp helps you to generate common repository files like `README.md`, `LICENSE`,
 
     vendor/bin/stamp --help
 
-## Workflow:
+## How does it work?
 
-### 1. Load `stamp.yml` configuration:
+When you run `stamp generate`, Stamp will look for it's configuration in a file called `stamp.yaml` in the current directory. You can also pass a specify config file using `-c`.
 
-Stamp looks for a file called `stamp.yml` in your project root (or you can specify one using `-c`) 
-and json file `metaculous.json` generated by linkorb/metaculous (or you can specify one using `-j`)
+Additionally, stamp loads data from a file called `data.json`, or you can specify one using `-j`.
 
-The config defines:
+For example `stamp.yaml` and `data.json` files, please check the `example/` directory.
 
-1. Project specific variables (i.e. license, project name, etc)
-2. A list of files to be generated. Each file can have a name, template (file or url) and a set of variables, that override the project variables for this file only.
-
+Stamp will then loop through the `templates` defined in the config file, and use the template files defined by the `src` key, and generate the file defined by the `dest` key.
 
-### 2. Generate files
+By specifying an `items` key, one template may be applied multiple times, resulting in multiple output files.
 
-Stamp loops through all the files defined in `stamp.yml`, loads their template, inserts the collected data, and saves the file to disk.
+By specifying a `variables` key, the variables at the template level will get merged with the project level variables before being passed to the template, allowing you to override/add variables at the template level. 
 
 ## stamp.yml example:
 
 Here's a simple example `stamp.yml` file:
 
 ```yml
 variables:
-  project:
-    title: Hello world
+  title: Hello world
+  license: mit
 
 files:
-  README.md:
-    template: stamp/README.md.twig
+  - src: stamp/README.md.twig
+    dest: README.md
     variables:
-      title: Hello world
-      blocks:
-        - "@doc/intro.md"
-        - "@doc/installation.md"
+      title: Hello world README file
 
-  LICENSE.md:
-    template: https://raw.githubusercontent.com/IQAndreas/markdown-licenses/master/mit.md
+  - src: https://raw.githubusercontent.com/IQAndreas/markdown-licenses/master/{{ license }}.md
+    dest: LICENSE
 
-  CONTRIBUTING.md:
-    template: https://raw.githubusercontent.com/gitlabhq/gitlabhq/master/CONTRIBUTING.md
+  - src: https://raw.githubusercontent.com/gitlabhq/gitlabhq/master/CONTRIBUTING.md
+    dest: CONTRIBUTING.md
 ```
 
 Simply type `stamp generate` (or `vendor/bin/stamp generate`) in the root of your project, and the listed files will be (re)generated based on their templates.
 
-Using URLs as templates allow you to manage your templates in one location, making it easy to update your projects based on updated templates.
+Using URLs as templates allow you to manage your templates in one location (a git repository), making it easy to update your projects based on updated templates.
+
+Stamp supports multiple template languages/engines, which will be used based on the template file (src) file extension:
+
+* `.twig`: Use the [Twig](https://twig.symfony.com/) template language
+* `.hbs`, `.handlebars`: Use the [Handlebars](https://handlebarsjs.com/) template language (powered by [LightnCandy](https://github.com/zordius/lightncandy))
+* `.mustache`: Use the [Mustache](https://mustache.github.io/) template language (powered by [LightnCandy](https://github.com/zordius/lightncandy))
+
+## Functions
+
+In `stamp.yaml`, you define `src`/`dest` filenames and `items` variables.
+These keys all support "expressions" in which you could optionally use a set of functions to apply to variables.
+
+* `strtolower`: lowercase the variable
+* `dict`: Convert a key/value dictionary into an array of `item.key` and `item.value` items.
 
-When the template files end in `.twig`, Stamp will use Twig to process the template based on the variables defined on the file and globally on the project.
+More functions can easily be registered in the constructor of `src/Generator.php`.
 
 ## Development / debugging:
 
-The `examples/` directory contains a collection of common files. While developing analyzers, you can run `./bin/stamp generate -c examples/full-project/stamp.yml` to run stamp in the context of the `examples/full-project/` directory.
-
-You can use the following command to debug the data that will be injected into any templates (including the output from the analyzers): 
-
-    ./bin/stamp generate -c examples/full-project/stamp.yml
-
-## Todo:
-
-* [x] Analyzer for `Dockerfile`: Simply define a variable if it exists.
-* [x] Analyzer for `docker-compose.yml`: Import the YAML as-is. Can be used to list defined containers.
-* [x] Analyzer for `Makefile`: Import the targets + comments, using the regex in `examples/full-project/Makefile`
-* [x] Analyzer for `bower.json`: Import the JSON as-is. Can be used to list jobs
-* [x] Analyzer for `.env.dist`: Import variables, their default values, and comments (line before the variable)
-* [x] Analyzer for `.circleci/config.yml`: Import the YAML as-is. Can be used to list jobs
-* [x] Analyzer for `.editorconfig`: Simply define a variable if it exists.
-* [x] Analyzer for `schema.xml`: Used to document schema
-* [x] Analyzer for `routes`: Used to document routes. Looks for `app/config/routes.yml` (Radvance)
-* [x] Analyzer for `routes`: Used to document routes. Uses symfony `bin/console debug:router --format JSON` to import route data
-* [x] Analyzer for `doctrine-schema`: Find a way to load doctrine schema into an array for entity documentation
-* [x] Analyzer for `fixtures`: (Haigha). Simply define a variable if it exists.
-* [x] Analyzer for `anonymizer.yml`: Simply define a variable if it exists.
-* [x] Analyzer for `github`: Request repository data like contributors, title, etc.
-* [x] Allow to use project variables in template filenames/urls (i.e. to fetch the proper license file)
-* [x] Allow to use either twig or handlebars templates (using `zordius/lightncandy`)
+The `examples/` directory contains an example configuration (`stamp.yaml`), data file (`data.json`) and template files.
+
+## License
+
+MIT. Please refer to the [license file](LICENSE) for details.
+
+## Brought to you by the LinkORB Engineering team
+
+<img src="http://www.linkorb.com/d/meta/tier1/images/linkorbengineering-logo.png" width="200px" /><br />
+Check out our other projects at [linkorb.com/engineering](http://www.linkorb.com/engineering).
+
+Btw, we're hiring!
+
+

composer.json

@@ -1,6 +1,6 @@
 {
   "name": "linkorb/stamp",
-  "description": "Stamp: Generate common repository files like README.md, LICENSE, etc",
+  "description": "Stamp: Generate files from templates and data files",
   "homepage": "https://github.com/linkorb/stamp",
   "keywords": ["stamp", "linkorb"],
   "type": "library",
@@ -17,7 +17,8 @@
     "twig/twig": "^1.0",
     "symfony/dotenv": "^3.0|^4.0",
     "symfony/routing": "^3.0|^4.0",
-    "zordius/lightncandy": "^0.0|^1.0"
+    "zordius/lightncandy": "^0.0|^1.0",
+    "symfony/expression-language": "^4.2"
   },
   "autoload": {
     "psr-4": {