Skip to content

Latest commit

 

History

History
176 lines (129 loc) · 7.52 KB

modules.md

File metadata and controls

176 lines (129 loc) · 7.52 KB

Module reference

Pixlet scripts have access to a couple of modules that can be very helpful in developing applets. To make use of a module, use the load statement.

The example below would load the render.star Starlark module, extract the render identifier and make it available to the script as the symbol render.

load("render.star", "render")

It's also possible to assign the identifiers to a different symbol. In this example, the render module is made available to the script as the symbol r instead of render:

load("render.star", r = "render")

Starlib modules

Pixlet offers a subset of the modules provided by the Starlib project. For documentation of the individual modules, please refer to the Starlib documentation.

Module Description
encoding/base64.star Base 64 encoding and decoding
encoding/csv.star CSV decoding
encoding/json.star JSON encoding and decoding
hash.star MD5, SHA1, SHA256 hash generation
html.star jQuery-like functions for HTML
http.star HTTP client
math.star Mathematical functions and constants
re.star Regular expressions
time.star Time operations

Pixlet module: Cache

In addition to the Starlib modules, Pixlet offers a cache module.

Function Description
set(key, value, ttl_seconds=60) Writes a key-value pair to the cache, with expiration as a TTL.
get(key) Retrieves a value by its key. Returns None if key doesn't exist or has expired.

Keys and values must all be string. Serialization of non-string data is the developer's responsibility.

Example:

load("cache.star", "cache")
def get_counter():
    i = cache.get("counter")
    if i == None:
        i = 0
    cache.set("counter", str(i + 1), ttl_seconds=3600)
    return i + 1
...

Pixlet module: Humanize

The humanize module has formatters for units to human friendly sizes.

Function Description
time(date) Lets you take a time.Time and spit it out in relative terms. For example, 12 seconds ago or 3 days from now.
relative_time(date1, date2, label1?, label2?) Formats a time into a relative string. It takes two time.Times and two labels. In addition to the generic time delta string (e.g. 5 minutes), the labels are used applied so that the label corresponding to the smaller time is applied.
time_format(format, date?) Takes a Java SimpleDateFormat and returns a Go layout string. If you pass it a date, it will apply the format using the converted layout string and return the formatted date.
bytes(size, iec?) Lets you take numbers like 82854982 and convert them to useful strings like, 83 MB. You can optionally format using IEC sizes like, 83 MiB.
parse_bytes(formatted_size) Lets you take strings like 83 MB and convert them to the number of bytes it represents like, 82854982.
comma(num) Lets you take numbers like 123456 or 123456.78 and convert them to comma-separated numbers like 123,456 or 123,456.78.
float(format, num) Returns a formatted number as string with options. Examples: given n = 12345.6789: #,###.## => 12,345.67, #,###. => 12,345
int(format, num) Returns a formatted number as string with options. Examples: given n = 12345: #,###. => 12,345
ordinal(num) Lets you take numbers like 1 or 2 and convert them to a rank/ordinal format strings like, 1st or 2nd.
ftoa(num, digits?) Converts a float to a string with no trailing zeros.
plural(quantity, singular, plural?) Formats an integer and a string into a single pluralized string. The simple English rules of regular pluralization will be used if the plural form is an empty string (i.e. not explicitly given)..
plural_word(quantity, singular, plural?) Builds the plural form of an English word. The simple English rules of regular pluralization will be used if the plural form is an empty string (i.e. not explicitly given).
word_series(words, conjunction) Converts a list of words into a word series in English. It returns a string containing all the given words separated by commas, the coordinating conjunction, and a serial comma, as appropriate.
oxford_word_series(words, conjunction) Converts a list of words into a word series in English, using an Oxford comma. It returns a string containing all the given words separated by commas, the coordinating conjunction, and a serial comma, as appropriate.

Example:

See examples/humanize.star for an example.

Pixlet module: XPath

The xpath module lets you extract data from XML documents using XPath queries.

Function Description
loads(doc) Parses an XML document and returns an xpath object

On an xpath object, the following methods are available:

Method Description
query(path) Retrieves text of the first tag matching the path
query_all(path) Retrieves text of all tags matching the path

Example:

load("xpath.star", "xpath")

doc = """
<foo>
    <bar>bar</bar>
    <bar>baz</bar>
</foo>
"""

def get_bars():
    x = xpath.loads(doc)
    return x.query_all("/foo/bar")
...

Pixlet module: Render

The render.star module is where Pixlet's Widgets live. All of them are documented in a fair bit of detail in the widget documentation.

Example:

load("render.star", r="render")
def main():
    return r.Root(child=r.Box(width=12, height=14, color="#ff0"))

Pixlet module: Schema

The schema module provides configuration options for your app. See the schema documentation for more details.

Example:

See examples/schema_hello_world.star for an example.

Pixlet module: Secret

The secret module can decrypt values that were encrypted with pixlet encrypt.

Function Description
decrypt(value) Decrypts and returns the value when running in Tidbyt cloud. Returns None when running locally. Decryption will fail if the name of the app doesn't match the name that was passed to pixlet encrypt.

Example:

load("secret.star", "secret")

ENCRYPTED_API_KEY = "AV6+..." . # from `pixlet encyrpt`

def main(config):
    api_key = secret.decrypt(ENCRYPTED_API_KEY) or config.get("dev_api_key")

Pixlet module: Sunrise

The sunrise module calculates sunrise and sunset times for a given set of GPS coordinates and timestamp.

Function Description
sunrise(lat, lng, date) Calculates the sunrise time for a given location and date.
sunset(lat, lng, date) Calculates the sunset time for a given location and date.

Example:

See examples/sunrise.star for an example.