GBOutputGenerator Class Reference
| Inherits from | NSObject |
| Declared in | GBOutputGenerator.h GBOutputGenerator.m |
Overview
The base class for all output generators.
Output generator is an object that handles a specific spet while generating output. These are helper classes for GBGenerator class; each concrete subclass handles specifics for certain step. Generator just ties all of these together into properly ordered chain as required by command line parameters.
Tasks
Initialization & disposal
-
+ generatorWithSettingsProvider:Returns autoreleased generator that work with the givenGBApplicationSettingsProviderimplementor. -
– initWithSettingsProvider:Initializes the generator to work with the givenGBApplicationSettingsProviderimplementor.
Generation handling
-
– initializeDirectoryAtPath:error:Initializes the directory at the given path. -
– initializeDirectoryAtPath:preserve:error:Initializes the directory at the given path optionally preserving any number of files or subdirectories. -
– copyTemplateFilesToOutputPath:Copies all files from the templates path to the output path as defined in assignedsettings, replicating the directory structure and stores all detected template files totemplateFilesdictionary. -
– copyOrMoveItemFromPath:toPath:error:Copies or moves directory or file from the given source path to the destination path. -
– generateOutputWithStore:error:Generates the output at the proper subdirectory of the output path as defined in assignedsettings. -
– writeString:toFile:error:Writes the given string to the given path, creating all necessary directories if they don't exist.
Subclass parameters and helpers
-
– templatePathForTemplateEndingWith:Returns the full path to the template ending with the given string. -
– outputPathToTemplateEndingWith:Returns the path to the template ending with the given string. -
templateFilesThe dictionary of all template files detected withincopyTemplateFilesToOutputPath:. property -
templateUserPathReturns user-friendly template path string includingoutputSubpath. property -
inputUserPathReturns user-friendly input path string. property -
outputUserPathReturns the output path includingoutputSubpath. property -
previousGeneratorReturns theGBOutputGeneratorthat was used just before this one ornilif this is the first generator in this session. property -
storeThe store as assigned togenerateOutput. property
Generation parameters
-
outputSubpathReturns the path relative to main output path, where all generated data is stored. property -
settingsTheGBApplicationSettingsProviderobject that provides application-wide settings for this session. property
Properties
inputUserPath
Returns user-friendly input path string.
@property (readonly) NSString *inputUserPathDiscussion
This is simply a shortcut for output path of previous generator. Internally it works by sending the outputUserPath message to previousGenerator and returning the result. If previous generator is nil (i.e. this is the first generator), nil is returned. Send stringByStandardizingPath` message to the returned value before using it!
Declared In
GBOutputGenerator.houtputSubpath
Returns the path relative to main output path, where all generated data is stored.
@property (readonly) NSString *outputSubpathDiscussion
At the same this, this also defines the path relative to main templates path, where all template files for this output generator are stored. Default implementation simply returns empty string, each subclass is supposed to override and return prover value.
See Also
Declared In
GBOutputGenerator.houtputUserPath
Returns the output path including outputSubpath.
@property (readonly) NSString *outputUserPathDiscussion
This uses the same string as entered by the user when starting the application. Send stringByStandardizingPath message to the returned value before using it!
Declared In
GBOutputGenerator.hpreviousGenerator
Returns the GBOutputGenerator that was used just before this one or nil if this is the first generator in this session.
@property (retain) GBOutputGenerator *previousGeneratorDiscussion
This is useful for subclasses that rely on files generated by previous generator. For example, we can get the location of generated files so we can further manipulate them. If a concrete subclass requires previous generator, and none is provided, it should throw an exception from generateOutputWithStore:error:!
Declared In
GBOutputGenerator.hsettings
The GBApplicationSettingsProvider object that provides application-wide settings for this session.
@property (retain) GBApplicationSettingsProvider *settingsDeclared In
GBOutputGenerator.hstore
The store as assigned to generateOutput.
@property (readonly, retain) GBStore *storeSee Also
Declared In
GBOutputGenerator.htemplateFiles
The dictionary of all template files detected within copyTemplateFilesToOutputPath:.
@property (readonly) NSMutableDictionary *templateFilesDiscussion
Each object has a key of template file name and relative path from templateUserPath. The keys are mapped to GBTemplateHandler instances associated with the template.
This is intended to be used within subclasses only. Dictionary contents are automatically updated and should not be changed by subclasses.
See Also
Declared In
GBOutputGenerator.htemplateUserPath
Returns user-friendly template path string including outputSubpath.
@property (readonly) NSString *templateUserPathDiscussion
This uses the same string as entered by the user when starting the application. Send stringByStandardizingPath message to the returned value before using it!
Declared In
GBOutputGenerator.hClass Methods
generatorWithSettingsProvider:
Returns autoreleased generator that work with the given GBApplicationSettingsProvider implementor.
+ (id)generatorWithSettingsProvider:(id)settingsProviderParameters
- settingsProvider
- Application-wide settings provider to use for checking parameters.
Return Value
Returns initialized instance or nil if initialization fails.
Exceptions
- NSException
- Thrown if the given application is
nil.
Declared In
GBOutputGenerator.hInstance Methods
copyOrMoveItemFromPath:toPath:error:
Copies or moves directory or file from the given source path to the destination path.
- (BOOL)copyOrMoveItemFromPath:(NSString *)source toPath:(NSString *)destination error:(NSError **)errorParameters
- source
- Source path to copy or move from.
- destination
- Destination path to copy or move to.
- error
- If copying fails, error description is returned here.
Return Value
Returns YES if all files were succesfully copied, NO otherwise.
Discussion
This method takes into account [GBApplicationSettings keepIntermediateFiles] and either copies or moves files regarding it's value. The method is designed to be used from within subclasses.
Declared In
GBOutputGenerator.hcopyTemplateFilesToOutputPath:
Copies all files from the templates path to the output path as defined in assigned settings, replicating the directory structure and stores all detected template files to templateFiles dictionary.
- (BOOL)copyTemplateFilesToOutputPath:(NSError **)errorParameters
- error
- If copying fails, error description is returned here.
Return Value
Returns YES if all files were succesfully copied, NO otherwise.
Discussion
The method uses [GBApplicationSettingsProvider templatesPath] as the base path for templates and [GBApplicationSettingsProvider outputPath] as the base path for output. In both cases, outputSubpath is used to determine the source and destination subdirectories. It then copies all files from template path to the output path, including the whole directory structure. If any special template file is found at source path, it is not copied! Template files are identified by having a -template suffix followed by optional extension. For example object-template.html. As this message prepares the ground for actual generation, it should be sent before any other messages (i.e. before generateOutput:).
To further aid subclasses, the method reads out all template files in templates path and stores them to templateFiles dictionary. Each template file is stored with a key correspoding to it's filename, including the subdirectory within the base template path and extension.
@warning Note: This message is intended to be sent from higher-level generator objects. Although it would present no error to run it several times, in most circumstances subclasses don't need to send it manually. If copying fails, a warning is logged and copying is stopped. Depending of type of failure, the method either returns YES or NO. If copying of all files is succesful, but reading or clearing template or ignored files fails, the operation is still considered succesful, so YES is returned. However if replicating the directory structure or copying files fails, this is considered an error and NO is returned. In such case, clients should abort further processing.
See Also
Declared In
GBOutputGenerator.hgenerateOutputWithStore:error:
Generates the output at the proper subdirectory of the output path as defined in assigned settings.
- (BOOL)generateOutputWithStore:(id)store error:(NSError **)errorParameters
- store
- The
GBStoreobject that holds the store with all parsed and processed data.
- error
- If generation fails, error description is returned here.
Discussion
This is the most important method of the GBOutputGenerator class. It generates all required output. It is intended to be overriden in subclasses. Default implementation assigns the given store and returns YES. Subclasses must call super class implementation before anything else!
Declared In
GBOutputGenerator.hinitWithSettingsProvider:
Initializes the generator to work with the given GBApplicationSettingsProvider implementor.
- (id)initWithSettingsProvider:(id)settingsProviderParameters
- settingsProvider
- Application-wide settings provider to use for checking parameters.
Return Value
Returns initialized instance or nil if initialization fails.
Discussion
This is the designated initializer.
Exceptions
- NSException
- Thrown if the given application is
nil.
Declared In
GBOutputGenerator.hinitializeDirectoryAtPath:error:
Initializes the directory at the given path.
- (BOOL)initializeDirectoryAtPath:(NSString *)path error:(NSError **)errorParameters
- path
- The path to initialize.
- error
- If initialization fails, error is returned here.
Return Value
Returns YES if initialization succeeds, NO otherwise.
Discussion
If the directory alreay exists, it is removed. Then a new one is created with all intermediate directories as needed. The result of the method is an empty directory at the given path. Sending this message has the same effect as sending initializeDirectoryAtPath:preserve:error: and passing nil for preserve argument.
Declared In
GBOutputGenerator.hinitializeDirectoryAtPath:preserve:error:
Initializes the directory at the given path optionally preserving any number of files or subdirectories.
- (BOOL)initializeDirectoryAtPath:(NSString *)path preserve:(NSArray *)preserve error:(NSError **)errorParameters
- path
- The path to initialize.
- preserve
- An array of paths to preserve.
- error
- If initialization fails, error is returned here.
Return Value
Returns YES if initialization succeeds, NO otherwise.
Discussion
If the directory doesn't exist, it is created. Otherwise all files and subdirectories are removed, except for the given array of files or subdirectories to preserve. If the array is nil or empty, all files are removed. Preserve array should contain paths relative to the given path. The paths are not handled recursively - only first level items are preserved!
The result of the method is an empty directory at the given path containing only files or subdirectories from the given array.
See Also
Declared In
GBOutputGenerator.houtputPathToTemplateEndingWith:
Returns the path to the template ending with the given string.
- (NSString *)outputPathToTemplateEndingWith:(NSString *)suffixParameters
- suffix
- Template file suffix to search for.
Return Value
Returns output path corresponding to the given template or nil if not found.
Discussion
The method searches templateFiles for a key ending with the given suffix and returns the path to the output directory corresponding to the given template subpath. This is useful for generating actual template file names - just append the desired filename and you have output file name ready!
Declared In
GBOutputGenerator.htemplatePathForTemplateEndingWith:
Returns the full path to the template ending with the given string.
- (NSString *)templatePathForTemplateEndingWith:(NSString *)suffixParameters
- suffix
- Template file suffix to search for.
Return Value
Returns template path to the given template or nil if not found.
Discussion
The method searches templateFiles for a key ending with the given suffix and returns full path to the given template. This is useful for getting the template for which we only know filename, but not the whole path for example.
Declared In
GBOutputGenerator.hwriteString:toFile:error:
Writes the given string to the given path, creating all necessary directories if they don't exist.
- (BOOL)writeString:(NSString *)string toFile:(NSString *)path error:(NSError **)errorParameters
- string
- The string to write.
- path
- The path and filename to write to.
- error
- If writting fails, error description is returned here.
Return Value
Returns YES is writting succeds, NO otherwise.
Discussion
This method is intended to be used from subclass, in most cases from generateOutputWithStore:error:.
See Also
Declared In
GBOutputGenerator.h