#855 Some API renames

brian Mon 7 Dec 2009

After talking with Andy about the DOM API, we were kind of debating about convention of current versus cur. To be consistent with other commonly used abbreviations we decided to stick with cur.

To consistently use cur and val I'm proposing the following API changes:

sys::Locale.current    => cur
sys::Locale.setCurrent => cur  // make as static field? its really threadlocal
sys::TimeZone.current  => cur
gfx::GfxEnv.current    => cur

Enum.values                 => vals    // this is generated by the compiler
sys::Map.values             => vals
sys::Type.isValue           => isVal  
dom::Elem.value             => val
flux::CachedOptions.value   => val
json::JsonParser.value      => val      // not public 
json::JsonWriter.writeValue => writeVal // not public

brian Mon 7 Dec 2009

Promoted to ticket #855 and assigned to brian

DanielFath Mon 7 Dec 2009

I'm tottally for val but cur feels weird IMHO. I think curr is the better alternative.

tactics Mon 7 Dec 2009

I'm +1 for cur. I use it all the time already.

brian Sat 12 Dec 2009

Ticket resolved in 1.0.48

These API changes have been completed.

Type.isValue and Enum.values must be fixed immediately due to be intertwined with the compiler code.

The remainder of the API changes leave the old slots in place with deprecation warnings. I will officially remove these slots in 1.0.49 to give everybody a build for fixing their code.

brian Fri 18 Dec 2009

Couple more things to think about as we try to standardize on when to use an abbreviation. I am thinking:

  • prefer msg to message
  • prefer rec to record

These are common terms that seem to get shortened almost as much as id for identifier.

If we do want to use msg and rec then I would propose:

Err.message                =>  Err.msg
Email.messageId            =>  Email.msgId
LogRecord                  =>  LogRec
LogRecord.message          =>  LogRec.msg
FileLogger.writeLogRecord  =>  writeLogRec

andy Fri 18 Dec 2009

I like it.

tactics Fri 18 Dec 2009

Sounds good.

brian Sun 20 Dec 2009

I made the msg and rec changes.

I also made Err.msg non-nullable - doesn't seem like a good reason to leave potentially NPE issues dangling out there for that field. If you have your own constructors with a nullable msg, you should change them to:

class MyErr : Err
{
  new make(Str msg := "", Err? cause := null) : super(msg, cause) {}
}

brian Mon 21 Dec 2009

Couple more places where I think we have some inconsistency:

  • prefer "addr" to "address"
  • prefer "option" to "opt"

This effects the following APIs:

inet::IpAddress => IpAddr
inet - some of the various APIs
web::WebReq.remoteAddress
wisp::WispReq.remoteAddress  
util::AbstractMain (everything uses opt)

EDIT: actually not sure about opt versus option for AbstractMain

brian Mon 21 Dec 2009

Another one - we inconsistently use err and error; switched everything to use err:

compiler::Compiler.errors
compiler::CompilerErr.isError
compiler::CompilerLog.error
docCompiler::DocCompiler.errors
fandoc::FandocParser.errors
fwt::Command.onInvokeError
sys::Log.isError
sys::Log.error
sys::LogLevel.error
web::WebRes.sendError
wisp::WispRes.sendError

tcolar Fri 9 Apr 2010

The Enum documentation (source code & this site) both still says "values" instead of "vals"

lel4866 Fri 9 Apr 2010

Not sure why you prefer option to opt. Seems opposite to the preferences for all the other abbreviations. I prefer opt.

Login or Signup to reply.