The trivial-project Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The trivial-project Reference Manual

This is the trivial-project Reference Manual, version 1.0.0, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 04:41:14 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

TRIVIAL-PROJECT

A simple tool for creating new 'projects' populated with files.

Almost every aspect of the project generation is configurable, including key-value substitution of text in files, filename renaming, specification of manifests of file actions, and even the syntax of the substitution engine. Multipass substitution creates many opportunities for generating complex projects with precision.

DEPENDENCIES

alexandria, cl-ppcre

LICENSE

BSD 3-clause license

INSTALLATION

Clone the repo at https://github.com/stacksmith/trivial-project.git to your local project directory.

(ql:quickload :trivial-project)
(tp:make-project :NAME "projname" )

This will create a simple project based on the 'lame' template that comes with this repo.

Follow the REPL instructions to create a custom template directory, and enter your local information in the .local.tp file. This will allow you to customize the projects with your name and preferences.

GENERAL USAGE

After setting your name/email address and preferred license in .local.tp file, you can just (tp:make-project :NAME ...)

Fine tune your template to fit your needs. Feel free to create different templates for different types of projects; specify the one you need with :TEMPLATE-PATH when creating projects.

Create your own key names (just insert ~~KEYNAME~~ in the text). Of course, you must either pass the value by hand in (make-project :NAME xxx :KEYNAME val...), or set a useful default in the .local.tp file (or both!). Same goes for file renaming, with TP_KEYNAME_TP syntax in the filename. If you don't like the ~~xx~~ syntax, change it with :REGEX-NORMAL...

Almost every aspect of project generation is configurable. The rest of this document describes the aspects of configuration.

KEY-VALUE SUBSTITUTION

In addition to copying files from the template directory, TRIVIAL-PROJECT will replace specially marked text and rename specially named files.

The syntax is simple: keys and values are obtained directly from the invocation of (make-project :name "test" :SOMEKEY somevalue ...); any occurrences of the string ~~SOMEKEY~~ 1 inside the files will be replaced with the value.

Filenames are likewise subject to substitution. For portability, the keys are tagged TP_SOMEKEY_TP1 in filenames; so the template file "TP_SYSTEM_TP.asd" will be named "test.asd" in the new project.

1: the tagging syntax is configurable by :REGEX-NORMAL and :REGEX-FILENAME keys.

FILE PROCESSING

All files in the template directory and its subdirectories are processed.

Possible actions for each file are :COPY :IGNORE :PROCESS. Each file in the template directory is processed as follows:

Note: the action is determined prior to file renaming. Use common sense in renaming files (such as not changing the extension).

The manifest is a list of files and file actions. Files are strings containing the subpath from the template directory. Only files (not directories) must be listed; directories are created automatically.

USEFUL KEYS

The :NAME key is required. The other keys used in the default template are:

KEY | DEFAULT | COMMENT ~~- | ~~~~~~- | ~~~~~~- :NAME | | !!! Required; Name of directory of new project :SYSTEM | value of :NAME | asdf system name :PACKAGE | value of :NAME | package name :AUTHOR | | set in .local.tp :LICENSE | | set in .local.tp :DESCRIPTION | | !!! :DEPENDS-ON | | !!! :DEFAULT-ACTION | :COPY | what to do with unknown files :REGEX-FILENAME | "TP_(.*?)_TP" | filenames TP_XXX_TP have :XXX key :REGEX-NORMAL | "~~(.*?)~~" | text ~~XXX~~ interpreted as :XXX key :EXTENSIONS | see below | list of extensions and actions :MANIFEST | | optional highest-priority list of files and actions :TEMPLATE-PATH | "~/trivial-project-template/" | pathname of template :OUTPUT-PATH | your local project directory | directory that will contain new project :TP-CONFIG-FILENAME | ".local.tp" | Configuration filename :TP-REGISTER-WITH-ASDF | ".local.tp" | when T register project path with asdf:central-registry

Feel free to add any keys you deem necessary (and change .local.tp to initialize them to useful values).

NOTES

Understanding substitution

