Thors BCDC++ LUA API Proposal

Post finished Clientside Scripts here, known supporting clients for LUA scripting.
Note: Client must be ADC 1.0

BCDC++ | RSX++

Thors BCDC++ LUA API Proposal

Post by Toast » 08 Jan 2011, 18:39

This file is for development purposes for the hopefully upcomming API for BCDC++ (DC++ LUA Plugin)

This file is mirrored from Thors site incase it goes down
(25.8 KiB) Downloaded 227 times

Junior Member
Posts: 41
Joined: 21 Jul 2009, 19:34

Re: Thors BCDC++ LUA API Proposal

Post by cologic » 23 Jan 2011, 05:43

Since this has come up a few times, and both Thor and Toast want a dialogue about this...

First, for easier cross-linking, the plugin API Launchpad bug and the live version of Thor's API documentation.

The good:
  • Per-script loading and unloading is a useful feature currently lacking (contrast with per-C++-plugin support, which is orthogonal). It comes with having distinct namespaces per Lua script, with attendant tradeoffs.
  • The UCType and UCContext enumerations are fine, since they actually are in ADC.
  • Using "dcpp." instead of "DC():" represents an improvement. I did that out of implementation convenience years ago, but I wouldn't particularly defend it.
  • OOP bonus: more uniform treatment of ADC and NMDC, where appropriate, than the status quo.
  • LogMessage is better than PrintDebug.
  • The retorts in metatable set up by the script are amusing.
The less good:
  • The StatusFlags enumeration doesn't have an obvious protocol correlate. About half of the ClientType enumeration members don't either (SU and OWNER, I believe; I don't recall the specific status of BOT at the moment). When discussing this in-hub, some people got the impression I was merely questioning the specific thresholds of these things. I was not. I'm not at all convinced any enumeration (or, more properly, set of flag - the documentation uses them kind of interchangeably when it's not really appropriate) with e.g. SERVER or FIREBALL should exist at all, whether in DC++ or a Lua interface. Certainly, DC++ currently doesn't use them, so inserting them into a Lua interface first seems strange (yes, I know, some mods have them). See also Utils.formatStatus, which thus also seems unnecessary.
  • Is REGGED something observable by other clients, either in ADC or NMDC?
  • The addUserCommand/getUserCommands model looks reasonable. But what does it have to do with FavoriteManager? More generally, what is the purpose of FavoriteManager?
  • Instead of both findHub and getHubs, perhaps combine them into a single getHubs function which returns a dict with hub_url -> Client object which Lua makes easy to run, basically, a findHub on. That satisfies both uses.
  • formatClientType needs the ClientType enum to be meaningful. See my criticism of that.
The trivial/bikeshedding/etc:
  • Nitpicking: Binded -> Bound.
  • The Utils namespace is awfully packed. I'm ambivalent about this, but it's a major change from the status quo.
  • sendUserCmd seems dangerously close to the set of UserCommand functions.
  • unavaible -> unavailable
  • Utils.getIpCountry depends on libgeoip. One more library dependency... (Which is as large as it is only to support lots of basically useless styles now. See BCDC++'s kml_geoip.lua for how to do this in a few lines of native Lua.
  • Client's getUserCount is pointless when one also has getUserList. It's very easy to emulate the former using the latter.
  • In ClientManager's getUsers, how common is the need to automate enumeration over all users on all hubs, including both ADC and NMDC?
  • Several of Utils functions seem unconvincing - decToIp, encodeURI, fileExists, ipToDec, isIp, maybe isPrivateIp,
  • sortByKeys is interesting, but also a non-DC-specific utility. It shouldn't live in the same namespace as all those basically DC-specific functions.
I know I've vacillated on this, but Thor's API does look pretty good at the moment, with substantial reservations. My most severe reservations involve interface elements I'm not sure should exist at all - see my last comment for why.

Junior Member
Posts: 41
Joined: 21 Jul 2009, 19:34

Re: Thors BCDC++ LUA API Proposal

Post by cologic » 13 Mar 2011, 18:12

Posted with permission of Thor, a chat on a DC hub about this topic:
<cologic> Also I'd like to point out ... f=32&t=728 again in case e.g. Thor was interested in commenting on it...
<Thor> unavaible -> unavailable << This is my common mistake, don't ask me why :D
<Thor> The addUserCommand/getUserCommands model looks reasonable. But what does it have to do with FavoriteManager? More generally, what is the purpose of FavoriteManager? << ask adrian_007 :) This API base on his removed Lua plugin (as you can see it on the manual)

<cologic> Ah, you're around. Odd to be a common mistake - aible isn't a common sequence to type, so it should be unusual to kind of fall into it via finger/muscle memory
<cologic> Yeah. I'm treating it separately from that though, so some of the questions are half playing-dumb.
<cologic> i.e. if you have something to propose, I'd be interested in reading it, but if it's 'oh well this thing, but without all the stuff that's there for separate, more or less irrelevant reason X which you can read about at URL Y', that's less compelling.

<Thor> The best solution would be if the client would offer enumeration...

<cologic> Of usercommands?

<Thor> For example. I meant about every enums.
<Thor> It might change, but if the startup.lua got them from the core, it would be always fresh and good =)

<cologic> Oh. Well some of them aren't true enums even - I was a bit sloppy (though I tried to fix that), but some of them are bitfields
<cologic> That's almost beside the point I was trying to make. There are (I claim) basically two kinds of enums/bit-value-sets. (1) Those specified in the ADC protocol which startup.lua or dependencies should have their own copies of anyway just as they parse ADC on their own; and (2) those which are pretty much 'oh this is what DC++ so do this too' which I vehemently disagree with existing in the API at all.
<cologic> (I'm not even thrilled with the settings changing/viewing API but it's not terrible to have)