Skip to content

Commit

Permalink
docs: refine API docs for files in File dir
Browse files Browse the repository at this point in the history
  • Loading branch information
@devvaannsh @abose
devvaannsh authored and abose committed Oct 29, 2024
1 parent 96d8dec commit 2a63dae
Show file tree
Hide file tree
Showing 2 changed files with 80 additions and 63 deletions.
128 changes: 68 additions & 60 deletions docs/API-Reference/file/FileUtils.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,28 +3,25 @@
const FileUtils = brackets.getModule("file/FileUtils")
```

<a name="list"></a>

## list : <code>List</code>
of File Extensions which will be opened in external Application

**Kind**: global variable
<a name="LINE_ENDINGS_CRLF"></a>

## LINE\_ENDINGS\_CRLF : <code>enum</code>
Line endings
Line endings crlf

**Kind**: global enum
<a name="Maximium"></a>
<a name="LINE_ENDINGS_LF"></a>

## Maximium : <code>Number</code>
file size (in megabytes) (for display strings) This must be a hard-coded value since this value tells how low-level APIs should behave which cannot have a load order dependency on preferences manager
## LINE\_ENDINGS\_LF : <code>enum</code>
Line endings lf

**Kind**: global constant
**Kind**: global enum
<a name="Maximium"></a>

## Maximium : <code>Number</code>
file size (in bytes) This must be a hard-coded value since this value tells how low-level APIs should behave which cannot have a load order dependency on preferences manager
file size (in bytes)
This must be a hard-coded value since this value
tells how low-level APIs should behave which cannot
have a load order dependency on preferences manager

**Kind**: global constant
<a name="readAsText"></a>
Expand All @@ -33,7 +30,9 @@ file size (in bytes) This must be a hard-coded value since this value tells
Asynchronously reads a file as UTF-8 encoded text.

**Kind**: global function
**Returns**: <code>$.Promise</code> - a jQuery promise that will be resolved with the file's text content plus its timestamp, or rejected with a FileSystemError string constant if the file can not be read.
**Returns**: <code>$.Promise</code> - a jQuery promise that will be resolved with the
file's text content plus its timestamp, or rejected with a FileSystemError string
constant if the file can not be read.

| Param | Type | Description |
| --- | --- | --- |
Expand All @@ -46,7 +45,8 @@ Asynchronously reads a file as UTF-8 encoded text.
Asynchronously writes a file as UTF-8 encoded text.

**Kind**: global function
**Returns**: <code>$.Promise</code> - a jQuery promise that will be resolved whenfile writing completes, or rejected with a FileSystemError string constant.
**Returns**: <code>$.Promise</code> - a jQuery promise that will be resolved when
file writing completes, or rejected with a FileSystemError string constant.

| Param | Type | Description |
| --- | --- | --- |
Expand All @@ -56,14 +56,15 @@ Asynchronously writes a file as UTF-8 encoded text.

<a name="getPlatformLineEndings"></a>

## getPlatformLineEndings() ⇒ [<code>LINE\_ENDINGS\_CRLF</code>](#LINE_ENDINGS_CRLF) \| <code>LINE\_ENDINGS\_LF</code>
## getPlatformLineEndings() ⇒ [<code>LINE\_ENDINGS\_CRLF</code>](#LINE_ENDINGS_CRLF) \| [<code>LINE\_ENDINGS\_LF</code>](#LINE_ENDINGS_LF)
Returns the standard line endings for the current platform

**Kind**: global function
<a name="sniffLineEndings"></a>

## sniffLineEndings(text) ⇒ <code>null</code> \| [<code>LINE\_ENDINGS\_CRLF</code>](#LINE_ENDINGS_CRLF) \| <code>LINE\_ENDINGS\_LF</code>
Scans the first 1000 chars of the text to determine how it encodes line endings. Returnsnull if usage is mixed or if no line endings found.
## sniffLineEndings(text) ⇒ <code>null</code> \| [<code>LINE\_ENDINGS\_CRLF</code>](#LINE_ENDINGS_CRLF) \| [<code>LINE\_ENDINGS\_LF</code>](#LINE_ENDINGS_LF)
Scans the first 1000 chars of the text to determine how it encodes line endings. Returns
null if usage is mixed or if no line endings found.

**Kind**: global function

Expand All @@ -81,7 +82,7 @@ Translates any line ending types in the given text to the be the single form spe
| Param | Type |
| --- | --- |
| text | <code>string</code> |
| lineEndings | <code>null</code> \| [<code>LINE\_ENDINGS\_CRLF</code>](#LINE_ENDINGS_CRLF) \| <code>LINE\_ENDINGS\_LF</code> |
| lineEndings | <code>null</code> \| [<code>LINE\_ENDINGS\_CRLF</code>](#LINE_ENDINGS_CRLF) \| [<code>LINE\_ENDINGS\_LF</code>](#LINE_ENDINGS_LF) |

<a name="getFileErrorString"></a>

Expand All @@ -93,19 +94,6 @@ Translates any line ending types in the given text to the be the single form spe
| --- | --- |
| name | <code>FileSystemError</code> |

<a name="showFileOpenError"></a>

## ..showFileOpenError(name) ⇒ <code>Dialog</code>..
***Deprecated***

Shows an error dialog indicating that the given file could not be opened due to the given error

**Kind**: global function

| Param | Type |
| --- | --- |
| name | <code>FileSystemError</code> |

<a name="makeDialogFileList"></a>

## makeDialogFileList(Array)
Expand All @@ -120,7 +108,10 @@ Creates an HTML string for a list of files to be reported on, suitable for use i
<a name="convertToNativePath"></a>

## convertToNativePath(path) ⇒ <code>string</code>
Convert a URI path to a native path.On both platforms, this unescapes the URIOn windows, URI paths start with a "/", but have a drive letter ("C:"). In thiscase, remove the initial "/".
Convert a URI path to a native path.
On both platforms, this unescapes the URI
On windows, URI paths start with a "/", but have a drive letter ("C:"). In this
case, remove the initial "/".

**Kind**: global function

Expand All @@ -131,7 +122,11 @@ Convert a URI path to a native path. On both platforms, this unescapes the URI O
<a name="convertWindowsPathToUnixPath"></a>

## convertWindowsPathToUnixPath(path) ⇒ <code>string</code>
Convert a Windows-native path to use Unix style slashes.On Windows, this converts "C:\foo\bar\baz.txt" to "C:/foo/bar/baz.txt".On Mac, this does nothing, since Mac paths are already in Unix syntax.(Note that this does not add an initial forward-slash. Internally, ourAPIs generally use the "C:/foo/bar/baz.txt" style for "native" paths.)
Convert a Windows-native path to use Unix style slashes.
On Windows, this converts "C:\foo\bar\baz.txt" to "C:/foo/bar/baz.txt".
On Mac, this does nothing, since Mac paths are already in Unix syntax.
(Note that this does not add an initial forward-slash. Internally, our
APIs generally use the "C:/foo/bar/baz.txt" style for "native" paths.)

**Kind**: global function
**Returns**: <code>string</code> - A Unix-style path.
Expand All @@ -143,7 +138,9 @@ Convert a Windows-native path to use Unix style slashes. On Windows, this conver
<a name="stripTrailingSlash"></a>

## stripTrailingSlash(path) ⇒ <code>string</code>
Removes the trailing slash from a path or URL, if it has one.Warning: this differs from the format of most paths used in Brackets! Use paths ending in "/"normally, as this is the format used by Directory.fullPath.
Removes the trailing slash from a path or URL, if it has one.
Warning: this differs from the format of most paths used in Brackets! Use paths ending in "/"
normally, as this is the format used by Directory.fullPath.

**Kind**: global function

Expand All @@ -157,7 +154,8 @@ Removes the trailing slash from a path or URL, if it has one. Warning: this diff
Get the name of a file or a directory, removing any preceding path.

**Kind**: global function
**Returns**: <code>string</code> - Returns the base name of a file or the name of adirectory
**Returns**: <code>string</code> - Returns the base name of a file or the name of a
directory

| Param | Type | Description |
| --- | --- | --- |
Expand All @@ -166,36 +164,33 @@ Get the name of a file or a directory, removing any preceding path.
<a name="getNativeBracketsDirectoryPath"></a>

## getNativeBracketsDirectoryPath() ⇒ <code>string</code>
Returns a native absolute path to the 'brackets' source directory.Note that this only works when run in brackets/src/index.html, so it doesnot work for unit tests (which is run from brackets/test/SpecRunner.html)WARNING: unlike most paths in Brackets, this path EXCLUDES the trailing "/".
Returns a native absolute path to the 'brackets' source directory.
Note that this only works when run in brackets/src/index.html, so it does
not work for unit tests (which is run from brackets/test/SpecRunner.html)

WARNING: unlike most paths in Brackets, this path EXCLUDES the trailing "/".

**Kind**: global function
<a name="getNativeModuleDirectoryPath"></a>

## getNativeModuleDirectoryPath() ⇒ <code>string</code>
Given the module object passed to JS module define function,convert the path to a native absolute path.Returns a native absolute path to the module folder.WARNING: unlike most paths in Brackets, this path EXCLUDES the trailing "/".
Given the module object passed to JS module define function,
convert the path to a native absolute path.
Returns a native absolute path to the module folder.

WARNING: unlike most paths in Brackets, this path EXCLUDES the trailing "/".

**Kind**: global function
<a name="getFileExtension"></a>

## getFileExtension(fullPath) ⇒ <code>string</code>
Get the file extension (excluding ".") given a path OR a bare filename.Returns "" for names with no extension. If the name starts with ".", thefull remaining text is considered the extension.
Get the file extension (excluding ".") given a path OR a bare filename.
Returns "" for names with no extension. If the name starts with ".", the
full remaining text is considered the extension.

**Kind**: global function
**Returns**: <code>string</code> - Returns the extension of a filename or empty string ifthe argument is a directory or a filename with no extension

| Param | Type | Description |
| --- | --- | --- |
| fullPath | <code>string</code> | full path to a file or directory |

<a name="getSmartFileExtension"></a>

## ..getSmartFileExtension(fullPath) ⇒ <code>string</code>..
***Deprecated***

Get the file extension (excluding ".") given a path OR a bare filename.Returns "" for names with no extension.If the only `.` in the file is the first character,returns "" as this is not considered an extension.This method considers known extensions which include `.` in them.

**Kind**: global function
**Returns**: <code>string</code> - Returns the extension of a filename or empty string ifthe argument is a directory or a filename with no extension
**Returns**: <code>string</code> - Returns the extension of a filename or empty string if
the argument is a directory or a filename with no extension

| Param | Type | Description |
| --- | --- | --- |
Expand All @@ -204,7 +199,12 @@ Get the file extension (excluding ".") given a path OR a bare filename. Returns
<a name="getRelativeFilename"></a>

## getRelativeFilename(basePath, filename) ⇒ <code>string</code>
Computes filename as relative to the basePath. For example:basePath: /foo/bar/, filename: /foo/bar/baz.txtreturns: baz.txtThe net effect is that the common prefix is stripped away. If basePath is nota prefix of filename, then undefined is returned.
Computes filename as relative to the basePath. For example:
basePath: /foo/bar/, filename: /foo/bar/baz.txt
returns: baz.txt

The net effect is that the common prefix is stripped away. If basePath is not
a prefix of filename, then undefined is returned.

**Kind**: global function
**Returns**: <code>string</code> - relative path
Expand Down Expand Up @@ -232,7 +232,8 @@ Determine if file extension is a static html file extension.
Get the parent directory of a file. If a directory is passed, the SAME directory is returned.

**Kind**: global function
**Returns**: <code>string</code> - Returns the path to the parent directory of a file or the path of a directory, including trailing "/"
**Returns**: <code>string</code> - Returns the path to the parent directory of a file or the path of a directory,
including trailing "/"

| Param | Type | Description |
| --- | --- | --- |
Expand All @@ -241,7 +242,9 @@ Get the parent directory of a file. If a directory is passed, the SAME directory
<a name="getParentPath"></a>

## getParentPath(fullPath) ⇒ <code>string</code>
Get the parent folder of the given file/folder path. Differs from getDirectoryPath() when 'fullPath'is a directory itself: returns its parent instead of the original path. (Note: if you already have aFileSystemEntry, it's faster to use entry.parentPath instead).
Get the parent folder of the given file/folder path. Differs from getDirectoryPath() when 'fullPath'
is a directory itself: returns its parent instead of the original path. (Note: if you already have a
FileSystemEntry, it's faster to use entry.parentPath instead).

**Kind**: global function
**Returns**: <code>string</code> - Path of containing folder (including trailing "/"); or "" if path was the root
Expand All @@ -265,7 +268,8 @@ Get the file name without the extension. Returns "" if name starts with "."
<a name="compareFilenames"></a>

## compareFilenames(filename1, filename2, extFirst) ⇒ <code>number</code>
Compares 2 filenames in lowercases. In Windows it compares the names without theextension first and then the extensions to fix issue #4409
Compares 2 filenames in lowercases. In Windows it compares the names without the
extension first and then the extensions to fix issue #4409

**Kind**: global function
**Returns**: <code>number</code> - The result of the compare function
Expand All @@ -279,10 +283,13 @@ Compares 2 filenames in lowercases. In Windows it compares the names without the
<a name="comparePaths"></a>

## comparePaths(path1, path2) ⇒ <code>number</code>
Compares two paths segment-by-segment, used for sorting. When two files share a path prefix,the less deeply nested one is sorted earlier in the list. Sorts files within the same parentfolder based on `compareFilenames()`.
Compares two paths segment-by-segment, used for sorting. When two files share a path prefix,
the less deeply nested one is sorted earlier in the list. Sorts files within the same parent
folder based on `compareFilenames()`.

**Kind**: global function
**Returns**: <code>number</code> - -1, 0, or 1 depending on whether path1 is less than, equal to, or greater than path2 according to this ordering.
**Returns**: <code>number</code> - -1, 0, or 1 depending on whether path1 is less than, equal to, or greater than
path2 according to this ordering.

| Param | Type |
| --- | --- |
Expand All @@ -293,7 +300,8 @@ Compares two paths segment-by-segment, used for sorting. When two files share a

## encodeFilePath(path) ⇒ <code>string</code>
**Kind**: global function
**Returns**: <code>string</code> - URI-encoded version suitable for appending to 'file:///`. It's not safe to use encodeURI() directly since it doesn't escape chars like "#".
**Returns**: <code>string</code> - URI-encoded version suitable for appending to 'file:///`. It's not safe to use encodeURI()
directly since it doesn't escape chars like "#".

