README

Sat, 25 Jul 2009 23:04:16 +0100

author
Matthew Wild <mwild1@gmail.com>
date
Sat, 25 Jul 2009 23:04:16 +0100
changeset 17
3d4ba37b1554
child 35
8843ea9f9e27
permissions
-rw-r--r--

Add README and COPYRIGHT files

17
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
1
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
2 # Squish - One language to write them all, one squisher to squish them
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
3
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
4 Squish is a simple script to build a single file out of multiple scripts, modules, and other files.
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
5
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
6 For example if you have a script called A, and it requires modules X, Y and Z, all of them could be squished
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
7 into a single file, B.
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
8
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
9 When run, Squish reads a file called 'squishy' in the current (or specified) directory, which contains
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
10 instructions on how to squish a project.
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
11
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
12 For an example you can see Squish's own squishy file, included in this package. For reference, see below.
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
13
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
14 ## Squishing
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
15
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
16 Running squish will search for a 'squishy' file in the current directory. Alternatively you can pass to squish
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
17 a directory to look in.
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
18
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
19 Command-line options vary depending on what features squish has been built with. Below are the standard ones.
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
20
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
21 ### Minify
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
22 'Minification' is the act of condensing source code by stripping out spaces, line breaks, comments and anything
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
23 that isn't required to be there. Although the source code is re-organised and changed, the program is still the
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
24 same and runs without any changes.
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
25
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
26 #### --no-minify
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
27 Disable minification of the output file after squishing. Default is to minify.
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
28
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
29 #### --minify-level=level
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
30 The level may be one of: none, basic, default, full
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
31
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
32 They vary in effectiveness, and the time taken to process large files. Experiment!
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
33
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
34 ### Uglify
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
35 'Uglification' is the name Squish gives to a certain basic form of compression. With large files it can reduce the
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
36 size by some kilobytes, even after full minification. It works by replacing Lua keywords with a single byte and
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
37 inserting code at the start of the script to expand the keywords when it is run.
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
38
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
39 #### --uglify
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
40 Enable the uglification filter. Default is to not uglify.
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
41
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
42 ### Compile
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
43 Squish can compile the resulting file to Lua bytecode. This is experimental at this stage (you may get better results
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
44 with luac right now), however it's a work in progress. Compiling to bytecode can actually increase the size of
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
45 minified output, but it can speed up loading (not that you would notice it anyway, since the Lua compiler is so fast).
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
46
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
47 #### --compile
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
48 Enables compilation of the output file.
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
49
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
50 ## Squishy reference
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
51
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
52 A squishy file is actually a Lua script which calls some Squish functions. These functions are listed here.
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
53
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
54 ### Module "name" "path"
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
55 Adds the specified module to the list of those to be squished into the output file. The optional path specifies
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
56 where to find the file (relative to the squishy file), otherwise Squish will attempt to find the module itself.
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
57
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
58 ### Main "script.lua"
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
59 Adds a script into the squished output. Scripts are executed in the order specified in the squishy file, but only
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
60 after all modules have been loaded.
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
61
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
62 ### Output "filename.lua"
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
63 Names the output file. If none is specified, the default is 'squished.out.lua'.
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
64
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
65 ### Option "name" "value"
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
66 Sets the specified option, to 'true', or to the optional given value. This allows a squishy file to set default
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
67 command-line options.
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
68
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
69 ### GetOption "name"
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
70 Returns the current value of the given option.
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
71
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
72 ### Resource "name" "path"
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
73 Adds a 'resource' to the squished file. A resource may be any file, text, binary, large or small. Scripts can
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
74 retrieve the resource at runtime by calling require_resource("name"). If no path is given then the name is used
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
75 as the path.
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
76
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
77 ### AutoFetchURL "url"
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
78 **Experimental** feature which is subject to change. When specified, all the following Module statements will be
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
79 fetched via HTTP if not found on the filesystem. A ? (question mark) in the URL is replaced by the relative path
3d4ba37b1554 Add README and COPYRIGHT files
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
80 of the module file that was given in the Module statement.

mercurial