The key-name substitution is done repeatedly until no keys are left. It is possible to expand keys to other keys, but be careful to avoid circularity as it will lock up the system.

Keep in mind that substitution, especially from parameters in the .local.tp file, involves:

  1. The act of Lisp reading the .local.tp file using (read). At this point, values are read in without interpretation; string are strings, symbols are symbols, and lists are lists.

  2. Expansion: cl-ppcre expands strings; so any expansion-bound values must be strings. This process takes place after all keywords have been parsed in; therefore any values may include any other keywords (keeping in mind the circularity problem).

If you examine the stock .local.tp file you will see that :SYSTEM is defined as "~~NAME~~". This will expand correctly into the value of :NAME. There will be two expansions: ~~SYSTEM~~ into ~~NAME~~, followed by ~~NAME~~ into the value of :NAME in the invocation.

:DEFAULT-ACTION however is define as :COPY. :DEFAULT-ACTION is never expanded - it is an internal symbol only, used to configure the expansion engine.

Reserved Symbols

:DEFAULT-ACTION resolves to a symbol and is not expnadable. :TEMPATE-PATH, :OUTPUT-PATH are used by the system and are not useful (there are better ways to portably get the project path for instance).

Other internal symbols are :EXTENSIONS and :MANIFEST, which are used to internally map file types and names to actions. Therefore symbols ~~EXTENSIONS~~ and ~~MANIFEST~~ should never be used inside text (or at least I cannot think of why you would want to introspect on TRIVIAL-PROJECT itself)

File Renaming

As mentioned before, the (default but changeable) syntax for keys in filenames to be renamed is TP_xxx_TP, in order to work with the file systems (dashes in filenames are problematic). In case of a multipass renaming, keep in mind that intermediate names must be in the 'normal' syntax. The final result should be a valid filename and intermediate results are not relevant.

As an example, the stock template has a file named TP_SYSTEM_TP.asd. It will expand to ~~NAME~~.asd and finally to the value of :NAME with extension .asd, unless :SYSTEM has been explicitly set.

Multipass Renaming

Each string, be it a filename or the contents of a file, is subject to multipass renaming. It will continue to be processed until no keys are found in the file.

Note: only the first pass in filenames uses the filename syntax; from second pass on, the standard syntax is used. This merges the keywords for both filenames and normal string expansion

Local configuration file and security

TRIVIAL-PROJECT reads the .local.tp configuration file, which presents some security risks. In practice, the risk is low; by using any system that generates Lisp files you are indicating some trust in it. The configuration file is placed by you into your local home directory which is subject to your security settings. Finally, this library generates stubs of your project, and chances are that you will look at the files it generates before compiling and running the generated project sight unseen.

But you are warned; as with all security related details, you must be vigilant.

Bluesky projects

There is no particular reason to limit yourself to using TRIVIAL-PROJECT for lisp projects, as long as you keep in mind the reserved symbols and circulatiry issues.

WORK IN PROGRESS


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 trivial-project

Author

StackSmith <fpgasm@apple2.x10.mx>

License

BSD Simplified (2-clause)

Description

A simple project skeleton generator with key-value substitution

Version

1.0.0

Dependencies
Source

trivial-project.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 trivial-project.asd

Location

trivial-project.asd

Systems

