1 | /*
|
2 | * Copyright (C) 2017 Alasdair Mercer, !ninja
|
3 | *
|
4 | * Permission is hereby granted, free of charge, to any person obtaining a copy
|
5 | * of this software and associated documentation files (the "Software"), to deal
|
6 | * in the Software without restriction, including without limitation the rights
|
7 | * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
8 | * copies of the Software, and to permit persons to whom the Software is
|
9 | * furnished to do so, subject to the following conditions:
|
10 | *
|
11 | * The above copyright notice and this permission notice shall be included in all
|
12 | * copies or substantial portions of the Software.
|
13 | *
|
14 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
15 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
16 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
17 | * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
18 | * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
19 | * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
20 | * SOFTWARE.
|
21 | */
|
22 |
|
23 | ;
|
24 |
|
25 | const pollock = require('pollock');
|
26 |
|
27 | /**
|
28 | * Supports a single output format for SVG conversion.
|
29 | *
|
30 | * @public
|
31 | * @abstract
|
32 | */
|
33 | class Provider {
|
34 |
|
35 | /**
|
36 | * Returns the extension to be used for converted output files.
|
37 | *
|
38 | * By default, this method will return {@link Provider#getType} in lower case, however, implementations are free to
|
39 | * override this behavior, if required.
|
40 | *
|
41 | * @return {string} The output file extension.
|
42 | * @public
|
43 | */
|
44 | getExtension() {
|
45 | return this.getType().toLowerCase();
|
46 | }
|
47 |
|
48 | /**
|
49 | * Returns the human-friendly output format.
|
50 | *
|
51 | * This is primarily intended for feedback purposes (e.g. displaying the output format).
|
52 | *
|
53 | * By default, this method will return {@link Provider#getType} in upper case, however, implementations are free to
|
54 | * override this behavior, if required.
|
55 | *
|
56 | * @return {string} The output format.
|
57 | * @public
|
58 | */
|
59 | getFormat() {
|
60 | return this.getType().toUpperCase();
|
61 | }
|
62 |
|
63 | }
|
64 |
|
65 | /**
|
66 | * Returns the background color to be used by the HTML page containing the SVG based on the <code>options</code>
|
67 | * provided.
|
68 | *
|
69 | * The background color will only be applied to transparent sections of the SVG, if any.
|
70 | *
|
71 | * All implementations of {@link Provider} <b>must</b> override this method.
|
72 | *
|
73 | * @param {Converter~ConvertOptions} options - the parsed convert options
|
74 | * @return {string} The background color.
|
75 | * @public
|
76 | * @abstract
|
77 | * @memberof Provider#
|
78 | * @method getBackgroundColor
|
79 | */
|
80 | pollock(Provider, 'getBackgroundColor');
|
81 |
|
82 | /**
|
83 | * Returns any additional CLI options that are supported by this {@link Provider} on top of the core CLI options.
|
84 | *
|
85 | * This method may return <code>null</code> or an empty array to indicate that no additional CLI options are available.
|
86 | *
|
87 | * All implementations of {@link Provider} <b>must</b> override this method.
|
88 | *
|
89 | * @return {?Array.<CLI~Option>} Any additional CLI options or <code>null</code> if there are none.
|
90 | * @public
|
91 | * @abstract
|
92 | * @memberof Provider#
|
93 | * @method getCLIOptions
|
94 | */
|
95 | pollock(Provider, 'getCLIOptions');
|
96 |
|
97 | /**
|
98 | * Returns any additional options that are to be passed to <code>puppeteer</code>'s <code>Page#screenshot</code> method
|
99 | * based on the <code>options</code> provided.
|
100 | *
|
101 | * This method may return <code>null</code> or an empty object to indicate that no additional options are to be passed
|
102 | * and any options returned by this method will override the core options, where applicable.
|
103 | *
|
104 | * All implementations of {@link Provider} <b>must</b> override this method.
|
105 | *
|
106 | * @param {Converter~ConvertOptions} options - the parsed convert options
|
107 | * @return {?Object} Any additional options for <code>Page#screenshot</code> or <code>null</code> if there are none.
|
108 | * @public
|
109 | * @abstract
|
110 | * @memberof Provider#
|
111 | * @method getScreenshotOptions
|
112 | */
|
113 | pollock(Provider, 'getScreenshotOptions');
|
114 |
|
115 | /**
|
116 | * Returns the output type as supported by <code>puppeteer</code>'s <code>Page#screenshot</code> method.
|
117 | *
|
118 | * All implementations of {@link Provider} <b>must</b> override this method.
|
119 | *
|
120 | * @return {string} The output type.
|
121 | * @public
|
122 | * @abstract
|
123 | * @memberof Provider#
|
124 | * @method getType
|
125 | */
|
126 | pollock(Provider, 'getType');
|
127 |
|
128 | /**
|
129 | * Returns the version of the package containing this {@link Provider}.
|
130 | *
|
131 | * All implementations of {@link Provider} <b>must</b> override this method.
|
132 | *
|
133 | * @return {string} The version.
|
134 | * @public
|
135 | * @abstract
|
136 | * @memberof Provider#
|
137 | * @method getVersion
|
138 | */
|
139 | pollock(Provider, 'getVersion');
|
140 |
|
141 | /**
|
142 | * Parses and validates the specified <code>options</code> for {@link API}.
|
143 | *
|
144 | * This method should limit the options that it parses/validates to only those added by this {@link Provider} and leave
|
145 | * the core options as-is.
|
146 | *
|
147 | * An error will occur if any of the options are invalid.
|
148 | *
|
149 | * All implementations of {@link Provider} <b>must</b> override this method.
|
150 | *
|
151 | * @param {Object} options - the options to be parsed
|
152 | * @param {?string} inputFilePath - the path of the SVG file to be converted
|
153 | * @return {void}
|
154 | * @throws {Error} If any of <code>options</code> are invalid.
|
155 | * @public
|
156 | * @abstract
|
157 | * @memberof Provider#
|
158 | * @method parseAPIOptions
|
159 | */
|
160 | pollock(Provider, 'parseAPIOptions');
|
161 |
|
162 | /**
|
163 | * Parses the specified the specified <code>command</code> for {@link CLI} into options for {@link API}.
|
164 | *
|
165 | * This method should limit the options that it parses to only those added by this {@link Provider} and leave the core
|
166 | * options as-is.
|
167 | *
|
168 | * Validation does not need to be performed by this method as this should be done by {@link Provider#parseAPIOptions}.
|
169 | *
|
170 | * All implementations of {@link Provider} <b>must</b> override this method.
|
171 | *
|
172 | * @param {Object} options - the object on which the parsed options are to be added
|
173 | * @param {Command} command - the <code>Command</code> from which the options are to be parsed
|
174 | * @return {void}
|
175 | * @public
|
176 | * @abstract
|
177 | * @memberof Provider#
|
178 | * @method parseCLIOptions
|
179 | */
|
180 | pollock(Provider, 'parseCLIOptions');
|
181 |
|
182 | module.exports = Provider;
|