jwosty / fable.system.io Goto Github PK

Lightweight System.IO.Path and System.IO.File for Fable - https://www.nuget.org/packages/Fable.System.IO/

License: MIT License

F# 98.76% HTML 0.52% JavaScript 0.58% Batchfile 0.06% Shell 0.08%

fable.system.io's Introduction

Fable.System.IO

Fable.System.IO is a Fable-compatible implementation of Path and some of the File APIs from .NET. This library is built to behave identically to the real .NET APIs, whether using it from .NET or Javascript.

To use the library, just reference the Fable.System.IO NuGet package and replace all occurrences of open System.IO with open Fable.System.IO.

Fable.System.IO will behave the same as the browser's current platform, as detected by platform-detect. In other words, when running in a Unix agent, it will use / as the directory separator; and in a Windows agent, it will use \ instead.

File APIs in Fable?!

Fable.System.IO gives File read operations the ability to make web requests, and will most of the time "do the right thing" when used in a Fable context. For example (works in .NET and Fable):

open Fable.System.IO // Don't forget this!
// Get the index page of Google.
let google = File.ReadAllText "https://google.com"

Or, if we're on example.org/foo/bar.html, and you want to get a file right beside the html page called data.csv:

// If running in Fable, and browser is at example.org/foo/bar.html, this fetches example.org/foo/data.csv
// If running on .NET, this will behave as usual (read the file from the current working directory)
let data = File.ReadAllLines "./data.csv"

Or, if we're on example.org/foo/bar.html and you want to read example.org/some/thing/else.json, asynchronously:

async {
    let! data = File.AsyncReadAllLines "../some/thing/else.json"
    // alternatively
    let! data = File.AsyncReadAllLines "/some/thing/else.json"
}

Choosing emulated OS

By default, this library will emulate the path behavior for the current detected operating system. If you want to force Windows path behavior, you can open Fable.Windows.System.IO. Likewise, to force Unix path behavior, open Fable.Unix.System.IO. For example:

open Fable
open Fable.Unix.System.IO

printfn "Path.Combine(\"foo\", \"bar\") = \"%s\"" (Path.Combine ("foo", "bar"))

// This will output "foo/bar" on all systems

Supported APIs

Here is a list of currently implemented APIs in Fable.System.IO:

System.IO
- Path (static methods) (Microsoft docs here)
  - GetInvalidFileNameChars()
  - GetInvalidPathChars()
  - IsPathRooted(string)
  - Combine(string[])
  - Join(string, string)
  - GetRelativePath(string, string)
  - GetDirectoryName(string)
  - GetFileName(string)
  - GetFileNameWithoutExtension(string)
  - GetExtension(string)
  - HasExtension(string)
  - DirectorySeparatorChar : string
  - AltDirectorySeparatorChar : string
- File (static methods) (Microsoft docs here)
  - File.ReadAllLines
  - File.AsyncReadAllLines^†
  - File.ReadAllText
  - File.AsyncReadAllText^†
  - File.ReadLines

† Convenience methods (not part of the BCL) that can be used in place of the asynchronous Task<'T> variations. You can safely use these instead of the BCL async methods on both .NET and Fable runtimes.

Development

You can open the Fable.System.IO.sln directly in your favorite .NET IDE.

You can run all tests (.NET and Javascript) with:

dotnet tool restore
dotnet paket restore
dotnet fable build -t Test

To run the test suite only under .NET, use:

dotnet test

To run the test suite only under node, use:

yarn test

The Path tests include "Oracle" tests cases, which test the API against the BCL implementation. Therefore, for complete testing, one should make sure to run the test suite under a Windows system and a Unix system. The GitHub CI runs the full test suite under Windows and Ubuntu.

fable.system.io's People

Contributors

Stargazers

Watchers

Forkers

shmew ingted

fable.system.io's Issues

Implement Path.GetFullPath

Ditch npm dependency

I went ahead and wrote up a native implementation of platform-detect excluding the out of place parts (the form factor stuff) and added it to Fable.Extras. This lets you remove an installation step for users of the library.

So all you need to do is add a reference to that and replace pieces like:

PlatformDetect.os.windows || PlatformDetect.os.uwp

with this:

open Fable.Extras.Platform

JSe.Platform.is.windows || JSe.Platform.is.uwp

Implement File APIs

It would be pretty cool to make calling File.Open work in some circumstances. Here would be the ideal approach:

The File class would be implemented in such a way that it would accept URIs as paths (and would never allow writing; only reading), so you could do something like this:

use contents = File.OpenText("https://example.com/something.json")
let result = contents.ReadToEnd ()
printfn "something.json:\n%s" result

It should also be able to handle relative paths, which would be treated as if they are relative to some kind of easy-to-reason about point -- perhaps the top-level uri of the host website. In other words, say we have the following website structure:

https://example.com/
- app.js
- something.json

Calling File.OpenText("something.json") from within app.js should obviously return the contents from https://example.com/something.json. The only question would be: what is this "current directory" actually relative to? Is it the website root? Or is it relative to the current script? In other words, in the following scenario, which something.json should we point to?

https://example.com/
- something.json
- app/
  - something.js
  - app.js

One final note -- this really is exactly equivalent to setting some reasonable environment-wide CurrentDirectory, while extending all these APIs to understand URIs instead of paths. Perhaps the current directory should be settable as well, like it normally is (provided that you give it a URI instead?).

Switch to build.fsproj style FAKE setup

See: https://fake.build/guide/getting-started.html#Run-FAKE-using-a-dedicated-build-project

Pros: Better Intellisense support (the IDEs can never figure out build.fsx), works on arm64 macOS dotnet
Cons: It's work

Implement Stream

PR #10 adds a few static File methods related to file reading, but does not implement things like File.Open. If we had a Stream proxy in Fable, it would enable that to happen

I'm dubious as to how often Stream would be used in Fable however, so I personally have no plans to do this unless I hear concrete evidence of desire for it.

If someone created a high-quality PR for this, I would consider taking it.

open Fable.System.IO no longer works

I seem to have broken the namespace structure such that open Fable.System.IO now generates a compile error:

error FS0039: The namespace 'IO' is not defined.

which results in things like this, further down the line:

error FS0039: The value, namespace, type or module 'Path' is not defined.

Workaround

Workaround for now is to either downgrade Fable.System.IO to 0.1.1, or replace instances of Path.SomeMethod with Fable.System.IO.Path.SomeMethod (and likewise with File methods).

Publish symbols

Assembly symbols should be published to NuGet (either by being published separately, or by being included in the package). Ideally, we should have SourceLink set up to make the symbols automatically get referenced from GitHub (supposedly it's as easy as doing the steps listed here: https://github.com/dotnet/sourcelink#using-source-link-in-net-projects).