From 3c12a672c918cec58d958842b4bbc5deba705b1a Mon Sep 17 00:00:00 2001 From: Sean Barag Date: Mon, 4 Jan 2021 13:52:10 -0800 Subject: [PATCH 1/3] doc: List unsupported BrightScript components, functions, and statements The maintainers of this `brs` often receive questions that are answered with "X isn't implemented", but determining that X isn't yet implemented is a daunting task for someone not familiar with the project. Add a list of unsupported BrightScript statements, functions, and components that we can reference. --- docs/NotImplemented.md | 90 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 docs/NotImplemented.md diff --git a/docs/NotImplemented.md b/docs/NotImplemented.md new file mode 100644 index 000000000..7044c89b8 --- /dev/null +++ b/docs/NotImplemented.md @@ -0,0 +1,90 @@ +# Statements +* [try/catch/throw](https://developer.roku.com/docs/references/brightscript/language/error-handling.md) +* [goto](https://developer.roku.com/docs/references/brightscript/language/program-statements.md#goto-label) +* [end](https://developer.roku.com/docs/references/brightscript/language/program-statements.md#end) +* [stop](https://developer.roku.com/docs/references/brightscript/language/program-statements.md#stop) and the associated interactive debugger + +# Global Functions +* [Eval](https://developer.roku.com/docs/references/brightscript/language/runtime-functions.md#evalcode-as-string-as-dynamic) - deprecated in RBI and will not be implemented in `brs` +* [GetLastRunCompileError](https://developer.roku.com/docs/references/brightscript/language/runtime-functions.md#getlastruncompileerror-as-object) - compile errors are reported immediately +* [GetLastRunRuntimeError](https://developer.roku.com/docs/references/brightscript/language/runtime-functions.md#getlastrunruntimeerror-as-integer) - runtime errors are reported immediately +* [RunGarbageCollector](https://developer.roku.com/docs/references/brightscript/language/global-utility-functions.md#rungarbagecollector-as-object) +* [Sleep](https://developer.roku.com/docs/references/brightscript/language/global-utility-functions.md#sleepmilliseconds-as-integer-as-void) +* [Wait](https://developer.roku.com/docs/references/brightscript/language/global-utility-functions.md#waittimeout-as-integer-port-as-object-as-object) - requires `roMessagePort` to be implemented (see below) +* [UpTime](https://developer.roku.com/docs/references/brightscript/language/global-utility-functions.md#uptimedummy-as-integer-as-float) + +# BrightScript Components +The following components are not currently implemented in `brs`, meaning that they can't be instantiated via `createObject`. They may be implemented in the future + +* [roAppInfo](https://developer.roku.com/docs/references/brightscript/components/roappinfo.md) +* [roAppManager](https://developer.roku.com/docs/references/brightscript/components/roappmanager.md) +* [roAudioGuide](https://developer.roku.com/docs/references/brightscript/components/roaudioguide.md) +* [roAudioMetadata](https://developer.roku.com/docs/references/brightscript/components/roaudioguide.md) +* [roAudioPlayer](https://developer.roku.com/docs/references/brightscript/components/roaudioplayer.md) +* [roAudioResource](https://developer.roku.com/docs/references/brightscript/components/roaudioresource.md) +* [roBitmap](https://developer.roku.com/docs/references/brightscript/components/robitmap.md) +* [roByteArray](https://developer.roku.com/docs/references/brightscript/components/robytearray.md) +* [roChannelStore](https://developer.roku.com/docs/references/brightscript/components/rochannelstore.md) +* [roCompositor](https://developer.roku.com/docs/references/brightscript/components/rocompositor.md) +* [roDataGramSocket](https://developer.roku.com/docs/references/brightscript/components/rodatagramsocket.md) +* [roDeviceCrypto](https://developer.roku.com/docs/references/brightscript/components/rodevicecrypto.md) +* [roEVPCipher](https://developer.roku.com/docs/references/brightscript/components/roevpcipher.md) +* [roEVPDigest](https://developer.roku.com/docs/references/brightscript/components/roevpdigest.md) +* [roEVPDigest](https://developer.roku.com/docs/references/brightscript/components/roevpdigest.md) +* [roFileSystem](https://developer.roku.com/docs/references/brightscript/components/rofilesystem.md) +* [roFileSystem](https://developer.roku.com/docs/references/brightscript/components/rofilesystem.md) +* [roFont](https://developer.roku.com/docs/references/brightscript/components/rofont.md) +* [roFontRegistry](https://developer.roku.com/docs/references/brightscript/components/rofontregistry.md) +* [roFunction](https://developer.roku.com/docs/references/brightscript/components/rofunction.md) +* [roHdmiStatus](https://developer.roku.com/docs/references/brightscript/components/rohdmistatus.md) +* [roHMAC](https://developer.roku.com/docs/references/brightscript/components/rohmac.md) +* [roHttpAgent](https://developer.roku.com/docs/references/brightscript/components/rohttpagent.md) +* [roHttpAgent](https://developer.roku.com/docs/references/brightscript/components/rohttpagent.md) +* [roImageMetadata](https://developer.roku.com/docs/references/brightscript/components/roimagemetadata.md) +* [roInput](https://developer.roku.com/docs/references/brightscript/components/roinput.md) +* [roList](https://developer.roku.com/docs/references/brightscript/components/rolist.md) +* [roLocalization](https://developer.roku.com/docs/references/brightscript/components/rolocalization.md) +* [roLongInteger](https://developer.roku.com/docs/references/brightscript/components/rolonginteger.md) +* [roMessagePort](https://developer.roku.com/docs/references/brightscript/components/romessageport.md) +* [roMicrophone](https://developer.roku.com/docs/references/brightscript/components/romicrophone.md) +* [roPath](https://developer.roku.com/docs/references/brightscript/components/ropath.md) +* [roProgramGuide](https://developer.roku.com/docs/references/brightscript/components/roprogramguide.md) +* [roRegion](https://developer.roku.com/docs/references/brightscript/components/roregion.md) +* [roRegistry](https://developer.roku.com/docs/references/brightscript/components/roregistry.md) +* [roRegistrySection](https://developer.roku.com/docs/references/brightscript/components/roregistrysection.md) +* [roRSA](https://developer.roku.com/docs/references/brightscript/components/rorsa.md) +* [roScreen](https://developer.roku.com/docs/references/brightscript/components/roscreen.md) +* [roSGScreen](https://developer.roku.com/docs/references/brightscript/components/rosgscreen.md) +* [roSocketAddress](https://developer.roku.com/docs/references/brightscript/components/rosocketaddress.md) +* [roSpringboardScreen](https://developer.roku.com/docs/references/brightscript/components/rospringboardscreen.md) +* [roSprite](https://developer.roku.com/docs/references/brightscript/components/rosprite.md) +* [roStreamSocket](https://developer.roku.com/docs/references/brightscript/components/rostreamsocket.md) +* [roSystemLog](https://developer.roku.com/docs/references/brightscript/components/rosystemlog.md) +* [roTextToSpeech](https://developer.roku.com/docs/references/brightscript/components/rotexttospeech.md) +* [roTextureManager](https://developer.roku.com/docs/references/brightscript/components/rotexturemanager.md) +* [roTextureRequest](https://developer.roku.com/docs/references/brightscript/components/rotexturerequest.md) +* [roUrlTransfer](https://developer.roku.com/docs/references/brightscript/components/rourltransfer.md) +* [roVideoPlayer](https://developer.roku.com/docs/references/brightscript/components/rovideoplayer.md) +* [roXMLElement](https://developer.roku.com/docs/references/brightscript/components/roxmlelement.md) +* [roXMLList](https://developer.roku.com/docs/references/brightscript/components/roxmllist.md) + +## Deprecated in RBI +The following components are deprecated in the Reference BrightScript Interpreter (RBI), and thus will not be implemented in this project. + +* [roCaptionRenderer](https://developer.roku.com/docs/references/brightscript/components/robytearray.md) +* [roCodeRegistrationScreen](https://developer.roku.com/docs/references/brightscript/components/rocoderegistrationscreen.md) +* [roFontMetrics](https://developer.roku.com/docs/references/brightscript/components/rofontmetrics.md) +* [roGridScreen](https://developer.roku.com/docs/references/brightscript/components/rogridscreen.md) +* [roImageCanvas](https://developer.roku.com/docs/references/brightscript/components/roimagecanvas.md) +* [roKeyboardScreen](https://developer.roku.com/docs/references/brightscript/components/rokeyboardscreen.md) +* [roListScreen](https://developer.roku.com/docs/references/brightscript/components/rolistscreen.md) +* [roMessageDialog](https://developer.roku.com/docs/references/brightscript/components/romessagedialog.md) +* [roOneLineDialog](https://developer.roku.com/docs/references/brightscript/components/roonelinedialog.md) +* [roParagraphScreen](https://developer.roku.com/docs/references/brightscript/components/roparagraphscreen.md) +* [roPinEntryDialog](https://developer.roku.com/docs/references/brightscript/components/ropinentrydialog.md) +* [roPosterScreen](https://developer.roku.com/docs/references/brightscript/components/roposterscreen.md) +* [roSearchHistory](https://developer.roku.com/docs/references/brightscript/components/rosearchhistory.md) +* [roSearchHistory](https://developer.roku.com/docs/references/brightscript/components/rosearchhistory.md) +* [roSlideShow](https://developer.roku.com/docs/references/brightscript/components/roslideshow.md) +* [roTextScreen](https://developer.roku.com/docs/references/brightscript/components/rotextscreen.md) +* [roVideoScreen](https://developer.roku.com/docs/references/brightscript/components/rovideoscreen.md) From aa58d64e51c61747a30de3528058ffd8472842a9 Mon Sep 17 00:00:00 2001 From: Sean Barag Date: Mon, 4 Jan 2021 13:54:39 -0800 Subject: [PATCH 2/3] doc: Remove project maturity concession The `brs` project has now existed for over 3 years old and with ~25 contributors, so saying the project isn't mature enough to support UI emulation is no longer accurate. Remove the maturity concession, but keep references to the amount of effort involved. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 69e0da914..07c45e718 100644 --- a/README.md +++ b/README.md @@ -86,7 +86,7 @@ Dennis Ritchie said "Hello, World!" The [Roku](https://roku.com) series of media streaming devices are wildly popular amongst consumers, and several [very](https://netflix.com) [popular](https://hulu.com) [streaming](https://amazon.com/primevideo) [services](https://crackle.com) offer Channels for the Roku platform. Unfortunately, Roku chanels *must* be written in a language called BrightScript, which is only executable directly on a Roku device. BRS hopes to change that by allowing Roku developers to test their code on their own machines, thus improving the quality of their channels and the end-user's experience as a whole. ## So can I use this to watch TV without a Roku? -Nope! The BRS project currently has no intention of emulating the Roku user interface, integrating with the Roku store, or emulating content playback. In addition to likely getting this project in legal trouble, that sort of emulation is a ton of work. BRS isn't mature enough to be able to sustain that yet. +Nope! The BRS project currently has no intention of emulating the Roku user interface, integrating with the Roku store, or emulating content playback. In addition to likely getting this project in legal trouble, that sort of emulation is a ton of work. ## Building from source The BRS project follows pretty standard `node` development patterns, with the caveat that it uses `yarn` for dependency management. From d4775e23f332688aadd3252481d1f92706d259ed Mon Sep 17 00:00:00 2001 From: Sean Barag Date: Mon, 4 Jan 2021 14:06:17 -0800 Subject: [PATCH 3/3] doc: Link to NotImplemented.md in README --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 07c45e718..4a2315ed6 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,7 @@ - [Testing](#testing) - [Cleaning](#cleaning) - [All Together](#all-together) + - [Gaps](#gaps) - [Extensions](#extensions) - [`_brs_.getStackTrace(numEntries = 10, excludePatterns = [])`](#_brs_getstacktracenumentries--10-excludepatterns--) - [`_brs_.global`](#_brs_global) @@ -165,6 +166,9 @@ Thanks to the [npm-run-all](https://www.npmjs.com/package/npm-run-all) package, $ yarn run-s clean build test ``` +## Gaps +The API provided to BrightScript developers is quite large, and implementing it in its entirety is a daunting task. Parts in the standard library included with the Reference BrightScript Implementation (RBI) are [listed in NotImplemented.md](./docs/NotImplemented.md). + ## Extensions For the most part, `brs` attempts to emulate BrightScript as closely as possible. However, in the spirit of unit testing, it also has a few extensions that will help with testing.