diff options
Diffstat (limited to 'doc/reference/jsextensions')
6 files changed, 120 insertions, 107 deletions
diff --git a/doc/reference/jsextensions/jsextension-file.qdoc b/doc/reference/jsextensions/jsextension-file.qdoc index 4da051bd2..71225188b 100644 --- a/doc/reference/jsextensions/jsextension-file.qdoc +++ b/doc/reference/jsextensions/jsextension-file.qdoc @@ -39,18 +39,11 @@ The \c File service offers limited access to the file system for operations such as copying or removing files. - \section1 Making the Service Available - To gain access to file system operations, import the service using the - following statement at the top of your project file: - \code - import qbs.File - \endcode - \section1 Available Operations \section2 copy \code - File.copy(sourceFilePath, targetFilePath) + File.copy(sourceFilePath: string, targetFilePath: string): boolean \endcode Copies \c sourceFilePath to \c targetFilePath. Any directory components in \c targetFilePath that do not yet exist will be created. If \c sourceFilePath is a directory, a recursive @@ -61,13 +54,13 @@ \section2 exists \code - File.exists(filePath) + File.exists(filePath: string): boolean \endcode Returns true if and only if there is a file at \c filePath. \section2 lastModified \code - File.lastModified(filePath) + File.lastModified(filePath: string): number \endcode Returns the time of last modification for the file at \c filePath. The concrete semantics of the returned value are platform-specific. You should only rely on the property that a smaller value @@ -75,7 +68,7 @@ \section2 remove \code - File.remove(filePath) + File.remove(filePath: string): boolean \endcode Removes the file at \c filePath. In case of a directory, it will be removed recursively. */ diff --git a/doc/reference/jsextensions/jsextension-fileinfo.qdoc b/doc/reference/jsextensions/jsextension-fileinfo.qdoc index 74c03173e..c8e28f376 100644 --- a/doc/reference/jsextensions/jsextension-fileinfo.qdoc +++ b/doc/reference/jsextensions/jsextension-fileinfo.qdoc @@ -39,56 +39,48 @@ The \c FileInfo service offers various operations on file paths, such as turning absolute paths into relative ones, splitting a path into its components, and so on. - \section1 Making the Service Available - - In order to gain access to file path operations, you need to import the service using the - following statement at the top of your project file: - \code - import qbs.FileInfo - \endcode - \section1 Available Operations \section2 baseName \code - FileInfo.baseName(filePath) + FileInfo.baseName(filePath: string): string \endcode Returns the file name of \c filePath up to (but not including) the first '.' character. \section2 completeBaseName \code - FileInfo.completeBaseName(filePath) + FileInfo.completeBaseName(filePath: string): string \endcode Returns the file name of \c filePath up to (but not including) the last '.' character. \section2 fileName \code - FileInfo.fileName(filePath) + FileInfo.fileName(filePath: string): string \endcode Returns the last component of \c filePath, that is, everything after the last '/' character. \section2 fromWindowsSeparators \code - FileInfo.fromWindowsSeparators(filePath) + FileInfo.fromWindowsSeparators(filePath: string): string \endcode Returns \c filePath with all '\\' characters replaced by '/'. \section2 isAbsolutePath \code - FileInfo.isAbsolutPath(filePath) + FileInfo.isAbsolutePath(filePath: string): boolean \endcode Returns true if \c filePath is an absolute path and false if it is a relative one. \section2 joinPaths \code - FileInfo.joinPaths(path1, path2, ...) + FileInfo.joinPaths(...paths: string[]): string \endcode Concatenates the given paths using the '/' character. \section2 path \code - FileInfo.path(filePath) + FileInfo.path(filePath: string): string \endcode Returns the part of \c filePath that is not the file name, that is, everything up to @@ -98,7 +90,7 @@ \section2 relativePath \code - FileInfo.relativePath(dirPath, filePath) + FileInfo.relativePath(dirPath: string, filePath: string): string \endcode Returns a relative path so that joining \c dirPath and the returned path results in \c filePath. If necessary, '..' components are inserted. @@ -107,7 +99,7 @@ \section2 toWindowsSeparators \code - FileInfo.toWindowsSeparators(filePath) + FileInfo.toWindowsSeparators(filePath: string): string \endcode Returns \c filePath with all '/' characters replaced by '\\'. */ diff --git a/doc/reference/jsextensions/jsextension-process.qdoc b/doc/reference/jsextensions/jsextension-process.qdoc index 0d5b1cecb..3df109333 100644 --- a/doc/reference/jsextensions/jsextension-process.qdoc +++ b/doc/reference/jsextensions/jsextension-process.qdoc @@ -39,14 +39,6 @@ The \c Process service allows you to start processes, track their output, and so on. - \section1 Making the Service Available - In order to gain access to process management operations, you need to import - the service using the - following statement at the top of your project file: - \code - import qbs.Process - \endcode - \section1 Available Operations \section2 Constructor @@ -57,14 +49,14 @@ \section2 close \code - close() + close(): void \endcode Frees the resources associated with the process. We recommended to always call this function as soon as you are finished with the process. \section2 exec \code - exec(filePath, arguments, throwOnError) + exec(filePath: string, arguments: string[], throwOnError: boolean): number \endcode Executes the program at \c filePath with the given argument list and blocks until the process is finished. If an error occurs (for example, there is no executable @@ -75,38 +67,38 @@ \section2 exitCode \code - exitCode() + exitCode(): number \endcode Returns the exit code of the process. This is needed for retrieving the exit code from processes started via \c start(), rather than \c exec(). \section2 getEnv \code - getEnv(varName) + getEnv(varName: string): string \endcode Returns the value of the variable \c varName in the process' environment. \section2 kill \code - kill() + kill(): void \endcode Kills the process, causing it to exit immediately. \section2 readLine \code - readLine() + readLine(): string \endcode Reads and returns one line of text from the process output, without the newline character(s). \section2 readStdErr \code - readStdErr() + readStdErr(): string \endcode Reads and returns all data from the process' standard error channel. \section2 readStdOut \code - readStdOut() + readStdOut(): string \endcode Reads and returns all data from the process' standard output channel. @@ -120,38 +112,38 @@ \section2 setEnv \code - setEnv(varName, varValue) + setEnv(varName: string, varValue: string): string \endcode Sets the value of variable \c varName to \c varValue in the process environment. This only has an effect if called before the process is started. \section2 setWorkingDirectory \code - setWorkingDirectory(dir) + setWorkingDirectory(path: string): void \endcode Sets the directory the process will be started in. This only has an effect if called before the process is started. \section2 start \code - start(filePath, arguments) + start(filePath: string, arguments: string[]): boolean \endcode - Starts the program at \c filePath with the given list of arguments. Returns true if the - process could be started and false otherwise. + Starts the program at \c filePath with the given list of arguments. Returns \c{true} if the + process could be started and \c{false} otherwise. \note This call returns right after starting the process and should be used only if you need to interact with the process while it is running. Most of the time, you want to use \c exec() instead. \section2 terminate \code - terminate() + terminate(): void \endcode Tries to terminate the process. This is not guaranteed to make the process exit immediately; if you need that, use \c kill(). \section2 waitForFinished \code - waitForFinished(timeout) + waitForFinished(timeout: number): boolean \endcode Blocks until the process has finished or \c timeout milliseconds have passed (default is 30000). Returns true if the process has finished and false if the operation has timed out. @@ -160,19 +152,19 @@ \section2 workingDirectory \code - \workingDirectory() + workingDirectory(): string \endcode Returns the directory the process will be started in. \section2 write \code - write(data) + write(data: string): void \endcode Writes \c data into the process' input channel. \section2 writeLine \code - writeLine(data) + writeLine(data: string): void \endcode Writes \c data, followed by the newline character(s), into the process' input channel. */ diff --git a/doc/reference/jsextensions/jsextension-propertylist.qdoc b/doc/reference/jsextensions/jsextension-propertylist.qdoc index 3ba3b0dc8..bfde8616d 100644 --- a/doc/reference/jsextensions/jsextension-propertylist.qdoc +++ b/doc/reference/jsextensions/jsextension-propertylist.qdoc @@ -41,14 +41,6 @@ This service is only available on Darwin platforms such as OS X and iOS. - \section1 Making the Service Available - In order to gain access to property list operations, you need to import the - service using the - following statement at the top of your project file: - \code - import qbs.PropertyList - \endcode - \section1 Available operations \section2 Constructor @@ -59,19 +51,19 @@ \section2 clear \code - clear() + clear(): void \endcode Voids the property list by deleting its internal object reference. \section2 isEmpty \code - isEmpty() + isEmpty(): boolean \endcode Returns true if the property list has no internal object reference set, otherwise false. \section2 format \code - format() + format(): string \endcode Returns the data format that the property list data was deserialized from. This property is set after calling \c readFromString or \c readFromFile. @@ -81,30 +73,43 @@ \section2 readFromFile \code - readFromFile(filePath) + readFromFile(filePath: string): void \endcode Parses the file and stores the result in the property list. Throws an exception if an I/O error occurs or the input is in an invalid format. + \section2 readFromObject + \code + readFromObject(obj: any): void + \endcode + Sets the given object as the property list's internal object. + \c format() will return \c undefined as this method does not deserialize a storage format. + \section2 readFromString \code - readFromString(input) + readFromString(input: string): void \endcode Parses \c input and stores the result in the property list. This is most useful for initializing a property list object from the result of a \c JSON.stringify call. Throws an exception if the input is in an invalid format. - \section2 toJSONString + \section2 toObject + \code + toObject(): any + \endcode + Returns an object representing the property list. + + \section2 toJSON \code - toJSONString(style) + toJSON(style: string = "compact"): string \endcode Returns a string representation of the property list in JSON format. Possible values for \c style include \c "pretty" and \c "compact". The default is compact. \section2 toString \code - toString(format) + toString(format: string): string \endcode Returns a string representation of the property list in the specified format. Possible values for \c format include: \c "json" (compact), \c "json-compact", \c "json-pretty", @@ -113,14 +118,14 @@ \section2 toXMLString \code - toXMLString() + toXMLString(): string \endcode Returns a string representation of the property list in XML format. This function is a synonym for \c toString("xml1"). \section2 writeToFile \code - writeToFile(filePath, format) + writeToFile(filePath: string, format: string): void \endcode Writes the property list to the file in the given format. Possible values for \c format include: \c "binary1", \c "json" (compact), \c "json-compact", diff --git a/doc/reference/jsextensions/jsextension-textfile.qdoc b/doc/reference/jsextensions/jsextension-textfile.qdoc index ecb586215..92dcf8519 100644 --- a/doc/reference/jsextensions/jsextension-textfile.qdoc +++ b/doc/reference/jsextensions/jsextension-textfile.qdoc @@ -38,73 +38,71 @@ The \c TextFile service allows you to read from and write into text files. - \section1 Making the Service Available - In order to gain access to text file operations, you need to import the - service using the - following statement at the top of your project file: + \section1 Related Declarations + + \section2 TextFile.OpenMode \code - import qbs.TextFile + enum TextFile.OpenMode { ReadOnly, WriteOnly, ReadWrite } \endcode + List of modes that a file may be opened in. \section1 Available operations \section2 Constructor \code - TextFile(filePath, openMode) + TextFile(filePath: string, openMode: OpenMode = TextFile.ReadOnly) \endcode Opens the file at \c filePath in the given mode and returns the object representing the file. - Possible values for \c openMode are \c TextFile.ReadOnly (which is the default), - \c TextFile.WriteOnly and \c TextFile.ReadWrite. Note that the mode influences which - of the operations listed below can actually be used on the file. + \note The mode influences which of the operations listed below can actually be used on the file. \section2 atEof \code - atEof() + atEof(): boolean \endcode - Returns true if no more data can be read from the file, false otherwise. + Returns \c{true} if no more data can be read from the file, \c{false} otherwise. \section2 close \code - close() + close(): void \endcode Closes the file. We recommended to always call this function as soon as you are finished with the file, in order to keep the number of in-flight file descriptors as low as possible. \section2 readAll \code - readAll() + readAll(): string \endcode Reads all data from the file and returns it. \section2 readLine \code - readLine() + readLine(): string \endcode Reads one line of text from the file and returns it. The returned string does not contain the newline characters. \section2 setCodec \code - setCodec(codec) + setCodec(codec: string): void \endcode Sets the text codec to \c codec. The supported codecs are the same as for \c QTextCodec, for example: "UTF-8", "UTF-16", and "ISO 8859-1". \section2 truncate \code - truncate() + truncate(): void \endcode Truncates the file, that is, gives it the size of zero, removing all content. \section2 write \code - write(data) + write(data: string): void \endcode Writes \c data into the file at the current position. \section2 writeLine \code - writeLine(data) + writeLine(data: string): void \endcode Writes \c data into the file at the current position and appends the newline character(s). */ diff --git a/doc/reference/jsextensions/jsextensions-general.qdoc b/doc/reference/jsextensions/jsextensions-general.qdoc index cc6112fa3..8cf3cb36e 100644 --- a/doc/reference/jsextensions/jsextensions-general.qdoc +++ b/doc/reference/jsextensions/jsextensions-general.qdoc @@ -1,6 +1,7 @@ /**************************************************************************** ** ** Copyright (C) 2015 The Qt Company Ltd. +** Copyright (C) 2015 Petroules Corporation. ** Contact: http://www.qt.io/licensing ** ** This file is part of the Qt Build Suite. @@ -37,58 +38,90 @@ \brief Provides various operations. These are operations that do not fit into any of the other categories. - They are automatically available in any \QBS project file. + They are automatically available in any \QBS project file or JavaScript file. \section1 Available Operations - \section2 getEnv + \section2 qbs.getEnv \code - qbs.getEnv(name) + qbs.getEnv(key: string): string \endcode Tries to find a variable with the given name in the build environment and returns its value. If no such variable could be found, \c undefined is returned. - \section2 getHostOS + \section2 qbs.getHash \code - qbs.getHostOS(name) + qbs.getHash(key: string): string \endcode - Returns the name of the operating system on which \QBS is running. - \note Do not confuse this with the \c{qbs.targetOS} property, which represents the operating - system on which the binaries produced by \QBS will run. + Calculates a 16-byte hash of the input and returns it. + Rules in modules should use this function to find unique locations for output + artifacts in the build directory without duplicating the whole directory structure of + the respective input file (to deal with the case of two files with the same name in different + subdirectories of the same product). + + \section2 qbs.rfc1034Identifier + \code + qbs.rfc1034Identifier(str: string): string + \endcode + Returns an RFC 1034 compliant identifier based on the given string by replacing each character + that is not Latin alphanumeric or \c{.} with \c{-}. \section2 loadFile \code - var MyFunctions = loadFile("myfunctions.js"); - MyFunctions.doSomething(); + loadFile(filePath: string): any \endcode Loads a JavaScript file and returns an object that contains the evaluated context of this file. This function is only available in JavaScript files. + For example: + \code + var MyFunctions = loadFile("myfunctions.js"); + MyFunctions.doSomething(); + \endcode \section2 loadExtension \code - var FileInfo = loadExtension("qbs.FileInfo"); - var fileName = FileInfo.fileName(filePath); + loadExtension(extensionName: string): any \endcode Loads a \QBS extension and returns an object that contains all functions of that extension. This function is only available in JavaScript files. + For example: + \code + var FileInfo = loadExtension("qbs.FileInfo"); + var fileName = FileInfo.fileName(filePath); + \endcode \section1 Extensions to JavaScript Built-in Objects - \section2 \c{Array.contains(e)} + \section2 Array.contains + \code + Array.contains(e: any): boolean + \endcode Returns \c{true} if the array contains the element \c{e}. Returns \c{false} otherwise. - \section2 \c{Array.uniqueConcat(other)} + \section2 Array.uniqueConcat + \code + Array.uniqueConcat(other: any[]): any[] + \endcode Returns a copy of this array joined with the array \c{other}. Duplicates that would originate from the concatenation are removed. The order of elements is preserved. - \section2 \c{String.contains(s)} + \section2 String.contains + \code + String.contains(s: string): boolean + \endcode Returns \c{true} if the string contains the substring \c{s}. Returns \c{false} otherwise. - \section2 \c{String.startsWith(s)} + \section2 startsWith + \code + String.startsWith(s: string): boolean + \endcode Returns \c{true} if the string starts with the substring \c{s}. Returns \c{false} otherwise. - \section2 \c{String.endsWith(s)} + \section2 endsWith + \code + String.endsWith(s: string): boolean + \endcode Returns \c{true} if the string ends with the substring \c{s}. Returns \c{false} otherwise. */ |