+###*
+ * Main list-edit module.
+ *
+ * @module ListEdit
+###
+
 {CompositeDisposable, Range, TextBuffer} = require 'atom'
 _ = require 'underscore-plus'
 TextManipulation = require './text-manipulation'

          # Can also use => in the definition of the callbacks that require @, but this is safer
          (callback.bind this) editor, textBuffer, bufferText, selectionIxRange, elementList, listSelection

  mkListEditMeta: (elementList, selStart, selEnd) ->
    { startIx: listStartIx, endIx: listEndIx
    , openBracket: openBracket, separator: separator

        textBuffer.setTextInRange pasteRange, pasteText
        editor.setCursorBufferPosition (textBuffer.positionForCharacterIndex pasteIxRange[0] + pasteText.length)

  # TODO: @callbacks and @typedefs somehow need to be global or they cannot be referenced (~ an / don't work).
  ###*
   * Wrapper callback for accessing objects common to all list-edit actions.
   * @global
   * @callback WrapperCallback
   * @param {TextEditor}  editor           - The active text editor.
   * @param {TextBuffer}  textBuffer       - The corresponding text buffer.
   * @param {string}      bufferText       - The text string for textBuffer.
   * @param {number[]}    selectionIxRange - Character index range ([startIx, endIx]) for the most recently added user selection (multiple ranges are not supported).
   * @param {ElementList} elementList      - The element list that contains selectionIxRange.
   * @param {number[]}    listSelection    - List-element index range corresponding to selectionIxRange.
  ###

  ###*
   * Wrapper that creates the ElementList object and provides access to common objects.
   * @param  {WrapperCallback} callback - Is only called if there is a valid element list for the current selection.
  ###
  withSelectedList: (callback) ->
    editor = atom.workspace.getActiveTextEditor()
    if editor?
      textBuffer = editor.getBuffer()
      bufferText = textBuffer.getText()
      selectionIxRange = TextManipulation.getIxRangeForRange textBuffer, (editor.getSelectedBufferRange())
      ignoreRanges = @scanIgnoreRanges editor
      elementList = TextManipulation.ElementList.getElementList bufferText, ignoreRanges, selectionIxRange
      if not elementList?
        atom.notifications.addWarning 'Selection is not in well-formed list.'
