STONE(1)

💖 STONE(1) 💖

okay bestie, sit down, grab a boba, because we're reading the stone(1) page from the General Commands Manual and it's genuinely so much. she's an interface description language (IDL) for APIs and she is serving. let's get into it 🫶

✨ NAME ✨

stone — interface description language (IDL) for APIs 💅

🌸 SYNOPSIS 🌸

stone [-h] [-v] [--clean-build] [-f FILTER_BY_ROUTE_ATTR] [-r
ROUTE_WHITELIST_FILTER] [-a ATTRIBUTE] [-w WHITELIST_NAMESPACE_ROUTES]
[-b BLACKLIST_NAMESPACE_ROUTES] [backend] [output] [spec ...]

🦋 DESCRIPTION 🦋

okay so this manual page is the brief version of what stone does. just the highlights, the trailer, the little teaser 🎬

and like, real talk — this page was written for the Debian distribution because the original program literally does not have a manual page. not one. so Debian said "fine, we'll do it ourselves" and honestly? iconic behaviour 👑

so what is stone? she's a code generator. you hand her your specification and she translates it into objects and functions in whatever programming languages you want. it's giving "I speak every language, actually" 🌈✨

💅 OPTIONS 💅

so this program follows the usual GNU command line syntax, meaning long options start with two dashes (-). summary of options is right here, bestie:

• -h, --help — shows you the help message and then dips. bye! 👋
• -v, --verbose — prints debugging statements. she's a yapper and she's telling you everything 🗣️
• --clean-build — removes build_path before the source files get compiled into them. fresh start energy, no crumbs left behind 🧹
• -f, --filter-by-route-attr — removes routes that don't match the expression. the expression has to specify a route attribute on the left-hand side and a value on the right-hand side. use quotes for strings and bytes. the only operators supported are = and !=. for example, if hide is a route attribute, you can use this filter: hide!=true. and yes you can combine multiple expressions with and/or and use parentheses to enforce precedence. lowkey powerful fr fr 💪
• -r, --route-whitelist-filter — restricts datatype generation to only the routes in the whitelist plus their dependencies. input should be a file containing a JSON dict shaped like this:

{"route_whitelist": {}, "datatype_whitelist": {}}

where each object maps namespaces to lists of routes or datatypes to whitelist. it's giving curated. it's giving selective 🌸

• -a, --attribute — route attributes that the backend will have access to and presumably expose in generated code. use :all to select all attributes defined in stone_cfg.Route. and heads up: you can filter (-f) by attributes that are not listed here. sneaky but legal 😌
• -w, --whitelist-namespace-routes — if set, backends will only see the specified namespaces as having routes.
• -b, --blacklist-namespace-routes — if set, backends will not see any routes for the specified namespaces. blocked. not invited. 🙈

🎀 ARGUMENTS 🎀

• backend — either the name of a built-in backend or the path to a backend module. paths to backend modules must end with a stoneg.py extension. and the built-in backends are, in order: obj_c_client, obj_c_types, obj_c_tests, js_client, js_types, tsd_client, tsd_types, python_types, python_type_stubs, python_client, swift_types, swift_client. that's twelve, count em, twelve 💫
• output — the folder to save generated files to. that's where the babies go 🍼
• spec — path to API specifications. each one must have a .stone extension. if it's omitted or set to -, the spec is read from stdin. and you can provide multiple namespaces over stdin by concatenating multiple specs together. chef's kiss, that's the combo move 🔥

📜 AUTHOR 📜

this manual page was written by fladi fladi@debian.org for the Debian system (and may be used by others). permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 any later version published by the Free Software Foundation.

on Debian systems, the complete text of the GNU General Public License can be found in /usr/share/common-licenses/GPL. go read it, it's right there 🫶

okay that's the whole page bestie, nothing skipped, nothing skipped, every flag accounted for 💯

and that's a wrap on stone(1), straight out of section 1 of the General Commands Manual — written for Debian, and yeah it may be used by others too 😌 stay hydrated, filter your routes, and slay 💅✨🎀🦋