Metadata-Version: 1.1
Name: poppage
Version: 0.6.3
Summary: Utility for generating files and directories from templates.
Home-page: https://github.com/jeffrimko/PopPage
Author: Jeff Rimko
Author-email: jeffrimko@gmail.com
License: MIT
Description: Introduction
        ============
        
        PopPage is a simple command-line utility originally intended as a static
        website generator but has since grown into a
        `cookiecutter <https://github.com/audreyr/cookiecutter>`__ clone. The
        main features of PopPage are:
        
        -  Uses `Jinja2 templates <http://jinja.pocoo.org/>`__ to generate
           output.
        
        -  Uses YAML to store default key/values for template variables.
        
        -  Output can be single files or directories.
        
        -  Key/values applied to the templates variables can specified on the
           command line.
        
        Status
        ======
        
        Currently, this project is in the **development release** stage. While
        this project is suitable for use, please note that there may be
        incompatibilities in new releases.
        
        Release notes are maintained in the project
        `changelog <https://github.com/jeffrimko/PopPage/blob/master/CHANGELOG.adoc>`__.
        
        Requirements
        ============
        
        PopPage should run on any Python 2.7/3.x interpreter without additional
        dependencies.
        
        Usage
        =====
        
        PopPage can be run from the command line using ``poppage``. Type
        ``poppage --help`` for usage information. The following subcommands are
        available:
        
        -  ``check`` - Check the given INPATH template for variables.
        
        -  ``make`` - Generates directories and files based on the given INPATH
           template.
        
        -  ``run`` - Generates the OUTPATH, executes commands, then deletes
           OUTPATH.
        
        Some Important Notes
        --------------------
        
        Before showing any examples, keep these notes in mind:
        
        -  Template file/directory names can contain template variables (e.g.
           ``{{foo}}.txt``). The provided key/values will be used for the output
           file generation unless an explicit OUTPATH is provided.
        
        -  The output will be passed to ``stdout`` if INPATH is a file (rather
           than a directory) and INPATH does not contain a template variable and
           no OUTPATH is specified.
        
        CLI Key/Values
        --------------
        
        The following is a quick example of using PopPage from the CLI:
        
        -  Template file (``template.jinja2``):
        
           ::
        
               Hello {{name}}!
        
        -  PopPage command:
        
           ::
        
               poppage make --inpath template.jinja2 --string name world
        
        -  Output to ``stdout``:
        
           ::
        
               Hello world!
        
        YAML Key/Values
        ---------------
        
        Additionally, default key/values can be stored in a YAML file:
        
        -  Template file (``template.jinja2``):
        
           ::
        
               Hello {{name}}!
        
        -  Defaults file (``defaults.yaml``):
        
           ::
        
               name: sun
        
        -  PopPage command:
        
           ::
        
               poppage make --inpath template.jinja2 --defaults defaults.yaml
        
        -  Output to ``stdout``:
        
           ::
        
               Hello sun!
        
        Custom YAML Tags
        ----------------
        
        The following custom YAML tags are provided:
        
        -  ``!file`` - Reads value from a file as a string.
        
        -  ``!yaml`` - Reads value from file as YAML.
        
        -  ``!opt`` - Like ``!yaml`` but only for populating the ``opt`` key.
        
        -  ``!cmd`` - Reads value from a CLI command output.
        
        -  ``!ask`` - Prompts the user to input a value.
        
        Check out this example:
        
        -  Template file (``template.jinja2``):
        
           ::
        
               Hello {{first}} {{last}}!
        
        -  Defaults file (``defaults.yaml``):
        
           ::
        
               first: !file myfile.txt
               last: !cmd python -c "print('Skywalker')"
        
        -  Content of ``myfile.txt``:
        
           ::
        
               Anakin
        
        -  PopPage command:
        
           ::
        
               poppage make --inpath template.jinja2 --defaults defaults.yaml
        
        -  Output to ``stdout``:
        
           ::
        
               Hello Anakin Skywalker!
        
        Option Defaults
        ---------------
        
        Default utility options can be provided in the defaults file under the
        ``opt`` root key.
        
        Check out these examples:
        
        -  Basic option defaults:
        
           ::
        
               __opt__:
                   inpath: template.jinja2
                   outpath: myfile.txt
        
        -  Another options example:
        
           ::
        
               __opt__:
                   inpath: template.jinja2
                   outpath: myfile.py
                   execute: python myfile.py
        
        -  The execute option can be a template:
        
           ::
        
               __opt__:
                   inpath: template.jinja2
                   execute: python {{outpath}}
        
        -  Populate the options using a YAML file:
        
           ::
        
               __opt__: !opt myopts.yaml
        
        Cookiecutter Compatiblity
        -------------------------
        
        PopPage should be compatible with many
        `cookiecutter <https://github.com/audreyr/cookiecutter>`__ templates.
        Using https://github.com/solarnz/cookiecutter-avr as an example, check
        for the variables in the template:
        
        ::
        
            poppage check --inpath https://github.com/solarnz/cookiecutter-avr
            # Found variables:
            #   cookiecutter::full_name
            #   cookiecutter::repo_name
            #   cookiecutter::year
        
        Create a file to store your default values, for example
        ``defaults.yaml``:
        
        ::
        
            cookiecutter:
                full_name: Henry Jones
                repo_name: LastCrusade
                year: 1989
        
        Run PopPage to generate your files:
        
        ::
        
            poppage make --inpath https://github.com/solarnz/cookiecutter-avr --defaults defaults.yaml mydest
            # This will generate the entire repo to a new directory named mydest.
        
        ::
        
            # Or you can do:
            poppage make --inpath https://github.com/solarnz/cookiecutter-avr/tree/master/%7B%7Bcookiecutter.repo_name%7D%7D --defaults defaults.yaml
            # This will generate the {{cookiecutter.repo_name}} subdirectory to a new directory based on the given variables, in this case LastCrusade.
        
        Similar
        =======
        
        The following projects are similar and may be worth checking out:
        
        -  `cookiecutter <https://github.com/audreyr/cookiecutter>`__
        
Keywords: project-templates file-templates file-generation
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Topic :: Utilities
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
