Transferred file module documentation.

docs/en/modules/file.md

@@ -0,0 +1,342 @@
+# file Module
+The file module provides access to the file system and its individual files.
+
+The file system is a flat file system, with no notion of directories/folders.
+
+Only one file can be open at any given time.
+
+## file.fsinfo()
+
+Return size information for the file system, in bytes.
+
+####Syntax
+`file.fsinfo()`
+
+####Parameters
+`nil`
+
+####Returns
+- `remaining` (number)
+- `used`      (number)
+- `total`     (number)
+
+####Example
+
+```lua
+  -- get file system info
+  remaining, used, total=file.fsinfo()
+  print("\nFile system info:\nTotal : "..total.." Bytes\nUsed : "..used.." Bytes\nRemain: "..remaining.." Bytes\n")
+            ```
+```
+___
+## file.format()
+
+Format the file system. Completely erases any existing file system and writes a new one. Depending on the size of the flash chip in the ESP, this may take several seconds.
+
+####Syntax
+`file.format()`
+
+####Parameters
+`nil`
+
+####Returns
+`nil`
+
+####Example
+```lua
+    file.format()
+```
+
+####See also
+  - `file.remove()`
+___
+## file.list()
+
+Lists all files in the file system.
+
+####Syntax
+`file.list()`
+
+####Parameters
+`nil`
+
+####Returns
+a lua table which contains the {file name: file size} pairs
+
+####Example
+```lua
+    l = file.list();
+    for k,v in pairs(l) do
+      print("name:"..k..", size:"..v)
+    end
+```
+___
+## file.remove()
+
+Remove a file from the file system. The file must not be currently open.
+
+###Syntax
+`file.remove(filename)`
+
+####Parameters
+  - `filename`: file to remove
+
+####Returns
+`nil`
+
+####Example
+
+```lua
+    -- remove "foo.lua" from file system.
+    file.remove("foo.lua")
+```
+####See also
+  - `file.open()`
+___
+## file.rename()
+
+Renames a file. If a file is currently open, it will be closed first.
+
+####Syntax
+`file.rename(oldname, newname)`
+
+####Parameters
+  - `oldname`: old file name
+  - `newname`: new file name
+
+####Returns
+`true` on success, `false` on error.
+
+####Example
+
+```lua
+    -- rename file 'temp.lua' to 'init.lua'.
+    file.rename("temp.lua","init.lua")
+```
+___
+## file.open()
+
+Opens a file for access, potentially creating it (for write modes).
+
+When done with the file, it must be closed using `file.close()`.
+
+####Syntax
+`file.open(filename, mode)`
+
+####Parameters
+  - `filename`: file to be opened, directories are not supported
+  - `mode`:
+    - "r": read mode (the default)<br />
+    - "w": write mode<br />
+    - "a": append mode<br />
+    - "r+": update mode, all previous data is preserved<br />
+    - "w+": update mode, all previous data is erased<br />
+    - "a+": append update mode, previous data is preserved, writing is only allowed at the end of file
+
+####Returns
+  - `nil` if file not opened, or not exists (read modes).  true` if file opened ok.
+
+####Example
+
+```lua
+    -- open 'init.lua', print the first line.
+    file.open("init.lua", "r")
+    print(file.readline())
+    file.close()
+```
+####See also
+  - `file.close()`
+  - `file.readline()`
+___
+## file.close()
+
+Closes the open file, if any.
+
+####Syntax
+`file.close()`
+
+####Parameters
+`nil`
+
+####Returns
+`nil`
+
+####Example
+
+```lua
+    -- open 'init.lua', print the first line.
+    file.open("init.lua", "r")
+    print(file.readline())
+    file.close()
+```
+####See also
+  - `file.open()`
+___
+## file.readline()
+
+Read the next line from the open file.
+
+####Syntax
+`file.readline()`
+
+####Parameters
+`nil`
+
+####Returns
+File content in string, line by line, include EOL('\n'). Return `nil` when EOF.
+
+####Example
+
+```lua
+    -- print the first line of 'init.lua'
+    file.open("init.lua", "r")
+    print(file.readline())
+    file.close()
+```
+####See also
+  - `file.open()`
+  - `file.close()`
+  - `file.read()`
+___
+## file.writeline()
+
+Write a string to the open file and append '\n' at the end.
+
+####Syntax
+`file.writeline(string)`
+
+####Parameters
+  - `string`: content to be write to file
+
+####Returns
+`true` if write ok, `nil` on error.
+
+####Example
+
+```lua
+    -- open 'init.lua' in 'a+' mode
+    file.open("init.lua", "a+")
+    -- write 'foo bar' to the end of the file
+    file.writeline('foo bar')
+    file.close()
+```
+
+####See also
+  - `file.open()`
+  - `file.readline()`
+___
+## file.read()
+
+Read content from the open file.
+####Syntax
+`file.read([n_or_str])`
+
+####Parameters
+  - `n_or_str`:
+    - if nothing passed in, read all byte in file.
+    - if pass a number n, then read n bytes from file, or EOF is reached.
+    - if pass a string "str", then read until 'str' or EOF is reached.
+
+####Returns
+File content in string, or nil when EOF.
+
+####Example
+```lua
+    -- print the first line of 'init.lua'
+    file.open("init.lua", "r")
+    print(file.read('\n'))
+    file.close()
+
+    -- print the first 5 byte of 'init.lua'
+    file.open("init.lua", "r")
+    print(file.read(5))
+    file.close()
+```
+
+####See also
+  - `file.open()`
+  - `file.readline()`
+___
+## file.write()
+
+Write a string to the open file.
+
+####Syntax
+`file.write(string)`
+
+####Parameters
+`string`: content to be write to file.
+
+####Returns
+`true` if the write is ok, `nil` on error.
+
+####Example
+
+```lua
+    -- open 'init.lua' in 'a+' mode
+    file.open("init.lua", "a+")
+    -- write 'foo bar' to the end of the file
+    file.write('foo bar')
+    file.close()
+```
+
+####See also
+  - `file.open()`
+  - `file.writeline()`
+___
+## file.flush()
+
+Flushes any pending writes to the file system, ensuring no data is lost on a restart. Closing the open file using `file.close()` performs an implicit flush as well.
+
+####Syntax
+`file.flush()`
+
+####Parameters
+`nil`
+
+####Returns
+`nil`
+
+####Example
+```lua
+    -- open 'init.lua' in 'a+' mode
+    file.open("init.lua", "a+")
+    -- write 'foo bar' to the end of the file
+    file.write('foo bar')
+    file.flush()
+    -- write 'baz' too
+    file.write('baz')
+    file.close()
+```
+####See also
+  - `file.close()`
+___
+## file.seek()
+Sets and gets the file position, measured from the beginning of the file, to the position given by offset plus a base specified by the string whence.
+
+####Syntax
+`file.seek([whence [, offset]])`
+
+####Parameters
+  - `whence`:
+    - "set": base is position 0 (beginning of the file)
+    - "cur": base is current position (default value)
+    - "end": base is end of file
+  - offset: default 0
+
+If no parameters are given, the function simply returns the current file offset.
+
+####Returns
+The resulting file position, or `nil` on error.
+
+####Example
+```lua
+    file.open("init.lua", "r")
+    -- skip the first 5 bytes of the file
+    file.seek("set", 5)
+    print(file.readline())
+    file.close()
+```
+####See also
+  - `file.open()`
+___

mkdocs.yml

@@ -30,5 +30,6 @@ pages:
     - Support: 'en/support.md'
     - Modules:
         - 'node': 'en/modules/node.md'
+        - 'file': 'en/modules/file.md'
 - Deutsch:
     - Home: 'de/index.md'