From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp0 ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id QPZzFJl0xGHz9wAAgWs5BA (envelope-from ) for ; Thu, 23 Dec 2021 14:07:37 +0100 Received: from aspmx1.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp0 with LMTPS id qI8/EJl0xGEORgAA1q6Kng (envelope-from ) for ; Thu, 23 Dec 2021 13:07:37 +0000 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id E209826B6A for ; Thu, 23 Dec 2021 14:07:36 +0100 (CET) Received: from localhost ([::1]:41808 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1n0Nok-00009J-NY for larch@yhetil.org; Thu, 23 Dec 2021 08:07:34 -0500 Received: from eggs.gnu.org ([209.51.188.92]:52286) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n0Ncc-0004Ki-Dr for guix-patches@gnu.org; Thu, 23 Dec 2021 07:55:02 -0500 Received: from debbugs.gnu.org ([209.51.188.43]:49071) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1n0Ncc-0000Wg-1v for guix-patches@gnu.org; Thu, 23 Dec 2021 07:55:02 -0500 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1n0Ncb-0006Jb-S6 for guix-patches@gnu.org; Thu, 23 Dec 2021 07:55:01 -0500 X-Loop: help-debbugs@gnu.org Subject: [bug#52600] [PATCH] doc: Document (gnu services configuration). Resent-From: Xinglu Chen Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Thu, 23 Dec 2021 12:55:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 52600 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: Attila Lendvai Cc: Ludovic =?UTF-8?Q?Court=C3=A8s?= , 52600@debbugs.gnu.org, Maxim Cournoyer , Andrew Tropin Received: via spool by 52600-submit@debbugs.gnu.org id=B52600.164026409424256 (code B ref 52600); Thu, 23 Dec 2021 12:55:01 +0000 Received: (at 52600) by debbugs.gnu.org; 23 Dec 2021 12:54:54 +0000 Received: from localhost ([127.0.0.1]:60617 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1n0NcT-0006JA-Dw for submit@debbugs.gnu.org; Thu, 23 Dec 2021 07:54:53 -0500 Received: from h87-96-130-155.cust.a3fiber.se ([87.96.130.155]:53322 helo=mail.yoctocell.xyz) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1n0NcR-0006Ix-Uk for 52600@debbugs.gnu.org; Thu, 23 Dec 2021 07:54:52 -0500 From: Xinglu Chen DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yoctocell.xyz; s=mail; t=1640264085; bh=Ews1GYAP2HxNpS5lEWJ0chi/431GT5qIv5SkLu0j3mM=; h=From:To:Cc:Subject:In-Reply-To:References:Date; b=vXW6tHb6fHySjVLDTZptIFlvXG5diP5x7SSl6ShtHmveqF2W/4YQi8W7HE0irQr87 QNNqOza8Sn+NM47rw+iyXlDpgsoNrY9nq1p7/kVnP66lyqziTLDyky68TMMalm/2JU 5jYJ65CzzB19ZFfO+J7QDiwEM5ftPn2lWIT2WnoI= In-Reply-To: References: <665c4d2070de80af1d3594a268f0f6d3fb596d15.1639839498.git.public@yoctocell.xyz> <877dbwz3r7.fsf@gnu.org> <87ilvfd2lx.fsf@yoctocell.xyz> Date: Thu, 23 Dec 2021 13:54:44 +0100 Message-ID: <87a6grcwh7.fsf@yoctocell.xyz> MIME-Version: 1.0 Content-Type: multipart/signed; boundary="=-=-="; micalg=pgp-sha256; protocol="application/pgp-signature" X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+larch=yhetil.org@gnu.org Sender: "Guix-patches" X-Migadu-Flow: FLOW_IN X-Migadu-Country: US ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1640264857; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type:resent-cc:resent-from:resent-sender: resent-message-id:in-reply-to:in-reply-to:references:references: list-id:list-help:list-unsubscribe:list-subscribe:list-post: dkim-signature; bh=Ews1GYAP2HxNpS5lEWJ0chi/431GT5qIv5SkLu0j3mM=; b=Fi2+a5hbSRF2wNBHGc4Z9XTmC1Pv4zqaKvRO+x/oHwa6eC2Hpv9T0lXtadNVwpHU0SWo0W CkBhOizaySdym9oYv6JdE7tbbTZb/BURigYllIv4Z77w/1dWKDTU/WnlX3TKZSY/qr9rFu PUECz5eAm+wHDhxWidsVA6D1cQtSsi3T4rmLOPd17JKt0HMX3YQda0utakTAu1VjCeyE80 mHuaWKwn27RCu1PGi5m6enKrxZ/nxsandBmuUzMSKoI6FtGmas7MbgVjXwxux3ANtkIT6u V6IACw53DQPaB91sd8NSPP/wwuierDsbmJTSqXpIdHcwjvm42U6bUP1zHnARPQ== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1640264857; a=rsa-sha256; cv=none; b=OJKcZHdeCpNztvRjg41FxHPw9uPFbK/8z0M0IAAbGCTJmgawd7R3nsKaLyTAtyU7h4d7ak OLeUdyGSElUmSxiziZni60h1PU+MfDTv9gx9Pmg3tPfL4WwamPj0qVE8HHi7jTIyHV3JWp vIuT1ZU3v74FzYXj5SItJaFJmviK+UgkWOM68TOkRjlsUvYAZk7e0HInSt6w3GckjSulTX vKzMNJnLIpcVeDXGttGTooWqXqfGynbB4QglN5SWCHuYYxNaAaT250DItNn1/m7qzXPWrz iXaHTwXD7C7Uew/I4be6E2IgKAht9xVZQspat1FxaiDU6T4Wl3p0GJyuL4MvqQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=yoctocell.xyz header.s=mail header.b=vXW6tHb6; dmarc=fail reason="SPF not aligned (relaxed)" header.from=yoctocell.xyz (policy=none); spf=pass (aspmx1.migadu.com: domain of "guix-patches-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-patches-bounces+larch=yhetil.org@gnu.org" X-Migadu-Spam-Score: -3.05 Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=yoctocell.xyz header.s=mail header.b=vXW6tHb6; dmarc=fail reason="SPF not aligned (relaxed)" header.from=yoctocell.xyz (policy=none); spf=pass (aspmx1.migadu.com: domain of "guix-patches-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-patches-bounces+larch=yhetil.org@gnu.org" X-Migadu-Queue-Id: E209826B6A X-Spam-Score: -3.05 X-Migadu-Scanner: scn0.migadu.com X-TUID: ifgkI0A49fR4 --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Attila schrieb am Donnerstag der 23. Dezember 2021 um 11:18 GMT: >> Great, thanks for taking a look. I didn=E2=80=99t receive any message fr= om >> Attila though, and there doesn=E2=80=99t seem to be anything on the ML e= ither. >> >> I guess he sent it when all the GNU infra was down, but unless he didn= =E2=80=99t >> Cc me, I don=E2=80=99t see why I wouldn=E2=80=99t receive it. > > yep. since then i have resent it, available at: > > https://issues.guix.gnu.org/52600#1 Oh, I already had it in my archive, but it was missing a subject, and it wasn=E2=80=99t part of any thread, so I didn=E2=80=99t see it. Now to the reply: > as for some higher level feedback: >=20 > i have just finished my first Guix service, a rather complex > one. based on the examples, and on the config codebase itself, i had > used define-configuration, and i had encountered a surprise WRT > undefined values and maybe- types (only after that have i found this > documentation). >=20 > > default-value is the default value corresponding to the field; if > > none is specified, the user is forced to provide a value when creating > > an object of the record type. >=20 > i was expecting it to be possible to have a field like: >=20 > (foo > (maybe-integer?)) A =E2=80=98maybe-=E2=80=99 type doesn=E2=80=99t necessarily have to have a = default value set to =E2=80=98disabled=E2=80=99. The default value of the =E2=80=98foo=E2=80=99= field could just as well be =E2=80=983=E2=80=99 or something. > and its behavior would be to hold an undocumented value by default, > that the service implementations need to check for using a public > predicate function. What do you mean by =E2=80=9Cundocumented value=E2=80=9D? > some of the config values in my service can conditionally derive its > default value based on the value of other fields. I don=E2=80=99t think this is possible with =E2=80=98define-configuration= =E2=80=99 yet. But it would be a nice feature to have. > i need to be able to differentiate between undefined or user provided > field values (i.e. completely independent of anything related to > serialization). Maybe we could change =E2=80=98undefined=E2=80=99 to instead be an exceptio= n, which will raised when the user doesn=E2=80=99t provide anything. > > Sometimes a field should not be serialized if the user doesn=E2=80=99t = specify a > > value. To achieve this, you can use the @code{define-maybe} macro to > > define a ``maybe type''; if the value of a maybe type is set to the > > @code{disabled}, it will not be serialized. >=20 > the use of 'disabled here was very confusing because configuration > objects are typically full of boolean fields... is 'disabled a valid > app value, or part of the guix API? Boolean fields would be specified using Guile booleans, which would then get serialized to whatever syntax the configuration language expects. But you are right that it could be ambigous sometimes. > maybe we should use guile's *undefined*, and undefined? predicate > (which is sadly a macro). or reexport an undefined? function, and > shadow guile's macro? it's messy, and guile specific. I am not familiar with Guile internals, but I think that =E2=80=98#=E2=80=99 is just a thing that the pretty-printer pr= ints. Maybe we could use =E2=80=9Cproper=E2=80=9D Maybe types, like in SRFI-189[1]? [1]: Using > or maybe we could use a heap object of an unusual/private type in a > global private variable to represent undefined field values, and add a > public predicate to test for it. using a cons cell for this is > tempting, but it would leak implementation details for fields of type > cons?. i'm new to scheme, but the best candidate is maybe a private > dummy record instance? But what if a user wants to set a field to =E2=80=98disabled=E2=80=99 (beca= use they don=E2=80=99t want anything to get serialized), then that record would have= to be public. > i'd add a configuration-undefined-value? predicate, and also add a > configuration-defined-value? whose semantics is to return the value > itself, or #false when undefined. it comes handy in (or > (defined-value? foo) 42) patterns for non-boolean fields. But what if the value itself is #f? You wouldn=E2=80=99t be able to distin= guish between the cases where the value is undefined and when the value is #f. > in fact, i had these two in my service impl, before reading/writing > any of this: >=20 > (define (defined-value? x) > (if (eq? x 'undefined) #false x)) >=20 > (define (undefined-value? x) > (eq? x 'undefined)) >=20 > then the question arises: do we want to differentiate between the > cases when the field value comes from a default form, and when it is > set by the user (e.g. at object construction time)? if so, then one > well-known value as a marker is not enough, but i don't think it's > worth the additional complexity. people with rare, complex use-cases > can always resort to define-record*. I don=E2=80=99t really see a use of having that functionality; do you have = any examples when this would be useful to have? > another thing that has initially misled me was the word 'serialize': i > don't have a better suggestion, but i have associated it to a more > formal serialize/deserialize protocol, as opposed to turning scheme > objects into various different configuration file formats that are > native for the target binary. >=20 > maybe it's worth hinting at in the documentation where serialization > is first mentioned. The second paragraph explains this, no? Or do you think it can be improved? =2D-8<---------------cut here---------------start------------->8--- The main utility is the @code{define-configuration} macro, which you will use to define a Scheme record type (@pxref{Record Overview,,, guile, GNU Guile Reference Manual}). The Scheme record will be serialized to a configuration file by using @dfn{serializers}, which are procedures that take some kind of Scheme value and returns a G-expression (@pxref{G-Expressions}), which should, once serialized to the disk, return a string. More details are listed below. =2D-8<---------------cut here---------------end--------------->8--- > if the API of validate-configuration is to raise errors, then maybe it > could return the config object if everything is fine. that can > simplify the code at the call site. That=E2=80=99s probably a good idea. --=-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQJJBAEBCAAzFiEEAVhh4yyK5+SEykIzrPUJmaL7XHkFAmHEcZQVHHB1YmxpY0B5 b2N0b2NlbGwueHl6AAoJEKz1CZmi+1x5a+EP/3OILpTCVj22h22NP1P5xlhZZP1R /aXn+kKeIV+S6Nu0pmLYNwWhV14o6gzi4X5iJUSvDyULe0AT2BsviUSSlEsnQONL /GQOwBlfJRE4rkfaOD9uxIzalDGYLTCvjnAnJz4sIXKIpxF8rJjESjTzowrNpE2h Yatza/YWDJ/XvyY/r3FdycYOhAbeIGBOI/gfITKoK+bScot4cS84v0GU71VmHsXg NVjMmiUyT5INC/rnNXHHKaN9n53SP86U/jndiubXDn65RLG4Ue/GTUAik4FxK9i+ uTqksbV0H7HBFsNtBi58A6XpasdnbEUt62kUZ++5gJgL74mMIXedejJ1MaQ3iOEj 4b6Xzg9fBNUGZXyaVVdQSWz4KK6UHS1KLxbUBE30R7iR37dgUiwDvZi1/rt+CZCb 9ulTod7YqxfKb5KTCNFZfjrPKHLh8o6Od629TP5BIuqXlJTY1nmjSWGRm17NcKXm gSTqu6URtXtvi1u1BrREumzUWoSyCcp6kl4AFKsAiCpEERMdVNlObp6FbhzkYgsO 8itLxEd3oeKSsbcNwTH9zubpjyrT326HqHfK8ZBqqKJpEI0yURuymw5KLgwAUu/Q 2A0bFwbsVjhDmErXHf/cXffylEdx7hnM6Iv0nFbD2cmHYDNzGzcC52logs2FNk4o uE/3uBtSyCz6v0nZ =iZAt -----END PGP SIGNATURE----- --=-=-=--