Add outline command (similar to ls in irb and pry)

[st0012]

As described in #172 (comment), we can't rely on irb for the implementation. This PR introduces the feature by borrowing irb's ls implementation with some modifications. And we decided to name it outline instead of ls after discussing the name in this PR's comments.

It also avoids 2 issues we see in #172:

• Can't run on remote console.
• No-color config is not respected.

Closes #29

[st0012]

@ko1 btw, what does the list command name mean? list code? if it's not borrowed from other references (like other debugger's convention), how about renaming it to source? that way we can avoid the confusion between ls and list

[ono-max]

I'd like to confirm just in case. These code are based on irb project, right? Is that ok not to write any license here?

[st0012]

@ono-max Both projects' copyright belongs to Matz, so I'm not sure if that's necessary.

[ko1]

Now I'm thinking about the name again.

ls is shorthand of list. However debugger has l[ist] command.

[st0012]

@ko1 if list is not borrowed from other common references (like other debugger's convention), how about renaming it to source? irb and pry both use show source command to show source code.
and then we can avoid the confusion between ls and list.

[ko1]

It is one idea.
But l[ist] is from gdb, lldb, byebug, lib/debug.rb, traditional one.

[st0012]

I see, thanks for the references 👍
Because the ls command here does exactly the same as irb’s and people could often switch between debugger and irb, I strongly recommend keeping it consistent to avoid confusion.
How about giving it a different official name but make ls an alias to it?

[ko1]

I see. I think m[ethod[s]] expr but maybe pry's ls lists more.

BTW

• ls <obj>
  • Show you available methods, constants, local variables, and instance variables of the given obj.

what is "constants, local variables" of given obj? Constants only if obj is Class/Module?

[st0012]

@ko1 what do you think about overview (I know it's long but we can use shorthand o)? I think that's what ls does.

what is "constants, local variables" of given obj? Constants only if obj is Class/Module?

I'll update it.

[st0012]

@ko1 I've updated the description.

[ko1]

what is `"local variables" of given object?

[ko1]

I think i[nfo] can show lvars of current frame (now it showed) and ivars of self. List of methods of self is one idea.

[st0012]

ls provides these info:

• constants
• local variables
• methods
• instance variables

So maybe we can update info command like this then we don't need the ls?

• info shows current frame's
  • local variables
  • instance variables
  • constants (if it's a class/module)
  • other info that the current info already shows
• info locals - same as the above (perhaps this can go?)
• info <object> shows the object's
  • instance variables
  • constants (if it's a class/module)
• info m[ethod] shows current frame's
  • methods
• info m[ethod] <object> shows the object's
  • methods
• info thread shows (perhaps this can go?)
  • threads

[ko1]

Yes, I think similar, but:

info <object> shows the object's

It can conflict with other subcommand and I couldn't find good subcommand for that.

i[nfo] o[bject] <expr>

does make sense?

[ko1]

But I agree nobody use info object ... because too long (I also don't want to use it).

p obj for inspection.
X obj for digging into obj. d[ig] ...? (but it seems Hash#dig)

[ko1]

describe from common lisp https://twitter.com/anohana/status/1415887628465963008
I prefer this word.

• d[escribe]: describe about self
• d[escribe] <expr>: describe about <expr>

[ko1]

BTW, for the local variables, now info locals shows name = inspect_result lines but ls shows only names in one line (or in a few lines).

Which is useful? I like current info locals output, but I don't use it in big apps.

[st0012]

@ko1 I'm confused. Is describe for replacing info <object> or ls?
(the name describe is good to me btw)

Which is useful? I like current info locals output, but I don't use it in big apps.

Info

In some objects like Rails controllers, the current info could print dozens of lines:

%self => #<Api::Ticketbooth::V1::MemberController:0x00007ff391c84088
 @_action_has_layout=true,
 @_action_name="signup",
 @_config={},
 @_lookup_context=
  #<ActionView::LookupContext:0x00007ff391c7fda8
   @cache=true,
   @details=
...(1387 lines)
 @resource_klass_name="Api::Ticketbooth::V1::MemberResource">
email => "foo@example.com"
email_confirmation => "foo@example.com"
password => "somepass"
password_confirmation => "somepass"
cart => nil
customer => nil
member => nil
@_action_has_layout => true
@rendered_format => nil
@_routes => nil
@_request => #<ActionDispatch::Request:0x00007ff391cbec60
 @env=
  {"rack.version"=>[1, 3],
   "rack.input"=>#<StringIO:0x00007ff3914c0d60>,
   "rack.errors"=>#<StringIO:0x00007ff3914c0e00>,
   "rack.multithread"=>true,
   "rack.multiprocess"=>true,
   "rack.run_once"=>false,
...(1108 lines)
 @request_method="POST">
@_response => #<ActionDispatch::Response:0x00007ff391c843f8
 @cache_control={},
 @committed=false,
 @cv=
  #<MonitorMixin::ConditionVariable:0x00007ff391c84290
   @cond=#<Thread::ConditionVariable:0x00007ff391c84218>,
   @monitor=#<Monitor:0x00007ff391c84380>>,
 @header=
...(1118 lines)
   @str_body=nil>>
@_lookup_context => #<ActionView::LookupContext:0x00007ff391c7fda8
 @cache=true,
 @details=
  {:locale=>[:"en-GB"],
   :formats=>[:html],
   :variants=>[],
   :handlers=>[:raw, :erb, :html, :builder, :ruby]},
 @details_key=nil,
...(552 lines)
       #<Concurrent::Map:0x00007ff3a2d28028 entries=0 default_proc=nil>>]>>
@_action_name => "signup"
@_response_body => nil
@_params => <ActionController::Parameters {"data"=><ActionController::Parameters {"email"=>"foo@example.com", "password"=>"somepass"} permitted: true>, "include"=>"customer", "controller"=>"api/ticketbooth/v1/member", "action"=>"signup"} permitted: true>
@_config => {}
@resource_klass_name => "Api::Ticketbooth::V1::MemberResource"
@resource_klass => Api::Ticketbooth::V1::MemberResource
@context => #<Api::Ticketbooth::V1::TicketboothBaseResource::ResourceContext:0x00007ff3a7bc7e40
 @account=
  #<Account:0x00007ff3d0dcccf8
   id: 12,
   name: "Test1626419207",
   country_id: 105,
   ts_cache_version: 29,
   account_id: 12,
...(38 lines)
   updated_at: Fri, 16 Jul 2021 08:06:48 IST +01:00>>
@current_member => nil
@cart => #<Cart:0x00007ff3a7bc4858
 id: 125,
 created_at: Fri, 16 Jul 2021 08:07:27 IST +01:00,
 customer_id: 20,
 amends_order_id: nil,
 order_type: "online",
 account_id: 12,
 lock_version: 1,
...(9 lines)
 uuid: "7e68afa7-9215-4b5d-ac06-035b38eb3d54">
@request => #<JSONAPI::RequestParser:0x00007ff3949e08d8
 @context=
  #<Api::Ticketbooth::V1::TicketboothBaseResource::ResourceContext:0x00007ff3a7bc7e40
   @account=
    #<Account:0x00007ff3d0dcccf8
     id: 12,
     name: "Test1626419207",
     country_id: 105,
...(93 lines)
 @warnings=[]>

ls

Because ls prints all methods, in my project's controller the full result takes 600 lines....

But variables are listed at the bottom 3 lines. So for reading available variables (without the values), it's a more convenient option:

instance variables: @_action_has_layout  @_action_name  @_config  @_lookup_context  @_params  @_request  @_response  @_response_body  @_routes  @cart  @context  @current_member  @rendered_format  @request  @resource_klass  @resource_klass_name
class variables: @@server_error_callbacks
locals: _  cart  customer  email  email_confirmation  member  password  password_confirmation

[ko1]

@ko1 I'm confused. Is describe for replacing info or ls?

Yes.

But variables are listed at the bottom 3 lines. So for reading available variables (without the values), it's a more convenient option:

I see. It is same as ls command which only shows the name, but doesn't show the contents.
describe <expr> sounds to show the contents or names ...?

On clisp

Break 5 [6]> (describe 1)

1 is an integer, uses 1 bit, is represented as a fixnum.

it seems man (so it describe by documentation).

[ko1]

BTW info should output 1 line inspect if it takes 2 or more lines. I'll change.

[ko1]

could you try current master with one-line info? (sorry for off-topic)

[st0012]

@ko1 I haven't used tool/language with a describe command or keyword, so I don't have a specific expectation for it.
But describe sounds like a good command for type information 🤔 Perhaps we can save it for later?
What do you think about intro? Available methods + ivars + constants feels like an introduction to the given object or current scope?

[st0012]

could you try current master with one-line info? (sorry for off-topic)

The new info commands are pretty useful (`info consts) and also easier to read 👍

[ko1]

Today I was thinking about ls, the main purpose of this command is listing. And discussing with my wife (Rubyist), she proposed outline. It is similar to overview but I googled it the differences, overview is written in sentence and outline is written in itemized format. intro(duction) seems also sentence.

Now I prefer to use o[utline] <expr>. Fortunately, o seems "object".

But describe sounds like a good command for type information 🤔 Perhaps we can save it for later?

I see. Common Lisp describe also shows manual, so we can reserve it.

[st0012]

outline sounds good to me too 👍
Do you want to reserve the ls as an alias, or we just mention that in the doc?
Also is there anything else you want to change other than the name?

[st0012]

@ko1 I've renamed the command and the PR

[ko1]

Sorry for late.
It's ok to add ls as alias of outline.

Document: please use <expr> for this purpose instead of <object>.

For source code, I don't want to increase a file and classes. It is okay to merge current source and I rewrite it.

(also I'll confirmed about license before merge to the original author)

[st0012]

It's ok to add ls as alias of outline.
Document: please use for this purpose instead of .

👍

For source code, I don't want to increase a file and classes.

Can you tell me the reason? Is it for performance concern or code maintenance?

I feel like the thread_client.rb contains more and more command-specific logic and makes it harder to navigate. For example, the methods for info command takes about 100 lines and it's far away from where they're used. I feel like having a place to put them (if you're not a fan of new class, perhaps a InformationHelper module?) will make future contributors easier to understand ThreadClient.

(also I'll confirmed about license before merge to the original author)

thanks 🙂

[ko1]

Is it for performance concern or code maintenance?

Yes. I want to make them smaller.

[st0012]

I see, thanks. Is mixin an option then?

[ko1]

More comments, if we introduce such file, maybe we want to separate all of components into small files.

[st0012]

More comments, if we introduce such file, maybe we want to separate all of components into small files.

that's what I'm thinking about. I think info can be extracted, for example.

[st0012]

@ko1 have you decided whether to use similar file pattern for other commands?
also, I think the outline command is now ready for merge.

[ko1]

Sorry I didn't heard about license yet.

Anyway, now I don't want to allow file separations for each command, this patch is not acceptable for me.
I'll change the implementation after merging. Can I do that after merging?

[st0012]

@ko1 sure 👍

[ko1]

author Kokubun-san allow me to copy it.

[st0012]

@ko1 thank you!