| Param | Type | Description |
| --- | --- | --- |
Expand Down
15 changes: 12 additions & 3 deletions src/file/FileUtils.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@ define(function (require, exports, module) {

/**
* @const {Number} Maximium file size (in megabytes)
* @private
* (for display strings)
* This must be a hard-coded value since this value
* tells how low-level APIs should behave which cannot
Expand All @@ -61,6 +62,7 @@ define(function (require, exports, module) {

/**
* @var {List} list of File Extensions which will be opened in external Application
* @private
*/
var extListToBeOpenedInExtApp = [];

Expand Down Expand Up @@ -118,11 +120,16 @@ define(function (require, exports, module) {
}

/**
* Line endings
* Line endings crlf
* @enum {string}
*/
const LINE_ENDINGS_CRLF = "CRLF";

/**
* Line endings lf
* @enum {string}
*/
var LINE_ENDINGS_CRLF = "CRLF",
LINE_ENDINGS_LF = "LF";
const LINE_ENDINGS_LF = "LF";

/**
* Returns the standard line endings for the current platform
Expand Down Expand Up @@ -203,6 +210,7 @@ define(function (require, exports, module) {

/**
* Shows an error dialog indicating that the given file could not be opened due to the given error
* @private
* @deprecated Use DocumentCommandHandlers.showFileOpenError() instead
*
* @param {!FileSystemError} name
Expand Down Expand Up @@ -352,6 +360,7 @@ define(function (require, exports, module) {
* If the only `.` in the file is the first character,
* returns "" as this is not considered an extension.
* This method considers known extensions which include `.` in them.
* @private
* @deprecated Use LanguageManager.getCompoundFileExtension() instead
*
* @param {string} fullPath full path to a file or directory
Expand Down

0 comments on commit 2a63dae

Please sign in to comment.