trivial-project (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 trivial-project/package.lisp

Parent

trivial-project (system)

Location

package.lisp

Packages

trivial-project


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 trivial-project/params.lisp

Dependency

package.lisp (file)

Parent

trivial-project (system)

Location

params.lisp

Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.4 trivial-project/trivial-project.lisp

Dependency

params.lisp (file)

Parent

trivial-project (system)

Location

trivial-project.lisp

Exported Definitions

make-project (function)

Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 trivial-project

Source

package.lisp (file)

Nickname

tp

Use List
Exported Definitions

make-project (function)

Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Functions

Function: make-project &rest PARAMS &key NAME &allow-other-keys

Create a project named (name must be a string) based on a template and other keys.

Package

trivial-project

Source

trivial-project.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *extensions*
Package

trivial-project

Source

params.lisp (file)

Special Variable: *files*
Package

trivial-project

Source

params.lisp (file)

Special Variable: *output-path*
Package

trivial-project

Source

params.lisp (file)

Special Variable: *params*
Package

trivial-project

Source

trivial-project.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Functions

Function: all-files-below DIRECTORY ROOT

collect all filenames at or below root, relative to root, as strings

Package

trivial-project

Source

trivial-project.lisp (file)

Function: extensions-initialize ()
Package

trivial-project

Source

params.lisp (file)

Function: filename-action ENOUGHPATH
Package

trivial-project

Source

params.lisp (file)

Function: files-initialize ()
Package

trivial-project

Source

params.lisp (file)

Function: initial-keys PARAMS
Package

trivial-project

Source

params.lisp (file)

Function: local-template ()
Package

trivial-project

Source

params.lisp (file)

Function: process-file SRCPATH DESTPATH
Package

trivial-project

Source

trivial-project.lisp (file)

Function: process-files ()
Package

trivial-project

Source

trivial-project.lisp (file)

Function: process-string STRING &optional REGEX
Package

trivial-project

Source

trivial-project.lisp (file)

Function: set-params-from-file PATH &key IN
Package

trivial-project

Source

params.lisp (file)

Function: set-params-from-list LIST

set (overwriting) *params* from plist-like list

Package

trivial-project

Source

params.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   T  
Index Entry  Section

F
File, Lisp, trivial-project.asd: The trivial-project<dot>asd file
File, Lisp, trivial-project/package.lisp: The trivial-project/package<dot>lisp file
File, Lisp, trivial-project/params.lisp: The trivial-project/params<dot>lisp file
File, Lisp, trivial-project/trivial-project.lisp: The trivial-project/trivial-project<dot>lisp file

L
Lisp File, trivial-project.asd: The trivial-project<dot>asd file
Lisp File, trivial-project/package.lisp: The trivial-project/package<dot>lisp file
Lisp File, trivial-project/params.lisp: The trivial-project/params<dot>lisp file
Lisp File, trivial-project/trivial-project.lisp: The trivial-project/trivial-project<dot>lisp file

T
trivial-project.asd: The trivial-project<dot>asd file
trivial-project/package.lisp: The trivial-project/package<dot>lisp file
trivial-project/params.lisp: The trivial-project/params<dot>lisp file
trivial-project/trivial-project.lisp: The trivial-project/trivial-project<dot>lisp file

Jump to:   F   L   T  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   A   E   F   I   L   M   P   S  
Index Entry  Section

A
all-files-below: Internal functions

E
extensions-initialize: Internal functions

F
filename-action: Internal functions
files-initialize: Internal functions
Function, all-files-below: Internal functions
Function, extensions-initialize: Internal functions
Function, filename-action: Internal functions
Function, files-initialize: Internal functions
Function, initial-keys: Internal functions
Function, local-template: Internal functions
Function, make-project: Exported functions
Function, process-file: Internal functions
Function, process-files: Internal functions
Function, process-string: Internal functions
Function, set-params-from-file: Internal functions
Function, set-params-from-list: Internal functions

I
initial-keys: Internal functions

L
local-template: Internal functions

M
make-project: Exported functions

P
process-file: Internal functions
process-files: Internal functions
process-string: Internal functions

S
set-params-from-file: Internal functions
set-params-from-list: Internal functions

Jump to:   A   E   F   I   L   M   P   S  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*extensions*: Internal special variables
*files*: Internal special variables
*output-path*: Internal special variables
*params*: Internal special variables

S
Special Variable, *extensions*: Internal special variables
Special Variable, *files*: Internal special variables
Special Variable, *output-path*: Internal special variables
Special Variable, *params*: Internal special variables

Jump to:   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   P   S   T  
Index Entry  Section

P
Package, trivial-project: The trivial-project package

S
System, trivial-project: The trivial-project system

T
trivial-project: The trivial-project system
trivial-project: The trivial-project package

Jump to:   P   S   T